pcb-scene3d-viewer 1.1.21 → 1.1.22

package/src/PcbScene3dCompanionBasePlacementAdjuster.mjs

@@ -0,0 +1,242 @@
+import { PcbScene3dExternalCompanionFallback } from './PcbScene3dExternalCompanionFallback.mjs'
+
+/**
+ * Lifts authored model placements that sit on companion fallback bases.
+ */
+export class PcbScene3dCompanionBasePlacementAdjuster {
+    static #ENVELOPE_MARGIN_RATIO = 0.25
+    static #ENVELOPE_MIN_MARGIN_MIL = 20
+    static #POSITION_EPSILON = 1e-6
+
+    /**
+     * Returns a scene copy with placements seated on companion fallback bases.
+     * @param {object} sceneDescription Scene description.
+     * @returns {object}
+     */
+    static adjust(sceneDescription) {
+        const bases =
+            PcbScene3dCompanionBasePlacementAdjuster.#companionBases(
+                sceneDescription
+            )
+        if (!bases.length) {
+            return sceneDescription
+        }
+
+        return {
+            ...sceneDescription,
+            externalPlacements:
+                PcbScene3dCompanionBasePlacementAdjuster.#adjustPlacements(
+                    sceneDescription?.externalPlacements,
+                    bases
+                ),
+            staticBodyPlacements:
+                PcbScene3dCompanionBasePlacementAdjuster.#adjustPlacements(
+                    sceneDescription?.staticBodyPlacements,
+                    bases
+                )
+        }
+    }
+
+    /**
+     * Resolves companion fallback bases from components in one scene.
+     * @param {object} sceneDescription Scene description.
+     * @returns {object[]}
+     */
+    static #companionBases(sceneDescription) {
+        return (
+            Array.isArray(sceneDescription?.components)
+                ? sceneDescription.components
+                : []
+        )
+            .filter((component) =>
+                PcbScene3dExternalCompanionFallback.shouldKeepFallback(
+                    sceneDescription,
+                    component
+                )
+            )
+            .map((component) =>
+                PcbScene3dCompanionBasePlacementAdjuster.#buildBase(component)
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Builds one companion base descriptor from a component.
+     * @param {object} component Scene component.
+     * @returns {object | null}
+     */
+    static #buildBase(component) {
+        const size = component?.body?.sizeMil || {}
+        const heightMil = Number(size.height || 0)
+        const widthMil = Number(size.width || 0)
+        const depthMil = Number(size.depth || 0)
+        if (!(heightMil > 0) || !(widthMil > 0) || !(depthMil > 0)) {
+            return null
+        }
+
+        return {
+            designator: String(component?.designator || '').trim(),
+            mountSide: String(component?.mountSide || 'top').toLowerCase(),
+            positionMil: {
+                x: Number(component?.positionMil?.x || 0),
+                y: Number(component?.positionMil?.y || 0),
+                z: Number(component?.positionMil?.z || 0)
+            },
+            rotationDeg: Number(component?.rotationDeg || 0),
+            widthMil,
+            depthMil,
+            heightMil,
+            signedLiftMil:
+                (PcbScene3dCompanionBasePlacementAdjuster.#isBottomSide(
+                    component?.mountSide
+                )
+                    ? -1
+                    : 1) * heightMil
+        }
+    }
+
+    /**
+     * Adjusts one placement list against all companion bases.
+     * @param {object[] | undefined} placements Original placements.
+     * @param {object[]} bases Companion bases.
+     * @returns {object[]}
+     */
+    static #adjustPlacements(placements, bases) {
+        return (Array.isArray(placements) ? placements : []).map((placement) =>
+            PcbScene3dCompanionBasePlacementAdjuster.#adjustPlacement(
+                placement,
+                bases
+            )
+        )
+    }
+
+    /**
+     * Adjusts one placement when it overlaps a companion base.
+     * @param {object} placement Original placement.
+     * @param {object[]} bases Companion bases.
+     * @returns {object}
+     */
+    static #adjustPlacement(placement, bases) {
+        const base = bases.find((candidate) =>
+            PcbScene3dCompanionBasePlacementAdjuster.#isPlacementOnBase(
+                placement,
+                candidate
+            )
+        )
+        if (!base) {
+            return placement
+        }
+
+        return {
+            ...placement,
+            positionMil: {
+                ...(placement?.positionMil || {}),
+                z: PcbScene3dCompanionBasePlacementAdjuster.#roundMil(
+                    Number(placement?.positionMil?.z || 0) + base.signedLiftMil
+                )
+            }
+        }
+    }
+
+    /**
+     * Checks whether a placement should be lifted onto one companion base.
+     * @param {object} placement Candidate placement.
+     * @param {object} base Companion base descriptor.
+     * @returns {boolean}
+     */
+    static #isPlacementOnBase(placement, base) {
+        if (
+            !PcbScene3dCompanionBasePlacementAdjuster.#isSameSide(
+                placement,
+                base
+            )
+        ) {
+            return false
+        }
+
+        const local =
+            PcbScene3dCompanionBasePlacementAdjuster.#toBaseLocalPosition(
+                placement,
+                base
+            )
+        const envelopeMarginMil =
+            PcbScene3dCompanionBasePlacementAdjuster.#envelopeMarginMil(base)
+
+        return (
+            Math.abs(local.x) <= base.widthMil / 2 + envelopeMarginMil &&
+            Math.abs(local.y) <= base.depthMil / 2 + envelopeMarginMil
+        )
+    }
+
+    /**
+     * Checks whether a placement and base are on the same board side.
+     * @param {object} placement Candidate placement.
+     * @param {object} base Companion base descriptor.
+     * @returns {boolean}
+     */
+    static #isSameSide(placement, base) {
+        return (
+            String(placement?.mountSide || 'top').toLowerCase() ===
+            String(base?.mountSide || 'top').toLowerCase()
+        )
+    }
+
+    /**
+     * Converts a placement anchor into a companion-base local frame.
+     * @param {object} placement Candidate placement.
+     * @param {object} base Companion base descriptor.
+     * @returns {{ x: number, y: number }}
+     */
+    static #toBaseLocalPosition(placement, base) {
+        const dx =
+            Number(placement?.positionMil?.x || 0) -
+            Number(base?.positionMil?.x || 0)
+        const dy =
+            Number(placement?.positionMil?.y || 0) -
+            Number(base?.positionMil?.y || 0)
+        const radians = -((Number(base?.rotationDeg || 0) * Math.PI) / 180)
+        const cos = Math.cos(radians)
+        const sin = Math.sin(radians)
+
+        return {
+            x: dx * cos - dy * sin,
+            y: dx * sin + dy * cos
+        }
+    }
+
+    /**
+     * Resolves loose matching margin for authored parts near a base edge.
+     * @param {object} base Companion base descriptor.
+     * @returns {number}
+     */
+    static #envelopeMarginMil(base) {
+        return Math.max(
+            PcbScene3dCompanionBasePlacementAdjuster.#ENVELOPE_MIN_MARGIN_MIL,
+            Math.min(Number(base?.widthMil || 0), Number(base?.depthMil || 0)) *
+                PcbScene3dCompanionBasePlacementAdjuster.#ENVELOPE_MARGIN_RATIO
+        )
+    }
+
+    /**
+     * Checks whether a mount side is bottom.
+     * @param {string | undefined} mountSide Mount side.
+     * @returns {boolean}
+     */
+    static #isBottomSide(mountSide) {
+        return String(mountSide || 'top').toLowerCase() === 'bottom'
+    }
+
+    /**
+     * Rounds one mil coordinate.
+     * @param {number} value Candidate value.
+     * @returns {number}
+     */
+    static #roundMil(value) {
+        const rounded =
+            Math.round(
+                Number(value || 0) /
+                    PcbScene3dCompanionBasePlacementAdjuster.#POSITION_EPSILON
+            ) * PcbScene3dCompanionBasePlacementAdjuster.#POSITION_EPSILON
+        return Object.is(rounded, -0) ? 0 : rounded
+    }
+}

package/src/PcbScene3dComponentVisibility.mjs

@@ -1,3 +1,5 @@
+import { PcbScene3dFallbackVisibility } from './PcbScene3dFallbackVisibility.mjs'
+
 /**
  * Applies per-component hidden state on top of existing 3D visibility toggles.
  */
@@ -46,7 +48,7 @@ export class PcbScene3dComponentVisibility {
 
     /**
      * Applies component visibility to all selectable render roots.
-     * @param {{ selectionRoots?: Map<string, Set<any>>, hiddenDesignators?: Set<string>, fallbackBodyRoots?: Map<string, Set<any>>, loadedExternalModelDesignators?: Set<string>, modelSearchExternalModelRoots?: Set<any>, toggles?: { 'external-models'?: boolean, 'fallback-bodies'?: boolean, 'model-search-models'?: boolean }, hasLoadedBoardAssemblyModel?: boolean }} state Visibility state.
+     * @param {{ selectionRoots?: Map<string, Set<any>>, selectedDesignator?: string, hiddenDesignators?: Set<string>, fallbackBodyRoots?: Map<string, Set<any>>, loadedExternalModelDesignators?: Set<string>, modelSearchExternalModelRoots?: Set<any>, toggles?: { 'external-models'?: boolean, 'fallback-bodies'?: boolean, 'model-search-models'?: boolean }, hasLoadedBoardAssemblyModel?: boolean }} state Visibility state.
      * @returns {void}
      */
     static apply(state) {
@@ -55,6 +57,11 @@ export class PcbScene3dComponentVisibility {
             return
         }
 
+        const selectedVariantGroupKeys =
+            PcbScene3dComponentVisibility.#selectedVariantGroupKeys(
+                selectionRoots,
+                state?.selectedDesignator
+            )
         selectionRoots.forEach((roots, designator) => {
             roots?.forEach?.((rootObject) => {
                 if (!rootObject) {
@@ -66,6 +73,12 @@ export class PcbScene3dComponentVisibility {
                         state?.hiddenDesignators,
                         designator
                     ) &&
+                    !PcbScene3dComponentVisibility.#isUnselectedVariantSibling(
+                        rootObject,
+                        designator,
+                        state?.selectedDesignator,
+                        selectedVariantGroupKeys
+                    ) &&
                     PcbScene3dComponentVisibility.#resolveRootVisible(
                         state,
                         designator,
@@ -75,6 +88,75 @@ export class PcbScene3dComponentVisibility {
         })
     }
 
+    /**
+     * Resolves variant groups represented by the selected component roots.
+     * @param {Map<string, Set<any>>} selectionRoots Registered selectable roots.
+     * @param {string | undefined} selectedDesignator Current selection.
+     * @returns {Set<string>}
+     */
+    static #selectedVariantGroupKeys(selectionRoots, selectedDesignator) {
+        const selectedKey =
+            PcbScene3dComponentVisibility.#normalizeDesignator(
+                selectedDesignator
+            )
+        const groups = new Set()
+        if (!selectedKey) {
+            return groups
+        }
+
+        selectionRoots.get(selectedKey)?.forEach?.((rootObject) => {
+            const groupKey =
+                PcbScene3dComponentVisibility.#variantGroupKey(rootObject)
+            if (groupKey) {
+                groups.add(groupKey)
+            }
+        })
+        return groups
+    }
+
+    /**
+     * Checks whether one selectable root is an alternate of the selection.
+     * @param {any} rootObject Selectable root.
+     * @param {string} designator Root designator.
+     * @param {string | undefined} selectedDesignator Current selection.
+     * @param {Set<string>} selectedVariantGroupKeys Selected variant groups.
+     * @returns {boolean}
+     */
+    static #isUnselectedVariantSibling(
+        rootObject,
+        designator,
+        selectedDesignator,
+        selectedVariantGroupKeys
+    ) {
+        const selectedKey =
+            PcbScene3dComponentVisibility.#normalizeDesignator(
+                selectedDesignator
+            )
+        if (!selectedKey || !selectedVariantGroupKeys.size) {
+            return false
+        }
+
+        if (
+            PcbScene3dComponentVisibility.#normalizeDesignator(designator) ===
+            selectedKey
+        ) {
+            return false
+        }
+
+        const groupKey =
+            PcbScene3dComponentVisibility.#variantGroupKey(rootObject)
+        return Boolean(groupKey && selectedVariantGroupKeys.has(groupKey))
+    }
+
+    /**
+     * Reads the authored co-located variant group key from a render root.
+     * @param {any} rootObject Render root.
+     * @returns {string}
+     */
+    static #variantGroupKey(rootObject) {
+        return String(rootObject?.userData?.scene3dVariantGroupKey || '').trim()
+    }
+
     /**
      * Resolves root-level visibility before selected-component hiding.
      * @param {{ fallbackBodyRoots?: Map<string, Set<any>>, loadedExternalModelDesignators?: Set<string>, modelSearchExternalModelRoots?: Set<any>, toggles?: { 'external-models'?: boolean, 'fallback-bodies'?: boolean, 'model-search-models'?: boolean }, hasLoadedBoardAssemblyModel?: boolean }} state Visibility state.
@@ -92,7 +174,8 @@ export class PcbScene3dComponentVisibility {
         ) {
             return PcbScene3dComponentVisibility.#resolveFallbackVisible(
                 state,
-                designator
+                designator,
+                rootObject
             )
         }
 
@@ -110,14 +193,27 @@ export class PcbScene3dComponentVisibility {
      * Resolves fallback root visibility from current detail toggles.
      * @param {{ loadedExternalModelDesignators?: Set<string>, toggles?: { 'external-models'?: boolean, 'fallback-bodies'?: boolean }, hasLoadedBoardAssemblyModel?: boolean }} state Visibility state.
      * @param {string} designator Component designator.
+     * @param {any} rootObject Render root.
      * @returns {boolean}
      */
-    static #resolveFallbackVisible(state, designator) {
+    static #resolveFallbackVisible(state, designator, rootObject) {
         const boardAssemblyActive =
             Boolean(state?.hasLoadedBoardAssemblyModel) &&
             Boolean(state?.toggles?.['external-models'])
-        const showFallbackBodies =
-            Boolean(state?.toggles?.['fallback-bodies']) && !boardAssemblyActive
+        if (boardAssemblyActive) {
+            return false
+        }
+
+        if (
+            PcbScene3dFallbackVisibility.shouldKeepExternalCompanion(
+                rootObject,
+                state?.toggles
+            )
+        ) {
+            return true
+        }
+
+        const showFallbackBodies = Boolean(state?.toggles?.['fallback-bodies'])
         const hideForLoadedExternal =
             Boolean(state?.toggles?.['external-models']) &&
             state?.loadedExternalModelDesignators?.has?.(

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/PcbScene3dExternalModels.mjs

@@ -293,6 +293,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 =