pcb-scene3d-viewer 1.1.21 → 1.1.31

package/src/PcbScene3dExternalCompanionFallback.mjs

@@ -0,0 +1,202 @@
+/**
+ * Detects fallback bodies that should remain visible as companions for partial
+ * external model placements.
+ */
+export class PcbScene3dExternalCompanionFallback {
+    /**
+     * Checks whether a component fallback body should remain visible as the
+     * package companion for a partial embedded external model.
+     * @param {{ externalPlacements?: object[], staticBodyPlacements?: object[] }} sceneDescription Scene data.
+     * @param {{ designator?: string, mountSide?: string, positionMil?: { x?: number, y?: number }, body?: { sizeMil?: { width?: number, depth?: number } } }} component Component scene entry.
+     * @returns {boolean}
+     */
+    static shouldKeepFallback(sceneDescription, component) {
+        const designator =
+            PcbScene3dExternalCompanionFallback.#normalizedDesignator(
+                component?.designator
+            )
+        if (!designator) {
+            return false
+        }
+
+        if (
+            PcbScene3dExternalCompanionFallback.#hasAuthoredCompanionBase(
+                sceneDescription,
+                component
+            )
+        ) {
+            return false
+        }
+
+        return PcbScene3dExternalCompanionFallback.#externalPlacements(
+            sceneDescription
+        ).some(
+            (placement) =>
+                PcbScene3dExternalCompanionFallback.#normalizedDesignator(
+                    placement?.designator
+                ) === designator &&
+                PcbScene3dExternalCompanionFallback.#isPartialEmbeddedPlacement(
+                    placement
+                )
+        )
+    }
+
+    /**
+     * Checks whether an authored static body already provides the package base
+     * for one partial embedded placement.
+     * @param {{ staticBodyPlacements?: object[] }} sceneDescription Scene data.
+     * @param {{ mountSide?: string, positionMil?: { x?: number, y?: number }, body?: { sizeMil?: { width?: number, depth?: number } } }} component Component scene entry.
+     * @returns {boolean}
+     */
+    static #hasAuthoredCompanionBase(sceneDescription, component) {
+        return PcbScene3dExternalCompanionFallback.#staticBodyPlacements(
+            sceneDescription
+        ).some(
+            (placement) =>
+                PcbScene3dExternalCompanionFallback.#isSameSide(
+                    placement,
+                    component
+                ) &&
+                PcbScene3dExternalCompanionFallback.#isRenderableBase(
+                    placement
+                ) &&
+                PcbScene3dExternalCompanionFallback.#isNearComponent(
+                    placement,
+                    component
+                )
+        )
+    }
+
+    /**
+     * Resolves normalized external placements from one scene description.
+     * @param {{ externalPlacements?: object[] }} sceneDescription Scene data.
+     * @returns {object[]}
+     */
+    static #externalPlacements(sceneDescription) {
+        return Array.isArray(sceneDescription?.externalPlacements)
+            ? sceneDescription.externalPlacements
+            : []
+    }
+
+    /**
+     * Resolves normalized static body placements from one scene description.
+     * @param {{ staticBodyPlacements?: object[] }} sceneDescription Scene data.
+     * @returns {object[]}
+     */
+    static #staticBodyPlacements(sceneDescription) {
+        return Array.isArray(sceneDescription?.staticBodyPlacements)
+            ? sceneDescription.staticBodyPlacements
+            : []
+    }
+
+    /**
+     * Checks whether a placement and component share a board side.
+     * @param {object} placement Static body placement.
+     * @param {object} component Scene component.
+     * @returns {boolean}
+     */
+    static #isSameSide(placement, component) {
+        return (
+            String(placement?.mountSide || 'top').toLowerCase() ===
+            String(component?.mountSide || 'top').toLowerCase()
+        )
+    }
+
+    /**
+     * Checks whether one static body can act as a package base.
+     * @param {object} placement Static body placement.
+     * @returns {boolean}
+     */
+    static #isRenderableBase(placement) {
+        const geometry = placement?.geometry || {}
+        return (
+            String(geometry?.kind || '').toLowerCase() === 'extruded-polygon' &&
+            PcbScene3dExternalCompanionFallback.#geometrySpan(geometry).width >
+                0 &&
+            PcbScene3dExternalCompanionFallback.#geometrySpan(geometry).depth >
+                0
+        )
+    }
+
+    /**
+     * Checks whether one authored base is close enough to own a component base.
+     * @param {object} placement Static body placement.
+     * @param {object} component Scene component.
+     * @returns {boolean}
+     */
+    static #isNearComponent(placement, component) {
+        const span = PcbScene3dExternalCompanionFallback.#geometrySpan(
+            placement?.geometry
+        )
+        const componentSize = component?.body?.sizeMil || {}
+        const threshold = Math.max(
+            30,
+            Number(span.width || 0) / 2,
+            Number(span.depth || 0) / 2,
+            Number(componentSize.width || 0) / 2,
+            Number(componentSize.depth || 0) / 2
+        )
+        const dx =
+            Number(placement?.positionMil?.x || 0) -
+            Number(component?.positionMil?.x || 0)
+        const dy =
+            Number(placement?.positionMil?.y || 0) -
+            Number(component?.positionMil?.y || 0)
+
+        return Math.hypot(dx, dy) <= threshold
+    }
+
+    /**
+     * Resolves width and depth for one polygon geometry.
+     * @param {{ verticesMil?: { x?: number, y?: number }[] } | undefined} geometry Static geometry.
+     * @returns {{ width: number, depth: number }}
+     */
+    static #geometrySpan(geometry) {
+        const vertices = Array.isArray(geometry?.verticesMil)
+            ? geometry.verticesMil
+            : []
+        if (vertices.length < 3) {
+            return { width: 0, depth: 0 }
+        }
+
+        const xs = vertices.map((vertex) => Number(vertex?.x || 0))
+        const ys = vertices.map((vertex) => Number(vertex?.y || 0))
+
+        return {
+            width: Math.max(...xs) - Math.min(...xs),
+            depth: Math.max(...ys) - Math.min(...ys)
+        }
+    }
+
+    /**
+     * Checks for embedded external placements that represent a sub-body, not a
+     * complete replacement for the procedural component body.
+     * @param {object} placement External model placement.
+     * @returns {boolean}
+     */
+    static #isPartialEmbeddedPlacement(placement) {
+        const projection = placement?.projection || {}
+        const bounds = projection?.boundsMil || {}
+
+        return (
+            String(placement?.externalModel?.origin || '').toLowerCase() ===
+                'embedded' &&
+            String(projection?.source || '').toLowerCase() ===
+                'model-anchor-fallback' &&
+            Math.max(
+                Number(bounds.width || 0),
+                Number(bounds.depth || 0),
+                Number(bounds.height || 0)
+            ) <= 0
+        )
+    }
+
+    /**
+     * Normalizes one designator for component/external placement matching.
+     * @param {unknown} designator Candidate designator.
+     * @returns {string}
+     */
+    static #normalizedDesignator(designator) {
+        return String(designator || '').trim()
+    }
+}

package/src/PcbScene3dExternalModelCenteringPolicy.mjs

@@ -0,0 +1,21 @@
+/**
+ * Resolves which external-model placements can be centered after loading.
+ */
+export class PcbScene3dExternalModelCenteringPolicy {
+    /**
+     * Checks whether a loaded model should be centered on its owner footprint.
+     * @param {object | null | undefined} placement External placement.
+     * @returns {boolean}
+     */
+    static shouldCenterOnOwner(placement) {
+        const source = String(placement?.projection?.source || '').toLowerCase()
+        if (source === 'pad-fallback') {
+            return true
+        }
+
+        return (
+            source === 'model-anchor-fallback' &&
+            Boolean(placement?.modelTransform?.ownerAnchorOffsetMil)
+        )
+    }
+}

package/src/PcbScene3dExternalModelOpacity.mjs

@@ -0,0 +1,51 @@
+import { PcbScene3dTransparentMeshSplitter } from './PcbScene3dTransparentMeshSplitter.mjs'
+
+/**
+ * Applies source-authored display opacity to loaded external model materials.
+ */
+export class PcbScene3dExternalModelOpacity {
+    /**
+     * Applies source-authored placement opacity to every material below a
+     * loaded external model.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ bodyOpacity?: number | string } | null | undefined} placement Placement metadata.
+     * @param {any} placementGroup Rendered placement root.
+     * @returns {void}
+     */
+    static apply(THREE, placement, placementGroup) {
+        const opacity = Number(placement?.bodyOpacity)
+        if (!Number.isFinite(opacity) || opacity < 0 || opacity >= 1) {
+            return
+        }
+
+        const clampedOpacity = Math.max(0, Math.min(1, opacity))
+        PcbScene3dExternalModelOpacity.#visitMaterials(
+            placementGroup,
+            (material) => {
+                material.transparent = true
+                material.opacity = clampedOpacity
+                material.depthWrite = false
+                material.needsUpdate = true
+            }
+        )
+        PcbScene3dTransparentMeshSplitter.split(THREE, placementGroup)
+    }
+
+    /**
+     * Visits material instances below one object tree.
+     * @param {any} rootObject Root object.
+     * @param {(material: any) => void} visitor Material visitor.
+     * @returns {void}
+     */
+    static #visitMaterials(rootObject, visitor) {
+        rootObject?.traverse?.((object) => {
+            const materials = Array.isArray(object?.material)
+                ? object.material
+                : object?.material
+                  ? [object.material]
+                  : []
+
+            materials.filter(Boolean).forEach((material) => visitor(material))
+        })
+    }
+}

package/src/PcbScene3dExternalModelPlacementRepair.mjs

@@ -1,3 +1,5 @@
+import { PcbScene3dExternalModelCenteringPolicy } from './PcbScene3dExternalModelCenteringPolicy.mjs'
+
 /**
  * Repairs loaded external-model placements using normalized scene metadata.
  */
@@ -352,8 +354,9 @@ export class PcbScene3dExternalModelPlacementRepair {
         if (
             !component ||
             !placementGroup?.position ||
-            String(placement?.projection?.source || '').toLowerCase() !==
-                'pad-fallback' ||
+            !PcbScene3dExternalModelCenteringPolicy.shouldCenterOnOwner(
+                placement
+            ) ||
             !THREE?.Box3
         ) {
             return

package/src/PcbScene3dExternalModelSourceOriginPolicy.mjs

@@ -0,0 +1,41 @@
+/**
+ * Resolves source-origin adjustment policy for external model placements.
+ */
+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.
+     * @returns {boolean}
+     */
+    static shouldSkipOwnerAnchoredAdjustment(placement) {
+        return (
+            Boolean(placement?.modelTransform?.ownerAnchorOffsetMil) &&
+            !PcbScene3dExternalModelSourceOriginPolicy.#isTransparentCoverSizedPlacement(
+                placement
+            )
+        )
+    }
+
+    /**
+     * Checks whether a placement looks like an authored translucent cover body.
+     * @param {{ bodyOpacity?: number | string, projection?: { boundsMil?: { width?: number, depth?: number } } }} placement Placement metadata.
+     * @returns {boolean}
+     */
+    static #isTransparentCoverSizedPlacement(placement) {
+        const opacity = Number(placement?.bodyOpacity)
+        const bounds = placement?.projection?.boundsMil || {}
+        const width = Number(bounds.width)
+        const depth = Number(bounds.depth)
+
+        return (
+            Number.isFinite(opacity) &&
+            opacity >= 0 &&
+            opacity < 1 &&
+            Number.isFinite(width) &&
+            Number.isFinite(depth) &&
+            Math.min(Math.abs(width), Math.abs(depth)) >= 200
+        )
+    }
+}

package/src/PcbScene3dExternalModels.mjs

@@ -2,8 +2,10 @@ import { PcbScene3dBoardAssemblyPresentation } from './PcbScene3dBoardAssemblyPr
 import { PcbScene3dBoardAssemblyPlacement } from './PcbScene3dBoardAssemblyPlacement.mjs'
 import { PcbScene3dBoardAssemblyTransform } from './PcbScene3dBoardAssemblyTransform.mjs'
 import { PcbScene3dBufferAttributeFactory } from './PcbScene3dBufferAttributeFactory.mjs'
+import { PcbScene3dExternalModelOpacity } from './PcbScene3dExternalModelOpacity.mjs'
 import { PcbScene3dExternalModelPlacementRepair } from './PcbScene3dExternalModelPlacementRepair.mjs'
 import { PcbScene3dExternalModelLoadOrder } from './PcbScene3dExternalModelLoadOrder.mjs'
+import { PcbScene3dExternalModelSourceOriginPolicy } from './PcbScene3dExternalModelSourceOriginPolicy.mjs'
 import { PcbScene3dModelBounds } from './PcbScene3dModelBounds.mjs'
 import { PcbScene3dMountRig } from './PcbScene3dMountRig.mjs'
 import { PcbScene3dStepLoader } from './PcbScene3dStepLoader.mjs'
@@ -54,7 +56,6 @@ export class PcbScene3dExternalModels {
                     if (!loadedGroup || options?.isDisposed?.()) {
                         continue
                     }
-
                     externalModelsGroup.add(loadedGroup)
                     PcbScene3dExternalModelPlacementRepair.apply(
                         options.three,
@@ -65,6 +66,11 @@ export class PcbScene3dExternalModels {
                     PcbScene3dExternalModelPlacementRepair.isolatePlacementMaterials(
                         loadedGroup
                     )
+                    PcbScene3dExternalModelOpacity.apply(
+                        options.three,
+                        placement,
+                        loadedGroup
+                    )
                     options?.onPlacementGroup?.(placement, loadedGroup)
                     processedPlacements += 1
                     if (processedPlacements % 12 === 0) {
@@ -293,6 +299,12 @@ export class PcbScene3dExternalModels {
             designator,
             sourceType: 'external-model'
         }
+        const variantGroupKey = String(
+            placement?.coLocatedVariantGroupKey || ''
+        ).trim()
+        if (variantGroupKey) {
+            wrapperGroup.userData.scene3dVariantGroupKey = variantGroupKey
+        }
         adjustmentGroup.userData.scene3dAdjustmentTarget = true
         adjustmentGroup.userData.scene3dAdjustmentDesignator = designator
         adjustmentGroup.userData.scene3dAdjustmentBaseline =
@@ -497,6 +509,9 @@ export class PcbScene3dExternalModels {
         if (
             String(placement?.externalModel?.origin || '').toLowerCase() !==
                 'embedded' ||
+            PcbScene3dExternalModelSourceOriginPolicy.shouldSkipOwnerAnchoredAdjustment(
+                placement
+            ) ||
             PcbScene3dExternalModels.#normalizeAngle(modelRotation?.x) !==
                 270 ||
             !Number.isFinite(centerX) ||
@@ -917,15 +932,12 @@ export class PcbScene3dExternalModels {
         const triangleCount = Math.floor(Number(indices?.length || 0) / 3)
         let triangleIndex = 0
         let faceColorIndex = 0
-
         while (triangleIndex < triangleCount) {
             const firstIndex = triangleIndex
             let lastIndex = triangleCount
             let materialIndex = 0
-
             if (faceColorIndex < faceColors.length) {
                 const currentFaceColor = faceColors[faceColorIndex]
-
                 if (triangleIndex < currentFaceColor.first) {
                     lastIndex = currentFaceColor.first
                 } else {
@@ -937,7 +949,6 @@ export class PcbScene3dExternalModels {
                     faceColorIndex += 1
                 }
             }
-
             geometry.addGroup(
                 firstIndex * 3,
                 Math.max(lastIndex - firstIndex, 0) * 3,
@@ -957,7 +968,6 @@ export class PcbScene3dExternalModels {
         const first = Number(faceColor?.first)
         const last = Number(faceColor?.last)
         const triangleCount = Math.floor(Number(indices?.length || 0) / 3)
-
         return (
             Number.isInteger(first) &&
             Number.isInteger(last) &&
@@ -977,7 +987,6 @@ export class PcbScene3dExternalModels {
         if (!Array.isArray(color) || color.length < 3) {
             return 0xc8c8c8
         }
-
         return new THREE.Color(
             Number(color[0] || 0),
             Number(color[1] || 0),

package/src/PcbScene3dFallbackBodyFactory.mjs

@@ -0,0 +1,105 @@
+import { PcbScene3dBodyColor } from './PcbScene3dBodyColor.mjs'
+import { PcbScene3dComponentAdjustment } from './PcbScene3dComponentAdjustment.mjs'
+import { PcbScene3dMountRig } from './PcbScene3dMountRig.mjs'
+
+/**
+ * Builds procedural fallback body render roots for PCB components.
+ */
+export class PcbScene3dFallbackBodyFactory {
+    /**
+     * Builds one procedural fallback body root.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ designator?: string, positionMil: { x: number, y: number, z: number }, rotationDeg: number, mountSide: string, body: { family: string, sizeMil: { width: number, depth: number, height: number } } }} component Component scene entry.
+     * @param {{ companionBase?: boolean }} [options] Rendering options.
+     * @returns {{ rootGroup: any, adjustmentGroup: any }}
+     */
+    static build(THREE, component, options = {}) {
+        const family = component.body.family
+        const size = component.body.sizeMil
+        const material = new THREE.MeshStandardMaterial({
+            color: PcbScene3dFallbackBodyFactory.#resolveColor(family, options),
+            roughness: 0.72,
+            metalness: family === 'chip' ? 0.12 : 0.08
+        })
+        const mesh = PcbScene3dFallbackBodyFactory.#buildMesh(
+            THREE,
+            family,
+            size,
+            material
+        )
+        const mountRig = PcbScene3dMountRig.create(THREE, component)
+        const adjustmentGroup =
+            PcbScene3dFallbackBodyFactory.#buildAdjustmentGroup(
+                THREE,
+                component
+            )
+
+        mountRig.rootGroup.userData.scene3dSelection = {
+            designator: String(component?.designator || 'component'),
+            sourceType: 'component'
+        }
+        adjustmentGroup.add(mesh)
+        mountRig.faceGroup.add(adjustmentGroup)
+
+        return {
+            rootGroup: mountRig.rootGroup,
+            adjustmentGroup
+        }
+    }
+
+    /**
+     * Resolves the fallback body color.
+     * @param {string} family Package family.
+     * @param {{ companionBase?: boolean }} options Rendering options.
+     * @returns {number}
+     */
+    static #resolveColor(family, options) {
+        return options?.companionBase
+            ? 0x808080
+            : PcbScene3dBodyColor.resolve(family)
+    }
+
+    /**
+     * Builds the body mesh for one package family.
+     * @param {any} THREE Three.js namespace.
+     * @param {string} family Package family.
+     * @param {{ width: number, depth: number, height: number }} size Body size.
+     * @param {any} material Mesh material.
+     * @returns {any}
+     */
+    static #buildMesh(THREE, family, size, material) {
+        if (family === 'radial-capacitor' || family === 'test-point') {
+            return new THREE.Mesh(
+                new THREE.CylinderGeometry(
+                    size.width / 2,
+                    size.width / 2,
+                    size.height,
+                    28
+                ),
+                material
+            )
+        }
+
+        return new THREE.Mesh(
+            new THREE.BoxGeometry(size.width, size.depth, size.height),
+            material
+        )
+    }
+
+    /**
+     * Builds the transform node used by live component adjustments.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ designator?: string }} component Component scene entry.
+     * @returns {any}
+     */
+    static #buildAdjustmentGroup(THREE, component) {
+        const adjustmentGroup = new THREE.Group()
+        adjustmentGroup.userData.scene3dAdjustmentTarget = true
+        adjustmentGroup.userData.scene3dAdjustmentDesignator = String(
+            component?.designator || 'component'
+        )
+        adjustmentGroup.userData.scene3dAdjustmentBaseline =
+            PcbScene3dComponentAdjustment.neutral()
+        return adjustmentGroup
+    }
+}

package/src/PcbScene3dFallbackVisibility.mjs

@@ -74,9 +74,66 @@ export class PcbScene3dFallbackVisibility {
                     return
                 }
 
+                const stitchedCompanion =
+                    PcbScene3dFallbackVisibility.shouldKeepExternalCompanion(
+                        rootObject,
+                        toggles
+                    )
                 rootObject.visible =
-                    showFallbackBodies && !hideForLoadedExternal
+                    stitchedCompanion ||
+                    (showFallbackBodies && !hideForLoadedExternal)
             })
         })
     }
+
+    /**
+     * Checks whether any fallback root should keep the fallback group visible
+     * as part of a stitched external-model package.
+     * @param {Map<string, Set<any>>} fallbackRoots Fallback root registry.
+     * @param {{ 'external-models'?: boolean }} toggles Detail toggles.
+     * @returns {boolean}
+     */
+    static hasVisibleExternalCompanion(fallbackRoots, toggles) {
+        if (
+            !(fallbackRoots instanceof Map) ||
+            !Boolean(toggles?.['external-models'])
+        ) {
+            return false
+        }
+
+        let hasCompanion = false
+        fallbackRoots.forEach((roots) => {
+            roots?.forEach?.((rootObject) => {
+                hasCompanion =
+                    hasCompanion ||
+                    PcbScene3dFallbackVisibility.#isExternalCompanion(
+                        rootObject
+                    )
+            })
+        })
+        return hasCompanion
+    }
+
+    /**
+     * Checks whether one fallback body should stay visible as a stitched
+     * external-model companion under the active toggles.
+     * @param {any} rootObject Fallback root object.
+     * @param {{ 'external-models'?: boolean }} toggles Detail toggles.
+     * @returns {boolean}
+     */
+    static shouldKeepExternalCompanion(rootObject, toggles) {
+        return (
+            Boolean(toggles?.['external-models']) &&
+            PcbScene3dFallbackVisibility.#isExternalCompanion(rootObject)
+        )
+    }
+
+    /**
+     * Checks whether a fallback body is part of a stitched external model.
+     * @param {any} rootObject Fallback root object.
+     * @returns {boolean}
+     */
+    static #isExternalCompanion(rootObject) {
+        return Boolean(rootObject?.userData?.scene3dFallbackExternalCompanion)
+    }
 }

package/src/PcbScene3dMaskCoveredCopperSideGroupBuilder.mjs

@@ -0,0 +1,68 @@
+import { PcbScene3dGeometryZCompressor } from './PcbScene3dGeometryZCompressor.mjs'
+
+/**
+ * Builds side-specific copper relief groups that sit below solder mask.
+ */
+export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
+    /**
+     * Builds one side group from prepared mask-covered copper meshes.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ trackMesh?: any | null, arcMesh?: any | null, fillMesh?: any | null, z?: number, mirrorY?: boolean }} options
+     * @returns {any}
+     */
+    static build(
+        THREE,
+        {
+            trackMesh = null,
+            arcMesh = null,
+            fillMesh = null,
+            z = 0,
+            mirrorY = false
+        } = {}
+    ) {
+        const group = new THREE.Group()
+
+        PcbScene3dMaskCoveredCopperSideGroupBuilder.#addCompressedMesh(
+            group,
+            trackMesh,
+            'mask-covered-copper-tracks',
+            z
+        )
+        PcbScene3dMaskCoveredCopperSideGroupBuilder.#addCompressedMesh(
+            group,
+            arcMesh,
+            'mask-covered-copper-arcs',
+            z
+        )
+        PcbScene3dMaskCoveredCopperSideGroupBuilder.#addCompressedMesh(
+            group,
+            fillMesh,
+            'mask-covered-copper-fills',
+            z
+        )
+
+        if (mirrorY && group.children.length) {
+            group.rotation.x = Math.PI
+        }
+
+        return group
+    }
+
+    /**
+     * Compresses one mesh into mask relief space before adding it to a group.
+     * @param {any} group Parent group.
+     * @param {any | null} mesh Mesh to add.
+     * @param {string} name Scene object name.
+     * @param {number} z Source center Z.
+     * @returns {void}
+     */
+    static #addCompressedMesh(group, mesh, name, z) {
+        if (!mesh) {
+            return
+        }
+
+        PcbScene3dGeometryZCompressor.compressMaskCoveredCopperMesh(mesh, z)
+        mesh.name = name
+        group.add(mesh)
+    }
+}