pcb-scene3d-viewer 1.0.1

package/src/PcbScene3dFallbackVisibility.mjs

@@ -0,0 +1,82 @@
+/**
+ * Manages when procedural fallback bodies should stay visible alongside
+ * external 3D models.
+ */
+export class PcbScene3dFallbackVisibility {
+    /**
+     * Registers one fallback render root under a component designator.
+     * @param {Map<string, Set<any>>} fallbackRoots
+     * @param {string} designator
+     * @param {any} rootObject
+     * @returns {void}
+     */
+    static registerFallbackRoot(fallbackRoots, designator, rootObject) {
+        if (!(fallbackRoots instanceof Map) || !rootObject) {
+            return
+        }
+
+        const normalizedDesignator = String(designator || '').trim()
+        if (!normalizedDesignator) {
+            return
+        }
+
+        if (!fallbackRoots.has(normalizedDesignator)) {
+            fallbackRoots.set(normalizedDesignator, new Set())
+        }
+
+        fallbackRoots.get(normalizedDesignator)?.add(rootObject)
+    }
+
+    /**
+     * Marks one designator as having a successfully loaded external model.
+     * @param {Set<string>} loadedDesignators
+     * @param {string} designator
+     * @returns {void}
+     */
+    static markExternalModelLoaded(loadedDesignators, designator) {
+        if (!(loadedDesignators instanceof Set)) {
+            return
+        }
+
+        const normalizedDesignator = String(designator || '').trim()
+        if (!normalizedDesignator) {
+            return
+        }
+
+        loadedDesignators.add(normalizedDesignator)
+    }
+
+    /**
+     * Applies the current visibility policy to all registered fallback roots.
+     * Fallbacks stay visible when their toggle is enabled and either no
+     * external model loaded for that designator or external models are hidden.
+     * @param {Map<string, Set<any>>} fallbackRoots
+     * @param {Set<string>} loadedDesignators
+     * @param {{ 'fallback-bodies'?: boolean, 'external-models'?: boolean }} toggles
+     * @returns {void}
+     */
+    static applyVisibility(fallbackRoots, loadedDesignators, toggles) {
+        if (!(fallbackRoots instanceof Map)) {
+            return
+        }
+
+        const showFallbackBodies = Boolean(toggles?.['fallback-bodies'])
+        const showExternalModels = Boolean(toggles?.['external-models'])
+
+        fallbackRoots.forEach((roots, designator) => {
+            const hideForLoadedExternal =
+                showExternalModels &&
+                loadedDesignators instanceof Set &&
+                loadedDesignators.has(String(designator || '').trim())
+
+            roots?.forEach?.((rootObject) => {
+                if (!rootObject) {
+                    return
+                }
+
+                rootObject.visible =
+                    showFallbackBodies && !hideForLoadedExternal
+            })
+        })
+    }
+}

package/src/PcbScene3dInteractionHints.mjs

@@ -0,0 +1,56 @@
+/**
+ * Centralizes pointer and touch interaction defaults for the 3D PCB viewport.
+ */
+export class PcbScene3dInteractionHints {
+    /**
+     * Applies explicit OrbitControls input mappings for desktop and touch.
+     * @param {{ mouseButtons?: any, touches?: any }} controls
+     * @param {{ MOUSE?: any, TOUCH?: any }} THREE
+     * @returns {void}
+     */
+    static configureControls(controls, THREE) {
+        if (!controls) {
+            return
+        }
+
+        if (THREE?.MOUSE) {
+            controls.mouseButtons = {
+                LEFT: THREE.MOUSE.ROTATE,
+                MIDDLE: THREE.MOUSE.DOLLY,
+                RIGHT: THREE.MOUSE.PAN
+            }
+        }
+
+        if (THREE?.TOUCH) {
+            controls.touches = {
+                ONE: THREE.TOUCH.ROTATE,
+                TWO: THREE.TOUCH.DOLLY_PAN
+            }
+        }
+    }
+
+    /**
+     * Resolves the default interaction copy for the current pointer type.
+     * @param {{ matchMedia?: (query: string) => { matches?: boolean } }} [environment]
+     * @param {((key: string) => string) | null} [translate] Translation lookup.
+     * @returns {string}
+     */
+    static resolveDefaultMessage(
+        environment = globalThis.window,
+        translate = null
+    ) {
+        if (environment?.matchMedia?.('(pointer: coarse)')?.matches) {
+            if (typeof translate === 'function') {
+                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.'
+        }
+
+        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.'
+    }
+}

package/src/PcbScene3dMountRig.mjs

@@ -0,0 +1,53 @@
+/**
+ * Builds a stable transform hierarchy for one PCB-mounted 3D object.
+ */
+export class PcbScene3dMountRig {
+    /**
+     * Creates one transform rig that keeps the XY anchor fixed while flipping
+     * bottom-side content around the board face.
+     * @param {any} THREE
+     * @param {{ mountSide?: string, rotationDeg?: number, positionMil?: { x?: number, y?: number, z?: number } }} placement
+     * @returns {{ rootGroup: any, orientationGroup: any, sideGroup: any, faceGroup: any }}
+     */
+    static create(THREE, placement) {
+        const rootGroup = new THREE.Group()
+        const orientationGroup = new THREE.Group()
+        const sideGroup = new THREE.Group()
+        const faceGroup = new THREE.Group()
+        const positionMil = placement?.positionMil || {}
+
+        rootGroup.position.set(
+            Number(positionMil.x || 0),
+            Number(positionMil.y || 0),
+            0
+        )
+        orientationGroup.rotation.z =
+            (Number(placement?.rotationDeg || 0) * Math.PI) / 180
+        if (PcbScene3dMountRig.#isBottomSide(placement?.mountSide)) {
+            sideGroup.rotation.y = Math.PI
+            sideGroup.rotation.z = Math.PI
+        }
+
+        faceGroup.position.z = Math.abs(Number(positionMil.z || 0))
+
+        sideGroup.add(faceGroup)
+        orientationGroup.add(sideGroup)
+        rootGroup.add(orientationGroup)
+
+        return {
+            rootGroup,
+            orientationGroup,
+            sideGroup,
+            faceGroup
+        }
+    }
+
+    /**
+     * Returns true when one placement belongs on the underside of the board.
+     * @param {string | undefined} mountSide
+     * @returns {boolean}
+     */
+    static #isBottomSide(mountSide) {
+        return String(mountSide || 'top').toLowerCase() === 'bottom'
+    }
+}

package/src/PcbScene3dOutlineBuilder.mjs

@@ -0,0 +1,210 @@
+/**
+ * Builds stable board-outline commands for the 3D PCB runtime.
+ */
+export class PcbScene3dOutlineBuilder {
+    static #DEGENERATE_LINE_EPSILON = 0.01
+
+    /**
+     * Converts one board outline into local move/line/arc commands.
+     * @param {{ centerX?: number, centerY?: number, segments?: Array<Record<string, number | string>> }} board
+     * @returns {Array<Record<string, number | boolean>>}
+     */
+    static buildCommands(board) {
+        const segments = Array.isArray(board?.segments) ? board.segments : []
+        if (!segments.length) {
+            return []
+        }
+
+        const centerX = Number(board?.centerX || 0)
+        const centerY = Number(board?.centerY || 0)
+        const firstPoint = PcbScene3dOutlineBuilder.#toLocalPoint(
+            Number(segments[0].x1 || 0),
+            Number(segments[0].y1 || 0),
+            centerX,
+            centerY
+        )
+        const commands = [
+            {
+                type: 'move',
+                x: firstPoint.x,
+                y: firstPoint.y
+            }
+        ]
+
+        for (const segment of segments) {
+            if (segment.type === 'arc') {
+                const arcCommand = PcbScene3dOutlineBuilder.#buildArcCommand(
+                    segment,
+                    centerX,
+                    centerY
+                )
+                if (arcCommand) {
+                    commands.push(arcCommand)
+                }
+                continue
+            }
+
+            const lineCommand = PcbScene3dOutlineBuilder.#buildLineCommand(
+                segment,
+                centerX,
+                centerY
+            )
+            if (lineCommand) {
+                commands.push(lineCommand)
+            }
+        }
+
+        return commands
+    }
+
+    /**
+     * Converts one outline line segment into a local line command.
+     * @param {Record<string, number | string>} segment
+     * @param {number} centerX
+     * @param {number} centerY
+     * @returns {{ type: 'line', x: number, y: number } | null}
+     */
+    static #buildLineCommand(segment, centerX, centerY) {
+        const startPoint = PcbScene3dOutlineBuilder.#toLocalPoint(
+            Number(segment.x1 || 0),
+            Number(segment.y1 || 0),
+            centerX,
+            centerY
+        )
+        const endPoint = PcbScene3dOutlineBuilder.#toLocalPoint(
+            Number(segment.x2 || 0),
+            Number(segment.y2 || 0),
+            centerX,
+            centerY
+        )
+
+        if (
+            PcbScene3dOutlineBuilder.#distanceBetween(startPoint, endPoint) <
+            PcbScene3dOutlineBuilder.#DEGENERATE_LINE_EPSILON
+        ) {
+            return null
+        }
+
+        return {
+            type: 'line',
+            x: endPoint.x,
+            y: endPoint.y
+        }
+    }
+
+    /**
+     * Converts one outline arc segment into a local arc command traced from
+     * the ordered segment endpoints instead of the serialized angle fields.
+     * @param {Record<string, number | string>} segment
+     * @param {number} centerX
+     * @param {number} centerY
+     * @returns {{ type: 'arc', cx: number, cy: number, radius: number, startX: number, startY: number, endX: number, endY: number, startAngleRad: number, endAngleRad: number, clockwise: boolean } | null}
+     */
+    static #buildArcCommand(segment, centerX, centerY) {
+        const arcCenter = PcbScene3dOutlineBuilder.#toLocalPoint(
+            Number(segment.cx || 0),
+            Number(segment.cy || 0),
+            centerX,
+            centerY
+        )
+        const startPoint = PcbScene3dOutlineBuilder.#toLocalPoint(
+            Number(segment.x1 || 0),
+            Number(segment.y1 || 0),
+            centerX,
+            centerY
+        )
+        const endPoint = PcbScene3dOutlineBuilder.#toLocalPoint(
+            Number(segment.x2 || 0),
+            Number(segment.y2 || 0),
+            centerX,
+            centerY
+        )
+        const radius =
+            Math.max(
+                Number(segment.radius || 0),
+                PcbScene3dOutlineBuilder.#distanceBetween(
+                    arcCenter,
+                    startPoint
+                ),
+                PcbScene3dOutlineBuilder.#distanceBetween(arcCenter, endPoint)
+            ) || 0
+
+        if (!radius) {
+            return null
+        }
+
+        const startAngleRad = Math.atan2(
+            startPoint.y - arcCenter.y,
+            startPoint.x - arcCenter.x
+        )
+        const endAngleRad = Math.atan2(
+            endPoint.y - arcCenter.y,
+            endPoint.x - arcCenter.x
+        )
+        const deltaAngle = PcbScene3dOutlineBuilder.#resolveShortDeltaAngle(
+            startAngleRad,
+            endAngleRad
+        )
+
+        return {
+            type: 'arc',
+            cx: arcCenter.x,
+            cy: arcCenter.y,
+            radius,
+            startX: startPoint.x,
+            startY: startPoint.y,
+            endX: endPoint.x,
+            endY: endPoint.y,
+            startAngleRad,
+            endAngleRad,
+            clockwise: deltaAngle < 0
+        }
+    }
+
+    /**
+     * Converts one board-space point into local centered scene coordinates.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} centerX
+     * @param {number} centerY
+     * @returns {{ x: number, y: number }}
+     */
+    static #toLocalPoint(x, y, centerX, centerY) {
+        return {
+            x: Number(x || 0) - centerX,
+            y: Number(y || 0) - centerY
+        }
+    }
+
+    /**
+     * Measures one point-to-point distance.
+     * @param {{ x: number, y: number }} left
+     * @param {{ x: number, y: number }} right
+     * @returns {number}
+     */
+    static #distanceBetween(left, right) {
+        const deltaX = Number(right.x || 0) - Number(left.x || 0)
+        const deltaY = Number(right.y || 0) - Number(left.y || 0)
+        return Math.hypot(deltaX, deltaY)
+    }
+
+    /**
+     * Resolves the shortest signed delta between two radians.
+     * @param {number} startAngleRad
+     * @param {number} endAngleRad
+     * @returns {number}
+     */
+    static #resolveShortDeltaAngle(startAngleRad, endAngleRad) {
+        let deltaAngle = endAngleRad - startAngleRad
+
+        if (deltaAngle > Math.PI) {
+            deltaAngle -= Math.PI * 2
+        }
+
+        if (deltaAngle < -Math.PI) {
+            deltaAngle += Math.PI * 2
+        }
+
+        return deltaAngle
+    }
+}