pcb-scene3d-viewer 1.1.19 → 1.1.21

package/src/PcbAssemblyWrlWriter.mjs

@@ -0,0 +1,144 @@
+import { PcbAssemblyExportCoordinateFrame } from './PcbAssemblyExportCoordinateFrame.mjs'
+import { PcbAssemblyMeshUtils } from './PcbAssemblyMeshUtils.mjs'
+
+/**
+ * Writes PCB assembly meshes as VRML 2.0 WRL.
+ */
+export class PcbAssemblyWrlWriter {
+    /**
+     * Writes meshes to WRL text.
+     * @param {{ name?: string, meshes?: object[] }} assembly Assembly data.
+     * @returns {string}
+     */
+    static write(assembly = {}) {
+        const meshes = Array.isArray(assembly?.meshes) ? assembly.meshes : []
+
+        return (
+            '#VRML V2.0 utf8\n' +
+            'WorldInfo { title "' +
+            PcbAssemblyWrlWriter.#escapeString(assembly?.name || 'assembly') +
+            '" }\n' +
+            'Group {\n  children [\n' +
+            meshes.map((mesh) => PcbAssemblyWrlWriter.#shape(mesh)).join('') +
+            '  ]\n}\n'
+        )
+    }
+
+    /**
+     * Writes one mesh shape.
+     * @param {{ name?: string, vertices?: number[][], faces?: number[][], color?: number[] }} mesh Mesh data.
+     * @returns {string}
+     */
+    static #shape(mesh) {
+        const vertices = Array.isArray(mesh?.vertices) ? mesh.vertices : []
+        const faces = Array.isArray(mesh?.faces) ? mesh.faces : []
+        if (!vertices.length || !faces.length) {
+            return ''
+        }
+
+        return (
+            '    DEF ' +
+            PcbAssemblyWrlWriter.#safeVrmlName(mesh?.name || 'mesh') +
+            ' Shape {\n' +
+            '      appearance Appearance { material Material { diffuseColor ' +
+            PcbAssemblyWrlWriter.#color(mesh?.color) +
+            ' } }\n' +
+            '      geometry IndexedFaceSet {\n' +
+            '        solid TRUE\n' +
+            '        coord Coordinate { point [\n' +
+            vertices
+                .map(
+                    (vertex) =>
+                        '          ' + PcbAssemblyWrlWriter.#point(vertex)
+                )
+                .join('') +
+            '        ] }\n' +
+            '        coordIndex [\n' +
+            faces
+                .map(
+                    (face) =>
+                        '          ' +
+                        PcbAssemblyWrlWriter.#faceIndices(face) +
+                        ' -1,\n'
+                )
+                .join('') +
+            '        ]\n' +
+            '      }\n' +
+            '    }\n'
+        )
+    }
+
+    /**
+     * Formats one exported coordinate point.
+     * @param {number[]} vertex Internal mesh vertex in mils.
+     * @returns {string}
+     */
+    static #point(vertex) {
+        return (
+            PcbAssemblyExportCoordinateFrame.vertexMilToMm(vertex)
+                .map((value) => PcbAssemblyWrlWriter.#formatNumber(value))
+                .join(' ') + ',\n'
+        )
+    }
+
+    /**
+     * Formats one face index list.
+     * @param {number[]} face Face indices.
+     * @returns {string}
+     */
+    static #faceIndices(face) {
+        return (Array.isArray(face) ? face : [])
+            .map((index) => String(Number(index || 0)))
+            .join(' ')
+    }
+
+    /**
+     * Formats one RGB color.
+     * @param {number[] | undefined} color RGB color.
+     * @returns {string}
+     */
+    static #color(color) {
+        const normalized = Array.isArray(color) ? color : [0.55, 0.56, 0.58]
+        return [0, 1, 2]
+            .map((index) =>
+                PcbAssemblyWrlWriter.#formatNumber(
+                    Math.max(Math.min(Number(normalized[index] || 0), 1), 0)
+                )
+            )
+            .join(' ')
+    }
+
+    /**
+     * Formats a compact numeric literal.
+     * @param {number} value Numeric value.
+     * @returns {string}
+     */
+    static #formatNumber(value) {
+        const number = Number(value || 0)
+        return Math.abs(number) < 0.0000001
+            ? '0'
+            : Number(number.toFixed(6)).toString()
+    }
+
+    /**
+     * Escapes a WRL string.
+     * @param {string} value Source value.
+     * @returns {string}
+     */
+    static #escapeString(value) {
+        return String(value || '').replaceAll('"', '\\"')
+    }
+
+    /**
+     * Builds a valid VRML DEF token.
+     * @param {string} value Source value.
+     * @returns {string}
+     */
+    static #safeVrmlName(value) {
+        const safe = PcbAssemblyMeshUtils.safeName(value).replace(
+            /[^A-Za-z0-9_]+/gu,
+            '_'
+        )
+        return /^[A-Za-z_]/u.test(safe) ? safe : '_' + safe
+    }
+}

package/src/PcbScene3dCameraRig.mjs

@@ -267,12 +267,18 @@ export class PcbScene3dCameraRig {
      */
     static #applyOrthographicProjection(camera, state) {
         const zoom = Math.max(Number(camera.zoom || 1), 0.0001)
-        const height = Math.max(Number(state.orthographicHeight || 0) / zoom, 1)
+        const height = Math.max(Number(state.orthographicHeight || 0), 1)
         const width = height * Math.max(Number(camera.aspect || 1), 0.0001)
         const left = -width / 2
         const right = width / 2
         const top = height / 2
         const bottom = -height / 2
+        // Keep camera bounds unzoomed for OrbitControls pan math; apply zoom
+        // only to the projection matrix so dragging stays cursor-locked.
+        const projectedLeft = left / zoom
+        const projectedRight = right / zoom
+        const projectedTop = top / zoom
+        const projectedBottom = bottom / zoom
 
         camera.left = left
         camera.right = right
@@ -281,10 +287,10 @@ export class PcbScene3dCameraRig {
         camera.isPerspectiveCamera = false
         camera.isOrthographicCamera = true
         camera.projectionMatrix?.makeOrthographic?.(
-            left,
-            right,
-            top,
-            bottom,
+            projectedLeft,
+            projectedRight,
+            projectedTop,
+            projectedBottom,
             camera.near,
             camera.far
         )

package/src/PcbScene3dComponentVisibility.mjs

@@ -0,0 +1,161 @@
+/**
+ * Applies per-component hidden state on top of existing 3D visibility toggles.
+ */
+export class PcbScene3dComponentVisibility {
+    /**
+     * Stores one component hidden state.
+     * @param {Set<string>} hiddenDesignators Hidden designator set.
+     * @param {string} designator Component designator.
+     * @param {boolean} hidden Whether the component should be hidden.
+     * @returns {boolean}
+     */
+    static setHidden(hiddenDesignators, designator, hidden) {
+        if (!(hiddenDesignators instanceof Set)) {
+            return false
+        }
+
+        const normalizedDesignator =
+            PcbScene3dComponentVisibility.#normalizeDesignator(designator)
+        if (!normalizedDesignator) {
+            return false
+        }
+
+        const wasHidden = hiddenDesignators.has(normalizedDesignator)
+        if (hidden) {
+            hiddenDesignators.add(normalizedDesignator)
+        } else {
+            hiddenDesignators.delete(normalizedDesignator)
+        }
+        return wasHidden !== hiddenDesignators.has(normalizedDesignator)
+    }
+
+    /**
+     * Checks whether one component is hidden.
+     * @param {Set<string>} hiddenDesignators Hidden designator set.
+     * @param {string} designator Component designator.
+     * @returns {boolean}
+     */
+    static isHidden(hiddenDesignators, designator) {
+        return (
+            hiddenDesignators instanceof Set &&
+            hiddenDesignators.has(
+                PcbScene3dComponentVisibility.#normalizeDesignator(designator)
+            )
+        )
+    }
+
+    /**
+     * 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.
+     * @returns {void}
+     */
+    static apply(state) {
+        const selectionRoots = state?.selectionRoots
+        if (!(selectionRoots instanceof Map)) {
+            return
+        }
+
+        selectionRoots.forEach((roots, designator) => {
+            roots?.forEach?.((rootObject) => {
+                if (!rootObject) {
+                    return
+                }
+
+                rootObject.visible =
+                    !PcbScene3dComponentVisibility.isHidden(
+                        state?.hiddenDesignators,
+                        designator
+                    ) &&
+                    PcbScene3dComponentVisibility.#resolveRootVisible(
+                        state,
+                        designator,
+                        rootObject
+                    )
+            })
+        })
+    }
+
+    /**
+     * 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.
+     * @param {string} designator Component designator.
+     * @param {any} rootObject Render root.
+     * @returns {boolean}
+     */
+    static #resolveRootVisible(state, designator, rootObject) {
+        if (
+            PcbScene3dComponentVisibility.#isFallbackRoot(
+                state?.fallbackBodyRoots,
+                designator,
+                rootObject
+            )
+        ) {
+            return PcbScene3dComponentVisibility.#resolveFallbackVisible(
+                state,
+                designator
+            )
+        }
+
+        if (state?.modelSearchExternalModelRoots?.has?.(rootObject)) {
+            return (
+                Boolean(state?.toggles?.['external-models']) &&
+                state?.toggles?.['model-search-models'] !== false
+            )
+        }
+
+        return true
+    }
+
+    /**
+     * 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.
+     * @returns {boolean}
+     */
+    static #resolveFallbackVisible(state, designator) {
+        const boardAssemblyActive =
+            Boolean(state?.hasLoadedBoardAssemblyModel) &&
+            Boolean(state?.toggles?.['external-models'])
+        const showFallbackBodies =
+            Boolean(state?.toggles?.['fallback-bodies']) && !boardAssemblyActive
+        const hideForLoadedExternal =
+            Boolean(state?.toggles?.['external-models']) &&
+            state?.loadedExternalModelDesignators?.has?.(
+                PcbScene3dComponentVisibility.#normalizeDesignator(designator)
+            )
+
+        return showFallbackBodies && !hideForLoadedExternal
+    }
+
+    /**
+     * Checks whether a root belongs to fallback-body tracking.
+     * @param {Map<string, Set<any>> | undefined} fallbackBodyRoots Fallback roots.
+     * @param {string} designator Component designator.
+     * @param {any} rootObject Render root.
+     * @returns {boolean}
+     */
+    static #isFallbackRoot(fallbackBodyRoots, designator, rootObject) {
+        if (!(fallbackBodyRoots instanceof Map)) {
+            return false
+        }
+
+        return Boolean(
+            fallbackBodyRoots
+                .get(
+                    PcbScene3dComponentVisibility.#normalizeDesignator(
+                        designator
+                    )
+                )
+                ?.has?.(rootObject)
+        )
+    }
+
+    /**
+     * Normalizes component designator keys.
+     * @param {string} designator Raw designator.
+     * @returns {string}
+     */
+    static #normalizeDesignator(designator) {
+        return String(designator || '').trim()
+    }
+}

package/src/PcbScene3dController.mjs

@@ -4,6 +4,7 @@ import { PcbScene3dCircuitJsonAdapter } from './PcbScene3dCircuitJsonAdapter.mjs
 import { PcbScene3dInteractionHints } from './PcbScene3dInteractionHints.mjs'
 import { PcbScene3dRuntime } from './PcbScene3dRuntime.mjs'
 import { PcbScene3dSelectionInspectorRenderer } from './PcbScene3dSelectionInspectorRenderer.mjs'
+import { PcbScene3dSelectionVisibilityBinder } from './PcbScene3dSelectionVisibilityBinder.mjs'
 import { PcbScene3dText } from './PcbScene3dText.mjs'
 
 /**
@@ -31,6 +32,8 @@ export class PcbScene3dController {
     /** @type {PcbScene3dAdjustmentControlBinder | null} */
     #adjustmentControls
 
+    /** @type {PcbScene3dSelectionVisibilityBinder | null} */
+    #visibilityControls
     /** @type {Array<{ node: EventTarget, type: string, listener: (event: any) => void }>} */
     #listeners
 
@@ -43,7 +46,7 @@ export class PcbScene3dController {
     /** @type {string} */
     #selectedComponentKey
 
-    /** @type {{ setPreset?: (preset: string) => void, setToggle?: (toggleName: string, enabled: boolean) => void, setSelectedDesignator?: (designator: string) => void, setComponentAdjustment?: (designator: string, adjustment: { scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }) => void, dispose?: () => void } | null} */
+    /** @type {any | null} */
     #runtime
 
     /** @type {any | null} */
@@ -151,19 +154,36 @@ export class PcbScene3dController {
                     suppressed ? '' : this.#selectedComponentKey
                 )
             },
-            refreshSelection: (designator) => {
+            refreshSelection: (designator, sourceType) => {
                 this.#setSelection({
                     designator,
-                    sourceType: this.#resolveSelectionSourceType(designator)
+                    sourceType:
+                        sourceType ||
+                        this.#resolveSelectionSourceType(designator)
+                })
+            }
+        })
+        this.#visibilityControls = new PcbScene3dSelectionVisibilityBinder({
+            resolveDesignator: () => this.#selectedComponentKey,
+            resolveHidden: (designator) =>
+                Boolean(this.#runtime?.isComponentHidden?.(designator)),
+            setHidden: (designator, hidden) => {
+                this.#runtime?.setComponentHidden?.(designator, hidden)
+            },
+            refreshSelection: (designator, source) => {
+                this.#setSelection({
+                    designator,
+                    sourceType:
+                        source || this.#resolveSelectionSourceType(designator)
                 })
             }
         })
-
         this.#bindPresets()
         this.#setActivePresetButton('isometric')
         this.#bindToggles()
         this.#bindExportAction()
         this.#adjustmentControls.bindSelectionNode(this.#selectionNode)
+        this.#visibilityControls.bindSelectionNode(this.#selectionNode)
         this.#setSelection(null)
         this.#setLoadingVisible(true)
         const circuitJsonModel = PcbScene3dController.#resolveCircuitJsonModel(
@@ -287,6 +307,8 @@ export class PcbScene3dController {
         this.#scenePrepClient = null
         this.#adjustmentControls?.dispose()
         this.#adjustmentControls = null
+        this.#visibilityControls?.dispose()
+        this.#visibilityControls = null
         this.#runtime?.dispose?.()
         this.#runtime = null
         this.#sceneDescription = null
@@ -739,6 +761,9 @@ export class PcbScene3dController {
             this.#selectionNode.innerHTML =
                 PcbScene3dSelectionInspectorRenderer.renderSelected({
                     designator,
+                    hidden: Boolean(
+                        this.#runtime?.isComponentHidden?.(designator)
+                    ),
                     selection,
                     selectionEntry,
                     adjustment,

package/src/PcbScene3dExternalModelPlacementRepair.mjs

@@ -13,7 +13,7 @@ export class PcbScene3dExternalModelPlacementRepair {
         '#333333',
         '#3f3f3f'
     ])
-    static #MIN_CENTER_ERROR_MIL = 25
+    static #MIN_CENTER_ERROR_MIL = 1
     static #MIN_TERMINAL_SIZE_MIL = 1
     static #SOURCE_ORIGIN_SHIFT_EPSILON_MIL = 0.01
     static #SOURCE_Z_DEPTH_MIN_RATIO = 1.5

package/src/PcbScene3dInteractionHints.mjs

@@ -6,24 +6,32 @@ export class PcbScene3dInteractionHints {
      * Applies explicit OrbitControls input mappings for desktop and touch.
      * @param {{ mouseButtons?: any, touches?: any }} controls
      * @param {{ MOUSE?: any, TOUCH?: any }} THREE
+     * @param {string} [preset] Active camera preset.
      * @returns {void}
      */
-    static configureControls(controls, THREE) {
+    static configureControls(controls, THREE, preset = 'isometric') {
         if (!controls) {
             return
         }
 
+        const inspectionPreset =
+            String(preset || '').toLowerCase() === 'top' ||
+            String(preset || '').toLowerCase() === 'bottom'
+
         if (THREE?.MOUSE) {
             controls.mouseButtons = {
-                LEFT: THREE.MOUSE.ROTATE,
+                LEFT: inspectionPreset ? THREE.MOUSE.PAN : THREE.MOUSE.ROTATE,
                 MIDDLE: THREE.MOUSE.DOLLY,
-                RIGHT: THREE.MOUSE.PAN
+                RIGHT: inspectionPreset ? THREE.MOUSE.ROTATE : THREE.MOUSE.PAN
             }
         }
 
         if (THREE?.TOUCH) {
             controls.touches = {
-                ONE: THREE.TOUCH.ROTATE,
+                ONE:
+                    inspectionPreset && THREE.TOUCH.PAN
+                        ? THREE.TOUCH.PAN
+                        : THREE.TOUCH.ROTATE,
                 TWO: THREE.TOUCH.DOLLY_PAN
             }
         }
@@ -44,13 +52,13 @@ export class PcbScene3dInteractionHints {
                 const value = translate('scene3d.touchHint')
                 if (value && value !== 'scene3d.touchHint') return value
             }
-            return 'Drag with one finger to orbit, pinch to zoom, and drag with two fingers to pan.'
+            return 'One-finger drag pans in Top/Bottom and orbits in Isometric. Pinch to zoom.'
         }
 
         if (typeof translate === 'function') {
             const value = translate('scene3d.pointerHint')
             if (value && value !== 'scene3d.pointerHint') return value
         }
-        return 'Drag to orbit, right-drag to pan, and use the wheel to zoom.'
+        return 'Drag pans in Top/Bottom and orbits in Isometric; right-drag uses the alternate action. Use the wheel to zoom.'
     }
 }

package/src/PcbScene3dRenderScheduler.mjs

@@ -0,0 +1,55 @@
+/**
+ * Coalesces high-frequency scene renders into animation frames.
+ */
+export class PcbScene3dRenderScheduler {
+    /** @type {() => void} */
+    #render
+
+    /** @type {number | null} */
+    #pendingFrame
+
+    /**
+     * @param {() => void} render Render callback.
+     */
+    constructor(render) {
+        this.#render = render
+        this.#pendingFrame = null
+    }
+
+    /**
+     * Queues a render for the next animation frame.
+     * @returns {void}
+     */
+    schedule() {
+        if (this.#pendingFrame !== null) {
+            return
+        }
+
+        const requestFrame = globalThis.window?.requestAnimationFrame
+        if (typeof requestFrame !== 'function') {
+            this.#render()
+            return
+        }
+
+        this.#pendingFrame = requestFrame(() => {
+            this.#pendingFrame = null
+            this.#render()
+        })
+    }
+
+    /**
+     * Cancels one pending animation-frame render.
+     * @returns {void}
+     */
+    cancel() {
+        if (this.#pendingFrame === null) {
+            return
+        }
+
+        const cancelFrame = globalThis.window?.cancelAnimationFrame
+        if (typeof cancelFrame === 'function') {
+            cancelFrame(this.#pendingFrame)
+        }
+        this.#pendingFrame = null
+    }
+}