pcb-scene3d-viewer 1.1.1 → 1.1.2

package/src/PcbScene3dExternalModels.mjs

@@ -3,6 +3,7 @@ import { PcbScene3dBoardAssemblyPlacement } from './PcbScene3dBoardAssemblyPlace
 import { PcbScene3dBoardAssemblyTransform } from './PcbScene3dBoardAssemblyTransform.mjs'
 import { PcbScene3dBufferAttributeFactory } from './PcbScene3dBufferAttributeFactory.mjs'
 import { PcbScene3dExternalModelLoadOrder } from './PcbScene3dExternalModelLoadOrder.mjs'
+import { PcbScene3dModelBounds } from './PcbScene3dModelBounds.mjs'
 import { PcbScene3dMountRig } from './PcbScene3dMountRig.mjs'
 import { PcbScene3dStepLoader } from './PcbScene3dStepLoader.mjs'
 import { PcbScene3dViewCompensation } from './PcbScene3dViewCompensation.mjs'
@@ -270,10 +271,18 @@ export class PcbScene3dExternalModels {
         const mountRig = PcbScene3dMountRig.create(THREE, placement)
         const wrapperGroup = mountRig.rootGroup
         const viewCompensationGroup = new THREE.Group()
+        const adjustmentGroup = new THREE.Group()
+        const designator = String(placement?.designator || 'component')
         wrapperGroup.userData.scene3dSelection = {
-            designator: String(placement?.designator || 'component'),
+            designator,
             sourceType: 'external-model'
         }
+        adjustmentGroup.userData.scene3dAdjustmentTarget = true
+        adjustmentGroup.userData.scene3dAdjustmentDesignator = designator
+        adjustmentGroup.userData.scene3dAdjustmentBaseline =
+            PcbScene3dExternalModels.#normalizeModelTransform(
+                placement?.modelTransform || {}
+            )
         viewCompensationGroup.userData.scene3dViewCompensation = true
         viewCompensationGroup.userData.scene3dSourceFrameScale =
             PcbScene3dExternalModels.#resolveSourceFrameScale(placement)
@@ -312,7 +321,7 @@ export class PcbScene3dExternalModels {
         modelGroup.position.set(
             modelOffset.x + sourceOriginAdjustment.offset.x,
             modelOffset.y + sourceOriginAdjustment.offset.y,
-            modelOffset.z + sourceOriginAdjustment.offset.z
+            sourceOriginAdjustment.offset.z
         )
         PcbScene3dExternalModels.#applyModelRotation(
             THREE,
@@ -323,7 +332,10 @@ export class PcbScene3dExternalModels {
             modelGroup,
             PcbScene3dExternalModels.#resolveModelScale(modelTransform)
         )
-        mountRig.faceGroup.add(modelGroup)
+        PcbScene3dModelBounds.seatOnMountPlane(THREE, modelGroup)
+        modelGroup.position.z += modelOffset.z
+        adjustmentGroup.add(modelGroup)
+        mountRig.faceGroup.add(adjustmentGroup)
 
         return wrapperGroup
     }
@@ -478,18 +490,50 @@ export class PcbScene3dExternalModels {
         }
 
         if (Math.abs(centerX) > maxDimension * 0.2) {
+            if (centerX * centerZ <= 0) {
+                return {
+                    offset: { x: centerX * 2, y: -centerZ * 2, z: 0 },
+                    rotationDeg: { x: 0, y: 0, z: 180 }
+                }
+            }
+
             return {
                 offset: { x: 0, y: 0, z: 0 },
                 rotationDeg: { x: 0, y: 0, z: 180 }
             }
         }
 
+        if (PcbScene3dExternalModels.#isDominantSourceZExtension(bounds)) {
+            return PcbScene3dExternalModels.#emptySourceOriginAdjustment()
+        }
+
         return {
             offset: { x: 0, y: centerZ * 2, z: 0 },
             rotationDeg: { x: 0, y: 0, z: 0 }
         }
     }
 
+    /**
+     * Checks whether source Z is the model's intentional edge-extension axis
+     * instead of a square-package source-origin bias.
+     * @param {{ sizeX?: number, sizeY?: number, sizeZ?: number } | null} bounds Source bounds.
+     * @returns {boolean}
+     */
+    static #isDominantSourceZExtension(bounds) {
+        const sourceZ = Math.abs(Number(bounds?.sizeZ || 0))
+        const lateralSize = Math.max(
+            Math.abs(Number(bounds?.sizeX || 0)),
+            Math.abs(Number(bounds?.sizeY || 0))
+        )
+
+        return (
+            Number.isFinite(sourceZ) &&
+            Number.isFinite(lateralSize) &&
+            lateralSize > 0 &&
+            sourceZ > lateralSize * 2
+        )
+    }
+
     /**
      * Returns the neutral embedded-source adjustment shape.
      * @returns {{ offset: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number } }}
@@ -711,7 +755,7 @@ export class PcbScene3dExternalModels {
             ? { meshPayloads: model.preparedMeshPayloads }
             : await stepLoader.loadModel(model)
         const group = new THREE.Group()
-        const sourceBounds = PcbScene3dExternalModels.#measureSourceBoundsMil(
+        const sourceBounds = PcbScene3dModelBounds.measureSourceBoundsMil(
             loadedModel.meshPayloads
         )
         group.scale.setScalar(1000)
@@ -766,71 +810,6 @@ export class PcbScene3dExternalModels {
         return group
     }
 
-    /**
-     * Measures raw STEP mesh bounds in mil before the group-level unit scale is
-     * applied.
-     * @param {{ positions?: ArrayLike<number> }[]} meshPayloads STEP mesh payloads.
-     * @returns {{ minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, centerX: number, centerY: number, centerZ: number, sizeX: number, sizeY: number, sizeZ: number } | null}
-     */
-    static #measureSourceBoundsMil(meshPayloads) {
-        let minX = Number.POSITIVE_INFINITY
-        let minY = Number.POSITIVE_INFINITY
-        let minZ = Number.POSITIVE_INFINITY
-        let maxX = Number.NEGATIVE_INFINITY
-        let maxY = Number.NEGATIVE_INFINITY
-        let maxZ = Number.NEGATIVE_INFINITY
-
-        ;(Array.isArray(meshPayloads) ? meshPayloads : []).forEach(
-            (meshPayload) => {
-                ;(PcbScene3dBufferAttributeFactory.isNumberSequence(
-                    meshPayload?.positions
-                )
-                    ? meshPayload.positions
-                    : []
-                ).forEach((value, index) => {
-                    const numericValue = Number(value || 0) * 1000
-
-                    if (index % 3 === 0) {
-                        minX = Math.min(minX, numericValue)
-                        maxX = Math.max(maxX, numericValue)
-                    } else if (index % 3 === 1) {
-                        minY = Math.min(minY, numericValue)
-                        maxY = Math.max(maxY, numericValue)
-                    } else {
-                        minZ = Math.min(minZ, numericValue)
-                        maxZ = Math.max(maxZ, numericValue)
-                    }
-                })
-            }
-        )
-
-        if (
-            !Number.isFinite(minX) ||
-            !Number.isFinite(minY) ||
-            !Number.isFinite(minZ) ||
-            !Number.isFinite(maxX) ||
-            !Number.isFinite(maxY) ||
-            !Number.isFinite(maxZ)
-        ) {
-            return null
-        }
-
-        return {
-            minX,
-            minY,
-            minZ,
-            maxX,
-            maxY,
-            maxZ,
-            centerX: (minX + maxX) / 2,
-            centerY: (minY + maxY) / 2,
-            centerZ: (minZ + maxZ) / 2,
-            sizeX: maxX - minX,
-            sizeY: maxY - minY,
-            sizeZ: maxZ - minZ
-        }
-    }
-
     /**
      * Builds the material set for one STEP mesh and assigns face-color groups
      * when the importer exposes them.
@@ -895,11 +874,17 @@ export class PcbScene3dExternalModels {
      * @returns {any}
      */
     static #createStepMaterial(THREE, color) {
-        return new THREE.MeshStandardMaterial({
+        const options = {
             color,
             roughness: 0.56,
             metalness: 0.14
-        })
+        }
+
+        if (THREE.DoubleSide !== undefined) {
+            options.side = THREE.DoubleSide
+        }
+
+        return new THREE.MeshStandardMaterial(options)
     }
 
     /**

package/src/PcbScene3dGeometryBoundsResolver.mjs

@@ -0,0 +1,78 @@
+/**
+ * Resolves lightweight XY bounds for Three.js-style geometry attributes.
+ */
+export class PcbScene3dGeometryBoundsResolver {
+    /**
+     * Resolves the XY bounds for one position attribute.
+     * @param {{ count?: number, getX?: (index: number) => number, getY?: (index: number) => number }} position Position attribute.
+     * @returns {{ minX: number, maxX: number, minY: number, maxY: number }}
+     */
+    static resolvePositionBounds(position) {
+        const bounds = {
+            minX: Infinity,
+            maxX: -Infinity,
+            minY: Infinity,
+            maxY: -Infinity
+        }
+
+        for (let index = 0; index < Number(position?.count || 0); index += 1) {
+            const x = Number(position.getX?.(index) || 0)
+            const y = Number(position.getY?.(index) || 0)
+
+            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)
+        }
+
+        return bounds
+    }
+
+    /**
+     * Returns true when one bounds box overlaps any entry bounds.
+     * @param {{ minX: number, maxX: number, minY: number, maxY: number }} bounds Bounds to test.
+     * @param {{ bounds?: { minX: number, maxX: number, minY: number, maxY: number } }[]} entries Entries with bounds.
+     * @param {number} [epsilon] Overlap tolerance.
+     * @returns {boolean}
+     */
+    static overlapsAny(bounds, entries, epsilon = 0) {
+        return (Array.isArray(entries) ? entries : []).some((entry) =>
+            PcbScene3dGeometryBoundsResolver.#boundsOverlap(
+                bounds,
+                entry?.bounds,
+                epsilon
+            )
+        )
+    }
+
+    /**
+     * Returns true when one position attribute cannot overlap any entry bounds.
+     * @param {{ count?: number, getX?: (index: number) => number, getY?: (index: number) => number }} position Position attribute.
+     * @param {{ bounds?: { minX: number, maxX: number, minY: number, maxY: number } }[]} entries Entries with bounds.
+     * @param {number} [epsilon] Overlap tolerance.
+     * @returns {boolean}
+     */
+    static missesAllPositionBounds(position, entries, epsilon = 0) {
+        return !PcbScene3dGeometryBoundsResolver.overlapsAny(
+            PcbScene3dGeometryBoundsResolver.resolvePositionBounds(position),
+            entries,
+            epsilon
+        )
+    }
+
+    /**
+     * Returns true when two bounding boxes overlap.
+     * @param {{ minX: number, maxX: number, minY: number, maxY: number }} first First bounds.
+     * @param {{ minX: number, maxX: number, minY: number, maxY: number } | undefined} second Second bounds.
+     * @param {number} epsilon Overlap tolerance.
+     * @returns {boolean}
+     */
+    static #boundsOverlap(first, second, epsilon) {
+        return (
+            first.minX <= Number(second?.maxX) + epsilon &&
+            first.maxX >= Number(second?.minX) - epsilon &&
+            first.minY <= Number(second?.maxY) + epsilon &&
+            first.maxY >= Number(second?.minY) - epsilon
+        )
+    }
+}

package/src/PcbScene3dModelBounds.mjs

@@ -0,0 +1,267 @@
+import { PcbScene3dBufferAttributeFactory } from './PcbScene3dBufferAttributeFactory.mjs'
+
+/**
+ * Measures and normalizes loaded 3D model bounds.
+ */
+export class PcbScene3dModelBounds {
+    static #POSITION_EPSILON = 1e-9
+    static #SUPPORT_BUCKET_MIL = 5
+    static #LOWER_SUPPORT_WINDOW_RATIO = 0.14
+    static #LOWER_SUPPORT_WINDOW_MAX_MIL = 30
+    static #LOWER_SUPPORT_MIN_GAP_MIL = 1
+    static #SUPPORT_BUCKET_MIN_DENSITY = 0.2
+
+    /**
+     * Seats one transformed model group on its local mount plane.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ position?: { z?: number }, updateMatrixWorld?: (force?: boolean) => void }} modelGroup Model group.
+     * @returns {void}
+     */
+    static seatOnMountPlane(THREE, modelGroup) {
+        if (!THREE?.Box3 || !modelGroup?.position) {
+            return
+        }
+
+        modelGroup.updateMatrixWorld?.(true)
+        const bounds = new THREE.Box3().setFromObject(modelGroup)
+        const currentZ = Number(modelGroup.position.z || 0)
+        const modelMinZ = Number(bounds?.min?.z) - currentZ
+        const mountPlaneZ = PcbScene3dModelBounds.#resolveMountPlaneZ(
+            THREE,
+            modelGroup,
+            modelMinZ
+        )
+
+        if (!Number.isFinite(mountPlaneZ)) {
+            return
+        }
+
+        const adjustedZ = modelGroup.position.z - mountPlaneZ
+        modelGroup.position.z =
+            Math.abs(adjustedZ) <= PcbScene3dModelBounds.#POSITION_EPSILON
+                ? 0
+                : adjustedZ
+        modelGroup.updateMatrixWorld?.(true)
+    }
+
+    /**
+     * Measures raw STEP mesh bounds in mil before the group-level unit scale is
+     * applied.
+     * @param {{ positions?: ArrayLike<number> }[]} meshPayloads STEP mesh payloads.
+     * @returns {{ minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, centerX: number, centerY: number, centerZ: number, sizeX: number, sizeY: number, sizeZ: number } | null}
+     */
+    static measureSourceBoundsMil(meshPayloads) {
+        let minX = Number.POSITIVE_INFINITY
+        let minY = Number.POSITIVE_INFINITY
+        let minZ = Number.POSITIVE_INFINITY
+        let maxX = Number.NEGATIVE_INFINITY
+        let maxY = Number.NEGATIVE_INFINITY
+        let maxZ = Number.NEGATIVE_INFINITY
+
+        ;(Array.isArray(meshPayloads) ? meshPayloads : []).forEach(
+            (meshPayload) => {
+                ;(PcbScene3dBufferAttributeFactory.isNumberSequence(
+                    meshPayload?.positions
+                )
+                    ? meshPayload.positions
+                    : []
+                ).forEach((value, index) => {
+                    const numericValue = Number(value || 0) * 1000
+
+                    if (index % 3 === 0) {
+                        minX = Math.min(minX, numericValue)
+                        maxX = Math.max(maxX, numericValue)
+                    } else if (index % 3 === 1) {
+                        minY = Math.min(minY, numericValue)
+                        maxY = Math.max(maxY, numericValue)
+                    } else {
+                        minZ = Math.min(minZ, numericValue)
+                        maxZ = Math.max(maxZ, numericValue)
+                    }
+                })
+            }
+        )
+
+        if (
+            !Number.isFinite(minX) ||
+            !Number.isFinite(minY) ||
+            !Number.isFinite(minZ) ||
+            !Number.isFinite(maxX) ||
+            !Number.isFinite(maxY) ||
+            !Number.isFinite(maxZ)
+        ) {
+            return null
+        }
+
+        return {
+            minX,
+            minY,
+            minZ,
+            maxX,
+            maxY,
+            maxZ,
+            centerX: (minX + maxX) / 2,
+            centerY: (minY + maxY) / 2,
+            centerZ: (minZ + maxZ) / 2,
+            sizeX: maxX - minX,
+            sizeY: maxY - minY,
+            sizeZ: maxZ - minZ
+        }
+    }
+
+    /**
+     * Resolves the model-local plane that should touch the board face.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ position?: { z?: number }, traverse?: (callback: (object: any) => void) => void, updateMatrixWorld?: (force?: boolean) => void }} modelGroup Model group.
+     * @param {number} fallbackMinZ Absolute lower bound fallback.
+     * @returns {number}
+     */
+    static #resolveMountPlaneZ(THREE, modelGroup, fallbackMinZ) {
+        const vertexZ = PcbScene3dModelBounds.#collectTransformedVertexZ(
+            THREE,
+            modelGroup
+        )
+        const dominantPlane =
+            PcbScene3dModelBounds.#resolveDominantLowerPlaneZ(vertexZ)
+
+        return Number.isFinite(dominantPlane) ? dominantPlane : fallbackMinZ
+    }
+
+    /**
+     * Collects transformed vertex Z coordinates in the model group's parent
+     * frame before the current model-group Z offset is applied.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ position?: { z?: number }, parent?: any, matrixWorld?: any, traverse?: (callback: (object: any) => void) => void, updateMatrixWorld?: (force?: boolean) => void }} modelGroup Model group.
+     * @returns {number[]}
+     */
+    static #collectTransformedVertexZ(THREE, modelGroup) {
+        if (!THREE?.Vector3 || typeof modelGroup?.traverse !== 'function') {
+            return []
+        }
+
+        modelGroup.updateMatrixWorld?.(true)
+        modelGroup.parent?.updateMatrixWorld?.(true)
+        const currentZ = Number(modelGroup?.position?.z || 0)
+        const parentInverse =
+            THREE?.Matrix4 && modelGroup.parent?.matrixWorld
+                ? new THREE.Matrix4()
+                      .copy(modelGroup.parent.matrixWorld)
+                      .invert()
+                : null
+        const vertex = new THREE.Vector3()
+        const values = []
+
+        modelGroup.traverse((object) => {
+            const position = object?.geometry?.attributes?.position
+            if (!position || !object?.matrixWorld) {
+                return
+            }
+
+            for (
+                let index = 0;
+                index < Number(position.count || 0);
+                index += 1
+            ) {
+                vertex.fromBufferAttribute(position, index)
+                vertex.applyMatrix4(object.matrixWorld)
+                if (parentInverse) {
+                    vertex.applyMatrix4(parentInverse)
+                }
+                values.push(vertex.z - currentZ)
+            }
+        })
+
+        return values.filter((value) => Number.isFinite(value))
+    }
+
+    /**
+     * Finds a dense lower support plane above sparse pin or lead protrusions.
+     * @param {number[]} values Model-local transformed Z coordinates.
+     * @returns {number | null}
+     */
+    static #resolveDominantLowerPlaneZ(values) {
+        if (!Array.isArray(values) || values.length < 3) {
+            return null
+        }
+
+        const { minZ, maxZ } = PcbScene3dModelBounds.#resolveZExtents(values)
+        const height = maxZ - minZ
+        if (!Number.isFinite(height) || height <= 0) {
+            return null
+        }
+
+        const lowerWindow = Math.min(
+            PcbScene3dModelBounds.#LOWER_SUPPORT_WINDOW_MAX_MIL,
+            height * PcbScene3dModelBounds.#LOWER_SUPPORT_WINDOW_RATIO
+        )
+        const bucketCounts = PcbScene3dModelBounds.#buildZBuckets(values)
+        const maxBucketCount =
+            PcbScene3dModelBounds.#resolveMaxBucketCount(bucketCounts)
+        const minCount =
+            maxBucketCount * PcbScene3dModelBounds.#SUPPORT_BUCKET_MIN_DENSITY
+        const candidates = [...bucketCounts.entries()]
+            .filter(([bucketZ, count]) => {
+                return (
+                    bucketZ >
+                        minZ +
+                            PcbScene3dModelBounds.#LOWER_SUPPORT_MIN_GAP_MIL &&
+                    bucketZ <= minZ + lowerWindow &&
+                    count >= minCount
+                )
+            })
+            .sort((left, right) => right[1] - left[1] || left[0] - right[0])
+
+        return candidates.length ? candidates[0][0] : null
+    }
+
+    /**
+     * Resolves minimum and maximum Z without spreading large vertex arrays.
+     * @param {number[]} values Model-local transformed Z coordinates.
+     * @returns {{ minZ: number, maxZ: number }}
+     */
+    static #resolveZExtents(values) {
+        let minZ = Number.POSITIVE_INFINITY
+        let maxZ = Number.NEGATIVE_INFINITY
+
+        values.forEach((value) => {
+            minZ = Math.min(minZ, value)
+            maxZ = Math.max(maxZ, value)
+        })
+
+        return { minZ, maxZ }
+    }
+
+    /**
+     * Resolves the largest bucket count without spreading map values.
+     * @param {Map<number, number>} bucketCounts Z bucket counts.
+     * @returns {number}
+     */
+    static #resolveMaxBucketCount(bucketCounts) {
+        let maxCount = 0
+
+        bucketCounts.forEach((count) => {
+            maxCount = Math.max(maxCount, count)
+        })
+
+        return maxCount
+    }
+
+    /**
+     * Buckets transformed Z coordinates to make dense support planes robust to
+     * small floating point and tessellation differences.
+     * @param {number[]} values Model-local transformed Z coordinates.
+     * @returns {Map<number, number>}
+     */
+    static #buildZBuckets(values) {
+        const buckets = new Map()
+
+        values.forEach((value) => {
+            const bucket =
+                Math.round(value / PcbScene3dModelBounds.#SUPPORT_BUCKET_MIL) *
+                PcbScene3dModelBounds.#SUPPORT_BUCKET_MIL
+            buckets.set(bucket, (buckets.get(bucket) || 0) + 1)
+        })
+
+        return buckets
+    }
+}

package/src/PcbScene3dModelSearchPlacement.mjs

@@ -0,0 +1,40 @@
+/**
+ * Tracks external model placements that came from app-side model lookup.
+ */
+export class PcbScene3dModelSearchPlacement {
+    /**
+     * Adds one loaded placement root when its model came from lookup.
+     * @param {any} placement External model placement.
+     * @param {any} rootObject Loaded model root.
+     * @param {Set<any>} roots Tracked lookup model roots.
+     * @returns {void}
+     */
+    static registerRoot(placement, rootObject, roots) {
+        if (
+            rootObject &&
+            roots &&
+            PcbScene3dModelSearchPlacement.isPlacement(placement)
+        ) {
+            roots.add(rootObject)
+        }
+    }
+
+    /**
+     * Checks whether an external placement came from app-side model lookup.
+     * @param {{ source?: string, origin?: string, externalModel?: { source?: string, origin?: string } }} placement External model placement.
+     * @returns {boolean}
+     */
+    static isPlacement(placement) {
+        return [
+            placement?.source,
+            placement?.origin,
+            placement?.externalModel?.source,
+            placement?.externalModel?.origin
+        ].some(
+            (value) =>
+                String(value || '')
+                    .trim()
+                    .toLowerCase() === 'model-search'
+        )
+    }
+}