altium-toolkit 1.4.7 → 1.4.8

package/docs/release-notes-v1.4.8.md

@@ -0,0 +1,42 @@
+# altium-toolkit 1.4.8
+
+Version 1.4.8 corrects embedded STEP placement for bottom-side components and
+for package owners recovered after initial scene construction.
+
+## Signed STEP source orientation
+
+- Embedded STEP registry entries expose signed source bounds derived from the
+  model payload and its declared length units.
+- Bottom-side models whose geometry is predominantly below the authored origin
+  preserve their authored half-turn instead of being normalized upside down.
+- Direct scene construction and asynchronous scene preparation share the same
+  convergence registry and builder path.
+
+## Late-owner model seating
+
+- Final placement owners are reconciled with their original component-body
+  metadata after historical ownership adapters complete.
+- A finite zero authored standoff clears only an unchanged positive source
+  `dzMil`, allowing the shared viewer's model-bounds seating to place the model
+  on the PCB surface.
+- Positive authored standoffs, unresolved bodies, downstream-adjusted offsets,
+  and unrelated model transformations remain unchanged.
+- The rule is derived from ownership and placement metadata without component,
+  model, vendor, package, project, or fixture-specific matching.
+
+## Compatibility
+
+- Historical native source remains frozen; the corrections live in the public
+  convergence layer.
+- Existing parser, renderer, extension, and viewer scene contracts remain
+  unchanged.
+
+## Verification
+
+- Repository-owned fake regressions cover signed-source bottom half-turns,
+  zero-standoff late owners, positive authored standoffs, unresolved bodies,
+  and downstream-adjusted offsets.
+- Exact local-board verification checks the affected model seating together
+  with the previously reported bottom connector orientation.
+- Release gates include the complete package suite, formatting check, npm dry
+  run, ECAD Forge integration tests, structured-data check, and static build.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "1.4.7",
+    "version": "1.4.8",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",

package/src/convergence/PcbScene3dBuilder.mjs

@@ -0,0 +1,243 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbScene3dBuilder as HistoricalPcbScene3dBuilder } from '../ui/PcbScene3dBuilder.mjs'
+
+const NEGATIVE_SOURCE_Z_DOMINANCE_RATIO = 0.8
+const POSITION_EPSILON_MIL = 1e-6
+
+/**
+ * Adds signed-source model orientation correction around the preserved native
+ * scene builder.
+ */
+export class PcbScene3dBuilder {
+    /**
+     * Builds a scene and preserves structurally negative-Z source half-turns.
+     * @param {object} documentModel Parsed Altium document model.
+     * @param {object} [options] Native scene-builder options.
+     * @returns {object}
+     */
+    static build(documentModel, options = {}) {
+        const scene = HistoricalPcbScene3dBuilder.build(documentModel, options)
+        if (!Array.isArray(scene?.externalPlacements)) {
+            return scene
+        }
+
+        return {
+            ...scene,
+            externalPlacements: scene.externalPlacements.map((placement) =>
+                PcbScene3dBuilder.#normalizePlacement(
+                    placement,
+                    documentModel?.pcb?.componentBodies,
+                    documentModel?.pcb?.components
+                )
+            )
+        }
+    }
+
+    /**
+     * Preserves one bottom placement half-turn when its source geometry is
+     * predominantly below the authored origin.
+     * @param {object} placement Built external placement.
+     * @param {object[] | undefined} componentBodies Source component bodies.
+     * @param {object[] | undefined} components Source PCB components.
+     * @returns {object}
+     */
+    static #normalizePlacement(placement, componentBodies, components) {
+        const componentBody = PcbScene3dBuilder.#resolveComponentBody(
+            placement,
+            componentBodies
+        )
+        const normalizedPlacement =
+            PcbScene3dBuilder.#normalizeRecoveredOwnerVerticalOffset(
+                placement,
+                componentBody,
+                components
+            )
+
+        if (
+            String(normalizedPlacement?.mountSide || '').toLowerCase() !==
+                'bottom' ||
+            !PcbScene3dBuilder.#isDominantlyNegativeSourceZ(
+                normalizedPlacement?.externalModel?.sourceBoundsMil
+            )
+        ) {
+            return normalizedPlacement
+        }
+
+        if (
+            PcbScene3dBuilder.#normalizeAngle(
+                componentBody?.modelRotationDeg?.x ??
+                    normalizedPlacement?.externalModel?.transform?.rotationDeg
+                        ?.x
+            ) !== 180
+        ) {
+            return normalizedPlacement
+        }
+
+        return {
+            ...normalizedPlacement,
+            modelTransform: {
+                ...(normalizedPlacement.modelTransform || {}),
+                rotationDeg: {
+                    ...(normalizedPlacement.modelTransform?.rotationDeg || {}),
+                    x: -180
+                }
+            }
+        }
+    }
+
+    /**
+     * Applies owned-package seating after a later adapter recovered the owner.
+     * @param {object} placement Built external placement.
+     * @param {object | null} componentBody Resolved source component body.
+     * @param {object[] | undefined} components Source PCB components.
+     * @returns {object}
+     */
+    static #normalizeRecoveredOwnerVerticalOffset(
+        placement,
+        componentBody,
+        components
+    ) {
+        if (
+            !PcbScene3dBuilder.#hasResolvedOwner(placement, components) ||
+            !PcbScene3dBuilder.#hasZeroAuthoredStandoff(componentBody) ||
+            !PcbScene3dBuilder.#retainsPositiveSourceOffset(
+                placement,
+                componentBody
+            )
+        ) {
+            return placement
+        }
+
+        return {
+            ...placement,
+            modelTransform: {
+                ...(placement.modelTransform || {}),
+                dzMil: 0
+            }
+        }
+    }
+
+    /**
+     * Checks whether the final placement designator resolves a source owner.
+     * @param {object} placement Built external placement.
+     * @param {object[] | undefined} components Source PCB components.
+     * @returns {boolean}
+     */
+    static #hasResolvedOwner(placement, components) {
+        const designator = String(placement?.designator || '')
+        return (
+            designator.length > 0 &&
+            (Array.isArray(components) ? components : []).some(
+                (component) =>
+                    String(component?.designator || '') === designator
+            )
+        )
+    }
+
+    /**
+     * Checks whether the source explicitly authors zero model standoff.
+     * @param {object | null} componentBody Resolved source component body.
+     * @returns {boolean}
+     */
+    static #hasZeroAuthoredStandoff(componentBody) {
+        const sourceStandoff = componentBody?.standoffHeightMil
+        if (
+            sourceStandoff === null ||
+            sourceStandoff === undefined ||
+            sourceStandoff === ''
+        ) {
+            return false
+        }
+
+        const standoff = Number(sourceStandoff)
+        return (
+            Number.isFinite(standoff) &&
+            Math.abs(standoff) <= POSITION_EPSILON_MIL
+        )
+    }
+
+    /**
+     * Checks whether the final placement still carries the positive source Z.
+     * @param {object} placement Built external placement.
+     * @param {object | null} componentBody Resolved source component body.
+     * @returns {boolean}
+     */
+    static #retainsPositiveSourceOffset(placement, componentBody) {
+        const sourceOffset = Number(componentBody?.dzMil)
+        const placementOffset = Number(placement?.modelTransform?.dzMil)
+
+        return (
+            Number.isFinite(sourceOffset) &&
+            sourceOffset > 0 &&
+            Number.isFinite(placementOffset) &&
+            Math.abs(placementOffset - sourceOffset) <= POSITION_EPSILON_MIL
+        )
+    }
+
+    /**
+     * Resolves the source body associated with one built placement.
+     * @param {object} placement Built external placement.
+     * @param {object[] | undefined} componentBodies Source component bodies.
+     * @returns {object | null}
+     */
+    static #resolveComponentBody(placement, componentBodies) {
+        const bodyPosition = placement?.bodyPositionMil || {}
+        const modelName = String(placement?.externalModel?.name || '')
+
+        return (
+            (Array.isArray(componentBodies) ? componentBodies : []).find(
+                (componentBody) =>
+                    String(componentBody?.name || '') === modelName &&
+                    PcbScene3dBuilder.#positionsMatch(
+                        componentBody?.positionMil,
+                        bodyPosition
+                    )
+            ) || null
+        )
+    }
+
+    /**
+     * Checks whether two model positions represent the same authored anchor.
+     * @param {{ x?: number, y?: number } | undefined} left Left position.
+     * @param {{ x?: number, y?: number } | undefined} right Right position.
+     * @returns {boolean}
+     */
+    static #positionsMatch(left, right) {
+        return (
+            Math.abs(Number(left?.x) - Number(right?.x)) <=
+                POSITION_EPSILON_MIL &&
+            Math.abs(Number(left?.y) - Number(right?.y)) <= POSITION_EPSILON_MIL
+        )
+    }
+
+    /**
+     * Checks whether at least four fifths of the source Z span lies below the
+     * authored origin.
+     * @param {{ minZ?: number, maxZ?: number } | null | undefined} sourceBoundsMil Signed source-model bounds.
+     * @returns {boolean}
+     */
+    static #isDominantlyNegativeSourceZ(sourceBoundsMil) {
+        const minZ = Number(sourceBoundsMil?.minZ)
+        const maxZ = Number(sourceBoundsMil?.maxZ)
+        if (!Number.isFinite(minZ) || !Number.isFinite(maxZ) || maxZ <= minZ) {
+            return false
+        }
+
+        const negativeSpan = Math.max(0, Math.min(0, maxZ) - minZ)
+        return negativeSpan / (maxZ - minZ) >= NEGATIVE_SOURCE_Z_DOMINANCE_RATIO
+    }
+
+    /**
+     * Normalizes one angle into the positive 0-359 degree range.
+     * @param {unknown} angle Source angle.
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        const numericAngle = Number(angle || 0)
+        const normalized = numericAngle % 360
+
+        return normalized < 0 ? normalized + 360 : normalized
+    }
+}

package/src/convergence/PcbScene3dModelRegistry.mjs

@@ -0,0 +1,184 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbScene3dModelRegistry as HistoricalPcbScene3dModelRegistry } from '../ui/PcbScene3dModelRegistry.mjs'
+
+const MILS_PER_METER = 39370.07874015748
+const MILS_PER_INCH = 1000
+
+/**
+ * Adds signed STEP source bounds to the preserved native model registry.
+ */
+export class PcbScene3dModelRegistry {
+    #registry
+
+    /**
+     * Creates one converged registry around either a preserved native registry
+     * or the native constructor's normalized model rows.
+     * @param {HistoricalPcbScene3dModelRegistry | object[]} registryOrModelFiles Native registry or normalized session models.
+     * @param {object[]} embeddedModels Normalized embedded models.
+     */
+    constructor(registryOrModelFiles, embeddedModels) {
+        this.#registry =
+            registryOrModelFiles instanceof HistoricalPcbScene3dModelRegistry
+                ? registryOrModelFiles
+                : new HistoricalPcbScene3dModelRegistry(
+                      registryOrModelFiles,
+                      embeddedModels
+                  )
+    }
+
+    /**
+     * Creates one model registry from session and embedded model assets.
+     * @param {{ name?: string, relativePath?: string, source?: string }[]} sessionFiles Session model files.
+     * @param {{ id?: string, checksum?: number | null, name?: string, format?: string, payloadText?: string, sourceStream?: string, transform?: object }[]} [embeddedModels] Embedded model payloads.
+     * @returns {PcbScene3dModelRegistry}
+     */
+    static create(sessionFiles, embeddedModels = []) {
+        return new PcbScene3dModelRegistry(
+            HistoricalPcbScene3dModelRegistry.create(
+                sessionFiles,
+                embeddedModels
+            )
+        )
+    }
+
+    /**
+     * Resolves the best available model for one component.
+     * @param {{ pattern?: string, source?: string, modelPath?: string }} component Component metadata.
+     * @returns {object | null}
+     */
+    resolveComponentModel(component) {
+        return this.#registry.resolveComponentModel(component)
+    }
+
+    /**
+     * Resolves a component-body model and exposes its signed STEP bounds.
+     * @param {{ modelId?: string, checksum?: number | null, name?: string }} componentBody Component-body metadata.
+     * @returns {object | null}
+     */
+    resolveComponentBodyModel(componentBody) {
+        const model = this.#registry.resolveComponentBodyModel(componentBody)
+        const sourceBoundsMil =
+            PcbScene3dModelRegistry.#resolveSourceBoundsMil(model)
+
+        return sourceBoundsMil ? { ...model, sourceBoundsMil } : model
+    }
+
+    /**
+     * Resolves a project-level full-board assembly model.
+     * @param {{ fileName?: string }} documentModel Document metadata.
+     * @returns {object | null}
+     */
+    resolveBoardAssemblyModel(documentModel) {
+        return this.#registry.resolveBoardAssemblyModel(documentModel)
+    }
+
+    /**
+     * Resolves signed bounds for one inline STEP model.
+     * @param {{ format?: string, payloadText?: string } | null} model Resolved model.
+     * @returns {{ minX: number, maxX: number, minY: number, maxY: number, minZ: number, maxZ: number } | null}
+     */
+    static #resolveSourceBoundsMil(model) {
+        const format = String(model?.format || '').toLowerCase()
+        if ((format !== 'step' && format !== 'stp') || !model?.payloadText) {
+            return null
+        }
+
+        const text = String(model.payloadText)
+        const points = []
+        const pointPattern =
+            /CARTESIAN_POINT\s*\(\s*(?:'[^']*'|[^,]*),\s*\(([^)]*)\)\s*\)/giu
+        let match = pointPattern.exec(text)
+
+        while (match) {
+            const coordinates = String(match[1] || '')
+                .split(',')
+                .slice(0, 3)
+                .map((value) => Number(value.trim()))
+            if (
+                coordinates.length === 3 &&
+                coordinates.every((value) => Number.isFinite(value))
+            ) {
+                points.push(coordinates)
+            }
+            match = pointPattern.exec(text)
+        }
+
+        if (points.length < 2) {
+            return null
+        }
+
+        const [firstPoint] = points
+        const bounds = {
+            minX: firstPoint[0],
+            maxX: firstPoint[0],
+            minY: firstPoint[1],
+            maxY: firstPoint[1],
+            minZ: firstPoint[2],
+            maxZ: firstPoint[2]
+        }
+        points.slice(1).forEach(([x, y, z]) => {
+            bounds.minX = Math.min(bounds.minX, x)
+            bounds.maxX = Math.max(bounds.maxX, x)
+            bounds.minY = Math.min(bounds.minY, y)
+            bounds.maxY = Math.max(bounds.maxY, y)
+            bounds.minZ = Math.min(bounds.minZ, z)
+            bounds.maxZ = Math.max(bounds.maxZ, z)
+        })
+
+        const scale = PcbScene3dModelRegistry.#resolveStepMilScale(text)
+        return Object.fromEntries(
+            Object.entries(bounds).map(([key, value]) => [key, value * scale])
+        )
+    }
+
+    /**
+     * Resolves the STEP length-unit scale to mils.
+     * @param {string} payloadText STEP text payload.
+     * @returns {number}
+     */
+    static #resolveStepMilScale(payloadText) {
+        const text = String(payloadText || '').toUpperCase()
+        if (/\bINCH\b|\.INCH\./u.test(text)) {
+            return MILS_PER_INCH
+        }
+
+        const siUnitMatch = text.match(
+            /SI_UNIT\s*\(\s*(\.[A-Z]+\.|\$)\s*,\s*\.METRE\.\s*\)/u
+        )
+        return (
+            PcbScene3dModelRegistry.#resolveSiPrefixScale(siUnitMatch?.[1]) *
+            MILS_PER_METER
+        )
+    }
+
+    /**
+     * Resolves one STEP SI length prefix to a meter multiplier.
+     * @param {string | undefined} prefix STEP SI prefix.
+     * @returns {number}
+     */
+    static #resolveSiPrefixScale(prefix) {
+        const scales = {
+            '.EXA.': 1e18,
+            '.PETA.': 1e15,
+            '.TERA.': 1e12,
+            '.GIGA.': 1e9,
+            '.MEGA.': 1e6,
+            '.KILO.': 1e3,
+            '.HECTO.': 1e2,
+            '.DECA.': 1e1,
+            $: 1,
+            '.DECI.': 1e-1,
+            '.CENTI.': 1e-2,
+            '.MILLI.': 1e-3,
+            '.MICRO.': 1e-6,
+            '.NANO.': 1e-9,
+            '.PICO.': 1e-12,
+            '.FEMTO.': 1e-15,
+            '.ATTO.': 1e-18
+        }
+
+        return scales[prefix || '.MILLI.'] ?? 1e-3
+    }
+}

package/src/convergence/PcbScene3dScenePreparator.mjs

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbScene3dBuilder } from './PcbScene3dBuilder.mjs'
+import { PcbScene3dModelRegistry } from './PcbScene3dModelRegistry.mjs'
+
+/**
+ * Builds converged renderer-ready scene descriptions for async preprocessing.
+ */
+export class PcbScene3dScenePreparator {
+    /**
+     * Builds one scene description with the converged registry and builder.
+     * @param {object} documentModel Parsed Altium document model.
+     * @param {{ sessionAssets?: object[], modelRegistry?: object | null, buildScene?: (documentModel: object, options: { modelRegistry: object }) => object }} [options] Scene preparation options.
+     * @returns {Promise<object>}
+     */
+    static async prepare(documentModel, options = {}) {
+        const modelRegistry =
+            options.modelRegistry ||
+            PcbScene3dModelRegistry.create(
+                options.sessionAssets || [],
+                Array.isArray(documentModel?.pcb?.embeddedModels)
+                    ? documentModel.pcb.embeddedModels
+                    : []
+            )
+        const buildScene =
+            options.buildScene ||
+            ((nextDocumentModel, buildOptions) =>
+                PcbScene3dBuilder.build(nextDocumentModel, buildOptions))
+
+        return buildScene(documentModel, { modelRegistry })
+    }
+}

package/src/extensions.mjs

@@ -4,9 +4,17 @@
 export * from 'circuitjson-toolkit/extensions'
 
 export { AltiumExtensionResolver } from './convergence/AltiumExtensionResolver.mjs'
+export { PcbScene3dBuilder } from './convergence/PcbScene3dBuilder.mjs'
+export { PcbScene3dModelRegistry } from './convergence/PcbScene3dModelRegistry.mjs'
+export { PcbScene3dScenePreparator } from './convergence/PcbScene3dScenePreparator.mjs'
 export { PcbSvgRenderer } from './convergence/PcbSvgRenderer.mjs'
 export { SchematicSvgRenderer } from './convergence/SchematicSvgRenderer.mjs'
 export * from './legacy-parser.mjs'
 export * from './legacy-netlist-query.mjs'
 export * from './legacy-renderers.mjs'
-export * from './legacy-scene3d.mjs'
+export {
+    AltiumScene3dAuthoredBodyAnchorAdapter,
+    PcbScene3dPackages,
+    PcbScene3dSummaryRenderer,
+    PcbScene3dTextBoxLayoutResolver
+} from './legacy-scene3d.mjs'