altium-toolkit 1.1.30 → 1.1.32

package/src/ui/PcbScene3dBuilder.mjs

@@ -8,12 +8,14 @@ import { PcbScene3dDrillCutoutBuilder } from './PcbScene3dDrillCutoutBuilder.mjs
 import { AltiumScene3dExternalPlacementAdapter } from './AltiumScene3dExternalPlacementAdapter.mjs'
 import { AltiumScene3dBottomPadRotationAdapter } from './AltiumScene3dBottomPadRotationAdapter.mjs'
 import { AltiumScene3dComponentBodyAdapter } from './AltiumScene3dComponentBodyAdapter.mjs'
+import { AltiumScene3dAuthoredBodyAnchorAdapter } from './AltiumScene3dAuthoredBodyAnchorAdapter.mjs'
 import { PcbFootprintPrimitiveSelector } from './PcbFootprintPrimitiveSelector.mjs'
 import { PcbScene3dPadLocalSpanResolver } from './PcbScene3dPadLocalSpanResolver.mjs'
 import { PcbScene3dPackages } from './PcbScene3dPackages.mjs'
 import { PcbScene3dPlacementSideResolver } from './PcbScene3dPlacementSideResolver.mjs'
 import { PcbScene3dStaticBodyPlacementBuilder } from './PcbScene3dStaticBodyPlacementBuilder.mjs'
 import { PcbScene3dTextBoxLayoutResolver } from './PcbScene3dTextBoxLayoutResolver.mjs'
+import { PcbFootprintPadAxisNormalizer } from './PcbFootprintPadAxisNormalizer.mjs'
 
 /**
  * Builds deterministic 3D scene data from the normalized PCB model.
@@ -24,10 +26,16 @@ export class PcbScene3dBuilder {
     static #DENSE_OVERLAY_MIN_TRACK_COUNT = 250
     static #DENSE_OVERLAY_KNOCKOUT_COLOR = 0x2f6a2c
     static #PRECISE_BODY_MATCH_TOLERANCE_MIL = 20
+    static #EXACT_BODY_MISMATCH_TOLERANCE_MIL = 1
+    static #NEAR_PACKAGE_AFFINITY_DISTANCE_MIL = 100
     static #UNMATCHED_BODY_OVERHANG_RATIO = 0.25
     static #UNMATCHED_BODY_MIN_OVERHANG_MIL = 150
     static #UNMATCHED_BODY_MAX_OVERHANG_MIL = 600
     static #TRUETYPE_TEXT_WIDTH_RATIO = 0.55
+    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 =
+        /(?:^|[^a-z0-9])(?:[a-z0-9]*dfn|[a-z0-9]*qfn|bga|cap|capacitor|crystal|diode|ferrite|ind|inductor|lga|lqg[a-z0-9]*|lqw[a-z0-9]*|osc|qfp|res|resistor|sot|transistor|xtal)(?:$|[^a-z0-9])/i
 
     /**
      * Builds a scene description for host 3D renderers.
@@ -36,7 +44,9 @@ export class PcbScene3dBuilder {
      * @returns {{ board: { widthMil: number, heightMil: number, thicknessMil: number, minX: number, minY: number, centerX: number, centerY: number, segments: Array<Record<string, number | string>> }, boardAssemblyModel: { origin: string, name: string, format: string, file?: File | Blob | null, relativePath?: string } | null, components: { designator: string, mountSide: string, rotationDeg: number, positionMil: { x: number, y: number, z: number }, boardPositionMil: { x: number, y: number, z: number }, pattern: string, source: string, body: { family: string, sizeMil: { width: number, depth: number, height: number } }, externalModel: { name: string, relativePath: string, format: string } | null }[], externalPlacements: { designator: string, mountSide: string, rotationDeg: number, positionMil: { x: number, y: number, z: number }, bodyPositionMil: { x: number, y: number }, bodyRotationDeg: number, modelTransform: { rotationDeg: { x: number, y: number, z: number }, dzMil: number }, externalModel: { origin: string, name: string, format: string, payloadText?: string, sourceStream?: string, relativePath?: string } }[], staticBodyPlacements: { designator: string, mountSide: string, rotationDeg: number, positionMil: { x: number, y: number, z: number }, bodyPositionMil: { x: number, y: number }, geometry: object }[], detail: { pads: any[], tracks: any[], arcs: any[], fills: any[], vias: any[], polygons: any[], silkscreen: { top: { fills: any[], tracks: any[], arcs: any[], texts: any[], fillColor?: number, strokeColor?: number }, bottom: { fills: any[], tracks: any[], arcs: any[], texts: any[], fillColor?: number, strokeColor?: number } } } }}
      */
     static build(documentModel, options = {}) {
-        const pcb = documentModel?.pcb || {}
+        const sceneDocumentModel =
+            PcbFootprintPadAxisNormalizer.apply(documentModel)
+        const pcb = sceneDocumentModel?.pcb || {}
         const appearance3d = pcb.appearance3d || {}
         const boardOutline = pcb.boardOutline || {}
         const primitiveLayers = Array.isArray(pcb.primitiveLayers)
@@ -77,10 +87,16 @@ export class PcbScene3dBuilder {
                 : []
         }
         const componentBodyModels = componentBodies.map((componentBody) =>
-            PcbScene3dBuilder.#resolveComponentBodyModel(
+            PcbScene3dBuilder.#shouldSuppressLayerlessBodyPlaceholder(
                 componentBody,
-                modelRegistry
+                componentBodies,
+                board
             )
+                ? null
+                : PcbScene3dBuilder.#resolveComponentBodyModel(
+                      componentBody,
+                      modelRegistry
+                  )
         )
         const bodyMatches = PcbScene3dBuilder.#resolveComponentBodyMatches(
             componentBodies,
@@ -171,28 +187,30 @@ export class PcbScene3dBuilder {
             }
         }
 
-        return AltiumScene3dBottomPadRotationAdapter.apply(
-            AltiumScene3dComponentBodyAdapter.apply(
-                AltiumScene3dExternalPlacementAdapter.apply(
-                    PcbScene3dBoardOutlineRefiner.refine(
-                        sceneDescription,
-                        documentModel
+        return AltiumScene3dAuthoredBodyAnchorAdapter.apply(
+            AltiumScene3dBottomPadRotationAdapter.apply(
+                AltiumScene3dComponentBodyAdapter.apply(
+                    AltiumScene3dExternalPlacementAdapter.apply(
+                        PcbScene3dBoardOutlineRefiner.refine(
+                            sceneDescription,
+                            sceneDocumentModel
+                        ),
+                        sceneDocumentModel
                     ),
-                    documentModel
-                ),
-                documentModel
+                    sceneDocumentModel
+                )
             )
         )
     }
 
     /**
      * Builds one procedural component scene entry.
-     * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null, source?: string, modelPath?: string }} component
+     * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null, source?: string, description?: string, parameters?: Record<string, unknown>, modelPath?: string }} component
      * @param {{ x: number, y: number, sizeTopX?: number, sizeTopY?: number, sizeMidX?: number, sizeMidY?: number, sizeBottomX?: number, sizeBottomY?: number }[]} pads
      * @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, 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 }}
      */
     static #buildComponent(
         component,
@@ -227,6 +245,13 @@ export class PcbScene3dBuilder {
             },
             pattern: String(component.pattern || ''),
             source: String(component.source || ''),
+            description: String(component.description || ''),
+            parameters:
+                component.parameters &&
+                typeof component.parameters === 'object' &&
+                !Array.isArray(component.parameters)
+                    ? { ...component.parameters }
+                    : {},
             body,
             externalModel: modelRegistry
                 ? modelRegistry.resolveComponentModel(component)
@@ -269,6 +294,16 @@ export class PcbScene3dBuilder {
             return null
         }
 
+        if (
+            !matchedComponent &&
+            PcbScene3dBuilder.#shouldDropUnmatchedPackageBody(
+                componentBody,
+                components
+            )
+        ) {
+            return null
+        }
+
         if (
             !matchedComponent &&
             !PcbScene3dBuilder.#isBodyPositionNearBoard(componentBody, board)
@@ -534,6 +569,12 @@ export class PcbScene3dBuilder {
                         bodyIndex,
                         componentIndex,
                         affinityScore,
+                        nearPackageAffinityScore:
+                            PcbScene3dBuilder.#nearPackageAffinityScore(
+                                componentBody,
+                                affinityScore,
+                                distance
+                            ),
                         preciseOwnerScore:
                             precise && (sideCompatible || affinityScore > 0)
                                 ? 1
@@ -549,6 +590,8 @@ export class PcbScene3dBuilder {
         closeCandidates
             .sort(
                 (left, right) =>
+                    right.nearPackageAffinityScore -
+                        left.nearPackageAffinityScore ||
                     right.preciseOwnerScore - left.preciseOwnerScore ||
                     right.sideAffinityScore - left.sideAffinityScore ||
                     right.affinityScore - left.affinityScore ||
@@ -798,7 +841,11 @@ export class PcbScene3dBuilder {
         distanceMil
     ) {
         if (PcbScene3dBuilder.#isPreciseBodyComponentDistance(distanceMil)) {
-            return true
+            return !PcbScene3dBuilder.#isIncompatiblePackageBodyMatch(
+                componentBody,
+                component,
+                distanceMil
+            )
         }
 
         if (
@@ -819,6 +866,242 @@ export class PcbScene3dBuilder {
         return bodyCount > 0 && bodyCount <= candidateCount
     }
 
+    /**
+     * Scores short-range package metadata matches above no-affinity anchors.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @param {number} affinityScore Shared body/component identity score.
+     * @param {number} distanceMil Body/component anchor distance.
+     * @returns {number}
+     */
+    static #nearPackageAffinityScore(
+        componentBody,
+        affinityScore,
+        distanceMil
+    ) {
+        return PcbScene3dBuilder.#isComponentPackageBody(componentBody) &&
+            Number(affinityScore || 0) > 0 &&
+            Number(distanceMil || 0) <=
+                PcbScene3dBuilder.#NEAR_PACKAGE_AFFINITY_DISTANCE_MIL
+            ? 1
+            : 0
+    }
+
+    /**
+     * Checks whether an unmatched package-like body should be suppressed
+     * because it sits on an exact but incompatible component anchor.
+     * @param {{ name?: string, identifier?: string, positionMil?: { x?: number, y?: number } }} componentBody Component-body record.
+     * @param {{ x: number, y: number, pattern?: string, source?: string, modelPath?: string }[]} components PCB components.
+     * @returns {boolean}
+     */
+    static #shouldDropUnmatchedPackageBody(componentBody, components) {
+        if (
+            !PcbScene3dBuilder.#isComponentPackageBody(componentBody) ||
+            PcbScene3dBuilder.#isAuthoredBodyIdentity(componentBody)
+        ) {
+            return false
+        }
+
+        const exactComponents = (
+            Array.isArray(components) ? components : []
+        ).filter(
+            (component) =>
+                PcbScene3dBuilder.#distanceBetweenBodyAndComponent(
+                    componentBody,
+                    component
+                ) <= PcbScene3dBuilder.#EXACT_BODY_MISMATCH_TOLERANCE_MIL
+        )
+
+        return (
+            exactComponents.length > 0 &&
+            exactComponents.every(
+                (component) =>
+                    PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
+                        componentBody,
+                        component
+                    ) <= 0
+            )
+        )
+    }
+
+    /**
+     * Checks whether a precise body/component pair is a package-family mismatch.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @param {{ pattern?: string, source?: string, modelPath?: string }} component PCB component.
+     * @param {number} distanceMil Body/component anchor distance.
+     * @returns {boolean}
+     */
+    static #isIncompatiblePackageBodyMatch(
+        componentBody,
+        component,
+        distanceMil
+    ) {
+        return (
+            Number(distanceMil || 0) <=
+                PcbScene3dBuilder.#EXACT_BODY_MISMATCH_TOLERANCE_MIL &&
+            PcbScene3dBuilder.#isComponentPackageBody(componentBody) &&
+            !PcbScene3dBuilder.#isAuthoredBodyIdentity(componentBody) &&
+            PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
+                componentBody,
+                component
+            ) <= 0
+        )
+    }
+
+    /**
+     * Checks whether a component body names a package model rather than an
+     * authored board mechanical.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @returns {boolean}
+     */
+    static #isComponentPackageBody(componentBody) {
+        return PcbScene3dBuilder.#COMPONENT_PACKAGE_BODY_PATTERN.test(
+            PcbScene3dBuilder.#componentBodyIdentityText(componentBody)
+        )
+    }
+
+    /**
+     * Checks whether a component body identity describes an authored hardware
+     * or connector anchor that can legitimately sit away from a footprint
+     * center.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @returns {boolean}
+     */
+    static #isAuthoredBodyIdentity(componentBody) {
+        return PcbScene3dBuilder.#AUTHORED_BODY_IDENTITY_PATTERN.test(
+            PcbScene3dBuilder.#componentBodyIdentityText(componentBody)
+        )
+    }
+
+    /**
+     * Checks whether a layerless component body is a footprint-library
+     * placeholder rather than a board-side placement.
+     * @param {{ layer?: string, name?: string, identifier?: string, modelId?: string, checksum?: number | null, positionMil?: { x?: number, y?: number } }} componentBody Component body record.
+     * @param {object[]} componentBodies All component body records.
+     * @param {{ minX: number, minY: number, widthMil: number, heightMil: number }} board Board envelope.
+     * @returns {boolean}
+     */
+    static #shouldSuppressLayerlessBodyPlaceholder(
+        componentBody,
+        componentBodies,
+        board
+    ) {
+        if (
+            !PcbScene3dBuilder.#isLayerlessComponentBody(componentBody) ||
+            PcbScene3dBuilder.#isAuthoredBodyIdentity(componentBody)
+        ) {
+            return false
+        }
+
+        return (
+            !PcbScene3dBuilder.#isBodyPositionNearBoard(componentBody, board) ||
+            PcbScene3dBuilder.#hasLayeredEquivalentPackageBody(
+                componentBody,
+                componentBodies
+            )
+        )
+    }
+
+    /**
+     * Checks whether a body lacks an authored mechanical layer.
+     * @param {{ layer?: string }} componentBody Component body record.
+     * @returns {boolean}
+     */
+    static #isLayerlessComponentBody(componentBody) {
+        return String(componentBody?.layer || '').trim() === ''
+    }
+
+    /**
+     * Checks whether a layerless body duplicates a real board-side body.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Candidate layerless body.
+     * @param {object[]} componentBodies All component body records.
+     * @returns {boolean}
+     */
+    static #hasLayeredEquivalentPackageBody(componentBody, componentBodies) {
+        return (Array.isArray(componentBodies) ? componentBodies : []).some(
+            (candidate) =>
+                candidate !== componentBody &&
+                !PcbScene3dBuilder.#isLayerlessComponentBody(candidate) &&
+                PcbScene3dBuilder.#componentBodiesShareModelIdentity(
+                    componentBody,
+                    candidate
+                ) &&
+                PcbScene3dBuilder.#distanceBetweenBodies(
+                    componentBody,
+                    candidate
+                ) <= PcbScene3dBuilder.#EXACT_BODY_MISMATCH_TOLERANCE_MIL
+        )
+    }
+
+    /**
+     * Checks whether two component bodies refer to the same external package.
+     * @param {{ name?: string, identifier?: string, modelId?: string, checksum?: number | null }} left First body.
+     * @param {{ name?: string, identifier?: string, modelId?: string, checksum?: number | null }} right Second body.
+     * @returns {boolean}
+     */
+    static #componentBodiesShareModelIdentity(left, right) {
+        const leftModelId = PcbScene3dBuilder.#normalizeIdentityToken(
+            left?.modelId
+        )
+        const rightModelId = PcbScene3dBuilder.#normalizeIdentityToken(
+            right?.modelId
+        )
+        if (leftModelId && rightModelId && leftModelId === rightModelId) {
+            return true
+        }
+
+        const leftChecksum = Number(left?.checksum)
+        const rightChecksum = Number(right?.checksum)
+        if (
+            Number.isFinite(leftChecksum) &&
+            Number.isFinite(rightChecksum) &&
+            leftChecksum === rightChecksum
+        ) {
+            return true
+        }
+
+        const leftName = PcbScene3dBuilder.#normalizeBodyNameToken(left)
+        const rightName = PcbScene3dBuilder.#normalizeBodyNameToken(right)
+
+        return Boolean(leftName && rightName && leftName === rightName)
+    }
+
+    /**
+     * Normalizes a body model name or identifier for duplicate detection.
+     * @param {{ name?: string, identifier?: string }} componentBody Component body.
+     * @returns {string}
+     */
+    static #normalizeBodyNameToken(componentBody) {
+        return PcbScene3dBuilder.#normalizeIdentityToken(
+            componentBody?.name || componentBody?.identifier
+        ).replace(/\.[a-z0-9]+$/i, '')
+    }
+
+    /**
+     * Normalizes an identity token for case-insensitive comparisons.
+     * @param {unknown} value Raw token.
+     * @returns {string}
+     */
+    static #normalizeIdentityToken(value) {
+        return String(value || '')
+            .trim()
+            .toLowerCase()
+    }
+
+    /**
+     * Builds searchable identity text for one component body.
+     * @param {{ name?: string, identifier?: string, modelId?: string }} componentBody Component-body record.
+     * @returns {string}
+     */
+    static #componentBodyIdentityText(componentBody) {
+        return [
+            componentBody?.identifier,
+            componentBody?.name,
+            componentBody?.modelId
+        ]
+            .map((value) => String(value || ''))
+            .join(' ')
+    }
+
     /**
      * Pairs one unresolved repeated body group with a repeated component group
      * by preserving the dominant ordering axis and choosing the pairing that
@@ -1535,6 +1818,21 @@ export class PcbScene3dBuilder {
         )
     }
 
+    /**
+     * Returns the euclidean distance between two component body anchors.
+     * @param {{ positionMil?: { x?: number, y?: number } }} left First body.
+     * @param {{ positionMil?: { x?: number, y?: number } }} right Second body.
+     * @returns {number}
+     */
+    static #distanceBetweenBodies(left, right) {
+        return Math.hypot(
+            Number(left?.positionMil?.x || 0) -
+                Number(right?.positionMil?.x || 0),
+            Number(left?.positionMil?.y || 0) -
+                Number(right?.positionMil?.y || 0)
+        )
+    }
+
     /**
      * Returns true when one unresolved body anchor still lies close enough to
      * the board envelope to be renderable without a component match.

package/src/ui/PcbScene3dPlacementSideResolver.mjs

@@ -81,7 +81,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 +94,11 @@ export class PcbScene3dPlacementSideResolver {
             PcbScene3dPlacementSideResolver.#collectMeaningfulTokens([
                 component?.pattern,
                 component?.source,
-                component?.modelPath
+                component?.modelPath,
+                component?.description,
+                ...PcbScene3dPlacementSideResolver.#componentPackageMetadata(
+                    component
+                )
             ])
         let score = 0
 
@@ -107,6 +111,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