altium-toolkit 1.0.7 → 1.0.9

package/src/ui/PcbInteractionLayerModel.mjs

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbInteractionIndex } from './PcbInteractionIndex.mjs'
+
+const VIRTUAL_LAYER_DEFINITIONS = [
+    { key: 'tracks', label: 'Tracks' },
+    { key: 'vias', label: 'Vias' },
+    { key: 'pads', label: 'Pads' },
+    { key: 'holes', label: 'Holes' },
+    { key: 'zones', label: 'Zones' },
+    { key: 'footprint-text', label: 'Footprint text' }
+]
+
+/**
+ * Builds a PCB layer summary with physical layers and virtual controls.
+ */
+export class PcbInteractionLayerModel {
+    /**
+     * Resolves physical and virtual interaction layers.
+     * @param {object} documentModel Toolkit document model.
+     * @returns {{ physicalLayers: object[], virtualLayers: object[] }}
+     */
+    static resolve(documentModel) {
+        const pcb = documentModel?.pcb || {}
+        const physicalLayers = PcbInteractionLayerModel.#physicalLayers(pcb)
+        const items = PcbInteractionIndex.build(documentModel)
+        const layersByObject = PcbInteractionLayerModel.#layersByObject(items)
+
+        return {
+            physicalLayers,
+            virtualLayers: VIRTUAL_LAYER_DEFINITIONS.map((definition) => ({
+                ...definition,
+                physicalLayerKeys: Array.from(
+                    layersByObject.get(definition.key) || []
+                )
+            }))
+        }
+    }
+
+    /**
+     * Resolves physical layer rows from board and primitive layer metadata.
+     * @param {object} pcb PCB model.
+     * @returns {object[]}
+     */
+    static #physicalLayers(pcb) {
+        const seen = new Set()
+        const layers = []
+        const sources = [
+            ...(Array.isArray(pcb?.layers) ? pcb.layers : []),
+            ...(Array.isArray(pcb?.primitiveLayers) ? pcb.primitiveLayers : [])
+        ]
+
+        for (const layer of sources) {
+            const key = String(layer?.name || layer?.layer || '').trim()
+            if (!key || seen.has(key)) continue
+            seen.add(key)
+            layers.push({
+                key,
+                label: key,
+                layerId: Number.isFinite(Number(layer?.layerId))
+                    ? Number(layer.layerId)
+                    : null
+            })
+        }
+
+        return layers
+    }
+
+    /**
+     * Collects referenced physical layer keys by virtual object key.
+     * @param {object[]} items Interaction items.
+     * @returns {Map<string, Set<string>>}
+     */
+    static #layersByObject(items) {
+        const layersByObject = new Map()
+
+        for (const item of items) {
+            if (!layersByObject.has(item.objectKey)) {
+                layersByObject.set(item.objectKey, new Set())
+            }
+            const layerSet = layersByObject.get(item.objectKey)
+            for (const layerKey of item.layerKeys || []) {
+                layerSet.add(layerKey)
+            }
+            if (item.type === 'pad' || item.type === 'via') {
+                if (!layersByObject.has('holes')) {
+                    layersByObject.set('holes', new Set())
+                }
+                for (const layerKey of item.layerKeys || []) {
+                    layersByObject.get('holes').add(layerKey)
+                }
+            }
+        }
+
+        return layersByObject
+    }
+}

package/src/ui/PcbScene3dBoardOutlineRefiner.mjs

@@ -46,17 +46,82 @@ export class PcbScene3dBoardOutlineRefiner {
             return sceneDescription
         }
 
+        const refinedBoard = {
+            ...board,
+            minX: candidate.minX,
+            minY: candidate.minY,
+            widthMil: candidate.widthMil,
+            heightMil: candidate.heightMil,
+            centerX: candidate.minX + candidate.widthMil / 2,
+            centerY: candidate.minY + candidate.heightMil / 2,
+            segments: candidate.segments
+        }
+
         return {
             ...sceneDescription,
-            board: {
-                ...board,
-                minX: candidate.minX,
-                minY: candidate.minY,
-                widthMil: candidate.widthMil,
-                heightMil: candidate.heightMil,
-                centerX: candidate.minX + candidate.widthMil / 2,
-                centerY: candidate.minY + candidate.heightMil / 2,
-                segments: candidate.segments
+            board: refinedBoard,
+            components: PcbScene3dBoardOutlineRefiner.#realignLocalPlacements(
+                sceneDescription?.components,
+                board,
+                refinedBoard
+            ),
+            externalPlacements:
+                PcbScene3dBoardOutlineRefiner.#realignLocalPlacements(
+                    sceneDescription?.externalPlacements,
+                    board,
+                    refinedBoard
+                )
+        }
+    }
+
+    /**
+     * Realigns precomputed local placements to a refined board center.
+     * @param {object[] | undefined} placements Scene placements.
+     * @param {{ centerX?: number, centerY?: number }} previousBoard Previous board.
+     * @param {{ centerX?: number, centerY?: number }} refinedBoard Refined board.
+     * @returns {object[] | undefined}
+     */
+    static #realignLocalPlacements(placements, previousBoard, refinedBoard) {
+        if (!Array.isArray(placements)) {
+            return placements
+        }
+
+        const deltaX =
+            Number(previousBoard?.centerX || 0) -
+            Number(refinedBoard?.centerX || 0)
+        const deltaY =
+            Number(previousBoard?.centerY || 0) -
+            Number(refinedBoard?.centerY || 0)
+
+        if (!deltaX && !deltaY) {
+            return placements
+        }
+
+        return placements.map((placement) =>
+            PcbScene3dBoardOutlineRefiner.#realignLocalPlacement(
+                placement,
+                deltaX,
+                deltaY
+            )
+        )
+    }
+
+    /**
+     * Applies one local origin delta to a scene placement.
+     * @param {object} placement Scene placement.
+     * @param {number} deltaX Local X delta.
+     * @param {number} deltaY Local Y delta.
+     * @returns {object}
+     */
+    static #realignLocalPlacement(placement, deltaX, deltaY) {
+        const positionMil = placement?.positionMil || {}
+
+        return {
+            ...placement,
+            positionMil: {
+                ...positionMil,
+                x: Number(positionMil.x || 0) + deltaX,
+                y: Number(positionMil.y || 0) + deltaY
             }
         }
     }

package/src/ui/PcbScene3dBuilder.mjs

@@ -18,14 +18,17 @@ export class PcbScene3dBuilder {
     static #DENSE_OVERLAY_MIN_REGION_AREA_RATIO = 0.2
     static #DENSE_OVERLAY_MIN_TRACK_COUNT = 250
     static #DENSE_OVERLAY_KNOCKOUT_COLOR = 0x2f6a2c
-    static #PRECISE_BODY_MATCH_TOLERANCE_MIL = 5
+    static #PRECISE_BODY_MATCH_TOLERANCE_MIL = 20
+    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
 
     /**
      * Builds a scene description for host 3D renderers.
      * @param {{ pcb?: { boardOutline?: { widthMil?: number, heightMil?: number, minX?: number, minY?: number, segments?: Array<Record<string, number | string>> }, primitiveLayers?: { layerId: number, name: string }[], pads?: { x: number, y: number, sizeTopX?: number, sizeTopY?: number, sizeMidX?: number, sizeMidY?: number, sizeBottomX?: number, sizeBottomY?: number }[], tracks?: any[], arcs?: any[], fills?: any[], vias?: any[], polygons?: any[], embeddedModels?: any[], componentBodies?: { modelId?: string, checksum?: number | null, embedded?: boolean, name?: string, identifier?: string, positionMil?: { x?: number, y?: number }, rotationDeg?: number, modelRotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number }[], components?: { designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null, source?: string, modelPath?: string }[] } }} documentModel
-     * @param {{ modelRegistry?: { resolveComponentModel: (component: any) => { name: string, relativePath: string, format: string } | null, resolveComponentBodyModel?: (componentBody: any) => { origin: string, name: string, format: string, payloadText?: string, sourceStream?: string, relativePath?: string } | null } | null, boardThicknessMil?: number }} [options]
-     * @returns {{ board: { widthMil: number, heightMil: number, thicknessMil: number, minX: number, minY: number, centerX: number, centerY: number, segments: Array<Record<string, number | string>> }, 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 } }[], 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 } } } }}
+     * @param {{ modelRegistry?: { resolveComponentModel: (component: any) => { name: string, relativePath: string, format: string } | null, resolveComponentBodyModel?: (componentBody: any) => { origin: string, name: string, format: string, payloadText?: string, sourceStream?: string, relativePath?: string } | null, resolveBoardAssemblyModel?: (documentModel: any) => { origin: string, name: string, format: string, file?: File | Blob | null, relativePath?: string } | null } | null, boardThicknessMil?: number }} [options]
+     * @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 } }[], 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 || {}
@@ -60,6 +63,10 @@ export class PcbScene3dBuilder {
             centerY:
                 Number(boardOutline.minY || 0) +
                 Number(boardOutline.heightMil || 0) / 2,
+            surfaceColor: Number.isInteger(appearance3d.solderMaskTopColor)
+                ? appearance3d.solderMaskTopColor
+                : appearance3d.solderMaskBottomColor,
+            edgeColor: appearance3d.boardCoreColor,
             segments: Array.isArray(boardOutline.segments)
                 ? boardOutline.segments
                 : []
@@ -103,6 +110,9 @@ export class PcbScene3dBuilder {
         const sceneDescription = {
             sourceFormat: 'altium',
             board,
+            boardAssemblyModel:
+                modelRegistry?.resolveBoardAssemblyModel?.(documentModel) ||
+                null,
             components: components.map((component) =>
                 PcbScene3dBuilder.#buildComponent(
                     component,
@@ -118,6 +128,7 @@ export class PcbScene3dBuilder {
                         componentBody,
                         bodyMatches[index],
                         components,
+                        pads,
                         board,
                         thicknessMil,
                         modelRegistry
@@ -205,6 +216,7 @@ export class PcbScene3dBuilder {
      * @param {{ modelId?: string, checksum?: number | null, embedded?: boolean, name?: string, identifier?: string, layer?: string, positionMil?: { x?: number, y?: number }, rotationDeg?: number, modelRotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number }} componentBody
      * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null } | null} matchedComponent
      * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, source?: string, modelPath?: string }[]} components
+     * @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 {{ resolveComponentBodyModel?: (componentBody: any) => { origin: string, name: string, format: string, payloadText?: string, sourceStream?: string, relativePath?: string } | null } | null} modelRegistry
@@ -214,6 +226,7 @@ export class PcbScene3dBuilder {
         componentBody,
         matchedComponent,
         components,
+        pads,
         board,
         thicknessMil,
         modelRegistry
@@ -272,10 +285,134 @@ export class PcbScene3dBuilder {
                 rotationDeg: modelRotation,
                 dzMil: Number(componentBody.dzMil || 0)
             },
+            projection: PcbScene3dBuilder.#resolveProjectionDiagnostics(
+                componentBody,
+                matchedComponent,
+                pads,
+                resolvedModel
+            ),
             externalModel: resolvedModel
         }
     }
 
+    /**
+     * Explains which footprint projection source informed one external model.
+     * @param {object} componentBody Normalized component body row.
+     * @param {{ x: number, y: number, height?: number | null } | null} matchedComponent Matched component.
+     * @param {object[]} pads Normalized pad rows.
+     * @param {object | null} resolvedModel Resolved model metadata.
+     * @returns {{ source: string, reason: string, boundsMil: { width: number, depth: number, height: number } }}
+     */
+    static #resolveProjectionDiagnostics(
+        componentBody,
+        matchedComponent,
+        pads,
+        resolvedModel
+    ) {
+        const authoredBounds = PcbScene3dBuilder.#firstBounds([
+            componentBody?.projectionOverrideMil,
+            componentBody?.projectionOverride?.boundsMil,
+            componentBody?.projectionBoundsMil
+        ])
+        if (authoredBounds) {
+            return {
+                source: 'authored-override',
+                reason: 'Component body carried an explicit projection override.',
+                boundsMil: authoredBounds
+            }
+        }
+
+        const modelBounds = PcbScene3dBuilder.#firstBounds([
+            componentBody?.modelBoundsMil,
+            resolvedModel?.boundsMil
+        ])
+        if (modelBounds) {
+            return {
+                source: 'model-bounds',
+                reason: 'Resolved 3D model bounds were available.',
+                boundsMil: modelBounds
+            }
+        }
+
+        if (matchedComponent) {
+            const padSpan = PcbScene3dBuilder.#resolvePadSpan(
+                matchedComponent,
+                pads
+            )
+            if (padSpan.width > 0 || padSpan.depth > 0) {
+                return {
+                    source: 'pad-fallback',
+                    reason: 'Projection fell back to nearby component pad span.',
+                    boundsMil: {
+                        width: padSpan.width,
+                        depth: padSpan.depth,
+                        height: Number(matchedComponent.height || 0)
+                    }
+                }
+            }
+
+            const body = PcbScene3dPackages.resolve(matchedComponent, padSpan)
+            return {
+                source: 'component-fallback',
+                reason: 'Projection fell back to the procedural component body.',
+                boundsMil: {
+                    width: body.sizeMil.width,
+                    depth: body.sizeMil.depth,
+                    height: body.sizeMil.height
+                }
+            }
+        }
+
+        return {
+            source: 'model-anchor-fallback',
+            reason: 'Projection used the model anchor because no owner geometry was available.',
+            boundsMil: { width: 0, depth: 0, height: 0 }
+        }
+    }
+
+    /**
+     * Returns the first complete bounds object from candidate metadata.
+     * @param {unknown[]} candidates Candidate bounds records.
+     * @returns {{ width: number, depth: number, height: number } | null}
+     */
+    static #firstBounds(candidates) {
+        for (const candidate of candidates || []) {
+            const bounds = PcbScene3dBuilder.#normalizeBounds(candidate)
+            if (bounds) {
+                return bounds
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Normalizes width/depth/height bounds metadata.
+     * @param {unknown} candidate Candidate bounds record.
+     * @returns {{ width: number, depth: number, height: number } | null}
+     */
+    static #normalizeBounds(candidate) {
+        if (!candidate || typeof candidate !== 'object') {
+            return null
+        }
+
+        const width = Number(candidate.width ?? candidate.x ?? candidate.sizeX)
+        const depth = Number(candidate.depth ?? candidate.y ?? candidate.sizeY)
+        const height = Number(
+            candidate.height ?? candidate.z ?? candidate.sizeZ
+        )
+
+        if (
+            !Number.isFinite(width) ||
+            !Number.isFinite(depth) ||
+            !Number.isFinite(height)
+        ) {
+            return null
+        }
+
+        return { width, depth, height }
+    }
+
     /**
      * Resolves explicit body placements to component anchors using a unique
      * nearest-neighbor pass plus an ordered-affinity fallback for repeated
@@ -1159,16 +1296,41 @@ export class PcbScene3dBuilder {
     static #isBodyPositionNearBoard(componentBody, board) {
         const bodyX = Number(componentBody?.positionMil?.x || 0)
         const bodyY = Number(componentBody?.positionMil?.y || 0)
-        const minX = Number(board?.minX || 0) - 600
-        const minY = Number(board?.minY || 0) - 600
+        const xOverhang = PcbScene3dBuilder.#resolveUnmatchedBodyOverhang(
+            board?.widthMil
+        )
+        const yOverhang = PcbScene3dBuilder.#resolveUnmatchedBodyOverhang(
+            board?.heightMil
+        )
+        const minX = Number(board?.minX || 0) - xOverhang
+        const minY = Number(board?.minY || 0) - yOverhang
         const maxX =
-            Number(board?.minX || 0) + Number(board?.widthMil || 0) + 600
+            Number(board?.minX || 0) + Number(board?.widthMil || 0) + xOverhang
         const maxY =
-            Number(board?.minY || 0) + Number(board?.heightMil || 0) + 600
+            Number(board?.minY || 0) + Number(board?.heightMil || 0) + yOverhang
 
         return bodyX >= minX && bodyX <= maxX && bodyY >= minY && bodyY <= maxY
     }
 
+    /**
+     * Resolves a proportional unresolved-body margin for one board axis.
+     * @param {number | string | undefined} spanMil Board axis span.
+     * @returns {number}
+     */
+    static #resolveUnmatchedBodyOverhang(spanMil) {
+        const proportional =
+            Math.max(Number(spanMil || 0), 0) *
+            PcbScene3dBuilder.#UNMATCHED_BODY_OVERHANG_RATIO
+
+        return Math.min(
+            PcbScene3dBuilder.#UNMATCHED_BODY_MAX_OVERHANG_MIL,
+            Math.max(
+                proportional,
+                PcbScene3dBuilder.#UNMATCHED_BODY_MIN_OVERHANG_MIL
+            )
+        )
+    }
+
     /**
      * Normalizes one angle into the range [0, 360).
      * @param {number} angle

package/src/ui/PcbScene3dModelRegistry.mjs

@@ -208,6 +208,49 @@ export class PcbScene3dModelRegistry {
         return this.#resolveExplicitMatch(componentBody?.name)
     }
 
+    /**
+     * Resolves a project-level full board assembly model for one PCB document.
+     * @param {{ fileName?: string }} documentModel
+     * @returns {{ origin: 'board-assembly', file?: File | Blob | null, name: string, relativePath: string, format: string } | null}
+     */
+    resolveBoardAssemblyModel(documentModel) {
+        const normalizedBoardBaseName = PcbScene3dModelRegistry.#normalizeToken(
+            PcbScene3dModelRegistry.#basenameWithoutExtension(
+                documentModel?.fileName
+            )
+        )
+        if (!normalizedBoardBaseName) {
+            return null
+        }
+
+        const rankedMatches = this.#modelFiles
+            .filter(
+                (file) =>
+                    file.normalizedBaseName === normalizedBoardBaseName &&
+                    PcbScene3dModelRegistry.#isBoardAssemblyPath(
+                        file.relativePath
+                    )
+            )
+            .sort(
+                (left, right) =>
+                    PcbScene3dModelRegistry.#formatRank(left.format) -
+                    PcbScene3dModelRegistry.#formatRank(right.format)
+            )
+
+        if (!rankedMatches.length) {
+            return null
+        }
+
+        const matchedFile = rankedMatches[0]
+        return {
+            origin: 'board-assembly',
+            file: matchedFile.file,
+            name: matchedFile.name,
+            relativePath: matchedFile.relativePath,
+            format: matchedFile.format
+        }
+    }
+
     /**
      * Normalizes one embedded payload for registry lookup.
      * @param {{ id?: string, checksum?: number | null, name?: string, format?: string, payloadText?: string, sourceStream?: string }} model
@@ -295,6 +338,37 @@ export class PcbScene3dModelRegistry {
         return format === 'wrl' ? 0 : 1
     }
 
+    /**
+     * Checks whether one model path is in a conventional board model folder.
+     * @param {string | undefined} relativePath
+     * @returns {boolean}
+     */
+    static #isBoardAssemblyPath(relativePath) {
+        return String(relativePath || '')
+            .replaceAll('\\', '/')
+            .split('/')
+            .some(
+                (part) =>
+                    PcbScene3dModelRegistry.#normalizeToken(part) === '3dbodies'
+            )
+    }
+
+    /**
+     * Returns one path basename without its extension.
+     * @param {string | undefined} filePath
+     * @returns {string}
+     */
+    static #basenameWithoutExtension(filePath) {
+        const baseName =
+            String(filePath || '')
+                .replaceAll('\\', '/')
+                .split('/')
+                .filter(Boolean)
+                .at(-1) || ''
+
+        return baseName.replace(/\.[^.]+$/u, '')
+    }
+
     /**
      * Normalizes one lookup token.
      * @param {string | undefined} value