pcb-scene3d-viewer 1.1.21 → 1.1.31

package/src/PcbScene3dCircuitJsonModelTransform.mjs

@@ -0,0 +1,232 @@
+import { CircuitJsonUnits } from 'circuitjson-toolkit'
+
+/**
+ * Normalizes CAD component model placement hints from CircuitJSON.
+ */
+export class PcbScene3dCircuitJsonModelTransform {
+    /**
+     * Builds optional model-local transforms.
+     * @param {object} cadComponent CAD component element.
+     * @returns {object | null}
+     */
+    static build(cadComponent) {
+        const offset = cadComponent?.model_offset || cadComponent?.offset
+        const rotation =
+            cadComponent?.model_rotation || cadComponent?.model_rotation_deg
+        const rawScale = cadComponent?.model_scale
+        const unitScale = PcbScene3dCircuitJsonModelTransform.#positiveFinite(
+            cadComponent?.model_unit_to_mm_scale_factor,
+            1
+        )
+        const originPositionMil =
+            PcbScene3dCircuitJsonModelTransform.#pointMmToMil(
+                cadComponent?.model_origin_position
+            )
+        const originAlignment =
+            PcbScene3dCircuitJsonModelTransform.#stringValue(
+                cadComponent?.model_origin_alignment
+            )
+        const objectFit = PcbScene3dCircuitJsonModelTransform.#stringValue(
+            cadComponent?.model_object_fit
+        )
+        const boardNormalDirection =
+            PcbScene3dCircuitJsonModelTransform.#stringValue(
+                cadComponent?.model_board_normal_direction
+            )
+        const targetSizeMil = PcbScene3dCircuitJsonModelTransform.#sizeMmToMil(
+            cadComponent?.model_size || cadComponent?.size
+        )
+
+        if (
+            !offset &&
+            !rotation &&
+            rawScale === undefined &&
+            unitScale === 1 &&
+            !originPositionMil &&
+            !originAlignment &&
+            !objectFit &&
+            !boardNormalDirection &&
+            !targetSizeMil
+        ) {
+            return null
+        }
+
+        return {
+            offsetMil: PcbScene3dCircuitJsonModelTransform.#offsetMil(offset),
+            rotationDeg:
+                PcbScene3dCircuitJsonModelTransform.#rotationDeg(rotation),
+            scale: PcbScene3dCircuitJsonModelTransform.#modelScale(
+                rawScale,
+                unitScale
+            ),
+            ...PcbScene3dCircuitJsonModelTransform.#optionalFields({
+                originPositionMil,
+                originAlignment,
+                objectFit,
+                boardNormalDirection,
+                targetSizeMil
+            })
+        }
+    }
+
+    /**
+     * Builds display metadata for a CAD component placement.
+     * @param {object} cadComponent CAD component element.
+     * @returns {{ bodyOpacity?: number }}
+     */
+    static displayMetadata(cadComponent) {
+        const opacity =
+            PcbScene3dCircuitJsonModelTransform.#displayOpacity(cadComponent)
+        return opacity === null ? {} : { bodyOpacity: opacity }
+    }
+
+    /**
+     * Builds optional transform fields from populated metadata.
+     * @param {object} fields Candidate optional fields.
+     * @returns {object}
+     */
+    static #optionalFields(fields) {
+        return Object.fromEntries(
+            Object.entries(fields).filter((entry) => entry[1] !== null)
+        )
+    }
+
+    /**
+     * Resolves model-local offset fields in mils.
+     * @param {object | undefined} offset Offset source in millimeters.
+     * @returns {{ x: number, y: number, z: number }}
+     */
+    static #offsetMil(offset) {
+        return {
+            x: CircuitJsonUnits.mmToMil(offset?.x, 0),
+            y: CircuitJsonUnits.mmToMil(offset?.y, 0),
+            z: CircuitJsonUnits.mmToMil(offset?.z, 0)
+        }
+    }
+
+    /**
+     * Resolves model-local rotation fields.
+     * @param {object | number | undefined} rotation Rotation metadata.
+     * @returns {{ x: number, y: number, z: number }}
+     */
+    static #rotationDeg(rotation) {
+        if (typeof rotation === 'number') {
+            return { x: 0, y: 0, z: Number(rotation || 0) }
+        }
+
+        return {
+            x: Number(rotation?.x || 0),
+            y: Number(rotation?.y || 0),
+            z: Number(rotation?.z || 0)
+        }
+    }
+
+    /**
+     * Normalizes model scale fields and unit scale.
+     * @param {unknown} scale Scale metadata.
+     * @param {number} unitScale Unit-to-millimeter scale factor.
+     * @returns {{ x: number, y: number, z: number }}
+     */
+    static #modelScale(scale, unitScale) {
+        if (typeof scale === 'number') {
+            const value = Number(scale) || 1
+            return {
+                x: value * unitScale,
+                y: value * unitScale,
+                z: value * unitScale
+            }
+        }
+
+        return {
+            x: (Number(scale?.x ?? 1) || 1) * unitScale,
+            y: (Number(scale?.y ?? 1) || 1) * unitScale,
+            z: (Number(scale?.z ?? 1) || 1) * unitScale
+        }
+    }
+
+    /**
+     * Converts an optional point from millimeters to mils.
+     * @param {object | undefined} point Point metadata.
+     * @returns {{ x: number, y: number, z: number } | null}
+     */
+    static #pointMmToMil(point) {
+        if (
+            !Number.isFinite(Number(point?.x)) &&
+            !Number.isFinite(Number(point?.y)) &&
+            !Number.isFinite(Number(point?.z))
+        ) {
+            return null
+        }
+
+        return {
+            x: CircuitJsonUnits.mmToMil(point?.x, 0),
+            y: CircuitJsonUnits.mmToMil(point?.y, 0),
+            z: CircuitJsonUnits.mmToMil(point?.z, 0)
+        }
+    }
+
+    /**
+     * Converts optional model target size from millimeters to mils.
+     * @param {object | undefined} size Size metadata.
+     * @returns {{ x: number, y: number, z: number } | null}
+     */
+    static #sizeMmToMil(size) {
+        const x = size?.x ?? size?.width
+        const y = size?.y ?? size?.height
+        const z = size?.z ?? size?.depth
+        if (
+            !Number.isFinite(Number(x)) &&
+            !Number.isFinite(Number(y)) &&
+            !Number.isFinite(Number(z))
+        ) {
+            return null
+        }
+
+        return {
+            x: CircuitJsonUnits.mmToMil(x, 0),
+            y: CircuitJsonUnits.mmToMil(y, 0),
+            z: CircuitJsonUnits.mmToMil(z, 0)
+        }
+    }
+
+    /**
+     * Resolves optional display opacity.
+     * @param {object} cadComponent CAD component element.
+     * @returns {number | null}
+     */
+    static #displayOpacity(cadComponent) {
+        for (const value of [
+            cadComponent?.bodyOpacity,
+            cadComponent?.body_opacity,
+            cadComponent?.model_opacity
+        ]) {
+            const opacity = Number(value)
+            if (Number.isFinite(opacity) && opacity > 0 && opacity < 1) {
+                return opacity
+            }
+        }
+
+        return cadComponent?.show_as_translucent_model === true ? 0.5 : null
+    }
+
+    /**
+     * Returns a non-empty string or null.
+     * @param {unknown} value Candidate string value.
+     * @returns {string | null}
+     */
+    static #stringValue(value) {
+        const text = String(value || '').trim()
+        return text ? text : null
+    }
+
+    /**
+     * Returns a positive finite number or fallback.
+     * @param {unknown} value Candidate value.
+     * @param {number} fallback Fallback value.
+     * @returns {number}
+     */
+    static #positiveFinite(value, fallback) {
+        const number = Number(value)
+        return Number.isFinite(number) && number > 0 ? number : fallback
+    }
+}

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,74 @@ 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(designator)
+        const activeKey =
+            PcbScene3dComponentVisibility.#normalizeDesignator(
+                selectedDesignator
+            )
+        if (!activeKey || !selectedVariantGroupKeys.size) {
+            return false
+        }
+
+        if (selectedKey === activeKey) {
+            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 +173,8 @@ export class PcbScene3dComponentVisibility {
         ) {
             return PcbScene3dComponentVisibility.#resolveFallbackVisible(
                 state,
-                designator
+                designator,
+                rootObject
             )
         }
 
@@ -110,14 +192,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?.(