pcb-scene3d-viewer 1.0.1

package/src/PcbScene3dViaFactory.mjs

@@ -0,0 +1,176 @@
+import { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
+
+/**
+ * Builds annular via barrels for the interactive 3D PCB scene.
+ */
+export class PcbScene3dViaFactory {
+    static #PAD_BARREL_OUTER_RADIUS_SCALE = 0.98
+    static #PAD_BARREL_MIN_WALL_MIL = 1.2
+    static #PAD_BARREL_WALL_FRACTION = 0.09
+
+    /**
+     * Builds the via mesh group for one scene.
+     * @param {any} THREE
+     * @param {{ diameter?: number, holeDiameter?: number, x?: number, y?: number, barrelOnly?: boolean }[]} vias
+     * @param {number} thicknessMil
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @returns {any}
+     */
+    static buildGroup(THREE, vias, thicknessMil, normalizeBoardPoint) {
+        const group = new THREE.Group()
+        const material = new THREE.MeshStandardMaterial({
+            color: 0xcaa24e,
+            roughness: 0.48,
+            metalness: 0.42,
+            side: THREE.DoubleSide
+        })
+        const geometryCache = new Map()
+
+        ;(vias || []).forEach((via) => {
+            const geometry = PcbScene3dViaFactory.#resolveGeometry(
+                THREE,
+                geometryCache,
+                via,
+                thicknessMil
+            )
+            const mesh = new THREE.Mesh(geometry, material)
+            const point = normalizeBoardPoint(
+                Number(via?.x || 0),
+                Number(via?.y || 0)
+            )
+            mesh.position.set(point.x, point.y, 0)
+            if (geometry.type === 'CylinderGeometry') {
+                mesh.rotation.x = Math.PI / 2
+            }
+            group.add(mesh)
+        })
+
+        return group
+    }
+
+    /**
+     * Resolves one reusable via geometry from the via drill spec.
+     * @param {any} THREE
+     * @param {Map<string, any>} geometryCache
+     * @param {{ diameter?: number, holeDiameter?: number, barrelOnly?: boolean }} via
+     * @param {number} thicknessMil
+     * @returns {any}
+     */
+    static #resolveGeometry(THREE, geometryCache, via, thicknessMil) {
+        const outerRadius = Math.max(Number(via?.diameter || 0) / 2, 1.2)
+        const holeDiameter = Math.max(Number(via?.holeDiameter || 0), 0)
+        const depth = thicknessMil + 2
+        const isBarrelOnly = Boolean(via?.barrelOnly)
+        const cacheKey = [
+            isBarrelOnly ? 'barrel' : 'annulus',
+            outerRadius.toFixed(4),
+            holeDiameter.toFixed(4),
+            depth.toFixed(4)
+        ].join(':')
+        const cached = geometryCache.get(cacheKey)
+        if (cached) {
+            return cached
+        }
+
+        let geometry
+        if (isBarrelOnly && holeDiameter > 0) {
+            geometry = PcbScene3dViaFactory.#buildPadBarrelGeometry(
+                THREE,
+                holeDiameter,
+                depth
+            )
+        } else if (holeDiameter > 0 && holeDiameter < outerRadius * 2 - 0.001) {
+            const shape = new THREE.Shape()
+            shape.moveTo(outerRadius, 0)
+            shape.absarc(0, 0, outerRadius, 0, Math.PI, false)
+            shape.absarc(0, 0, outerRadius, Math.PI, Math.PI * 2, false)
+            const drillHole = PcbScene3dDrillPathFactory.buildViaHolePath(
+                THREE,
+                via
+            )
+            if (drillHole) {
+                shape.holes.push(drillHole)
+            }
+            geometry = new THREE.ExtrudeGeometry(shape, {
+                depth,
+                bevelEnabled: false,
+                curveSegments: 24,
+                steps: 1
+            })
+            geometry.translate?.(0, 0, -depth / 2)
+        } else {
+            geometry = new THREE.CylinderGeometry(
+                outerRadius,
+                outerRadius,
+                depth,
+                18
+            )
+        }
+
+        geometryCache.set(cacheKey, geometry)
+        return geometry
+    }
+
+    /**
+     * Builds a visible copper sleeve for through-hole pads.
+     * @param {any} THREE
+     * @param {number} holeDiameter
+     * @param {number} depth
+     * @returns {any}
+     */
+    static #buildPadBarrelGeometry(THREE, holeDiameter, depth) {
+        const holeRadius = Math.max(Number(holeDiameter || 0) / 2, 0.8)
+        const outerRadius = Math.max(
+            holeRadius * PcbScene3dViaFactory.#PAD_BARREL_OUTER_RADIUS_SCALE,
+            0.8
+        )
+        const wallThickness = Math.max(
+            Number(holeDiameter || 0) *
+                PcbScene3dViaFactory.#PAD_BARREL_WALL_FRACTION,
+            PcbScene3dViaFactory.#PAD_BARREL_MIN_WALL_MIL
+        )
+        const innerRadius = Math.max(outerRadius - wallThickness, 0.6)
+        const shape = PcbScene3dViaFactory.#buildCircleShape(THREE, outerRadius)
+        shape.holes.push(
+            PcbScene3dViaFactory.#buildCirclePath(THREE, innerRadius)
+        )
+
+        const geometry = new THREE.ExtrudeGeometry(shape, {
+            depth,
+            bevelEnabled: false,
+            curveSegments: 24,
+            steps: 1
+        })
+        geometry.translate?.(0, 0, -depth / 2)
+        return geometry
+    }
+
+    /**
+     * Builds one filled circular shape centered on the origin.
+     * @param {any} THREE
+     * @param {number} radius
+     * @returns {any}
+     */
+    static #buildCircleShape(THREE, radius) {
+        const shape = new THREE.Shape()
+        shape.moveTo(radius, 0)
+        shape.absarc(0, 0, radius, 0, Math.PI, false)
+        shape.absarc(0, 0, radius, Math.PI, Math.PI * 2, false)
+        return shape
+    }
+
+    /**
+     * Builds one circular hole path centered on the origin.
+     * @param {any} THREE
+     * @param {number} radius
+     * @returns {any}
+     */
+    static #buildCirclePath(THREE, radius) {
+        const path = new THREE.Path()
+        path.moveTo(radius, 0)
+        path.absarc(0, 0, radius, 0, Math.PI, false)
+        path.absarc(0, 0, radius, Math.PI, Math.PI * 2, false)
+        path.closePath()
+        return path
+    }
+}

package/src/PcbScene3dViewCompensation.mjs

@@ -0,0 +1,109 @@
+/**
+ * Applies scene-view mirror compensation to selected 3D detail nodes.
+ */
+export class PcbScene3dViewCompensation {
+    /**
+     * Applies the active view mirror compensation throughout one scene branch.
+     * @param {any} root Root group or mesh.
+     * @param {{ x?: number, y?: number, z?: number } | null | undefined} viewScale Active scene view scale.
+     * @returns {void}
+     */
+    static apply(root, viewScale) {
+        const pendingGroups = [root]
+
+        while (pendingGroups.length) {
+            const group = pendingGroups.pop()
+            if (!group) {
+                continue
+            }
+
+            if (group.userData?.scene3dViewCompensation) {
+                PcbScene3dViewCompensation.applyToGroup(group, viewScale)
+            }
+
+            if (Array.isArray(group.children)) {
+                group.children.forEach((child) => pendingGroups.push(child))
+            }
+        }
+    }
+
+    /**
+     * Applies the active view mirror compensation to one marked object.
+     * @param {any} group View compensation target.
+     * @param {{ x?: number, y?: number, z?: number } | null | undefined} viewScale Active scene view scale.
+     * @returns {void}
+     */
+    static applyToGroup(group, viewScale) {
+        const axes = group?.userData?.scene3dViewCompensationAxes || {}
+        const axisSources =
+            group?.userData?.scene3dViewCompensationAxisSources || {}
+        const sourceScale = group?.userData?.scene3dSourceFrameScale || {}
+
+        group?.scale?.set?.(
+            PcbScene3dViewCompensation.#resolveScaleMultiplier(sourceScale?.x) *
+                (axes.x === false
+                    ? 1
+                    : PcbScene3dViewCompensation.#resolveCompensationSign(
+                          viewScale,
+                          'x',
+                          axisSources?.x
+                      )),
+            PcbScene3dViewCompensation.#resolveScaleMultiplier(sourceScale?.y) *
+                (axes.y === false
+                    ? 1
+                    : PcbScene3dViewCompensation.#resolveCompensationSign(
+                          viewScale,
+                          'y',
+                          axisSources?.y
+                      )),
+            PcbScene3dViewCompensation.#resolveScaleMultiplier(sourceScale?.z) *
+                (axes.z === false
+                    ? 1
+                    : PcbScene3dViewCompensation.#resolveCompensationSign(
+                          viewScale,
+                          'z',
+                          axisSources?.z
+                      ))
+        )
+    }
+
+    /**
+     * Resolves a source-frame scale multiplier.
+     * @param {number | string | undefined} value Source scale value.
+     * @returns {number}
+     */
+    static #resolveScaleMultiplier(value) {
+        const scale = Number(value)
+
+        return Number.isFinite(scale) && scale !== 0 ? scale : 1
+    }
+
+    /**
+     * Resolves the compensation sign for one view axis.
+     * @param {{ x?: number, y?: number, z?: number } | null | undefined} viewScale Active scene view scale.
+     * @param {'x' | 'y' | 'z'} axis Target scale axis.
+     * @param {string | undefined} source Axis source mode.
+     * @returns {number}
+     */
+    static #resolveCompensationSign(viewScale, axis, source) {
+        if (source === 'board-mirror') {
+            return (
+                PcbScene3dViewCompensation.#resolveViewScaleSign(viewScale?.x) *
+                PcbScene3dViewCompensation.#resolveViewScaleSign(viewScale?.y)
+            )
+        }
+
+        return PcbScene3dViewCompensation.#resolveViewScaleSign(
+            viewScale?.[axis]
+        )
+    }
+
+    /**
+     * Converts one view scale axis into the matching mirror compensation sign.
+     * @param {number | string | undefined} value View scale axis.
+     * @returns {1 | -1}
+     */
+    static #resolveViewScaleSign(value) {
+        return Number(value) < 0 ? -1 : 1
+    }
+}

package/src/PcbScene3dViewScale.mjs

@@ -0,0 +1,24 @@
+/**
+ * Resolves per-view scene scale transforms for PCB 3D presets.
+ */
+export class PcbScene3dViewScale {
+    /**
+     * Resolves the scene-scale transform for one named preset.
+     * @param {string} preset Preset name.
+     * @param {{ coordinateSystem?: string } | null} [sceneDescription] Scene coordinate metadata.
+     * @returns {{ x: number, y: number, z: number }}
+     */
+    static resolve(preset, sceneDescription = null) {
+        const normalizedPreset = String(preset || 'isometric').toLowerCase()
+
+        if (sceneDescription?.coordinateSystem === 'kicad-3d-y-up') {
+            return { x: 1, y: 1, z: 1 }
+        }
+
+        return normalizedPreset === 'top'
+            ? { x: 1, y: -1, z: 1 }
+            : normalizedPreset === 'bottom'
+              ? { x: -1, y: 1, z: 1 }
+              : { x: 1, y: -1, z: 1 }
+    }
+}

package/src/PcbScene3dViewportResize.mjs

@@ -0,0 +1,35 @@
+/**
+ * Viewport sizing helpers for the 3D runtime.
+ */
+export class PcbScene3dViewportResize {
+    /**
+     * Observes element-level viewport size changes.
+     * @param {typeof globalThis} globalRef Runtime global object.
+     * @param {HTMLElement | null} viewportNode Viewport mount node.
+     * @param {() => void} onResize Resize callback.
+     * @returns {{ disconnect?: () => void } | null}
+     */
+    static observe(globalRef, viewportNode, onResize) {
+        const ResizeObserverCtor = globalRef?.ResizeObserver
+        if (typeof ResizeObserverCtor !== 'function' || !viewportNode) {
+            return null
+        }
+
+        const observer = new ResizeObserverCtor(() => onResize())
+        observer.observe(viewportNode)
+        return observer
+    }
+
+    /**
+     * Resolves the viewport size while guarding against zero-sized mounts.
+     * @param {HTMLElement | null} viewportNode Viewport mount node.
+     * @returns {{ width: number, height: number }}
+     */
+    static resolveSize(viewportNode) {
+        const rect = viewportNode?.getBoundingClientRect?.()
+        return {
+            width: Math.max(Math.round(Number(rect?.width || 960)), 320),
+            height: Math.max(Math.round(Number(rect?.height || 560)), 320)
+        }
+    }
+}

package/src/PcbScene3dWorkerClient.mjs

@@ -0,0 +1,123 @@
+/**
+ * Browser-side client wrapper for the dedicated 3D scene prep worker.
+ */
+export class PcbScene3dWorkerClient {
+    /** @type {(() => Worker) | null} */
+    #createWorker
+
+    /** @type {Worker | null} */
+    #worker
+
+    /** @type {number} */
+    #requestSequence
+
+    /** @type {Map<string, { resolve: (sceneDescription: any) => void, reject: (error: Error) => void }>} */
+    #pendingRequests
+
+    /**
+     * @param {(() => Worker) | null} workerFactory
+     */
+    constructor(workerFactory) {
+        this.#createWorker = workerFactory || null
+        this.#worker = null
+        this.#requestSequence = 1
+        this.#pendingRequests = new Map()
+        this.#ensureWorker()
+    }
+
+    /**
+     * Sends one 3D scene prep request through the worker.
+     * @param {any} documentModel
+     * @param {any[]} [sessionAssets]
+     * @returns {Promise<any>}
+     */
+    prepareScene(documentModel, sessionAssets = []) {
+        return new Promise((resolve, reject) => {
+            if (!this.#worker) {
+                reject(new Error('3D scene worker is unavailable.'))
+                return
+            }
+
+            const requestId = 'scene3d-request-' + this.#requestSequence++
+            this.#pendingRequests.set(requestId, { resolve, reject })
+            this.#worker.postMessage({
+                type: 'scene3d:prepare',
+                requestId,
+                documentModel,
+                sessionAssets
+            })
+        })
+    }
+
+    /**
+     * Releases the worker and rejects any pending requests.
+     * @returns {void}
+     */
+    dispose() {
+        this.#pendingRequests.forEach(({ reject }) => {
+            reject(new Error('3D scene worker terminated.'))
+        })
+        this.#pendingRequests.clear()
+        this.#worker?.terminate()
+        this.#worker = null
+        this.#createWorker = null
+    }
+
+    /**
+     * Creates the backing worker and event listeners once.
+     * @returns {void}
+     */
+    #ensureWorker() {
+        if (!this.#createWorker || this.#worker) {
+            return
+        }
+
+        this.#worker = this.#createWorker()
+        this.#worker.addEventListener('message', (event) => {
+            this.#handleWorkerMessage(event?.data || {})
+        })
+        this.#worker.addEventListener('error', (event) => {
+            this.#rejectAllPending(
+                new Error(
+                    '3D scene worker failed: ' +
+                        String(event?.message || 'Unknown error.')
+                )
+            )
+        })
+    }
+
+    /**
+     * Routes one worker payload to the matching pending request.
+     * @param {{ type?: string, requestId?: string, sceneDescription?: any, message?: string }} payload
+     * @returns {void}
+     */
+    #handleWorkerMessage(payload) {
+        const requestId = String(payload?.requestId || '')
+        const pendingRequest = this.#pendingRequests.get(requestId) || null
+        if (!pendingRequest) {
+            return
+        }
+
+        this.#pendingRequests.delete(requestId)
+        if (payload?.type === 'scene3d:success') {
+            pendingRequest.resolve(payload.sceneDescription || {})
+            return
+        }
+
+        pendingRequest.reject(
+            new Error(payload?.message || '3D scene worker failed.')
+        )
+    }
+
+    /**
+     * Rejects every unresolved worker request with one shared error.
+     * @param {Error} error
+     * @returns {void}
+     */
+    #rejectAllPending(error) {
+        this.#pendingRequests.forEach(({ reject }) => {
+            reject(error)
+        })
+        this.#pendingRequests.clear()
+    }
+}

package/src/index.mjs

@@ -0,0 +1 @@
+export * from './scene3d.mjs'

package/src/scene3d.mjs

@@ -0,0 +1,44 @@
+export { PcbModelArchiveExporter } from './PcbModelArchiveExporter.mjs'
+export { PcbScene3dBoardAssemblyPlacement } from './PcbScene3dBoardAssemblyPlacement.mjs'
+export { PcbScene3dBoardAssemblyPresentation } from './PcbScene3dBoardAssemblyPresentation.mjs'
+export { PcbScene3dBoardEdgeCutoutBuilder } from './PcbScene3dBoardEdgeCutoutBuilder.mjs'
+export { PcbScene3dBoardMaterialPalette } from './PcbScene3dBoardMaterialPalette.mjs'
+export { PcbScene3dBoardShapeFactory } from './PcbScene3dBoardShapeFactory.mjs'
+export { PcbScene3dBoardSolderMaskFactory } from './PcbScene3dBoardSolderMaskFactory.mjs'
+export { PcbScene3dCameraRig } from './PcbScene3dCameraRig.mjs'
+export { PcbScene3dController } from './PcbScene3dController.mjs'
+export { PcbScene3dCircuitJsonAdapter } from './PcbScene3dCircuitJsonAdapter.mjs'
+export { PcbScene3dCopperDetailFilter } from './PcbScene3dCopperDetailFilter.mjs'
+export { PcbScene3dCopperFactory } from './PcbScene3dCopperFactory.mjs'
+export { PcbScene3dCopperTextFactory } from './PcbScene3dCopperTextFactory.mjs'
+export { PcbScene3dCutoutGeometryFilter } from './PcbScene3dCutoutGeometryFilter.mjs'
+export { PcbScene3dDetailCoordinateNormalizer } from './PcbScene3dDetailCoordinateNormalizer.mjs'
+export { PcbScene3dDrillCutoutFilter } from './PcbScene3dDrillCutoutFilter.mjs'
+export { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
+export { PcbScene3dDrillVoidFactory } from './PcbScene3dDrillVoidFactory.mjs'
+export { PcbScene3dExternalModelLoadOrder } from './PcbScene3dExternalModelLoadOrder.mjs'
+export { PcbScene3dExternalModels } from './PcbScene3dExternalModels.mjs'
+export { PcbScene3dFallbackVisibility } from './PcbScene3dFallbackVisibility.mjs'
+export { PcbScene3dInteractionHints } from './PcbScene3dInteractionHints.mjs'
+export { PcbScene3dMountRig } from './PcbScene3dMountRig.mjs'
+export { PcbScene3dOutlineBuilder } from './PcbScene3dOutlineBuilder.mjs'
+export { PcbScene3dPadFactory } from './PcbScene3dPadFactory.mjs'
+export { PcbScene3dPresetState } from './PcbScene3dPresetState.mjs'
+export { PcbScene3dRenderGroupVisibility } from './PcbScene3dRenderGroupVisibility.mjs'
+export { PcbScene3dRuntime } from './PcbScene3dRuntime.mjs'
+export { PcbScene3dRuntimeBoardMeshes } from './PcbScene3dRuntimeBoardMeshes.mjs'
+export { PcbScene3dSelectionStyler } from './PcbScene3dSelectionStyler.mjs'
+export { PcbScene3dShapePathFactory } from './PcbScene3dShapePathFactory.mjs'
+export { PcbScene3dShellRenderer } from './PcbScene3dShellRenderer.mjs'
+export { PcbScene3dSilkscreenFactory } from './PcbScene3dSilkscreenFactory.mjs'
+export { PcbScene3dSilkscreenStrokeWidthResolver } from './PcbScene3dSilkscreenStrokeWidthResolver.mjs'
+export { PcbScene3dStepLoader } from './PcbScene3dStepLoader.mjs'
+export { PcbScene3dStrokeFont } from './PcbScene3dStrokeFont.mjs'
+export { PcbScene3dStrokeGeometryBuilder } from './PcbScene3dStrokeGeometryBuilder.mjs'
+export { PcbScene3dText } from './PcbScene3dText.mjs'
+export { PcbScene3dTrueTypeTextFactory } from './PcbScene3dTrueTypeTextFactory.mjs'
+export { PcbScene3dViaFactory } from './PcbScene3dViaFactory.mjs'
+export { PcbScene3dViewCompensation } from './PcbScene3dViewCompensation.mjs'
+export { PcbScene3dViewScale } from './PcbScene3dViewScale.mjs'
+export { PcbScene3dViewportResize } from './PcbScene3dViewportResize.mjs'
+export { PcbScene3dWorkerClient } from './PcbScene3dWorkerClient.mjs'