altium-toolkit 1.1.35 → 1.1.37

package/src/ui/AltiumScene3dShapeStackOwnerAdapter.mjs

@@ -1,6 +1,4 @@
-const TIMING_PACKAGE_PATTERN =
-    /(?:^|[^a-z0-9])(?:clock|crystal|osc|oscillator|resonator|tcxo|txco|xtal)(?:$|[^a-z0-9])/i
-const TIMING_DESIGNATOR_PATTERN = /^(?:y|xo)\d+[a-z]?$/i
+import { AltiumScene3dShapeStackOwnerConflictPolicy } from './AltiumScene3dShapeStackOwnerConflictPolicy.mjs'
 
 /**
  * Keeps authored shape-based sub-bodies grouped under their carrier owner.
@@ -10,7 +8,8 @@ export class AltiumScene3dShapeStackOwnerAdapter {
     static #EXACT_OWNER_TOLERANCE_MIL = 1
     static #STACK_BODY_RADIUS_MIL = 220
     static #HEIGHT_TOLERANCE_MIL = 0.1
-
+    static #OPPOSITE_SIDE_OWNER_DISTANCE_MARGIN_MIL = 10
+    static #STACK_BODY_OWNER_CONFLICT_MARGIN_MIL = 5
     /**
      * Applies authored stack ownership to static and external placements.
      * @param {object} sceneDescription Built scene description.
@@ -53,23 +52,25 @@ export class AltiumScene3dShapeStackOwnerAdapter {
             ])
         )
 
+        const repairedExternalPlacements =
+            AltiumScene3dShapeStackOwnerAdapter.#repairExternalPlacements(
+                sceneDescription.externalPlacements,
+                componentBodies,
+                assignments,
+                sceneDescription.board,
+                components
+            )
+
         return {
             ...sceneDescription,
             components: AltiumScene3dShapeStackOwnerAdapter.#markComponents(
                 sceneDescription.components,
                 ownerGroupKeys
             ),
-            externalPlacements:
-                AltiumScene3dShapeStackOwnerAdapter.#repairExternalPlacements(
-                    sceneDescription.externalPlacements,
-                    componentBodies,
-                    assignments,
-                    sceneDescription.board
-                ),
+            externalPlacements: repairedExternalPlacements,
             staticBodyPlacements:
                 AltiumScene3dShapeStackOwnerAdapter.#repairStaticPlacements(
                     sceneDescription.staticBodyPlacements,
-                    componentBodies,
                     assignments,
                     sceneDescription.board
                 )
@@ -102,17 +103,19 @@ export class AltiumScene3dShapeStackOwnerAdapter {
      * @param {object[]} componentBodies Source component-body rows.
      * @param {object[]} assignments Carrier assignments.
      * @param {object | undefined} board Scene board metadata.
+     * @param {object[]} components Source components.
      * @returns {object[]}
      */
     static #repairExternalPlacements(
         placements,
         componentBodies,
         assignments,
-        board
+        board,
+        components
     ) {
         const usedComponentBodies = new Set()
 
-        return (Array.isArray(placements) ? placements : []).map(
+        return (Array.isArray(placements) ? placements : []).flatMap(
             (placement) => {
                 const componentBody =
                     AltiumScene3dShapeStackOwnerAdapter.#resolveComponentBody(
@@ -127,18 +130,27 @@ export class AltiumScene3dShapeStackOwnerAdapter {
                 const assignment =
                     AltiumScene3dShapeStackOwnerAdapter.#assignmentForBody(
                         componentBody,
-                        assignments
+                        assignments,
+                        components
                     )
                 if (!assignment) {
-                    return placement
+                    return AltiumScene3dShapeStackOwnerAdapter.#shouldDropConflictingStackBody(
+                        componentBody,
+                        assignments,
+                        components
+                    )
+                        ? []
+                        : [placement]
                 }
 
-                return AltiumScene3dShapeStackOwnerAdapter.#withOwner(
-                    placement,
-                    componentBody,
-                    assignment,
-                    board
-                )
+                return [
+                    AltiumScene3dShapeStackOwnerAdapter.#withOwner(
+                        placement,
+                        componentBody,
+                        assignment,
+                        board
+                    )
+                ]
             }
         )
     }
@@ -146,17 +158,11 @@ export class AltiumScene3dShapeStackOwnerAdapter {
     /**
      * Repairs carrier static body ownership.
      * @param {object[] | undefined} placements Scene static body placements.
-     * @param {object[]} componentBodies Source component-body rows.
      * @param {object[]} assignments Carrier assignments.
      * @param {object | undefined} board Scene board metadata.
      * @returns {object[]}
      */
-    static #repairStaticPlacements(
-        placements,
-        componentBodies,
-        assignments,
-        board
-    ) {
+    static #repairStaticPlacements(placements, assignments, board) {
         return (Array.isArray(placements) ? placements : []).map(
             (placement) => {
                 const assignment = assignments.find((candidate) =>
@@ -169,21 +175,103 @@ export class AltiumScene3dShapeStackOwnerAdapter {
                     return placement
                 }
 
-                return {
-                    ...placement,
-                    designator: String(assignment.owner.designator || ''),
-                    positionMil:
-                        AltiumScene3dShapeStackOwnerAdapter.#withOwnerAnchor(
-                            placement?.positionMil,
-                            assignment.owner,
-                            board
-                        ),
-                    coLocatedVariantGroupKey: assignment.groupKey
-                }
+                return AltiumScene3dShapeStackOwnerAdapter.#withStaticOwner(
+                    placement,
+                    assignment,
+                    board
+                )
             }
         )
     }
 
+    /**
+     * Applies one stack owner to a repaired static carrier body.
+     * @param {object} placement Static body placement.
+     * @param {{ owner: object, groupKey: string }} assignment Stack assignment.
+     * @param {object | undefined} board Scene board metadata.
+     * @returns {object}
+     */
+    static #withStaticOwner(placement, assignment, board) {
+        const ownerDesignator = String(assignment?.owner?.designator || '')
+        const mountSide =
+            AltiumScene3dShapeStackOwnerAdapter.#mountSide(assignment?.owner) ||
+            placement?.mountSide
+        const sidePlacement =
+            AltiumScene3dShapeStackOwnerAdapter.#withStaticMountSide(
+                placement,
+                mountSide
+            )
+
+        return {
+            ...sidePlacement,
+            designator: ownerDesignator,
+            selectionKey: ownerDesignator || sidePlacement.selectionKey,
+            positionMil: AltiumScene3dShapeStackOwnerAdapter.#withOwnerAnchor(
+                sidePlacement?.positionMil,
+                assignment.owner,
+                board
+            ),
+            coLocatedVariantGroupKey: assignment.groupKey
+        }
+    }
+
+    /**
+     * Applies a static placement side while preserving its height magnitude.
+     * @param {object} placement Static body placement.
+     * @param {string | undefined} mountSide Owner mount side.
+     * @returns {object}
+     */
+    static #withStaticMountSide(placement, mountSide) {
+        const currentSide =
+            AltiumScene3dShapeStackOwnerAdapter.#normalizeMountSide(
+                placement?.mountSide
+            )
+        const side = AltiumScene3dShapeStackOwnerAdapter.#normalizeMountSide(
+            mountSide || currentSide
+        )
+        const z = Math.abs(Number(placement?.positionMil?.z || 0))
+
+        return {
+            ...placement,
+            mountSide: side,
+            positionMil: {
+                ...(placement?.positionMil || {}),
+                z: side === 'bottom' ? -z : z
+            },
+            geometry:
+                currentSide === side
+                    ? placement?.geometry
+                    : AltiumScene3dShapeStackOwnerAdapter.#mirrorStaticGeometry(
+                          placement
+                      )
+        }
+    }
+
+    /**
+     * Mirrors source-coordinate static geometry for the opposite board side.
+     * @param {{ sourceCoordinateFrame?: boolean, geometry?: object }} placement Static body placement.
+     * @returns {object | undefined}
+     */
+    static #mirrorStaticGeometry(placement) {
+        const geometry = placement?.geometry
+        if (
+            !placement?.sourceCoordinateFrame ||
+            !Array.isArray(geometry?.verticesMil)
+        ) {
+            return geometry
+        }
+
+        return {
+            ...geometry,
+            verticesMil: geometry.verticesMil.map((vertex) => ({
+                x: AltiumScene3dShapeStackOwnerAdapter.#round(vertex?.x || 0),
+                y: AltiumScene3dShapeStackOwnerAdapter.#round(
+                    -Number(vertex?.y || 0)
+                )
+            }))
+        }
+    }
+
     /**
      * Re-anchors a repaired static carrier on the owning component position.
      * @param {object | undefined} position Existing render position.
@@ -214,7 +302,9 @@ export class AltiumScene3dShapeStackOwnerAdapter {
             AltiumScene3dShapeStackOwnerAdapter.#isCarrierBase(body)
         )
         const timingComponents = components.filter((component) =>
-            AltiumScene3dShapeStackOwnerAdapter.#isTimingComponent(component)
+            AltiumScene3dShapeStackOwnerConflictPolicy.isTimingComponent(
+                component
+            )
         )
         const groups =
             AltiumScene3dShapeStackOwnerAdapter.#groupCarrierBases(bases)
@@ -229,20 +319,26 @@ export class AltiumScene3dShapeStackOwnerAdapter {
                 return []
             }
 
-            const owners = timingComponents
-                .filter(
-                    (component) =>
-                        AltiumScene3dShapeStackOwnerAdapter.#distance(
-                            group.anchor,
-                            component
-                        ) <=
-                        AltiumScene3dShapeStackOwnerAdapter
-                            .#BASE_OWNER_TOLERANCE_MIL
-                )
-                .sort(
+            const owners =
+                AltiumScene3dShapeStackOwnerConflictPolicy.preferredSideOwners(
+                    group.anchor,
+                    timingComponents.filter(
+                        (component) =>
+                            AltiumScene3dShapeStackOwnerAdapter.#distance(
+                                group.anchor,
+                                component
+                            ) <=
+                            AltiumScene3dShapeStackOwnerAdapter
+                                .#BASE_OWNER_TOLERANCE_MIL
+                    ),
+                    AltiumScene3dShapeStackOwnerAdapter
+                        .#OPPOSITE_SIDE_OWNER_DISTANCE_MARGIN_MIL
+                ).sort(
                     (left, right) =>
-                        AltiumScene3dShapeStackOwnerAdapter.#ownerRank(right) -
-                            AltiumScene3dShapeStackOwnerAdapter.#ownerRank(
+                        AltiumScene3dShapeStackOwnerConflictPolicy.ownerRank(
+                            right
+                        ) -
+                            AltiumScene3dShapeStackOwnerConflictPolicy.ownerRank(
                                 left
                             ) ||
                         String(left?.designator || '').localeCompare(
@@ -305,12 +401,12 @@ export class AltiumScene3dShapeStackOwnerAdapter {
         return (
             exactOwners.some(
                 (component) =>
-                    !AltiumScene3dShapeStackOwnerAdapter.#isTimingComponent(
+                    !AltiumScene3dShapeStackOwnerConflictPolicy.isTimingComponent(
                         component
                     )
             ) &&
             !exactOwners.some((component) =>
-                AltiumScene3dShapeStackOwnerAdapter.#isTimingComponent(
+                AltiumScene3dShapeStackOwnerConflictPolicy.isTimingComponent(
                     component
                 )
             )
@@ -368,9 +464,109 @@ export class AltiumScene3dShapeStackOwnerAdapter {
      * Finds a carrier assignment for one positive-height sub-body.
      * @param {object | null} componentBody Source component-body row.
      * @param {object[]} assignments Carrier assignments.
+     * @param {object[]} components Source components.
      * @returns {object | null}
      */
-    static #assignmentForBody(componentBody, assignments) {
+    static #assignmentForBody(componentBody, assignments, components) {
+        return (
+            AltiumScene3dShapeStackOwnerAdapter.#assignmentCandidatesForBody(
+                componentBody,
+                assignments
+            )
+                .filter((candidate) =>
+                    AltiumScene3dShapeStackOwnerAdapter.#canAssignStackBodyCandidate(
+                        componentBody,
+                        candidate,
+                        components
+                    )
+                )
+                .sort(
+                    (left, right) =>
+                        left.heightError - right.heightError ||
+                        left.distance - right.distance
+                )[0]?.assignment || null
+        )
+    }
+
+    /**
+     * Checks whether a candidate stack owner can claim a raised body.
+     * @param {object | null} componentBody Source component-body row.
+     * @param {{ assignment: { owner: object } }} candidate Candidate assignment row.
+     * @param {object[]} components Source components.
+     * @returns {boolean}
+     */
+    static #canAssignStackBodyCandidate(componentBody, candidate, components) {
+        const hasConflictingOwner =
+            AltiumScene3dShapeStackOwnerConflictPolicy.hasConflictingComponentOwner(
+                componentBody,
+                candidate.assignment.owner,
+                components,
+                AltiumScene3dShapeStackOwnerAdapter
+                    .#STACK_BODY_OWNER_CONFLICT_MARGIN_MIL
+            )
+        if (!hasConflictingOwner) {
+            return true
+        }
+
+        return (
+            AltiumScene3dShapeStackOwnerConflictPolicy.hasStackDetailBodyIdentity(
+                componentBody
+            ) &&
+            !AltiumScene3dShapeStackOwnerConflictPolicy.hasExactOppositeSideOwner(
+                componentBody,
+                candidate.assignment.owner,
+                components,
+                AltiumScene3dShapeStackOwnerAdapter.#EXACT_OWNER_TOLERANCE_MIL
+            )
+        )
+    }
+
+    /**
+     * Checks whether an unassigned positive-height body should be suppressed
+     * because it conflicts with an opposite-side owner but has no exact owner
+     * of its own.
+     * @param {object | null} componentBody Source component-body row.
+     * @param {object[]} assignments Carrier assignments.
+     * @param {object[]} components Source components.
+     * @returns {boolean}
+     */
+    static #shouldDropConflictingStackBody(
+        componentBody,
+        assignments,
+        components
+    ) {
+        const conflict =
+            AltiumScene3dShapeStackOwnerAdapter.#assignmentCandidatesForBody(
+                componentBody,
+                assignments
+            ).find((candidate) =>
+                AltiumScene3dShapeStackOwnerConflictPolicy.hasConflictingComponentOwner(
+                    componentBody,
+                    candidate.assignment.owner,
+                    components,
+                    AltiumScene3dShapeStackOwnerAdapter
+                        .#STACK_BODY_OWNER_CONFLICT_MARGIN_MIL
+                )
+            )
+
+        return Boolean(
+            conflict &&
+            !AltiumScene3dShapeStackOwnerConflictPolicy.hasExactOppositeSideOwner(
+                componentBody,
+                conflict.assignment.owner,
+                components,
+                AltiumScene3dShapeStackOwnerAdapter.#EXACT_OWNER_TOLERANCE_MIL
+            )
+        )
+    }
+
+    /**
+     * Builds stack assignment candidates for one positive-height body.
+     * @param {object | null} componentBody Source component-body row.
+     * @param {object[]} assignments Carrier assignments.
+     * @returns {{ assignment: object, heightError: number, distance: number }[]}
+     */
+    static #assignmentCandidatesForBody(componentBody, assignments) {
         if (
             !componentBody ||
             !AltiumScene3dShapeStackOwnerAdapter.#isShapeBasedBody(
@@ -378,7 +574,7 @@ export class AltiumScene3dShapeStackOwnerAdapter {
             ) ||
             Number(componentBody?.standoffHeightMil || 0) <= 0
         ) {
-            return null
+            return []
         }
 
         const standoff = Number(componentBody.standoffHeightMil)
@@ -386,33 +582,26 @@ export class AltiumScene3dShapeStackOwnerAdapter {
             componentBody.positionMil
         )
 
-        return (
-            assignments
-                .map((assignment) => ({
-                    assignment,
-                    heightError: Math.abs(
-                        Number(assignment.heightMil || 0) - standoff
-                    ),
-                    distance: AltiumScene3dShapeStackOwnerAdapter.#distance(
-                        bodyPosition,
-                        assignment.owner
-                    )
-                }))
-                .filter(
-                    (candidate) =>
-                        candidate.heightError <=
-                            AltiumScene3dShapeStackOwnerAdapter
-                                .#HEIGHT_TOLERANCE_MIL &&
-                        candidate.distance <=
-                            AltiumScene3dShapeStackOwnerAdapter
-                                .#STACK_BODY_RADIUS_MIL
+        return (Array.isArray(assignments) ? assignments : [])
+            .map((assignment) => ({
+                assignment,
+                heightError: Math.abs(
+                    Number(assignment.heightMil || 0) - standoff
+                ),
+                distance: AltiumScene3dShapeStackOwnerAdapter.#distance(
+                    bodyPosition,
+                    assignment.owner
                 )
-                .sort(
-                    (left, right) =>
-                        left.heightError - right.heightError ||
-                        left.distance - right.distance
-                )[0]?.assignment || null
-        )
+            }))
+            .filter(
+                (candidate) =>
+                    candidate.heightError <=
+                        AltiumScene3dShapeStackOwnerAdapter
+                            .#HEIGHT_TOLERANCE_MIL &&
+                    candidate.distance <=
+                        AltiumScene3dShapeStackOwnerAdapter
+                            .#STACK_BODY_RADIUS_MIL
+            )
     }
 
     /**
@@ -619,57 +808,6 @@ export class AltiumScene3dShapeStackOwnerAdapter {
             : 0
     }
 
-    /**
-     * Checks whether a component is a timing-package owner.
-     * @param {object} component Source component.
-     * @returns {boolean}
-     */
-    static #isTimingComponent(component) {
-        const designator = String(component?.designator || '').trim()
-
-        return (
-            TIMING_DESIGNATOR_PATTERN.test(designator) ||
-            TIMING_PACKAGE_PATTERN.test(
-                [
-                    component?.pattern,
-                    component?.source,
-                    component?.description,
-                    component?.provenance?.footprintDescription,
-                    ...Object.values(component?.parameters || {})
-                ]
-                    .map((value) => String(value || ''))
-                    .join(' ')
-            )
-        )
-    }
-
-    /**
-     * Scores how strongly a component looks like the fitted stack owner.
-     * @param {object} component Source component.
-     * @returns {number}
-     */
-    static #ownerRank(component) {
-        const parameters = Object.values(component?.parameters || {}).filter(
-            (value) => String(value || '').trim()
-        )
-        return (
-            parameters.length * 10 +
-            (TIMING_DESIGNATOR_PATTERN.test(component?.designator) ? 5 : 0) +
-            (TIMING_PACKAGE_PATTERN.test(
-                [
-                    component?.pattern,
-                    component?.source,
-                    component?.description,
-                    component?.provenance?.footprintDescription
-                ]
-                    .map((value) => String(value || ''))
-                    .join(' ')
-            )
-                ? 3
-                : 0)
-        )
-    }
-
     /**
      * Checks whether one body row came from shape-based component metadata.
      * @param {object | null | undefined} componentBody Source body row.
@@ -691,6 +829,19 @@ export class AltiumScene3dShapeStackOwnerAdapter {
         return layer.includes('BOTTOM') || layer === 'BOT' ? 'bottom' : 'top'
     }
 
+    /**
+     * Normalizes a static placement side token.
+     * @param {string | undefined} mountSide Candidate mount side.
+     * @returns {'top' | 'bottom'}
+     */
+    static #normalizeMountSide(mountSide) {
+        return String(mountSide || 'top')
+            .trim()
+            .toLowerCase() === 'bottom'
+            ? 'bottom'
+            : 'top'
+    }
+
     /**
      * Resolves one board face Z coordinate.
      * @param {string} mountSide Mount side.