altium-toolkit 1.1.35 → 1.1.36

package/src/ui/PcbScene3dStaticBodyPlacementBuilder.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { PcbScene3dPlacementSideResolver } from './PcbScene3dPlacementSideResolver.mjs'
+import { PcbScene3dStaticBodyOwnerPromotion } from './PcbScene3dStaticBodyOwnerPromotion.mjs'
 import { PcbScene3dStaticBodyRecovery } from './PcbScene3dStaticBodyRecovery.mjs'
 import { PcbScene3dStaticBodySelectionKeyBuilder } from './PcbScene3dStaticBodySelectionKeyBuilder.mjs'
 
@@ -21,6 +22,7 @@ export class PcbScene3dStaticBodyPlacementBuilder {
     static #SOURCE_COORDINATE_MIRROR_MIN_OFFSET_MIL = 20
     static #GENERIC_MECHANICAL_IDENTITY_TOKENS = new Set([
         'can',
+        'clip',
         'cover',
         'enclosure',
         'frame',
@@ -66,6 +68,12 @@ export class PcbScene3dStaticBodyPlacementBuilder {
             )
             .filter(Boolean)
 
+        PcbScene3dStaticBodyOwnerPromotion.promote(
+            placementRows,
+            components,
+            board
+        )
+
         return PcbScene3dStaticBodySelectionKeyBuilder.assign(placementRows)
     }
 
@@ -183,6 +191,12 @@ export class PcbScene3dStaticBodyPlacementBuilder {
             Number(thicknessMil || 0) / 2 +
             (Number.isFinite(standoffMil) ? standoffMil : 0) +
             heightMil / 2
+        const renderGeometry =
+            PcbScene3dStaticBodyPlacementBuilder.#placementGeometry(
+                geometry,
+                staticGeometry,
+                mountSide
+            )
 
         return {
             designator:
@@ -194,11 +208,21 @@ export class PcbScene3dStaticBodyPlacementBuilder {
                 PcbScene3dStaticBodyPlacementBuilder.#sourceIdentityKey(
                     componentBody
                 ),
-            mountSide,
-            rotationDeg: PcbScene3dStaticBodyPlacementBuilder.#normalizeAngle(
-                Number(componentBody.rotationDeg || 0) +
-                    Number(matchedComponent?.rotation || 0)
+            sourceCoordinateFrame: Boolean(
+                staticGeometry.sourceCoordinateFrame
             ),
+            mountSideLocked:
+                PcbScene3dStaticBodyPlacementBuilder.#hasExplicitMountSide(
+                    componentBody,
+                    matchedComponent
+                ),
+            mountSide,
+            rotationDeg:
+                PcbScene3dStaticBodyPlacementBuilder.#placementRotationDeg(
+                    componentBody,
+                    matchedComponent,
+                    staticGeometry
+                ),
             positionMil: {
                 x: PcbScene3dStaticBodyPlacementBuilder.#roundMil(
                     Number(sourcePosition.x || 0) - Number(board.centerX || 0)
@@ -217,7 +241,107 @@ export class PcbScene3dStaticBodyPlacementBuilder {
             ...PcbScene3dStaticBodyPlacementBuilder.#displayMetadata(
                 componentBody
             ),
-            geometry
+            geometry: renderGeometry
+        }
+    }
+
+    /**
+     * Checks whether one body carries explicit top/bottom side evidence.
+     * @param {{ componentIndex?: number | string, layer?: string, standoffHeightMil?: number | string | null }} componentBody Component body.
+     * @param {{ layer?: string } | null} matchedComponent Matched owner component.
+     * @returns {boolean}
+     */
+    static #hasExplicitMountSide(componentBody, matchedComponent) {
+        if (
+            matchedComponent &&
+            Number.isInteger(Number(componentBody?.componentIndex))
+        ) {
+            return true
+        }
+
+        const layer = String(componentBody?.layer || '').trim()
+        if (!layer) {
+            const standoffMil = Number(componentBody?.standoffHeightMil)
+            return Number.isFinite(standoffMil) && standoffMil < 0
+        }
+
+        if (
+            !PcbScene3dStaticBodyPlacementBuilder.#isAuthoredMechanicalBody(
+                componentBody
+            )
+        ) {
+            return false
+        }
+
+        if (/(^|[^a-z])(top|bottom)([^a-z]|$)/i.test(layer)) {
+            return true
+        }
+
+        return /^MECHANICAL\s*\d+$/i.test(layer)
+    }
+
+    /**
+     * Checks whether one body identity looks like authored board mechanics.
+     * @param {{ identifier?: string, name?: string, modelTypeName?: string }} componentBody Component body.
+     * @returns {boolean}
+     */
+    static #isAuthoredMechanicalBody(componentBody) {
+        return PcbScene3dStaticBodyPlacementBuilder.#identityTokens(
+            componentBody
+        ).some((token) =>
+            PcbScene3dStaticBodyPlacementBuilder.#GENERIC_MECHANICAL_IDENTITY_TOKENS.has(
+                token
+            )
+        )
+    }
+
+    /**
+     * Resolves the rendered rotation for one static shape body.
+     * @param {{ rotationDeg?: number }} componentBody Component body.
+     * @param {{ rotation?: number } | null} matchedComponent Matched owner component.
+     * @param {{ sourceCoordinateFrame?: boolean }} normalizedStaticGeometry Normalized static geometry context.
+     * @returns {number}
+     */
+    static #placementRotationDeg(
+        componentBody,
+        matchedComponent,
+        normalizedStaticGeometry
+    ) {
+        const ownerRotation = normalizedStaticGeometry?.sourceCoordinateFrame
+            ? 0
+            : Number(matchedComponent?.rotation || 0)
+
+        return PcbScene3dStaticBodyPlacementBuilder.#normalizeAngle(
+            Number(componentBody.rotationDeg || 0) + ownerRotation
+        )
+    }
+
+    /**
+     * Converts normalized static geometry into the renderer mount-local frame.
+     * @param {object} geometry Normalized render geometry.
+     * @param {{ sourceCoordinateFrame?: boolean }} normalizedStaticGeometry Normalized static geometry context.
+     * @param {string} mountSide Resolved mount side.
+     * @returns {object}
+     */
+    static #placementGeometry(geometry, normalizedStaticGeometry, mountSide) {
+        if (
+            !normalizedStaticGeometry?.sourceCoordinateFrame ||
+            String(mountSide || 'top').toLowerCase() !== 'bottom' ||
+            !Array.isArray(geometry?.verticesMil)
+        ) {
+            return geometry
+        }
+
+        return {
+            ...geometry,
+            verticesMil: geometry.verticesMil.map((vertex) => ({
+                x: PcbScene3dStaticBodyPlacementBuilder.#roundMil(
+                    Number(vertex?.x || 0)
+                ),
+                y: PcbScene3dStaticBodyPlacementBuilder.#roundMil(
+                    -Number(vertex?.y || 0)
+                )
+            }))
         }
     }
 
@@ -226,19 +350,24 @@ export class PcbScene3dStaticBodyPlacementBuilder {
      * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component body.
      * @param {object | undefined} geometry Static geometry.
      * @param {{ x?: number, y?: number } | null} matchedComponent Matched owner component.
-     * @returns {{ geometry: object | undefined, placementCenterMil?: { x: number, y: number } }}
+     * @returns {{ geometry: object | undefined, placementCenterMil?: { x: number, y: number }, sourceCoordinateFrame: boolean }}
      */
     static #normalizeStaticGeometry(componentBody, geometry, matchedComponent) {
         if (
             String(geometry?.kind || '').toLowerCase() !== 'extruded-polygon' ||
             !Array.isArray(geometry?.verticesMil) ||
-            geometry.verticesMil.length < 3 ||
+            geometry.verticesMil.length < 3
+        ) {
+            return { geometry, sourceCoordinateFrame: false }
+        }
+
+        if (
             !PcbScene3dStaticBodyPlacementBuilder.#usesSourceCoordinateFrame(
                 componentBody,
                 geometry.verticesMil
             )
         ) {
-            return { geometry }
+            return { geometry, sourceCoordinateFrame: false }
         }
 
         const center =
@@ -255,6 +384,7 @@ export class PcbScene3dStaticBodyPlacementBuilder {
 
         return {
             placementCenterMil: placementCenter,
+            sourceCoordinateFrame: true,
             geometry: {
                 ...geometry,
                 verticesMil: geometry.verticesMil.map((vertex) => {

package/src/ui/PcbScene3dStaticBodyPrototypeRecovery.mjs

@@ -0,0 +1,445 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Recovers missing anonymous static-body polygons from complete same-model rows.
+ */
+export class PcbScene3dStaticBodyPrototypeRecovery {
+    /**
+     * Recovers repeated anonymous body rows that omit their vertex payload.
+     * @param {object[] | undefined} componentBodies Component bodies.
+     * @returns {object[]}
+     */
+    static recover(componentBodies) {
+        const bodies = Array.isArray(componentBodies) ? componentBodies : []
+        const prototypes =
+            PcbScene3dStaticBodyPrototypeRecovery.#prototypeMap(bodies)
+
+        if (!prototypes.size) {
+            return bodies
+        }
+
+        return bodies.map((componentBody) =>
+            PcbScene3dStaticBodyPrototypeRecovery.#recoverBody(
+                componentBody,
+                prototypes
+            )
+        )
+    }
+
+    /**
+     * Builds reusable complete-geometry prototypes by exact model identity.
+     * @param {object[]} componentBodies Component bodies.
+     * @returns {Map<string, object[]>}
+     */
+    static #prototypeMap(componentBodies) {
+        const prototypes = new Map()
+
+        componentBodies
+            .filter((componentBody) =>
+                PcbScene3dStaticBodyPrototypeRecovery.#isPrototype(
+                    componentBody
+                )
+            )
+            .forEach((componentBody) => {
+                const key =
+                    PcbScene3dStaticBodyPrototypeRecovery.#bodyFamilyKey(
+                        componentBody
+                    )
+                if (!key) {
+                    return
+                }
+
+                if (!prototypes.has(key)) {
+                    prototypes.set(key, [])
+                }
+                prototypes.get(key)?.push(componentBody)
+            })
+
+        return prototypes
+    }
+
+    /**
+     * Recovers one missing body from the closest compatible prototype.
+     * @param {object} componentBody Target body.
+     * @param {Map<string, object[]>} prototypes Complete prototype rows.
+     * @returns {object}
+     */
+    static #recoverBody(componentBody, prototypes) {
+        if (
+            !PcbScene3dStaticBodyPrototypeRecovery.#isRecoverableTarget(
+                componentBody
+            )
+        ) {
+            return componentBody
+        }
+
+        const key =
+            PcbScene3dStaticBodyPrototypeRecovery.#bodyFamilyKey(componentBody)
+        const prototype =
+            PcbScene3dStaticBodyPrototypeRecovery.#nearestPrototype(
+                componentBody,
+                prototypes.get(key)
+            )
+
+        return prototype
+            ? PcbScene3dStaticBodyPrototypeRecovery.#withPrototypeGeometry(
+                  componentBody,
+                  prototype
+              )
+            : componentBody
+    }
+
+    /**
+     * Checks whether a row can provide reusable static geometry.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {boolean}
+     */
+    static #isPrototype(componentBody) {
+        return (
+            PcbScene3dStaticBodyPrototypeRecovery.#isAnonymous(componentBody) &&
+            PcbScene3dStaticBodyPrototypeRecovery.#isCompleteExtrudedPolygon(
+                componentBody
+            ) &&
+            Boolean(
+                PcbScene3dStaticBodyPrototypeRecovery.#bodyFamilyKey(
+                    componentBody
+                )
+            )
+        )
+    }
+
+    /**
+     * Checks whether a row is missing renderable static polygon vertices.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {boolean}
+     */
+    static #isRecoverableTarget(componentBody) {
+        return (
+            PcbScene3dStaticBodyPrototypeRecovery.#isAnonymous(componentBody) &&
+            PcbScene3dStaticBodyPrototypeRecovery.#isExtrudedPolygonBody(
+                componentBody
+            ) &&
+            !PcbScene3dStaticBodyPrototypeRecovery.#isCompleteExtrudedPolygon(
+                componentBody
+            ) &&
+            PcbScene3dStaticBodyPrototypeRecovery.#hasRecoverablePosition(
+                componentBody
+            ) &&
+            PcbScene3dStaticBodyPrototypeRecovery.#heightMil(componentBody) > 0
+        )
+    }
+
+    /**
+     * Checks whether the body row has no authored identity text.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {boolean}
+     */
+    static #isAnonymous(componentBody) {
+        return ![componentBody?.identifier, componentBody?.name]
+            .map((value) => String(value || '').trim())
+            .some(Boolean)
+    }
+
+    /**
+     * Checks whether a body row describes an extruded polygon model.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {boolean}
+     */
+    static #isExtrudedPolygonBody(componentBody) {
+        return (
+            PcbScene3dStaticBodyPrototypeRecovery.#geometryKind(
+                componentBody
+            ) === 'extruded-polygon'
+        )
+    }
+
+    /**
+     * Checks whether a row already has complete extruded polygon vertices.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {boolean}
+     */
+    static #isCompleteExtrudedPolygon(componentBody) {
+        const geometry = componentBody?.staticGeometry
+
+        return (
+            PcbScene3dStaticBodyPrototypeRecovery.#isExtrudedPolygonBody(
+                componentBody
+            ) &&
+            String(geometry?.status || '').toLowerCase() === 'complete' &&
+            Array.isArray(geometry?.verticesMil) &&
+            geometry.verticesMil.length >= 3
+        )
+    }
+
+    /**
+     * Builds the exact model-family key used for prototype reuse.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {string}
+     */
+    static #bodyFamilyKey(componentBody) {
+        const identity = [
+            componentBody?.modelId,
+            componentBody?.checksum,
+            PcbScene3dStaticBodyPrototypeRecovery.#geometryKind(componentBody),
+            PcbScene3dStaticBodyPrototypeRecovery.#numberKey(
+                PcbScene3dStaticBodyPrototypeRecovery.#heightMil(componentBody)
+            ),
+            PcbScene3dStaticBodyPrototypeRecovery.#numberKey(
+                PcbScene3dStaticBodyPrototypeRecovery.#standoffMil(
+                    componentBody
+                )
+            )
+        ]
+            .map((value) =>
+                String(value ?? '')
+                    .trim()
+                    .toLowerCase()
+            )
+            .filter(Boolean)
+
+        return identity.length >= 4 ? identity.join('|') : ''
+    }
+
+    /**
+     * Chooses the closest layer-compatible prototype for one target row.
+     * @param {object} componentBody Target body.
+     * @param {object[] | undefined} candidates Candidate prototypes.
+     * @returns {object | null}
+     */
+    static #nearestPrototype(componentBody, candidates) {
+        const normalizedCandidates = Array.isArray(candidates) ? candidates : []
+
+        return (
+            normalizedCandidates
+                .filter((candidate) =>
+                    PcbScene3dStaticBodyPrototypeRecovery.#compatibleLayers(
+                        componentBody,
+                        candidate
+                    )
+                )
+                .map((candidate) => ({
+                    candidate,
+                    distance:
+                        PcbScene3dStaticBodyPrototypeRecovery.#distanceBetweenBodies(
+                            componentBody,
+                            candidate
+                        )
+                }))
+                .sort((left, right) => left.distance - right.distance)[0]
+                ?.candidate || null
+        )
+    }
+
+    /**
+     * Returns a cloned target row with translated prototype vertices.
+     * @param {object} componentBody Target body.
+     * @param {object} prototype Complete prototype body.
+     * @returns {object}
+     */
+    static #withPrototypeGeometry(componentBody, prototype) {
+        const geometry = componentBody?.staticGeometry || {}
+        const prototypeGeometry = prototype?.staticGeometry || {}
+        const heightMil =
+            PcbScene3dStaticBodyPrototypeRecovery.#heightMil(componentBody) ||
+            PcbScene3dStaticBodyPrototypeRecovery.#heightMil(prototype)
+        const standoffHeightMil =
+            PcbScene3dStaticBodyPrototypeRecovery.#standoffMil(componentBody) ||
+            PcbScene3dStaticBodyPrototypeRecovery.#standoffMil(prototype)
+
+        return {
+            ...componentBody,
+            staticGeometry: {
+                ...prototypeGeometry,
+                ...geometry,
+                kind: 'extruded-polygon',
+                status: 'complete',
+                units: geometry.units || prototypeGeometry.units || 'mil',
+                minZMil: Number(
+                    geometry.minZMil ?? prototypeGeometry.minZMil ?? 0
+                ),
+                maxZMil: Number(
+                    geometry.maxZMil ??
+                        prototypeGeometry.maxZMil ??
+                        heightMil + standoffHeightMil
+                ),
+                heightMil,
+                standoffHeightMil,
+                verticesMil:
+                    PcbScene3dStaticBodyPrototypeRecovery.#prototypeVerticesForTarget(
+                        componentBody,
+                        prototype
+                    )
+            }
+        }
+    }
+
+    /**
+     * Translates prototype vertices into the target body's coordinate frame.
+     * @param {object} componentBody Target body.
+     * @param {object} prototype Complete prototype body.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #prototypeVerticesForTarget(componentBody, prototype) {
+        const vertices = Array.isArray(prototype?.staticGeometry?.verticesMil)
+            ? prototype.staticGeometry.verticesMil
+            : []
+
+        if (
+            !PcbScene3dStaticBodyPrototypeRecovery.#usesSourceCoordinateFrame(
+                prototype,
+                vertices
+            )
+        ) {
+            return vertices.map((vertex) => ({
+                x: Number(vertex?.x || 0),
+                y: Number(vertex?.y || 0)
+            }))
+        }
+
+        const prototypeSource =
+            PcbScene3dStaticBodyPrototypeRecovery.#sourcePosition(prototype)
+        const targetSource =
+            PcbScene3dStaticBodyPrototypeRecovery.#sourcePosition(componentBody)
+
+        return vertices.map((vertex) => ({
+            x: targetSource.x + Number(vertex?.x || 0) - prototypeSource.x,
+            y: targetSource.y + Number(vertex?.y || 0) - prototypeSource.y
+        }))
+    }
+
+    /**
+     * Checks whether explicit mechanical layer values are compatible.
+     * @param {object | undefined} left Left body.
+     * @param {object | undefined} right Right body.
+     * @returns {boolean}
+     */
+    static #compatibleLayers(left, right) {
+        const leftLayer = String(left?.layer || '')
+            .trim()
+            .toLowerCase()
+        const rightLayer = String(right?.layer || '')
+            .trim()
+            .toLowerCase()
+
+        return !leftLayer || !rightLayer || leftLayer === rightLayer
+    }
+
+    /**
+     * Resolves the lower-case geometry kind for a body row.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {string}
+     */
+    static #geometryKind(componentBody) {
+        return String(
+            componentBody?.staticGeometry?.kind ||
+                componentBody?.modelTypeName ||
+                ''
+        )
+            .trim()
+            .toLowerCase()
+    }
+
+    /**
+     * Resolves the body extrusion height.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {number}
+     */
+    static #heightMil(componentBody) {
+        const height = Number(
+            componentBody?.staticGeometry?.heightMil ??
+                componentBody?.overallHeightMil
+        )
+
+        return Number.isFinite(height) ? height : 0
+    }
+
+    /**
+     * Resolves the body standoff height.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {number}
+     */
+    static #standoffMil(componentBody) {
+        const standoff = Number(
+            componentBody?.staticGeometry?.standoffHeightMil ??
+                componentBody?.standoffHeightMil
+        )
+
+        return Number.isFinite(standoff) ? standoff : 0
+    }
+
+    /**
+     * Checks whether the body row has a finite source anchor.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {boolean}
+     */
+    static #hasRecoverablePosition(componentBody) {
+        const source =
+            PcbScene3dStaticBodyPrototypeRecovery.#sourcePosition(componentBody)
+
+        return Number.isFinite(source.x) && Number.isFinite(source.y)
+    }
+
+    /**
+     * Resolves a body source position.
+     * @param {object | undefined} componentBody Candidate body.
+     * @returns {{ x: number, y: number }}
+     */
+    static #sourcePosition(componentBody) {
+        return {
+            x: Number(componentBody?.positionMil?.x),
+            y: Number(componentBody?.positionMil?.y)
+        }
+    }
+
+    /**
+     * Measures the source-anchor distance between two body rows.
+     * @param {object} left Left body.
+     * @param {object} right Right body.
+     * @returns {number}
+     */
+    static #distanceBetweenBodies(left, right) {
+        const leftSource =
+            PcbScene3dStaticBodyPrototypeRecovery.#sourcePosition(left)
+        const rightSource =
+            PcbScene3dStaticBodyPrototypeRecovery.#sourcePosition(right)
+
+        return Math.hypot(
+            leftSource.x - rightSource.x,
+            leftSource.y - rightSource.y
+        )
+    }
+
+    /**
+     * Checks whether polygon vertices use board/source coordinates.
+     * @param {object} componentBody Component body.
+     * @param {{ x?: number, y?: number }[]} vertices Vertices.
+     * @returns {boolean}
+     */
+    static #usesSourceCoordinateFrame(componentBody, vertices) {
+        const source =
+            PcbScene3dStaticBodyPrototypeRecovery.#sourcePosition(componentBody)
+        const coordinates = (Array.isArray(vertices) ? vertices : []).flatMap(
+            (vertex) => [Number(vertex?.x || 0), Number(vertex?.y || 0)]
+        )
+
+        return (
+            Math.max(Math.abs(source.x), Math.abs(source.y), ...coordinates) >
+            1000
+        )
+    }
+
+    /**
+     * Converts a number into a stable key fragment.
+     * @param {number | string | undefined | null} value Candidate value.
+     * @returns {string}
+     */
+    static #numberKey(value) {
+        const number = Number(value)
+
+        return Number.isFinite(number)
+            ? String(Math.round(number * 10000) / 10000)
+            : ''
+    }
+}

package/src/ui/PcbScene3dStaticBodyRecovery.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { PcbScene3dStaticBodySymmetryRecovery } from './PcbScene3dStaticBodySymmetryRecovery.mjs'
+import { PcbScene3dStaticBodyPrototypeRecovery } from './PcbScene3dStaticBodyPrototypeRecovery.mjs'
 
 /**
  * Recovers renderable static-body geometry and display metadata.
@@ -38,8 +39,13 @@ export class PcbScene3dStaticBodyRecovery {
      */
     static recover(componentBodies, bodyMatches = []) {
         const bodies = Array.isArray(componentBodies) ? componentBodies : []
+        const prototypeRecoveredBodies =
+            PcbScene3dStaticBodyPrototypeRecovery.recover(bodies)
         const symmetricRecoveredBodies =
-            PcbScene3dStaticBodySymmetryRecovery.recover(bodies, bodyMatches)
+            PcbScene3dStaticBodySymmetryRecovery.recover(
+                prototypeRecoveredBodies,
+                bodyMatches
+            )
         const topRecoveredBodies = symmetricRecoveredBodies.map(
             (componentBody) =>
                 PcbScene3dStaticBodyRecovery.#recoverCoverTopGeometry(