altium-toolkit 1.4.15 → 1.4.16

package/README.md

@@ -57,6 +57,10 @@ extension graphs retain their proven ownership instead of repeating defensive
 binary classification. See the
 [1.4.2 release notes](docs/release-notes-v1.4.2.md).
 
+Version 1.4.16 preserves validated authored STEP anchors during late geometric
+owner recovery and keeps board-space component yaw unchanged. See the
+[1.4.16 release notes](docs/release-notes-v1.4.16.md).
+
 Default `extensions: 'canonical'` keeps compact Altium summary metadata.
 Request the complete native read model with `extensions: 'full'`,
 `preserveRaw: true`, or `extensions: ['altium.native-model']`. Project batches
@@ -224,6 +228,7 @@ const legacyCircuitJson = AltiumParser.parseArrayBuffer(file.name, arrayBuffer)
 - [API](docs/api.md)
 - [Capabilities](docs/capabilities.md)
 - [Migration from 1.1.41](docs/migration.md)
+- [1.4.16 release notes](docs/release-notes-v1.4.16.md)
 - [1.4.2 release notes](docs/release-notes-v1.4.2.md)
 - [1.4.1 release notes](docs/release-notes-v1.4.1.md)
 - [1.4.0 release notes](docs/release-notes-v1.4.0.md)

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

@@ -0,0 +1,27 @@
+# altium-toolkit 1.4.16
+
+Version 1.4.16 preserves authored STEP anchors during late geometric owner
+recovery and leaves model-local orientation normalization to the 3D runtime.
+
+## 3D placement fidelity
+
+- Near-centroid surface-mount bodies retain their authored positions when the
+  recovered owner is geometrically unambiguous.
+- Height-backed owner recovery marks valid source anchors explicitly instead
+  of converting them into component-center offsets.
+- Geometric owner recovery preserves the component's authored board-space yaw;
+  it no longer infers package-specific half-turns from labels or pad topology.
+
+## Compatibility
+
+- Placement recovery remains based on generic body, pad, and footprint
+  geometry without project names, filenames, designators, or library strings.
+- Existing schematic colors, canvas borders, and public renderer signatures
+  remain unchanged.
+
+## Verification
+
+- Repository-owned synthetic tests cover near-centroid connectors,
+  height-backed authored anchors, and preserved switch yaw.
+- The complete package suite, formatting check, and npm package dry run are
+  required for release.

package/package.json

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

package/spec/altium-3d-late-owner-recovery.md

@@ -18,23 +18,23 @@ vendor names, or library identifiers.
   span.
 - Use component height agreement only as supporting evidence for nearby
   package ownership; height alone is insufficient.
-- Preserve a pad-centroid body position because it is already a valid authored
-  package center.
+- Preserve pad-centroid and nearby height-backed body positions because they
+  are valid authored source anchors, and mark height-backed anchors so the
+  runtime does not apply a second source-origin adjustment.
 - Center proven corner-origin and row-origin bodies on the component owner and
   retain the source offset as transform diagnostics.
 - Recompute component side and authored vertical standoff after late owner
   recovery.
-- Correct the half-turn of a four-pad tactile-switch model when its exact owner,
-  footprint topology, and tilted source frame jointly establish that package
-  class.
+- Preserve authored component yaw; model-local axis normalization belongs to
+  the runtime that has access to the imported mesh envelope.
 - Decline ambiguous matches.
 
 ## Verification
 
-- Focused synthetic tests use obfuscated package identities and cover pad
-  centroid, corner origin, row origin, late standoff, ambiguity rejection, and
-  tactile-switch yaw.
+- Focused synthetic tests use obfuscated package identities and cover exact and
+  near pad centroids, corner origin, row origin, authored source anchors, late
+  standoff, ambiguity rejection, and preserved component yaw.
 - The full toolkit test suite and formatting check pass.
 - A read-only probe of the supplied PCB must show real component designators
-  for the affected placements, owner-centered corner/row models, recovered
-  top-side standoff, and corrected switch yaw.
+  for the affected placements, owner-centered corner/row models, preserved
+  authored anchors, recovered top-side standoff, and source-authored yaw.

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.