pcb-scene3d-viewer 1.3.2 → 1.3.3

package/README.md

@@ -42,6 +42,11 @@ short-circuits non-subdividing copper-fill clipping without changing its
 observable geometry. See the
 [1.3.2 release notes](docs/release-notes-v1.3.2.md).
 
+Version 1.3.3 preserves validated STEP source anchors and avoids applying a
+second quarter-turn when the imported assembly envelope proves that its depth
+and height axes are already exchanged. See the
+[1.3.3 release notes](docs/release-notes-v1.3.3.md).
+
 ## CircuitJSON 1.1 convergence
 
 Version 1.2.2 accepts the common document and prepared-context shapes returned
@@ -150,6 +155,7 @@ const controller = new PcbScene3dController(viewportNode, document)
 
 - [API](docs/api.md)
 - [CircuitJSON usage](docs/circuitjson.md)
+- [1.3.3 release notes](docs/release-notes-v1.3.3.md)
 - [1.3.2 release notes](docs/release-notes-v1.3.2.md)
 - [1.3.1 release notes](docs/release-notes-v1.3.1.md)
 - [1.2.2 release notes](docs/release-notes-v1.2.2.md)

package/docs/model-format.md

@@ -186,6 +186,13 @@ Embedded STEP models can use:
 }
 ```
 
+For imported STEP assemblies, the runtime compares the fully assembled mesh
+envelope with an authored model-bounds projection before applying a separate
+quarter-turn around the model X axis. When the imported assembly has already
+exchanged its depth and height axes, the duplicate tilt is omitted. Toolkits
+can set `modelTransform.preserveSourceAnchor: true` when an authored body origin
+must remain fixed without requesting component-center recovery.
+
 ## Detail Primitives
 
 The runtime expects pre-normalized primitive lists for:

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

@@ -0,0 +1,28 @@
+# pcb-scene3d-viewer 1.3.3
+
+Version 1.3.3 improves external STEP placement when source-authored anchors and
+pre-oriented assemblies are present.
+
+## STEP placement fidelity
+
+- An explicit `preserveSourceAnchor` transform keeps a validated source body
+  origin fixed without activating component-center recovery.
+- Embedded STEP assemblies omit a duplicate quarter-turn only when their loaded
+  mesh envelope proves that the authored depth and height axes are already
+  exchanged.
+- Board-space component yaw and the original external-model asset remain
+  unchanged.
+
+## Compatibility
+
+- Detection uses source origin, projection metadata, mesh dimensions, and
+  bounded error thresholds; it does not inspect filenames, project identities,
+  component labels, or library names.
+- Existing scene colors, board geometry, and public APIs remain unchanged.
+
+## Verification
+
+- Repository-owned tests cover preserved source anchors and embedded-axis
+  normalization alongside the existing external-model placement suite.
+- The complete package suite, formatting check, and npm package dry run are
+  required for release.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.3.2",
+    "version": "1.3.3",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -39,6 +39,7 @@
         "docs/release-notes-v1.3.0.md",
         "docs/release-notes-v1.3.1.md",
         "docs/release-notes-v1.3.2.md",
+        "docs/release-notes-v1.3.3.md",
         "docs/model-format.md",
         "docs/testing.md",
         "spec",

package/src/PcbScene3dExternalModelSourceOriginPolicy.mjs

@@ -6,12 +6,13 @@ export class PcbScene3dExternalModelSourceOriginPolicy {
      * Checks whether an explicit owner anchor should keep source-origin repair
      * disabled. Translucent cover-sized bodies use corner-origin STEP data, so
      * they still need the embedded source-origin correction.
-     * @param {{ bodyOpacity?: number | string, modelTransform?: { ownerAnchorOffsetMil?: object }, projection?: { boundsMil?: { width?: number, depth?: number } } }} placement Placement metadata.
+     * @param {{ bodyOpacity?: number | string, modelTransform?: { ownerAnchorOffsetMil?: object, preserveSourceAnchor?: boolean }, projection?: { boundsMil?: { width?: number, depth?: number } } }} placement Placement metadata.
      * @returns {boolean}
      */
     static shouldSkipOwnerAnchoredAdjustment(placement) {
         return (
-            Boolean(placement?.modelTransform?.ownerAnchorOffsetMil) &&
+            (Boolean(placement?.modelTransform?.ownerAnchorOffsetMil) ||
+                placement?.modelTransform?.preserveSourceAnchor === true) &&
             !PcbScene3dExternalModelSourceOriginPolicy.#isTransparentCoverSizedPlacement(
                 placement
             )

package/src/PcbScene3dExternalModels.mjs

@@ -362,7 +362,16 @@ export class PcbScene3dExternalModels {
             viewCompensationGroup
         )
         const modelTransform = placement?.modelTransform || {}
-        const modelRotation = modelTransform.rotationDeg || {}
+        const authoredModelRotation = modelTransform.rotationDeg || {}
+        const modelRotation =
+            PcbScene3dExternalModels.#resolveEmbeddedModelRotation(
+                placement,
+                modelGroup,
+                authoredModelRotation
+            )
+        if (modelRotation !== authoredModelRotation) {
+            modelGroup.userData.scene3dEmbeddedAxisTiltRepair = true
+        }
         const modelOffset =
             PcbScene3dExternalModels.#resolveModelOffset(modelTransform)
         const sourceOriginAdjustment =
@@ -595,6 +604,73 @@ export class PcbScene3dExternalModels {
         }
     }
 
+    /**
+     * Removes a duplicated quarter-turn when the imported STEP assembly has
+     * already exchanged its authored depth and height axes. Native STEP point
+     * envelopes describe pre-assembly coordinates, while OCCT returns the
+     * fully placed mesh, so comparing both frames is required before applying
+     * the separate Altium body tilt.
+     * @param {{ externalModel?: { origin?: string }, projection?: { source?: string, boundsMil?: { depth?: number, height?: number } } }} placement Placement metadata.
+     * @param {{ userData?: { scene3dSourceBoundsMil?: { sizeY?: number, sizeZ?: number } } }} modelGroup Loaded model group.
+     * @param {{ x?: number, y?: number, z?: number }} modelRotation Authored model rotation.
+     * @returns {{ x?: number, y?: number, z?: number }}
+     */
+    static #resolveEmbeddedModelRotation(placement, modelGroup, modelRotation) {
+        const sourceBounds = modelGroup?.userData?.scene3dSourceBoundsMil || {}
+        const projectionBounds = placement?.projection?.boundsMil || {}
+        const sourceY = Math.abs(Number(sourceBounds.sizeY || 0))
+        const sourceZ = Math.abs(Number(sourceBounds.sizeZ || 0))
+        const projectedDepth = Math.abs(Number(projectionBounds.depth || 0))
+        const projectedHeight = Math.abs(Number(projectionBounds.height || 0))
+        const tilt = PcbScene3dExternalModels.#normalizeAngle(modelRotation?.x)
+        const directError =
+            PcbScene3dExternalModels.#relativeDimensionError(
+                sourceY,
+                projectedDepth
+            ) +
+            PcbScene3dExternalModels.#relativeDimensionError(
+                sourceZ,
+                projectedHeight
+            )
+        const exchangedError =
+            PcbScene3dExternalModels.#relativeDimensionError(
+                sourceY,
+                projectedHeight
+            ) +
+            PcbScene3dExternalModels.#relativeDimensionError(
+                sourceZ,
+                projectedDepth
+            )
+
+        if (
+            String(placement?.externalModel?.origin || '').toLowerCase() !==
+                'embedded' ||
+            String(placement?.projection?.source || '').toLowerCase() !==
+                'model-bounds' ||
+            (tilt !== 90 && tilt !== 270) ||
+            Math.min(sourceY, sourceZ, projectedDepth, projectedHeight) <= 0 ||
+            Math.max(projectedDepth, projectedHeight) /
+                Math.min(projectedDepth, projectedHeight) <
+                1.25 ||
+            exchangedError > 0.2 ||
+            directError - exchangedError < 0.5
+        ) {
+            return modelRotation
+        }
+
+        return { ...modelRotation, x: 0 }
+    }
+
+    /**
+     * Measures a scale-independent dimension mismatch.
+     * @param {number} actual Imported dimension.
+     * @param {number} expected Authored dimension.
+     * @returns {number}
+     */
+    static #relativeDimensionError(actual, expected) {
+        return Math.abs(actual - expected) / Math.max(actual, expected, 1)
+    }
+
     /**
      * Checks whether source Z is the model's intentional edge-extension axis
      * instead of a square-package source-origin bias.