altium-toolkit 1.4.15 → 1.4.17

package/spec/library-scope.md

@@ -7,8 +7,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 # Library Scope
 
 Altium Toolkit provides reusable native Altium parsing behind the common ECAD
-toolkit API. Canonical results use CircuitJSON; source-only facts and all
-historical 1.1.41 contracts remain explicit Altium extensions.
+toolkit API. Canonical results use CircuitJSON; source-only facts and historical
+1.1.41 APIs remain explicit Altium extensions with maintained implementations.
 
 ## In Scope
 
@@ -18,7 +18,8 @@ historical 1.1.41 contracts remain explicit Altium extensions.
   reusable document contexts
 - Shared CircuitJSON render, interaction, query, manufacturing, simulation,
   and data-only 3D scene services
-- Exact `/extensions` preservation of audited Altium 1.1.41 behavior
+- Preservation of audited Altium 1.1.41 `/extensions` API signatures and public
+  asset entrypoints and targets, with tested bug fixes and performance improvements
 - `.SchDoc`, `.PcbDoc`, `.PCBDwf`, `.SchLib`, `.PcbLib`, `.PrjPcb`, `.PrjScr`,
   and `.IntLib` parsing from `ArrayBuffer`
 - OLE and binary stream helpers needed by parser recovery

package/src/convergence/AltiumWorkerClient.mjs

@@ -74,18 +74,9 @@ export class AltiumWorkerClient {
      */
     static #client() {
         if (!client) {
-            client = new ParserWorkerClient({
-                createWorker: () => {
-                    const WorkerConstructor = globalThis.Worker
-                    return Reflect.construct(WorkerConstructor, [
-                        new URL(
-                            '../workers/parser.worker.mjs',
-                            import.meta.url
-                        ),
-                        { type: 'module' }
-                    ])
-                }
-            })
+            client = ParserWorkerClient.fromWorkerUrl(
+                new URL('../workers/parser.worker.mjs', import.meta.url)
+            )
         }
         return client
     }

package/src/ui/AltiumScene3dBodyPlacementIndex.mjs

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/** Matches placements to authored bodies within one adapter invocation. */
+export class AltiumScene3dBodyPlacementIndex {
+    #cells = new Map()
+
+    /**
+     * Groups authored body positions into one-mil cells in source order.
+     * @param {object[]} componentBodies Source component bodies.
+     */
+    constructor(componentBodies) {
+        componentBodies.forEach((componentBody, order) => {
+            const x = Number(componentBody?.positionMil?.x || 0)
+            const y = Number(componentBody?.positionMil?.y || 0)
+            if (!Number.isFinite(x) || !Number.isFinite(y)) return
+            const key = `${Math.floor(x)}:${Math.floor(y)}`
+            const cell = this.#cells.get(key) || []
+            cell.push({ componentBody, x, y, order })
+            this.#cells.set(key, cell)
+        })
+    }
+
+    /**
+     * Selects by identity affinity, distance, then original source order.
+     * @param {object} placement Built external placement.
+     * @returns {object | null}
+     */
+    resolve(placement) {
+        const x = Number(placement?.bodyPositionMil?.x || 0)
+        const y = Number(placement?.bodyPositionMil?.y || 0)
+        if (!Number.isFinite(x) || !Number.isFinite(y)) return null
+        const placementText = AltiumScene3dBodyPlacementIndex.#identityText([
+            placement?.designator,
+            placement?.externalModel?.name
+        ])
+        let best = null
+        let bestScore = -1
+        let bestDistance = Infinity
+        for (const dx of [-1, 0, 1]) {
+            for (const dy of [-1, 0, 1]) {
+                const cell =
+                    this.#cells.get(
+                        `${Math.floor(x) + dx}:${Math.floor(y) + dy}`
+                    ) || []
+                for (const candidate of cell) {
+                    const distance = Math.hypot(
+                        x - candidate.x,
+                        y - candidate.y
+                    )
+                    if (!(distance <= 0.01)) continue
+                    const bodyText =
+                        AltiumScene3dBodyPlacementIndex.#identityText([
+                            candidate.componentBody?.identifier,
+                            candidate.componentBody?.name
+                        ])
+                    const score =
+                        placementText &&
+                        bodyText &&
+                        placementText.includes(bodyText)
+                            ? bodyText.length
+                            : 0
+                    if (
+                        best &&
+                        !(
+                            score > bestScore ||
+                            (score === bestScore &&
+                                (distance < bestDistance ||
+                                    (distance === bestDistance &&
+                                        candidate.order < best.order)))
+                        )
+                    )
+                        continue
+                    best = candidate
+                    bestScore = score
+                    bestDistance = distance
+                }
+            }
+        }
+        return best?.componentBody || null
+    }
+
+    /**
+     * Normalizes metadata with the placement adapter's identity convention.
+     * @param {unknown[]} values Source identity fields.
+     * @returns {string}
+     */
+    static #identityText(values) {
+        return values
+            .map((value) => String(value || '').toLowerCase())
+            .join(' ')
+            .replace(/\.[a-z0-9]+\\b/g, '')
+            .replace(/[^a-z0-9]+/g, '')
+    }
+}

package/src/ui/AltiumScene3dComponentBodyAdapter.mjs

@@ -1,3 +1,4 @@
+import { PcbScene3dComponentGeometryResolver } from './PcbScene3dComponentGeometryResolver.mjs'
 import { PcbScene3dPadLocalSpanResolver } from './PcbScene3dPadLocalSpanResolver.mjs'
 
 const REFINABLE_FAMILIES = new Set(['chip', 'diode', 'generic', 'ic', 'sot'])
@@ -33,6 +34,10 @@ export class AltiumScene3dComponentBodyAdapter {
             return sceneDescription
         }
 
+        const componentGeometry = new PcbScene3dComponentGeometryResolver(
+            sourceComponents,
+            pads
+        )
         const sourceByDesignator = new Map(
             sourceComponents.map((component) => [
                 String(component?.designator || ''),
@@ -46,7 +51,7 @@ export class AltiumScene3dComponentBodyAdapter {
                 AltiumScene3dComponentBodyAdapter.#refineComponent(
                     component,
                     sourceByDesignator.get(String(component?.designator || '')),
-                    pads
+                    componentGeometry
                 )
             )
         }
@@ -56,10 +61,10 @@ export class AltiumScene3dComponentBodyAdapter {
      * Refines one procedural component body when nearby pads overinflated it.
      * @param {object} component Scene component.
      * @param {object | undefined} sourceComponent Source PCB component.
-     * @param {object[]} pads Source PCB pads.
+     * @param {PcbScene3dComponentGeometryResolver} componentGeometry Build-scoped geometry.
      * @returns {object}
      */
-    static #refineComponent(component, sourceComponent, pads) {
+    static #refineComponent(component, sourceComponent, componentGeometry) {
         const family = String(component?.body?.family || '')
         if (
             component?.externalModel ||
@@ -72,7 +77,7 @@ export class AltiumScene3dComponentBodyAdapter {
         const span = AltiumScene3dComponentBodyAdapter.#ownedPadSpan(
             sourceComponent,
             component.mountSide,
-            pads
+            componentGeometry
         )
         const size = component?.body?.sizeMil || {}
         if (
@@ -99,42 +104,17 @@ export class AltiumScene3dComponentBodyAdapter {
      * Resolves the owned surface-pad span for one source component.
      * @param {object} component Source component.
      * @param {string} mountSide Component mount side.
-     * @param {object[]} pads Source PCB pads.
+     * @param {PcbScene3dComponentGeometryResolver} componentGeometry Build-scoped geometry.
      * @returns {{ width: number, depth: number } | null}
      */
-    static #ownedPadSpan(component, mountSide, pads) {
-        const componentIndex = Number(component?.componentIndex)
-        if (!Number.isFinite(componentIndex)) {
-            return null
-        }
-
-        const ownedPads = pads.filter(
-            (pad) => Number(pad?.componentIndex) === componentIndex
-        )
-        const surfacePads = ownedPads.filter((pad) =>
-            AltiumScene3dComponentBodyAdapter.#isSurfacePad(pad, mountSide)
-        )
-        const spanPads = surfacePads.length ? surfacePads : ownedPads
-
+    static #ownedPadSpan(component, mountSide, componentGeometry) {
         return PcbScene3dPadLocalSpanResolver.resolve(
             component,
-            spanPads,
+            componentGeometry.componentPads(component, mountSide),
             mountSide
         )
     }
 
-    /**
-     * Checks whether one pad belongs to the component's mounted surface.
-     * @param {object} pad Source pad.
-     * @param {string} mountSide Component mount side.
-     * @returns {boolean}
-     */
-    static #isSurfacePad(pad, mountSide) {
-        return String(mountSide || '').toLowerCase() === 'bottom'
-            ? Boolean(pad?.hasBottomPasteMaskOpening)
-            : Boolean(pad?.hasTopPasteMaskOpening)
-    }
-
     /**
      * Checks whether the current body is clearly larger than owned pads.
      * @param {object} size Current body size.

package/src/ui/AltiumScene3dExternalPlacementAdapter.mjs

@@ -1,3 +1,4 @@
+import { AltiumScene3dBodyPlacementIndex } from './AltiumScene3dBodyPlacementIndex.mjs'
 import { AltiumScene3dIdentityTokens } from './AltiumScene3dIdentityTokens.mjs'
 import { AltiumScene3dAuthoredConnectorYawPolicy } from './AltiumScene3dAuthoredConnectorYawPolicy.mjs'
 import { AltiumScene3dPlacementRotationPolicy } from './AltiumScene3dPlacementRotationPolicy.mjs'
@@ -59,6 +60,7 @@ export class AltiumScene3dExternalPlacementAdapter {
             ])
         )
 
+        const bodyIndex = new AltiumScene3dBodyPlacementIndex(componentBodies)
         const repairedScene = {
             ...sceneDescription,
             externalPlacements: sceneDescription.externalPlacements
@@ -67,7 +69,7 @@ export class AltiumScene3dExternalPlacementAdapter {
                         placement,
                         components,
                         componentByDesignator,
-                        componentBodies,
+                        bodyIndex,
                         pads,
                         sceneDescription?.board
                     )
@@ -86,7 +88,7 @@ export class AltiumScene3dExternalPlacementAdapter {
         placement,
         components,
         componentByDesignator,
-        componentBodies,
+        bodyIndex,
         pads,
         board
     ) {
@@ -101,11 +103,7 @@ export class AltiumScene3dExternalPlacementAdapter {
             return placement
         }
 
-        const componentBody =
-            AltiumScene3dExternalPlacementAdapter.#resolveComponentBody(
-                placement,
-                componentBodies
-            )
+        const componentBody = bodyIndex.resolve(placement)
         const currentComponent = componentByDesignator.get(
             String(placement?.designator || '')
         )
@@ -1542,60 +1540,6 @@ export class AltiumScene3dExternalPlacementAdapter {
         ]
     }
 
-    /**
-     * Resolves the source component body row for one placement.
-     * @param {object} placement External model placement.
-     * @param {object[]} componentBodies Source component body rows.
-     * @returns {object | null}
-     */
-    static #resolveComponentBody(placement, componentBodies) {
-        const candidates = componentBodies
-            .map((componentBody) => ({
-                componentBody,
-                distance:
-                    AltiumScene3dExternalPlacementAdapter.#distanceBetweenPoints(
-                        placement?.bodyPositionMil,
-                        componentBody?.positionMil
-                    ),
-                identityScore:
-                    AltiumScene3dExternalPlacementAdapter.#bodyPlacementIdentityScore(
-                        placement,
-                        componentBody
-                    )
-            }))
-            .filter((candidate) => candidate.distance <= 0.01)
-            .sort(
-                (left, right) =>
-                    right.identityScore - left.identityScore ||
-                    left.distance - right.distance
-            )
-
-        return candidates[0]?.componentBody || null
-    }
-
-    /**
-     * Scores whether a source body row belongs to one placement.
-     * @param {object} placement External model placement.
-     * @param {object} componentBody Source component body.
-     * @returns {number}
-     */
-    static #bodyPlacementIdentityScore(placement, componentBody) {
-        const placementText =
-            AltiumScene3dExternalPlacementAdapter.#normalizeIdentityText([
-                placement?.designator,
-                placement?.externalModel?.name
-            ])
-        const bodyText =
-            AltiumScene3dExternalPlacementAdapter.#normalizeIdentityText([
-                componentBody?.identifier,
-                componentBody?.name
-            ])
-
-        return placementText && bodyText && placementText.includes(bodyText)
-            ? bodyText.length
-            : 0
-    }
-
     /**
      * Repairs model-local Altium rotation signs for embedded body transforms.
      * @param {object | null | undefined} modelTransform Placement transform.

package/src/ui/AltiumScene3dGeometricOwnerRecovery.mjs

@@ -13,6 +13,7 @@ export class AltiumScene3dGeometricOwnerRecovery {
     static #COMPONENT_INDEX_CELL_MIL = 500
     static #MINIMUM_SCORE = 12
     static #MINIMUM_SCORE_MARGIN = 4
+    static #PAD_CENTROID_TOLERANCE_MIL = 12
 
     /**
      * Applies geometry-backed owner recovery to final external placements.
@@ -108,14 +109,7 @@ export class AltiumScene3dGeometricOwnerRecovery {
         const currentOwner = context.componentsByDesignator.get(
             String(placement?.designator || '')
         )
-        if (currentOwner) {
-            return AltiumScene3dGeometricOwnerRecovery.#correctTactileYaw(
-                placement,
-                currentOwner,
-                body,
-                context.geometryByComponent.get(currentOwner)
-            )
-        }
+        if (currentOwner) return placement
 
         const match =
             AltiumScene3dGeometricOwnerRecovery.#resolveGeometricOwner(
@@ -125,18 +119,12 @@ export class AltiumScene3dGeometricOwnerRecovery {
             )
         if (!match) return placement
 
-        const recovered = AltiumScene3dGeometricOwnerRecovery.#withOwner(
+        return AltiumScene3dGeometricOwnerRecovery.#withOwner(
             placement,
             body,
             match,
             context.board
         )
-        return AltiumScene3dGeometricOwnerRecovery.#correctTactileYaw(
-            recovered,
-            match.component,
-            body,
-            context.geometryByComponent.get(match.component)
-        )
     }
 
     /**
@@ -329,7 +317,7 @@ export class AltiumScene3dGeometricOwnerRecovery {
 
         if (
             centroidDistance <=
-            AltiumScene3dGeometricOwnerRecovery.#ANCHOR_TOLERANCE_MIL
+            AltiumScene3dGeometricOwnerRecovery.#PAD_CENTROID_TOLERANCE_MIL
         ) {
             score = 24
             mode = 'pad-centroid'
@@ -570,7 +558,9 @@ export class AltiumScene3dGeometricOwnerRecovery {
         const component = match.component
         const mountSide =
             AltiumScene3dGeometricOwnerRecovery.#componentSide(component)
-        const preserveAnchor = match.mode === 'pad-centroid'
+        const preserveAnchor =
+            match.mode === 'pad-centroid' ||
+            match.mode === 'height-backed-origin'
         const offset = {
             x:
                 Number(placement?.bodyPositionMil?.x || 0) -
@@ -590,6 +580,10 @@ export class AltiumScene3dGeometricOwnerRecovery {
             dzMil: verticalOffset
         }
 
+        if (match.mode === 'height-backed-origin') {
+            modelTransform.preserveSourceAnchor = true
+        }
+
         if (!preserveAnchor) {
             modelTransform.ownerAnchorOffsetMil = offset
             modelTransform.offsetMil = { x: 0, y: 0, z: verticalOffset }
@@ -622,107 +616,6 @@ export class AltiumScene3dGeometricOwnerRecovery {
         }
     }
 
-    /**
-     * Corrects the source-frame half-turn for a four-pad tactile switch.
-     * @param {object} placement External placement.
-     * @param {object} component Resolved owner.
-     * @param {object} body Source body.
-     * @param {object | null} geometry Precomputed owner pad geometry.
-     * @returns {object}
-     */
-    static #correctTactileYaw(placement, component, body, geometry) {
-        const identity = [
-            component?.designator,
-            component?.description,
-            component?.provenance?.footprintDescription
-        ]
-            .map((value) => String(value || ''))
-            .join(' ')
-        const sourceTilt = AltiumScene3dGeometricOwnerRecovery.#normalizeAngle(
-            body?.modelRotationDeg?.x
-        )
-        const currentYaw = AltiumScene3dGeometricOwnerRecovery.#normalizeAngle(
-            placement?.rotationDeg
-        )
-        const componentYaw =
-            AltiumScene3dGeometricOwnerRecovery.#normalizeAngle(
-                component?.rotation
-            )
-        const isTactileSwitch =
-            /(?:^|[^a-z0-9])(?:tact|tactile|pushbutton)(?:$|[^a-z0-9])/i.test(
-                identity
-            ) &&
-            AltiumScene3dGeometricOwnerRecovery.#hasTactileContactTopology(
-                geometry
-            )
-
-        if (
-            !isTactileSwitch ||
-            (sourceTilt !== 90 && sourceTilt !== 270) ||
-            currentYaw !== componentYaw
-        ) {
-            return placement
-        }
-
-        return {
-            ...placement,
-            rotationDeg: AltiumScene3dGeometricOwnerRecovery.#normalizeAngle(
-                currentYaw + 180
-            )
-        }
-    }
-
-    /**
-     * Detects a two-by-two tactile contact layout with two duplicated routed
-     * contact pairs aligned along one footprint axis.
-     * @param {object | null} geometry Precomputed owner pad geometry.
-     * @returns {boolean}
-     */
-    static #hasTactileContactTopology(geometry) {
-        if (
-            geometry?.pads?.length !== 4 ||
-            geometry.xCount !== 2 ||
-            geometry.yCount !== 2
-        ) {
-            return false
-        }
-
-        const groups = new Map()
-        for (const pad of geometry.localPads) {
-            const sourcePad = pad.source
-            const netName = String(sourcePad?.netName || '').trim()
-            const netIndex = sourcePad?.netIndex
-            const contactKey = netName
-                ? `name:${netName}`
-                : netIndex !== null &&
-                    netIndex !== undefined &&
-                    netIndex !== '' &&
-                    Number.isFinite(Number(netIndex))
-                  ? `index:${Number(netIndex)}`
-                  : ''
-            if (!contactKey) return false
-            groups.set(contactKey, [...(groups.get(contactKey) || []), pad])
-        }
-        if (
-            groups.size !== 2 ||
-            [...groups.values()].some((group) => group.length !== 2)
-        ) {
-            return false
-        }
-
-        return [...groups.values()].every((group) => {
-            const sameX =
-                AltiumScene3dGeometricOwnerRecovery.#distinctCoordinateCount(
-                    group.map((pad) => Number(pad?.x || 0))
-                ) === 1
-            const sameY =
-                AltiumScene3dGeometricOwnerRecovery.#distinctCoordinateCount(
-                    group.map((pad) => Number(pad?.y || 0))
-                ) === 1
-            return sameX || sameY
-        })
-    }
-
     /**
      * Resolves a body vertical offset after a late owner recovery.
      * @param {object} body Source body.