altium-toolkit 1.1.24 → 1.1.26

package/src/ui/PcbDimensionPrimitiveRenderer.mjs

@@ -0,0 +1,422 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
+
+/**
+ * Renders parsed PCB dimension records into static SVG primitives.
+ */
+export class PcbDimensionPrimitiveRenderer {
+    /**
+     * Builds the dimension SVG group.
+     * @param {object[]} dimensions Normalized dimension records.
+     * @param {{ attributes?: (dimension: object, index: number) => string }} options Render options.
+     * @returns {string}
+     */
+    static buildMarkup(dimensions, options = {}) {
+        const markup = (dimensions || [])
+            .map((dimension, index) =>
+                PcbDimensionPrimitiveRenderer.#renderDimension(
+                    dimension,
+                    index,
+                    options.attributes
+                )
+            )
+            .filter(Boolean)
+            .join('')
+
+        return markup ? '<g class="pcb-dimensions">' + markup + '</g>' : ''
+    }
+
+    /**
+     * Pushes dimension extents into reusable viewBox coordinate arrays.
+     * @param {number[]} xs X extents.
+     * @param {number[]} ys Y extents.
+     * @param {object[]} dimensions Dimension records.
+     * @returns {void}
+     */
+    static pushExtents(xs, ys, dimensions) {
+        for (const dimension of dimensions || []) {
+            for (const point of [
+                ...(dimension?.references || []),
+                dimension?.textLocation
+            ]) {
+                if (!point) {
+                    continue
+                }
+                const x = Number(point.x)
+                const y = Number(point.y)
+                if (Number.isFinite(x) && Number.isFinite(y)) {
+                    xs.push(x)
+                    ys.push(y)
+                }
+            }
+        }
+    }
+
+    /**
+     * Renders one dimension record.
+     * @param {object} dimension Dimension record.
+     * @param {number} index Fallback index.
+     * @param {(dimension: object, index: number) => string | undefined} attributes Attribute callback.
+     * @returns {string}
+     */
+    static #renderDimension(dimension, index, attributes) {
+        const kind = PcbDimensionPrimitiveRenderer.#kind(dimension)
+        const references = PcbDimensionPrimitiveRenderer.#references(dimension)
+        const body = PcbDimensionPrimitiveRenderer.#bodyMarkup(
+            kind,
+            dimension,
+            references
+        )
+
+        if (!body) {
+            return ''
+        }
+
+        return (
+            '<g class="pcb-dimension pcb-dimension--' +
+            SchematicSvgUtils.escapeHtml(kind) +
+            '"' +
+            (typeof attributes === 'function'
+                ? attributes(dimension, index) || ''
+                : '') +
+            '>' +
+            body +
+            '</g>'
+        )
+    }
+
+    /**
+     * Renders the kind-specific dimension body.
+     * @param {string} kind Dimension kind.
+     * @param {object} dimension Dimension record.
+     * @param {{ x: number, y: number }[]} references Reference points.
+     * @returns {string}
+     */
+    static #bodyMarkup(kind, dimension, references) {
+        if (kind === 'angular') {
+            return PcbDimensionPrimitiveRenderer.#angularMarkup(
+                dimension,
+                references
+            )
+        }
+
+        if (['diameter', 'radial'].includes(kind)) {
+            return PcbDimensionPrimitiveRenderer.#leaderMarkup(
+                kind,
+                dimension,
+                references
+            )
+        }
+
+        return PcbDimensionPrimitiveRenderer.#linearMarkup(
+            dimension,
+            references
+        )
+    }
+
+    /**
+     * Renders one linear dimension.
+     * @param {object} dimension Dimension record.
+     * @param {{ x: number, y: number }[]} references Reference points.
+     * @returns {string}
+     */
+    static #linearMarkup(dimension, references) {
+        if (references.length < 2) {
+            return ''
+        }
+
+        const [start, end] = references
+        const label = PcbDimensionPrimitiveRenderer.#labelPoint(
+            dimension,
+            start,
+            end
+        )
+        const mid = PcbDimensionPrimitiveRenderer.#midpoint(start, end)
+
+        return (
+            PcbDimensionPrimitiveRenderer.#line(
+                'pcb-dimension__measure',
+                start,
+                end
+            ) +
+            PcbDimensionPrimitiveRenderer.#line(
+                'pcb-dimension__leader',
+                mid,
+                label
+            ) +
+            PcbDimensionPrimitiveRenderer.#label(dimension, label)
+        )
+    }
+
+    /**
+     * Renders one angular dimension.
+     * @param {object} dimension Dimension record.
+     * @param {{ x: number, y: number }[]} references Reference points.
+     * @returns {string}
+     */
+    static #angularMarkup(dimension, references) {
+        if (references.length < 3) {
+            return ''
+        }
+
+        const [start, vertex, end] = references
+        const startArc = PcbDimensionPrimitiveRenderer.#arcPoint(vertex, start)
+        const endArc = PcbDimensionPrimitiveRenderer.#arcPoint(vertex, end)
+        const radius = PcbDimensionPrimitiveRenderer.#distance(vertex, startArc)
+        const sweep =
+            PcbDimensionPrimitiveRenderer.#cross(vertex, start, end) >= 0
+                ? 1
+                : 0
+        const label =
+            PcbDimensionPrimitiveRenderer.#point(dimension?.textLocation) ||
+            PcbDimensionPrimitiveRenderer.#midpoint(startArc, endArc)
+
+        return (
+            PcbDimensionPrimitiveRenderer.#line(
+                'pcb-dimension__extension',
+                vertex,
+                start
+            ) +
+            PcbDimensionPrimitiveRenderer.#line(
+                'pcb-dimension__extension',
+                vertex,
+                end
+            ) +
+            '<path class="pcb-dimension__arc" d="M ' +
+            SchematicSvgUtils.formatNumber(startArc.x) +
+            ' ' +
+            SchematicSvgUtils.formatNumber(startArc.y) +
+            ' A ' +
+            SchematicSvgUtils.formatNumber(radius) +
+            ' ' +
+            SchematicSvgUtils.formatNumber(radius) +
+            ' 0 0 ' +
+            sweep +
+            ' ' +
+            SchematicSvgUtils.formatNumber(endArc.x) +
+            ' ' +
+            SchematicSvgUtils.formatNumber(endArc.y) +
+            '" />' +
+            PcbDimensionPrimitiveRenderer.#label(dimension, label)
+        )
+    }
+
+    /**
+     * Renders radial and diameter dimensions as leader dimensions.
+     * @param {string} kind Dimension kind.
+     * @param {object} dimension Dimension record.
+     * @param {{ x: number, y: number }[]} references Reference points.
+     * @returns {string}
+     */
+    static #leaderMarkup(kind, dimension, references) {
+        if (references.length < 2) {
+            return ''
+        }
+
+        const [start, end] = references
+        const label = PcbDimensionPrimitiveRenderer.#labelPoint(
+            dimension,
+            start,
+            end
+        )
+        const centerMark =
+            kind === 'diameter'
+                ? '<circle class="pcb-dimension__center" cx="' +
+                  SchematicSvgUtils.formatNumber(start.x) +
+                  '" cy="' +
+                  SchematicSvgUtils.formatNumber(start.y) +
+                  '" r="3" />'
+                : ''
+
+        return (
+            centerMark +
+            PcbDimensionPrimitiveRenderer.#line(
+                'pcb-dimension__measure',
+                start,
+                end
+            ) +
+            PcbDimensionPrimitiveRenderer.#line(
+                'pcb-dimension__leader',
+                end,
+                label
+            ) +
+            PcbDimensionPrimitiveRenderer.#label(dimension, label)
+        )
+    }
+
+    /**
+     * Renders one SVG line.
+     * @param {string} className SVG class name.
+     * @param {{ x: number, y: number }} start Start point.
+     * @param {{ x: number, y: number }} end End point.
+     * @returns {string}
+     */
+    static #line(className, start, end) {
+        return (
+            '<line class="' +
+            className +
+            '" x1="' +
+            SchematicSvgUtils.formatNumber(start.x) +
+            '" y1="' +
+            SchematicSvgUtils.formatNumber(start.y) +
+            '" x2="' +
+            SchematicSvgUtils.formatNumber(end.x) +
+            '" y2="' +
+            SchematicSvgUtils.formatNumber(end.y) +
+            '" />'
+        )
+    }
+
+    /**
+     * Renders one dimension label.
+     * @param {object} dimension Dimension record.
+     * @param {{ x: number, y: number }} point Label point.
+     * @returns {string}
+     */
+    static #label(dimension, point) {
+        const text =
+            dimension?.text ||
+            PcbDimensionPrimitiveRenderer.#formatMeasuredValue(dimension)
+        if (!text) {
+            return ''
+        }
+
+        return (
+            '<text class="pcb-dimension__label" x="' +
+            SchematicSvgUtils.formatNumber(point.x) +
+            '" y="' +
+            SchematicSvgUtils.formatNumber(point.y) +
+            '">' +
+            SchematicSvgUtils.escapeHtml(text) +
+            '</text>'
+        )
+    }
+
+    /**
+     * Resolves a display label from measured numeric fields.
+     * @param {object} dimension Dimension record.
+     * @returns {string}
+     */
+    static #formatMeasuredValue(dimension) {
+        const value =
+            dimension?.kind === 'angular'
+                ? dimension?.angleValue
+                : dimension?.measuredValue
+        if (!Number.isFinite(Number(value))) {
+            return ''
+        }
+
+        return (
+            SchematicSvgUtils.formatNumber(Number(value)) +
+            (dimension?.unit ? ' ' + String(dimension.unit).trim() : '')
+        )
+    }
+
+    /**
+     * Resolves a label point with a midpoint fallback.
+     * @param {object} dimension Dimension record.
+     * @param {{ x: number, y: number }} start Start point.
+     * @param {{ x: number, y: number }} end End point.
+     * @returns {{ x: number, y: number }}
+     */
+    static #labelPoint(dimension, start, end) {
+        return (
+            PcbDimensionPrimitiveRenderer.#point(dimension?.textLocation) ||
+            PcbDimensionPrimitiveRenderer.#midpoint(start, end)
+        )
+    }
+
+    /**
+     * Normalizes references into finite points.
+     * @param {object} dimension Dimension record.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #references(dimension) {
+        return (dimension?.references || [])
+            .map((reference) => PcbDimensionPrimitiveRenderer.#point(reference))
+            .filter(Boolean)
+    }
+
+    /**
+     * Normalizes one point-like object.
+     * @param {object | null | undefined} point Point candidate.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static #point(point) {
+        const x = Number(point?.x)
+        const y = Number(point?.y)
+        return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null
+    }
+
+    /**
+     * Resolves the canonical dimension kind.
+     * @param {object} dimension Dimension record.
+     * @returns {string}
+     */
+    static #kind(dimension) {
+        const kind = String(dimension?.kind || 'linear')
+            .trim()
+            .toLowerCase()
+        return kind || 'linear'
+    }
+
+    /**
+     * Returns the midpoint between two points.
+     * @param {{ x: number, y: number }} start Start point.
+     * @param {{ x: number, y: number }} end End point.
+     * @returns {{ x: number, y: number }}
+     */
+    static #midpoint(start, end) {
+        return {
+            x: (start.x + end.x) / 2,
+            y: (start.y + end.y) / 2
+        }
+    }
+
+    /**
+     * Returns a stable point on an angular dimension arc.
+     * @param {{ x: number, y: number }} vertex Arc center.
+     * @param {{ x: number, y: number }} reference Reference point.
+     * @returns {{ x: number, y: number }}
+     */
+    static #arcPoint(vertex, reference) {
+        const dx = reference.x - vertex.x
+        const dy = reference.y - vertex.y
+        const length = Math.max(Math.sqrt(dx * dx + dy * dy), 1)
+        const radius = Math.min(Math.max(length * 0.55, 16), 80)
+
+        return {
+            x: vertex.x + (dx / length) * radius,
+            y: vertex.y + (dy / length) * radius
+        }
+    }
+
+    /**
+     * Calculates distance between two points.
+     * @param {{ x: number, y: number }} start Start point.
+     * @param {{ x: number, y: number }} end End point.
+     * @returns {number}
+     */
+    static #distance(start, end) {
+        const dx = end.x - start.x
+        const dy = end.y - start.y
+        return Math.max(Math.sqrt(dx * dx + dy * dy), 1)
+    }
+
+    /**
+     * Calculates the sign of the angle from start to end around vertex.
+     * @param {{ x: number, y: number }} vertex Vertex point.
+     * @param {{ x: number, y: number }} start Start point.
+     * @param {{ x: number, y: number }} end End point.
+     * @returns {number}
+     */
+    static #cross(vertex, start, end) {
+        return (
+            (start.x - vertex.x) * (end.y - vertex.y) -
+            (start.y - vertex.y) * (end.x - vertex.x)
+        )
+    }
+}

package/src/ui/PcbScene3dBoardOutlineRefiner.mjs

@@ -70,6 +70,12 @@ export class PcbScene3dBoardOutlineRefiner {
                     sceneDescription?.externalPlacements,
                     board,
                     refinedBoard
+                ),
+            staticBodyPlacements:
+                PcbScene3dBoardOutlineRefiner.#realignLocalPlacements(
+                    sceneDescription?.staticBodyPlacements,
+                    board,
+                    refinedBoard
                 )
         }
     }

package/src/ui/PcbScene3dBuilder.mjs

@@ -8,6 +8,7 @@ import { PcbScene3dDrillCutoutBuilder } from './PcbScene3dDrillCutoutBuilder.mjs
 import { PcbFootprintPrimitiveSelector } from './PcbFootprintPrimitiveSelector.mjs'
 import { PcbScene3dPackages } from './PcbScene3dPackages.mjs'
 import { PcbScene3dPlacementSideResolver } from './PcbScene3dPlacementSideResolver.mjs'
+import { PcbScene3dStaticBodyPlacementBuilder } from './PcbScene3dStaticBodyPlacementBuilder.mjs'
 import { PcbScene3dTextBoxLayoutResolver } from './PcbScene3dTextBoxLayoutResolver.mjs'
 
 /**
@@ -26,9 +27,9 @@ export class PcbScene3dBuilder {
 
     /**
      * 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 {{ 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, staticGeometry?: object }[], 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, 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 } } } }}
+     * @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 || {}
@@ -142,6 +143,13 @@ export class PcbScene3dBuilder {
                     )
                 )
                 .filter(Boolean),
+            staticBodyPlacements: PcbScene3dStaticBodyPlacementBuilder.build(
+                componentBodies,
+                bodyMatches,
+                components,
+                board,
+                thicknessMil
+            ),
             detail: {
                 embeddedFonts: Array.isArray(pcb.embeddedFonts)
                     ? pcb.embeddedFonts

package/src/ui/PcbScene3dStaticBodyPlacementBuilder.mjs

@@ -0,0 +1,225 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbScene3dPlacementSideResolver } from './PcbScene3dPlacementSideResolver.mjs'
+
+/**
+ * Builds scene placements for static shape-based 3D bodies.
+ */
+export class PcbScene3dStaticBodyPlacementBuilder {
+    static #UNMATCHED_BODY_OVERHANG_RATIO = 0.25
+    static #UNMATCHED_BODY_MIN_OVERHANG_MIL = 150
+    static #UNMATCHED_BODY_MAX_OVERHANG_MIL = 600
+
+    /**
+     * 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 {({ 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 {{ 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 }[]}
+     */
+    static build(
+        componentBodies,
+        bodyMatches,
+        components,
+        board,
+        thicknessMil
+    ) {
+        return (Array.isArray(componentBodies) ? componentBodies : [])
+            .map((componentBody, index) =>
+                PcbScene3dStaticBodyPlacementBuilder.#buildPlacement(
+                    componentBody,
+                    bodyMatches?.[index] || null,
+                    components,
+                    board,
+                    thicknessMil
+                )
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * 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 {{ 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.
+     * @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 } | null}
+     */
+    static #buildPlacement(
+        componentBody,
+        matchedComponent,
+        components,
+        board,
+        thicknessMil
+    ) {
+        const geometry = componentBody?.staticGeometry
+
+        if (!geometry || geometry.status !== 'complete') {
+            return null
+        }
+
+        if (
+            !matchedComponent &&
+            !PcbScene3dStaticBodyPlacementBuilder.#isBodyPositionNearBoard(
+                componentBody,
+                board
+            )
+        ) {
+            return null
+        }
+
+        const mountSide = PcbScene3dPlacementSideResolver.resolvePlacementSide(
+            componentBody,
+            matchedComponent,
+            components,
+            board
+        )
+        const sourcePosition =
+            PcbScene3dStaticBodyPlacementBuilder.#sourcePosition(componentBody)
+        const heightMil =
+            PcbScene3dStaticBodyPlacementBuilder.#geometryHeight(geometry)
+        const standoffMil = Math.abs(
+            Number(
+                geometry.standoffHeightMil ?? componentBody.standoffHeightMil
+            )
+        )
+        const zOffset =
+            Number(thicknessMil || 0) / 2 +
+            (Number.isFinite(standoffMil) ? standoffMil : 0) +
+            heightMil / 2
+
+        return {
+            designator:
+                matchedComponent?.designator ||
+                String(
+                    componentBody.identifier || componentBody.name || '3D body'
+                ),
+            mountSide,
+            rotationDeg: PcbScene3dStaticBodyPlacementBuilder.#normalizeAngle(
+                Number(componentBody.rotationDeg || 0) +
+                    Number(matchedComponent?.rotation || 0)
+            ),
+            positionMil: {
+                x: PcbScene3dStaticBodyPlacementBuilder.#roundMil(
+                    Number(sourcePosition.x || 0) - Number(board.centerX || 0)
+                ),
+                y: PcbScene3dStaticBodyPlacementBuilder.#roundMil(
+                    Number(sourcePosition.y || 0) - Number(board.centerY || 0)
+                ),
+                z: PcbScene3dStaticBodyPlacementBuilder.#roundMil(
+                    mountSide === 'bottom' ? -zOffset : zOffset
+                )
+            },
+            bodyPositionMil: {
+                x: Number(componentBody.positionMil?.x || 0),
+                y: Number(componentBody.positionMil?.y || 0)
+            },
+            geometry
+        }
+    }
+
+    /**
+     * Returns the native body anchor.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component body.
+     * @returns {{ x: number, y: number }}
+     */
+    static #sourcePosition(componentBody) {
+        return {
+            x: Number(componentBody?.positionMil?.x || 0),
+            y: Number(componentBody?.positionMil?.y || 0)
+        }
+    }
+
+    /**
+     * Resolves static body height from geometry metadata.
+     * @param {object} geometry Static geometry.
+     * @returns {number}
+     */
+    static #geometryHeight(geometry) {
+        const height = Number(geometry?.heightMil)
+        if (Number.isFinite(height) && height > 0) {
+            return height
+        }
+
+        const radius = Number(geometry?.radiusMil)
+        if (Number.isFinite(radius) && radius > 0) {
+            return radius * 2
+        }
+
+        return 0
+    }
+
+    /**
+     * Returns true when one body anchor lies close enough to the board.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component body.
+     * @param {{ minX?: number, minY?: number, widthMil?: number, heightMil?: number }} board Board.
+     * @returns {boolean}
+     */
+    static #isBodyPositionNearBoard(componentBody, board) {
+        const bodyX = Number(componentBody?.positionMil?.x || 0)
+        const bodyY = Number(componentBody?.positionMil?.y || 0)
+        const xOverhang =
+            PcbScene3dStaticBodyPlacementBuilder.#unmatchedBodyOverhang(
+                board?.widthMil
+            )
+        const yOverhang =
+            PcbScene3dStaticBodyPlacementBuilder.#unmatchedBodyOverhang(
+                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) + xOverhang
+        const maxY =
+            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 #unmatchedBodyOverhang(spanMil) {
+        const proportional =
+            Math.max(Number(spanMil || 0), 0) *
+            PcbScene3dStaticBodyPlacementBuilder.#UNMATCHED_BODY_OVERHANG_RATIO
+
+        return Math.min(
+            PcbScene3dStaticBodyPlacementBuilder
+                .#UNMATCHED_BODY_MAX_OVERHANG_MIL,
+            Math.max(
+                proportional,
+                PcbScene3dStaticBodyPlacementBuilder
+                    .#UNMATCHED_BODY_MIN_OVERHANG_MIL
+            )
+        )
+    }
+
+    /**
+     * Rounds one mil value for stable scene output.
+     * @param {number} value Candidate value.
+     * @returns {number}
+     */
+    static #roundMil(value) {
+        const rounded = Math.round(Number(value) * 10000) / 10000
+        return Object.is(rounded, -0) ? 0 : rounded
+    }
+
+    /**
+     * Normalizes one angle into the range [0, 360).
+     * @param {number} angle Candidate angle.
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        const normalized = Number(angle || 0) % 360
+
+        return normalized < 0 ? normalized + 360 : normalized
+    }
+}