altium-toolkit 1.1.31 → 1.1.33

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
@@ -81,7 +137,7 @@ export class PcbScene3dPlacementSideResolver {
      * Scores how strongly one component record appears to belong to one body
      * record based on shared model/footprint tokens.
      * @param {{ name?: string, identifier?: string }} componentBody
-     * @param {{ pattern?: string, source?: string, modelPath?: string }} component
+     * @param {{ pattern?: string, source?: string, modelPath?: string, description?: string, parameters?: object, provenance?: object }} component
      * @returns {number}
      */
     static scoreBodyComponentAffinity(componentBody, component) {
@@ -94,7 +150,11 @@ export class PcbScene3dPlacementSideResolver {
             PcbScene3dPlacementSideResolver.#collectMeaningfulTokens([
                 component?.pattern,
                 component?.source,
-                component?.modelPath
+                component?.modelPath,
+                component?.description,
+                ...PcbScene3dPlacementSideResolver.#componentPackageMetadata(
+                    component
+                )
             ])
         let score = 0
 
@@ -107,6 +167,34 @@ export class PcbScene3dPlacementSideResolver {
         return score
     }
 
+    /**
+     * Resolves package-related component metadata that can identify generic
+     * embedded 3D bodies when pattern/source only name the electrical part.
+     * @param {{ parameters?: object, provenance?: object } | null | undefined} component Component record.
+     * @returns {string[]}
+     */
+    static #componentPackageMetadata(component) {
+        const parameters =
+            component?.parameters && typeof component.parameters === 'object'
+                ? component.parameters
+                : {}
+        const provenance =
+            component?.provenance && typeof component.provenance === 'object'
+                ? component.provenance
+                : {}
+
+        return [
+            parameters['Package / Case'],
+            parameters['Supplier Device Package'],
+            parameters['Part Description'],
+            parameters.Package,
+            provenance.footprintDescription,
+            provenance.sourceLibReference,
+            provenance.sourceFootprintLibrary,
+            provenance.sourceFootprintLibraryName
+        ].map((value) => String(value || ''))
+    }
+
     /**
      * Resolves side from the normalized component layer.
      * @param {string | undefined} layer

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.