altium-toolkit 1.1.32 → 1.1.33

package/src/ui/PcbScene3dBuilder.mjs

@@ -9,6 +9,7 @@ import { AltiumScene3dExternalPlacementAdapter } from './AltiumScene3dExternalPl
 import { AltiumScene3dBottomPadRotationAdapter } from './AltiumScene3dBottomPadRotationAdapter.mjs'
 import { AltiumScene3dComponentBodyAdapter } from './AltiumScene3dComponentBodyAdapter.mjs'
 import { AltiumScene3dAuthoredBodyAnchorAdapter } from './AltiumScene3dAuthoredBodyAnchorAdapter.mjs'
+import { AltiumScene3dShapeStackOwnerAdapter } from './AltiumScene3dShapeStackOwnerAdapter.mjs'
 import { PcbFootprintPrimitiveSelector } from './PcbFootprintPrimitiveSelector.mjs'
 import { PcbScene3dPadLocalSpanResolver } from './PcbScene3dPadLocalSpanResolver.mjs'
 import { PcbScene3dPackages } from './PcbScene3dPackages.mjs'
@@ -31,7 +32,10 @@ export class PcbScene3dBuilder {
     static #UNMATCHED_BODY_OVERHANG_RATIO = 0.25
     static #UNMATCHED_BODY_MIN_OVERHANG_MIL = 150
     static #UNMATCHED_BODY_MAX_OVERHANG_MIL = 600
+    static #OVERSIZED_GENERIC_FALLBACK_MAX_MIL = 800
     static #TRUETYPE_TEXT_WIDTH_RATIO = 0.55
+    static #LOW_CONFIDENCE_GENERIC_FOOTPRINT_PATTERN =
+        /(?:^|[^a-z0-9])(?:edge|finger|fingers|contact|contacts|mech|mechanical|jumper|jump)(?:$|[^a-z0-9])/i
     static #AUTHORED_BODY_IDENTITY_PATTERN =
         /(?:^|[^a-z0-9])(?:antenna|coax|conn|connector|edge|flex|fpc|frame|hardware|header|jack|mechanical|module|mount|shield|sma|socket|usb)(?:$|[^a-z0-9])/i
     static #COMPONENT_PACKAGE_BODY_PATTERN =
@@ -141,15 +145,17 @@ export class PcbScene3dBuilder {
             boardAssemblyModel:
                 modelRegistry?.resolveBoardAssemblyModel?.(documentModel) ||
                 null,
-            components: components.map((component) =>
-                PcbScene3dBuilder.#buildComponent(
-                    component,
-                    pads,
-                    board,
-                    thicknessMil,
-                    modelRegistry
+            components: components
+                .map((component) =>
+                    PcbScene3dBuilder.#buildComponent(
+                        component,
+                        pads,
+                        board,
+                        thicknessMil,
+                        modelRegistry
+                    )
                 )
-            ),
+                .filter(Boolean),
             externalPlacements: componentBodies
                 .map((componentBody, index) =>
                     PcbScene3dBuilder.#buildExternalPlacement(
@@ -167,6 +173,7 @@ export class PcbScene3dBuilder {
                 componentBodies,
                 bodyMatches,
                 components,
+                pads,
                 board,
                 thicknessMil
             ),
@@ -191,8 +198,11 @@ export class PcbScene3dBuilder {
             AltiumScene3dBottomPadRotationAdapter.apply(
                 AltiumScene3dComponentBodyAdapter.apply(
                     AltiumScene3dExternalPlacementAdapter.apply(
-                        PcbScene3dBoardOutlineRefiner.refine(
-                            sceneDescription,
+                        AltiumScene3dShapeStackOwnerAdapter.apply(
+                            PcbScene3dBoardOutlineRefiner.refine(
+                                sceneDescription,
+                                sceneDocumentModel
+                            ),
                             sceneDocumentModel
                         ),
                         sceneDocumentModel
@@ -210,7 +220,7 @@ export class PcbScene3dBuilder {
      * @param {{ centerX: number, centerY: number }} board
      * @param {number} thicknessMil
      * @param {{ resolveComponentModel: (component: any) => { name: string, relativePath: string, format: string } | null } | null} modelRegistry
-     * @returns {{ designator: string, mountSide: string, rotationDeg: number, positionMil: { x: number, y: number, z: number }, boardPositionMil: { x: number, y: number, z: number }, pattern: string, source: string, description: string, parameters: Record<string, unknown>, body: { family: string, sizeMil: { width: number, depth: number, height: number } }, externalModel: { name: string, relativePath: string, format: string } | null }}
+     * @returns {{ designator: string, mountSide: string, rotationDeg: number, positionMil: { x: number, y: number, z: number }, boardPositionMil: { x: number, y: number, z: number }, pattern: string, source: string, description: string, parameters: Record<string, unknown>, body: { family: string, sizeMil: { width: number, depth: number, height: number } }, externalModel: { name: string, relativePath: string, format: string } | null } | null}
      */
     static #buildComponent(
         component,
@@ -222,6 +232,19 @@ export class PcbScene3dBuilder {
         const mountSide = PcbScene3dBuilder.#resolveMountSide(component)
         const padSpan = PcbScene3dBuilder.#resolvePadSpan(component, pads)
         const body = PcbScene3dPackages.resolve(component, padSpan)
+        const externalModel = modelRegistry
+            ? modelRegistry.resolveComponentModel(component)
+            : null
+        if (
+            PcbScene3dBuilder.#shouldSuppressProceduralComponent(
+                component,
+                body,
+                externalModel
+            )
+        ) {
+            return null
+        }
+
         const halfBoardThickness = thicknessMil / 2
         const halfBodyHeight = body.sizeMil.height / 2
         const z =
@@ -253,12 +276,56 @@ export class PcbScene3dBuilder {
                     ? { ...component.parameters }
                     : {},
             body,
-            externalModel: modelRegistry
-                ? modelRegistry.resolveComponentModel(component)
-                : null
+            externalModel
         }
     }
 
+    /**
+     * Checks whether one generated fallback body is too uncertain to render.
+     * @param {{ pattern?: string, source?: string, description?: string }} component Source component.
+     * @param {{ family?: string, sizeMil?: { width?: number, depth?: number } }} body Procedural body.
+     * @param {object | null} externalModel Resolved external model.
+     * @returns {boolean}
+     */
+    static #shouldSuppressProceduralComponent(component, body, externalModel) {
+        return (
+            !externalModel &&
+            body?.family === 'generic' &&
+            PcbScene3dBuilder.#isOversizedGenericFallback(body) &&
+            PcbScene3dBuilder.#isLowConfidenceGenericFootprint(component)
+        )
+    }
+
+    /**
+     * Checks whether one generic fallback body spans too much of the board.
+     * @param {{ sizeMil?: { width?: number, depth?: number } }} body Procedural body.
+     * @returns {boolean}
+     */
+    static #isOversizedGenericFallback(body) {
+        return (
+            Math.max(
+                Number(body?.sizeMil?.width || 0),
+                Number(body?.sizeMil?.depth || 0)
+            ) > PcbScene3dBuilder.#OVERSIZED_GENERIC_FALLBACK_MAX_MIL
+        )
+    }
+
+    /**
+     * Checks for footprint identities that describe board features or
+     * mechanical placeholders more often than physical package bodies.
+     * @param {{ pattern?: string, source?: string, description?: string }} component Source component.
+     * @returns {boolean}
+     */
+    static #isLowConfidenceGenericFootprint(component) {
+        return PcbScene3dBuilder.#LOW_CONFIDENCE_GENERIC_FOOTPRINT_PATTERN.test(
+            [
+                component?.pattern,
+                component?.source,
+                component?.description
+            ].join(' ')
+        )
+    }
+
     /**
      * Resolves one component-body model through the active registry.
      * @param {{ modelId?: string, checksum?: number | null, name?: string }} componentBody Component body metadata.
@@ -352,7 +419,8 @@ export class PcbScene3dBuilder {
             modelTransform: {
                 rotationDeg: modelRotation,
                 dzMil: PcbScene3dBuilder.#resolveComponentBodyVerticalOffset(
-                    componentBody
+                    componentBody,
+                    matchedComponent
                 )
             },
             projection: PcbScene3dBuilder.#resolveProjectionDiagnostics(
@@ -369,16 +437,65 @@ export class PcbScene3dBuilder {
      * Resolves the vertical offset that should remain after the viewer seats
      * raw model bounds on the board face.
      * @param {{ dzMil?: number, standoffHeightMil?: number | null }} componentBody Component-body placement metadata.
+     * @param {object | null} matchedComponent Matched owner component.
      * @returns {number}
      */
-    static #resolveComponentBodyVerticalOffset(componentBody) {
+    static #resolveComponentBodyVerticalOffset(
+        componentBody,
+        matchedComponent = null
+    ) {
         const standoffHeightMil = Number(componentBody?.standoffHeightMil)
         if (Number.isFinite(standoffHeightMil)) {
-            return standoffHeightMil < 0 ? standoffHeightMil : 0
+            return standoffHeightMil < 0 ||
+                PcbScene3dBuilder.#shouldPreservePositiveBodyStandoff(
+                    componentBody,
+                    matchedComponent
+                )
+                ? standoffHeightMil
+                : 0
         }
 
         const dzMil = Number(componentBody?.dzMil)
-        return Number.isFinite(dzMil) && dzMil < 0 ? dzMil : 0
+        return Number.isFinite(dzMil) &&
+            (dzMil < 0 ||
+                PcbScene3dBuilder.#shouldPreservePositiveBodyStandoff(
+                    componentBody,
+                    matchedComponent
+                ))
+            ? dzMil
+            : 0
+    }
+
+    /**
+     * Checks whether a positive shape-body standoff is part of an authored
+     * stack instead of a model-origin quirk that should be seated on the board.
+     * @param {object | null | undefined} componentBody Component-body row.
+     * @param {object | null} matchedComponent Matched owner component.
+     * @returns {boolean}
+     */
+    static #shouldPreservePositiveBodyStandoff(
+        componentBody,
+        matchedComponent
+    ) {
+        return (
+            !matchedComponent &&
+            PcbScene3dBuilder.#isShapeBasedComponentBody(componentBody)
+        )
+    }
+
+    /**
+     * Checks whether one body row came from shape-based 3D body metadata.
+     * @param {object | null | undefined} componentBody Component-body row.
+     * @returns {boolean}
+     */
+    static #isShapeBasedComponentBody(componentBody) {
+        return (
+            String(componentBody?.sourceStream || '').includes(
+                'ShapeBasedComponentBodies'
+            ) ||
+            Boolean(componentBody?.staticGeometry) ||
+            Boolean(componentBody?.modelTypeName)
+        )
     }
 
     /**

package/src/ui/PcbScene3dPlacementSideResolver.mjs

@@ -64,6 +64,62 @@ export class PcbScene3dPlacementSideResolver {
         return standoffSide || 'top'
     }
 
+    /**
+     * Resolves which board side one authored static shape body should mount on.
+     * Shape bodies carry explicit mechanical-layer intent, so that side wins
+     * over loose nearby-package identity unless the body was directly matched.
+     * @param {{ layer?: string, positionMil?: { x?: number, y?: number }, standoffHeightMil?: number | null, overallHeightMil?: number | null }} componentBody
+     * @param {{ layer?: string } | null} matchedComponent
+     * @param {{ layer?: string, pattern?: string, source?: string, modelPath?: string, x?: number, y?: number }[]} components
+     * @param {{ minX?: number, minY?: number, widthMil?: number, heightMil?: number } | null} board
+     * @returns {'top' | 'bottom'}
+     */
+    static resolveStaticBodyPlacementSide(
+        componentBody,
+        matchedComponent,
+        components = [],
+        board = null
+    ) {
+        const matchedSide =
+            PcbScene3dPlacementSideResolver.#resolveComponentLayerSide(
+                matchedComponent?.layer
+            )
+        if (matchedSide) {
+            return matchedSide
+        }
+
+        const standoffSide =
+            PcbScene3dPlacementSideResolver.#resolveStandoffSide(componentBody)
+        if (
+            standoffSide &&
+            PcbScene3dPlacementSideResolver.#isBodyAnchorInsideBoard(
+                componentBody,
+                board
+            )
+        ) {
+            return standoffSide
+        }
+
+        const mechanicalSide =
+            PcbScene3dPlacementSideResolver.#resolveMechanicalLayerSide(
+                componentBody?.layer
+            )
+        if (mechanicalSide) {
+            return mechanicalSide
+        }
+
+        const nearbySide =
+            PcbScene3dPlacementSideResolver.#resolveNearbyComponentSide(
+                componentBody,
+                components
+            )
+        if (nearbySide) {
+            return nearbySide
+        }
+
+        return standoffSide || 'top'
+    }
+
     /**
      * Resolves the grouping key for repeated component-body matching.
      * @param {{ modelId?: string, name?: string, identifier?: string }} componentBody

package/src/ui/PcbScene3dStaticBodyPlacementBuilder.mjs

@@ -11,12 +11,27 @@ export class PcbScene3dStaticBodyPlacementBuilder {
     static #UNMATCHED_BODY_OVERHANG_RATIO = 0.25
     static #UNMATCHED_BODY_MIN_OVERHANG_MIL = 150
     static #UNMATCHED_BODY_MAX_OVERHANG_MIL = 600
+    static #OWNER_AFFINITY_DISTANCE_MIL = 600
+    static #OWNER_EXACT_DISTANCE_MIL = 5
+    static #OWNER_EXACT_MAX_SPAN_MIL = 500
+    static #GENERIC_MECHANICAL_IDENTITY_TOKENS = new Set([
+        'can',
+        'cover',
+        'enclosure',
+        'frame',
+        'hardware',
+        'leg',
+        'mechanical',
+        'plate',
+        'shield'
+    ])
 
     /**
      * Builds static shape-body scene placements.
-     * @param {{ identifier?: string, name?: string, layer?: string, positionMil?: { x?: number, y?: number }, rotationDeg?: number, standoffHeightMil?: number | null, overallHeightMil?: number | null, staticGeometry?: object }[]} componentBodies Component bodies.
+     * @param {{ componentIndex?: number, identifier?: string, name?: string, layer?: string, positionMil?: { x?: number, y?: number }, rotationDeg?: number, standoffHeightMil?: number | null, overallHeightMil?: number | null, bodyOpacity?: number | string, staticGeometry?: object }[]} componentBodies Component bodies.
      * @param {({ designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null } | null)[]} bodyMatches Matched components.
      * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, source?: string, modelPath?: string }[]} components Components.
+     * @param {{ x: number, y: number, sizeTopX?: number, sizeTopY?: number, sizeMidX?: number, sizeMidY?: number, sizeBottomX?: number, sizeBottomY?: number }[]} pads Pads.
      * @param {{ centerX: number, centerY: number, minX?: number, minY?: number, widthMil?: number, heightMil?: number }} board Board.
      * @param {number} thicknessMil Board thickness.
      * @returns {{ designator: string, mountSide: string, rotationDeg: number, positionMil: { x: number, y: number, z: number }, bodyPositionMil: { x: number, y: number }, geometry: object }[]}
@@ -25,6 +40,7 @@ export class PcbScene3dStaticBodyPlacementBuilder {
         componentBodies,
         bodyMatches,
         components,
+        pads,
         board,
         thicknessMil
     ) {
@@ -41,9 +57,18 @@ export class PcbScene3dStaticBodyPlacementBuilder {
             .filter(Boolean)
     }
 
+    /**
+     * Checks whether one static geometry is already complete.
+     * @param {object | undefined} geometry Static geometry.
+     * @returns {boolean}
+     */
+    static #isCompleteGeometry(geometry) {
+        return Boolean(geometry && geometry.status === 'complete')
+    }
+
     /**
      * Builds one static shape-body scene placement.
-     * @param {{ identifier?: string, name?: string, layer?: string, positionMil?: { x?: number, y?: number }, rotationDeg?: number, standoffHeightMil?: number | null, overallHeightMil?: number | null, staticGeometry?: object }} componentBody Component body.
+     * @param {{ componentIndex?: number, embedded?: boolean, identifier?: string, name?: string, layer?: string, positionMil?: { x?: number, y?: number }, rotationDeg?: number, standoffHeightMil?: number | null, overallHeightMil?: number | null, bodyOpacity?: number | string, staticGeometry?: object }} componentBody Component body.
      * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null } | null} matchedComponent Matched component.
      * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, source?: string, modelPath?: string }[]} components Components.
      * @param {{ centerX: number, centerY: number, minX?: number, minY?: number, widthMil?: number, heightMil?: number }} board Board.
@@ -57,9 +82,26 @@ export class PcbScene3dStaticBodyPlacementBuilder {
         board,
         thicknessMil
     ) {
-        const geometry = componentBody?.staticGeometry
+        const geometry =
+            PcbScene3dStaticBodyPlacementBuilder.#normalizeStaticGeometry(
+                componentBody,
+                componentBody?.staticGeometry
+            )
 
-        if (!geometry || geometry.status !== 'complete') {
+        if (
+            !PcbScene3dStaticBodyPlacementBuilder.#isCompleteGeometry(geometry)
+        ) {
+            return null
+        }
+
+        if (
+            !matchedComponent &&
+            PcbScene3dStaticBodyPlacementBuilder.#shouldSuppressStaticBody(
+                componentBody,
+                geometry,
+                components
+            )
+        ) {
             return null
         }
 
@@ -73,12 +115,13 @@ export class PcbScene3dStaticBodyPlacementBuilder {
             return null
         }
 
-        const mountSide = PcbScene3dPlacementSideResolver.resolvePlacementSide(
-            componentBody,
-            matchedComponent,
-            components,
-            board
-        )
+        const mountSide =
+            PcbScene3dPlacementSideResolver.resolveStaticBodyPlacementSide(
+                componentBody,
+                matchedComponent,
+                components,
+                board
+            )
         const sourcePosition =
             PcbScene3dStaticBodyPlacementBuilder.#sourcePosition(componentBody)
         const heightMil =
@@ -119,10 +162,283 @@ export class PcbScene3dStaticBodyPlacementBuilder {
                 x: Number(componentBody.positionMil?.x || 0),
                 y: Number(componentBody.positionMil?.y || 0)
             },
+            ...PcbScene3dStaticBodyPlacementBuilder.#displayMetadata(
+                componentBody
+            ),
             geometry
         }
     }
 
+    /**
+     * Converts source-space polygon vertices into render-local geometry.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component body.
+     * @param {object | undefined} geometry Static geometry.
+     * @returns {object | undefined}
+     */
+    static #normalizeStaticGeometry(componentBody, geometry) {
+        if (
+            String(geometry?.kind || '').toLowerCase() !== 'extruded-polygon' ||
+            !Array.isArray(geometry?.verticesMil) ||
+            geometry.verticesMil.length < 3 ||
+            !PcbScene3dStaticBodyPlacementBuilder.#usesSourceCoordinateFrame(
+                componentBody,
+                geometry.verticesMil
+            )
+        ) {
+            return geometry
+        }
+
+        const center =
+            PcbScene3dStaticBodyPlacementBuilder.#polygonBoundsCenter(
+                geometry.verticesMil
+            )
+
+        return {
+            ...geometry,
+            verticesMil: geometry.verticesMil.map((vertex) => ({
+                x: PcbScene3dStaticBodyPlacementBuilder.#roundMil(
+                    Number(vertex?.x || 0) - center.x
+                ),
+                y: PcbScene3dStaticBodyPlacementBuilder.#roundMil(
+                    Number(vertex?.y || 0) - center.y
+                )
+            }))
+        }
+    }
+
+    /**
+     * Checks whether polygon vertices use board/source coordinates instead of
+     * small body-local coordinates.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component body.
+     * @param {{ x?: number, y?: number }[]} vertices Vertices.
+     * @returns {boolean}
+     */
+    static #usesSourceCoordinateFrame(componentBody, vertices) {
+        const center =
+            PcbScene3dStaticBodyPlacementBuilder.#polygonBoundsCenter(vertices)
+        const source =
+            PcbScene3dStaticBodyPlacementBuilder.#sourcePosition(componentBody)
+
+        return (
+            Math.max(
+                Math.abs(center.x),
+                Math.abs(center.y),
+                Math.abs(source.x),
+                Math.abs(source.y)
+            ) > 1000
+        )
+    }
+
+    /**
+     * Resolves the axis-aligned polygon bounds center.
+     * @param {{ x?: number, y?: number }[]} vertices Vertices.
+     * @returns {{ x: number, y: number }}
+     */
+    static #polygonBoundsCenter(vertices) {
+        const points = (Array.isArray(vertices) ? vertices : []).map(
+            (vertex) => ({
+                x: Number(vertex?.x || 0),
+                y: Number(vertex?.y || 0)
+            })
+        )
+        const xs = points.map((point) => point.x)
+        const ys = points.map((point) => point.y)
+
+        return {
+            x: (Math.min(...xs) + Math.max(...xs)) / 2,
+            y: (Math.min(...ys) + Math.max(...ys)) / 2
+        }
+    }
+
+    /**
+     * Resolves optional display metadata for static body rendering.
+     * @param {{ bodyColor?: object, bodyOpacity?: number | string }} componentBody Component body.
+     * @returns {{ bodyColor?: object, bodyOpacity?: number }}
+     */
+    static #displayMetadata(componentBody) {
+        const metadata = {}
+        if (
+            componentBody?.bodyColor &&
+            typeof componentBody.bodyColor === 'object'
+        ) {
+            metadata.bodyColor = componentBody.bodyColor
+        }
+
+        const opacity = Number(componentBody?.bodyOpacity)
+        if (Number.isFinite(opacity)) {
+            metadata.bodyOpacity = opacity
+        }
+
+        return metadata
+    }
+
+    /**
+     * Checks whether an unowned static body is likely a translucent mechanical
+     * overlay instead of a component package.
+     * @param {{ componentIndex?: number, embedded?: boolean, bodyOpacity?: number | string, identifier?: string, name?: string, positionMil?: { x?: number, y?: number } }} componentBody Component body.
+     * @param {object} geometry Static geometry.
+     * @param {{ componentIndex?: number, x?: number, y?: number, pattern?: string, source?: string, modelPath?: string, description?: string, parameters?: object, provenance?: object }[]} components Components.
+     * @returns {boolean}
+     */
+    static #shouldSuppressStaticBody(componentBody, geometry, components) {
+        return (
+            PcbScene3dStaticBodyPlacementBuilder.#isTranslucentBody(
+                componentBody
+            ) &&
+            !PcbScene3dStaticBodyPlacementBuilder.#hasLikelyComponentOwner(
+                componentBody,
+                geometry,
+                components
+            )
+        )
+    }
+
+    /**
+     * Checks whether a body was authored with visible partial transparency.
+     * @param {{ bodyOpacity?: number | string }} componentBody Component body.
+     * @returns {boolean}
+     */
+    static #isTranslucentBody(componentBody) {
+        const opacity = Number(componentBody?.bodyOpacity)
+
+        return Number.isFinite(opacity) && opacity >= 0 && opacity < 1
+    }
+
+    /**
+     * Checks whether an otherwise unmatched body still has a plausible owning
+     * component.
+     * @param {{ componentIndex?: number, embedded?: boolean, identifier?: string, name?: string, positionMil?: { x?: number, y?: number } }} componentBody Component body.
+     * @param {object} geometry Static geometry.
+     * @param {{ componentIndex?: number, x?: number, y?: number, pattern?: string, source?: string, modelPath?: string, description?: string, parameters?: object, provenance?: object }[]} components Components.
+     * @returns {boolean}
+     */
+    static #hasLikelyComponentOwner(componentBody, geometry, components) {
+        if (componentBody?.embedded) {
+            return true
+        }
+
+        const componentIndex = Number(componentBody?.componentIndex)
+        if (
+            Number.isInteger(componentIndex) &&
+            (Array.isArray(components) ? components : []).some(
+                (component) =>
+                    Number(component?.componentIndex) === componentIndex
+            )
+        ) {
+            return true
+        }
+
+        const maxSpanMil =
+            PcbScene3dStaticBodyPlacementBuilder.#geometryMaxSpan(geometry)
+        const genericMechanical =
+            PcbScene3dStaticBodyPlacementBuilder.#hasGenericMechanicalIdentity(
+                componentBody
+            )
+
+        return (Array.isArray(components) ? components : []).some(
+            (component) => {
+                const distance =
+                    PcbScene3dStaticBodyPlacementBuilder.#distanceBetweenBodyAndComponent(
+                        componentBody,
+                        component
+                    )
+                const affinityScore =
+                    PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
+                        componentBody,
+                        component
+                    )
+
+                return (
+                    (!genericMechanical &&
+                        affinityScore > 0 &&
+                        distance <=
+                            PcbScene3dStaticBodyPlacementBuilder
+                                .#OWNER_AFFINITY_DISTANCE_MIL) ||
+                    (!genericMechanical &&
+                        distance <=
+                            PcbScene3dStaticBodyPlacementBuilder
+                                .#OWNER_EXACT_DISTANCE_MIL &&
+                        maxSpanMil <=
+                            PcbScene3dStaticBodyPlacementBuilder
+                                .#OWNER_EXACT_MAX_SPAN_MIL)
+                )
+            }
+        )
+    }
+
+    /**
+     * Checks for generic mechanical labels that are too weak to prove package
+     * ownership for translucent static bodies.
+     * @param {{ identifier?: string, name?: string }} componentBody Component body.
+     * @returns {boolean}
+     */
+    static #hasGenericMechanicalIdentity(componentBody) {
+        return PcbScene3dStaticBodyPlacementBuilder.#identityTokens(
+            componentBody
+        ).some((token) =>
+            PcbScene3dStaticBodyPlacementBuilder.#GENERIC_MECHANICAL_IDENTITY_TOKENS.has(
+                token
+            )
+        )
+    }
+
+    /**
+     * Collects normalized identity tokens from one body row.
+     * @param {{ identifier?: string, name?: string }} componentBody Component body.
+     * @returns {string[]}
+     */
+    static #identityTokens(componentBody) {
+        return [componentBody?.identifier, componentBody?.name]
+            .join(' ')
+            .toLowerCase()
+            .split(/[^a-z0-9]+/g)
+            .flatMap((fragment) => fragment.match(/[a-z]+|\d+/g) || [])
+            .filter(Boolean)
+    }
+
+    /**
+     * Resolves the largest horizontal span of a static body.
+     * @param {object} geometry Static geometry.
+     * @returns {number}
+     */
+    static #geometryMaxSpan(geometry) {
+        if (
+            Array.isArray(geometry?.verticesMil) &&
+            geometry.verticesMil.length
+        ) {
+            const points = geometry.verticesMil.map((vertex) => ({
+                x: Number(vertex?.x || 0),
+                y: Number(vertex?.y || 0)
+            }))
+            const xs = points.map((point) => point.x)
+            const ys = points.map((point) => point.y)
+
+            return Math.max(
+                Math.max(...xs) - Math.min(...xs),
+                Math.max(...ys) - Math.min(...ys)
+            )
+        }
+
+        const radius = Number(geometry?.radiusMil)
+
+        return Number.isFinite(radius) && radius > 0 ? radius * 2 : 0
+    }
+
+    /**
+     * Returns the euclidean distance between body and component anchors.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component body.
+     * @param {{ x?: number, y?: number }} component Component.
+     * @returns {number}
+     */
+    static #distanceBetweenBodyAndComponent(componentBody, component) {
+        return Math.hypot(
+            Number(component?.x || 0) -
+                Number(componentBody?.positionMil?.x || 0),
+            Number(component?.y || 0) -
+                Number(componentBody?.positionMil?.y || 0)
+        )
+    }
+
     /**
      * Returns the native body anchor.
      * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component body.