altium-toolkit 1.1.26 → 1.1.31

package/src/ui/PcbScene3dBuilder.mjs

@@ -5,11 +5,17 @@
 import { PcbEdgeFacingGlyphNormalizer } from './PcbEdgeFacingGlyphNormalizer.mjs'
 import { PcbScene3dBoardOutlineRefiner } from './PcbScene3dBoardOutlineRefiner.mjs'
 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.
@@ -32,7 +38,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)
@@ -167,9 +175,19 @@ export class PcbScene3dBuilder {
             }
         }
 
-        return PcbScene3dBoardOutlineRefiner.refine(
-            sceneDescription,
-            documentModel
+        return AltiumScene3dAuthoredBodyAnchorAdapter.apply(
+            AltiumScene3dBottomPadRotationAdapter.apply(
+                AltiumScene3dComponentBodyAdapter.apply(
+                    AltiumScene3dExternalPlacementAdapter.apply(
+                        PcbScene3dBoardOutlineRefiner.refine(
+                            sceneDescription,
+                            sceneDocumentModel
+                        ),
+                        sceneDocumentModel
+                    ),
+                    sceneDocumentModel
+                )
+            )
         )
     }
 
@@ -189,10 +207,7 @@ export class PcbScene3dBuilder {
         thicknessMil,
         modelRegistry
     ) {
-        const mountSide =
-            String(component.layer || 'TOP').toUpperCase() === 'BOTTOM'
-                ? 'bottom'
-                : 'top'
+        const mountSide = PcbScene3dBuilder.#resolveMountSide(component)
         const padSpan = PcbScene3dBuilder.#resolvePadSpan(component, pads)
         const body = PcbScene3dPackages.resolve(component, padSpan)
         const halfBoardThickness = thicknessMil / 2
@@ -1424,33 +1439,66 @@ export class PcbScene3dBuilder {
     }
 
     /**
-     * Resolves a rough pad-span box around one component.
-     * @param {{ x: number, y: number }} component
+     * Resolves the owned or nearby pad-span box around one component.
+     * @param {{ x: number, y: number, componentIndex?: number, layer?: string }} component
      * @param {{ x: number, y: number, sizeTopX?: number, sizeTopY?: number, sizeMidX?: number, sizeMidY?: number, sizeBottomX?: number, sizeBottomY?: number }[]} pads
      * @returns {{ width: number, depth: number }}
      */
     static #resolvePadSpan(component, pads) {
+        const componentPads = PcbScene3dBuilder.#componentPads(component, pads)
         const nearbyPads = pads.filter((pad) =>
             PcbScene3dBuilder.#isPadNearComponent(component, pad)
         )
+        const spanPads = componentPads.length ? componentPads : nearbyPads
 
-        if (!nearbyPads.length) {
+        if (!spanPads.length) {
             return { width: 0, depth: 0 }
         }
 
-        const xs = []
-        const ys = []
+        const mountSide = PcbScene3dBuilder.#resolveMountSide(component)
+        return (
+            PcbScene3dPadLocalSpanResolver.resolve(
+                component,
+                spanPads,
+                mountSide
+            ) || { width: 0, depth: 0 }
+        )
+    }
 
-        for (const pad of nearbyPads) {
-            const size = PcbScene3dBuilder.#resolvePadSize(pad)
-            xs.push(pad.x - size.width / 2, pad.x + size.width / 2)
-            ys.push(pad.y - size.depth / 2, pad.y + size.depth / 2)
+    /**
+     * Resolves pads explicitly owned by one component, preferring pads on the
+     * mounted surface when paste-mask side metadata is available.
+     * @param {{ componentIndex?: number, layer?: string }} component PCB component.
+     * @param {object[]} pads PCB pads.
+     * @returns {object[]}
+     */
+    static #componentPads(component, pads) {
+        const componentIndex = Number(component?.componentIndex)
+        if (!Number.isFinite(componentIndex)) {
+            return []
         }
 
-        return {
-            width: Math.max(...xs) - Math.min(...xs),
-            depth: Math.max(...ys) - Math.min(...ys)
-        }
+        const ownedPads = pads.filter(
+            (pad) => Number(pad?.componentIndex) === componentIndex
+        )
+        const mountSide = PcbScene3dBuilder.#resolveMountSide(component)
+        const surfacePads = ownedPads.filter((pad) =>
+            PcbScene3dBuilder.#isSurfacePad(pad, mountSide)
+        )
+
+        return surfacePads.length ? surfacePads : ownedPads
+    }
+
+    /**
+     * Checks whether one pad belongs to the requested component surface.
+     * @param {object} pad PCB pad.
+     * @param {'top' | 'bottom'} mountSide Component mount side.
+     * @returns {boolean}
+     */
+    static #isSurfacePad(pad, mountSide) {
+        return mountSide === 'bottom'
+            ? Boolean(pad?.hasBottomPasteMaskOpening)
+            : Boolean(pad?.hasTopPasteMaskOpening)
     }
 
     /**
@@ -1467,19 +1515,14 @@ export class PcbScene3dBuilder {
     }
 
     /**
-     * Resolves one visible pad size.
-     * @param {{ sizeTopX?: number, sizeTopY?: number, sizeMidX?: number, sizeMidY?: number, sizeBottomX?: number, sizeBottomY?: number }} pad
-     * @returns {{ width: number, depth: number }}
+     * Resolves the PCB surface a component is mounted on.
+     * @param {{ layer?: string }} component PCB component.
+     * @returns {'top' | 'bottom'}
      */
-    static #resolvePadSize(pad) {
-        return {
-            width:
-                Number(pad.sizeTopX || pad.sizeMidX || pad.sizeBottomX || 24) ||
-                24,
-            depth:
-                Number(pad.sizeTopY || pad.sizeMidY || pad.sizeBottomY || 24) ||
-                24
-        }
+    static #resolveMountSide(component) {
+        return String(component?.layer || 'TOP').toUpperCase() === 'BOTTOM'
+            ? 'bottom'
+            : 'top'
     }
 
     /**

package/src/ui/PcbScene3dPadLocalSpanResolver.mjs

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Resolves pad bounds in component-local axes for 3D procedural bodies.
+ */
+export class PcbScene3dPadLocalSpanResolver {
+    /**
+     * Measures a set of pads after rotating their corners into the component's
+     * local coordinate frame.
+     * @param {{ x?: number, y?: number, rotation?: number }} component Source component.
+     * @param {object[]} pads Pads to measure.
+     * @param {'top' | 'bottom'} mountSide Component mount side.
+     * @returns {{ width: number, depth: number } | null}
+     */
+    static resolve(component, pads, mountSide = 'top') {
+        if (!Array.isArray(pads) || !pads.length) {
+            return null
+        }
+
+        const originX = Number(component?.x || 0)
+        const originY = Number(component?.y || 0)
+        const componentRadians =
+            (-Number(component?.rotation || 0) * Math.PI) / 180
+        const componentCos = Math.cos(componentRadians)
+        const componentSin = Math.sin(componentRadians)
+        const xs = []
+        const ys = []
+
+        for (const pad of pads) {
+            for (const point of PcbScene3dPadLocalSpanResolver.#padCorners(
+                pad,
+                mountSide
+            )) {
+                const relativeX = point.x - originX
+                const relativeY = point.y - originY
+                xs.push(relativeX * componentCos - relativeY * componentSin)
+                ys.push(relativeX * componentSin + relativeY * componentCos)
+            }
+        }
+
+        const width = PcbScene3dPadLocalSpanResolver.#roundMil(
+            Math.max(...xs) - Math.min(...xs)
+        )
+        const depth = PcbScene3dPadLocalSpanResolver.#roundMil(
+            Math.max(...ys) - Math.min(...ys)
+        )
+
+        return width > 0 && depth > 0 ? { width, depth } : null
+    }
+
+    /**
+     * Rounds tiny trigonometric floating-point noise while preserving mil detail.
+     * @param {number} value Raw mil value.
+     * @returns {number}
+     */
+    static #roundMil(value) {
+        return Math.round(Number(value || 0) * 1000000) / 1000000
+    }
+
+    /**
+     * Builds the visible world-space corners of one rectangular pad.
+     * @param {object} pad Source pad.
+     * @param {'top' | 'bottom'} mountSide Component mount side.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #padCorners(pad, mountSide) {
+        const size = PcbScene3dPadLocalSpanResolver.#padSize(pad, mountSide)
+        const halfWidth = size.width / 2
+        const halfDepth = size.depth / 2
+        const radians = (Number(pad?.rotation || 0) * Math.PI) / 180
+        const cos = Math.cos(radians)
+        const sin = Math.sin(radians)
+        const centerX = Number(pad?.x || 0)
+        const centerY = Number(pad?.y || 0)
+
+        return [
+            { x: -halfWidth, y: -halfDepth },
+            { x: halfWidth, y: -halfDepth },
+            { x: halfWidth, y: halfDepth },
+            { x: -halfWidth, y: halfDepth }
+        ].map((point) => ({
+            x: centerX + point.x * cos - point.y * sin,
+            y: centerY + point.x * sin + point.y * cos
+        }))
+    }
+
+    /**
+     * Resolves a pad's visible size on the component side.
+     * @param {object} pad Source pad.
+     * @param {'top' | 'bottom'} mountSide Component mount side.
+     * @returns {{ width: number, depth: number }}
+     */
+    static #padSize(pad, mountSide) {
+        const bottom = String(mountSide || '').toLowerCase() === 'bottom'
+        const width = bottom
+            ? pad?.sizeBottomX || pad?.sizeMidX || pad?.sizeTopX
+            : pad?.sizeTopX || pad?.sizeMidX || pad?.sizeBottomX
+        const depth = bottom
+            ? pad?.sizeBottomY || pad?.sizeMidY || pad?.sizeTopY
+            : pad?.sizeTopY || pad?.sizeMidY || pad?.sizeBottomY
+
+        return {
+            width: Number(width || 24) || 24,
+            depth: Number(depth || 24) || 24
+        }
+    }
+}