pcb-scene3d-viewer 1.0.1

package/src/PcbScene3dRuntimeBoardMeshes.mjs

@@ -0,0 +1,99 @@
+import { PcbScene3dBoardMaterialPalette } from './PcbScene3dBoardMaterialPalette.mjs'
+import { PcbScene3dBoardShapeFactory } from './PcbScene3dBoardShapeFactory.mjs'
+
+/**
+ * Builds generated board meshes used by the interactive 3D runtime.
+ */
+export class PcbScene3dRuntimeBoardMeshes {
+    /**
+     * Builds the extruded board body mesh.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ board?: any, detail?: any, boardAssemblyModel?: any }} sceneDescription Scene metadata.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeDetailPoint Detail coordinate normalizer.
+     * @returns {any}
+     */
+    static buildBoardMesh(THREE, sceneDescription, normalizeDetailPoint) {
+        const board = sceneDescription.board
+        const geometry = PcbScene3dBoardShapeFactory.buildGeometry(
+            THREE,
+            board,
+            sceneDescription.detail,
+            normalizeDetailPoint
+        )
+        const hasBoardAssemblyModel = Boolean(
+            sceneDescription.boardAssemblyModel
+        )
+        const generatedBodyVisible =
+            PcbScene3dBoardMaterialPalette.isGeneratedBodyVisible({
+                hasBoardAssemblyModel
+            })
+        const materialOptions = {
+            roughness: 0.68,
+            metalness: 0.08,
+            visible: generatedBodyVisible
+        }
+        const edgeColor = Number(board.edgeColor)
+        const resolvedEdgeColor = Number.isInteger(edgeColor)
+            ? edgeColor
+            : 0xc9ca78
+        const surfaceColor = hasBoardAssemblyModel
+            ? resolvedEdgeColor
+            : PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
+                  hasBoardAssemblyModel
+              })
+
+        return new THREE.Mesh(geometry, [
+            new THREE.MeshStandardMaterial({
+                ...materialOptions,
+                color: surfaceColor,
+                side: THREE.FrontSide
+            }),
+            new THREE.MeshStandardMaterial({
+                ...materialOptions,
+                color: resolvedEdgeColor,
+                side: THREE.DoubleSide
+            }),
+            new THREE.MeshStandardMaterial({
+                color: 0xd9a61d,
+                roughness: 0.38,
+                metalness: 0.55,
+                visible: generatedBodyVisible,
+                side: THREE.DoubleSide
+            })
+        ])
+    }
+
+    /**
+     * Builds a line outline around the board edge.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ board?: any, detail?: any }} sceneDescription Scene metadata.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeDetailPoint Detail coordinate normalizer.
+     * @returns {any}
+     */
+    static buildBoardOutline(THREE, sceneDescription, normalizeDetailPoint) {
+        const shape = PcbScene3dBoardShapeFactory.buildShape(
+            THREE,
+            sceneDescription.board,
+            sceneDescription.detail,
+            normalizeDetailPoint
+        )
+        const points = shape.getPoints(120)
+        const positions = []
+        const topZ = sceneDescription.board.thicknessMil / 2 + 0.8
+
+        points.forEach((point) => {
+            positions.push(point.x, point.y, topZ)
+        })
+
+        const geometry = new THREE.BufferGeometry()
+        geometry.setAttribute(
+            'position',
+            new THREE.Float32BufferAttribute(positions, 3)
+        )
+
+        return new THREE.LineLoop(
+            geometry,
+            new THREE.LineBasicMaterial({ color: 0xc9ca78, transparent: true })
+        )
+    }
+}

package/src/PcbScene3dSelectionStyler.mjs

@@ -0,0 +1,252 @@
+/**
+ * Applies shared highlight state to all rendered roots for one selected
+ * component designator.
+ */
+export class PcbScene3dSelectionStyler {
+    /**
+     * Registers one rendered root object under a component designator.
+     * @param {Map<string, Set<any>>} selectionRoots
+     * @param {string} designator
+     * @param {any} rootObject
+     * @returns {void}
+     */
+    static registerSelectionRoot(selectionRoots, designator, rootObject) {
+        if (!(selectionRoots instanceof Map) || !rootObject) {
+            return
+        }
+
+        const normalizedDesignator = String(designator || '').trim()
+        if (!normalizedDesignator) {
+            return
+        }
+
+        if (!selectionRoots.has(normalizedDesignator)) {
+            selectionRoots.set(normalizedDesignator, new Set())
+        }
+
+        selectionRoots.get(normalizedDesignator)?.add(rootObject)
+    }
+
+    /**
+     * Applies the current highlighted designator, restoring the previous one.
+     * @param {Map<string, Set<any>>} selectionRoots
+     * @param {string} previousDesignator
+     * @param {string} nextDesignator
+     * @param {number} highlightColor
+     * @returns {void}
+     */
+    static applySelection(
+        selectionRoots,
+        previousDesignator,
+        nextDesignator,
+        highlightColor
+    ) {
+        PcbScene3dSelectionStyler.#setDesignatorHighlighted(
+            selectionRoots,
+            previousDesignator,
+            false,
+            highlightColor
+        )
+        PcbScene3dSelectionStyler.#setDesignatorHighlighted(
+            selectionRoots,
+            nextDesignator,
+            true,
+            highlightColor
+        )
+    }
+
+    /**
+     * Highlights or restores every root registered for one designator.
+     * @param {Map<string, Set<any>>} selectionRoots
+     * @param {string} designator
+     * @param {boolean} highlighted
+     * @param {number} highlightColor
+     * @returns {void}
+     */
+    static #setDesignatorHighlighted(
+        selectionRoots,
+        designator,
+        highlighted,
+        highlightColor
+    ) {
+        if (!(selectionRoots instanceof Map)) {
+            return
+        }
+
+        const normalizedDesignator = String(designator || '').trim()
+        if (!normalizedDesignator) {
+            return
+        }
+
+        const roots = selectionRoots.get(normalizedDesignator)
+        if (!roots) {
+            return
+        }
+
+        roots.forEach((rootObject) => {
+            PcbScene3dSelectionStyler.#visitMaterialNodes(
+                rootObject,
+                (material) =>
+                    PcbScene3dSelectionStyler.#setMaterialHighlighted(
+                        material,
+                        highlighted,
+                        highlightColor
+                    )
+            )
+        })
+    }
+
+    /**
+     * Visits every material-bearing node in one rendered object tree.
+     * @param {any} rootObject
+     * @param {(material: any) => void} visitor
+     * @returns {void}
+     */
+    static #visitMaterialNodes(rootObject, visitor) {
+        if (!rootObject) {
+            return
+        }
+
+        PcbScene3dSelectionStyler.#normalizeMaterials(
+            rootObject.material
+        ).forEach((material) => visitor(material))
+
+        const children = Array.isArray(rootObject.children)
+            ? rootObject.children
+            : []
+        children.forEach((child) =>
+            PcbScene3dSelectionStyler.#visitMaterialNodes(child, visitor)
+        )
+    }
+
+    /**
+     * Applies or restores one material's highlight state.
+     * @param {any} material
+     * @param {boolean} highlighted
+     * @param {number} highlightColor
+     * @returns {void}
+     */
+    static #setMaterialHighlighted(material, highlighted, highlightColor) {
+        if (!material) {
+            return
+        }
+
+        const baseState =
+            PcbScene3dSelectionStyler.#ensureMaterialBaseState(material)
+
+        if (PcbScene3dSelectionStyler.#canWriteColor(material.emissive)) {
+            if (PcbScene3dSelectionStyler.#canWriteColor(material.color)) {
+                PcbScene3dSelectionStyler.#writeColor(
+                    material.color,
+                    highlighted ? 0x000000 : baseState.colorHex
+                )
+            }
+            PcbScene3dSelectionStyler.#writeColor(
+                material.emissive,
+                highlighted ? highlightColor : baseState.emissiveHex
+            )
+            material.emissiveIntensity = highlighted
+                ? 1
+                : baseState.emissiveIntensity
+            material.needsUpdate = true
+            return
+        }
+
+        if (PcbScene3dSelectionStyler.#canWriteColor(material.color)) {
+            PcbScene3dSelectionStyler.#writeColor(
+                material.color,
+                highlighted ? highlightColor : baseState.colorHex
+            )
+            material.needsUpdate = true
+        }
+    }
+
+    /**
+     * Stores the original material state the first time a material is seen.
+     * @param {any} material
+     * @returns {{ colorHex: number | null, emissiveHex: number | null, emissiveIntensity: number }}
+     */
+    static #ensureMaterialBaseState(material) {
+        if (!material.userData) {
+            material.userData = {}
+        }
+
+        if (!material.userData.scene3dHighlightBase) {
+            material.userData.scene3dHighlightBase = {
+                colorHex: PcbScene3dSelectionStyler.#readColor(material.color),
+                emissiveHex: PcbScene3dSelectionStyler.#readColor(
+                    material.emissive
+                ),
+                emissiveIntensity: Number(material.emissiveIntensity || 0)
+            }
+        }
+
+        return material.userData.scene3dHighlightBase
+    }
+
+    /**
+     * Normalizes a Three material field into an array.
+     * @param {any} materials
+     * @returns {any[]}
+     */
+    static #normalizeMaterials(materials) {
+        if (Array.isArray(materials)) {
+            return materials.filter(Boolean)
+        }
+
+        return materials ? [materials] : []
+    }
+
+    /**
+     * Reads one color-like object into a hex value.
+     * @param {any} color
+     * @returns {number | null}
+     */
+    static #readColor(color) {
+        if (!color) {
+            return null
+        }
+
+        if (typeof color.getHex === 'function') {
+            return color.getHex()
+        }
+
+        if (Number.isFinite(Number(color.hex))) {
+            return Number(color.hex)
+        }
+
+        return null
+    }
+
+    /**
+     * Writes one hex value into a color-like object.
+     * @param {any} color
+     * @param {number | null} hex
+     * @returns {void}
+     */
+    static #writeColor(color, hex) {
+        if (!color || !Number.isFinite(Number(hex))) {
+            return
+        }
+
+        if (typeof color.setHex === 'function') {
+            color.setHex(Number(hex))
+            return
+        }
+
+        if ('hex' in color) {
+            color.hex = Number(hex)
+        }
+    }
+
+    /**
+     * Returns true when the color-like object supports hex writes.
+     * @param {any} color
+     * @returns {boolean}
+     */
+    static #canWriteColor(color) {
+        return Boolean(
+            color && (typeof color.setHex === 'function' || 'hex' in color)
+        )
+    }
+}

package/src/PcbScene3dShapePathFactory.mjs

@@ -0,0 +1,220 @@
+/**
+ * Builds Three shape paths from Altium shape-based region contours.
+ */
+export class PcbScene3dShapePathFactory {
+    static #ARC_SEGMENT_DEGREES = 12
+    static #GEOMETRY_EPSILON = 0.001
+
+    /**
+     * Normalizes authored contour points while preserving arc metadata.
+     * @param {{ x?: number, y?: number, isArc?: boolean, centerX?: number, centerY?: number, radius?: number, startAngle?: number, endAngle?: number }[]} points
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @param {boolean} mirrorY
+     * @returns {{ x: number, y: number, isArc?: boolean, centerX?: number, centerY?: number, radius?: number, startAngle?: number, endAngle?: number, arcYDirection?: number }[]}
+     */
+    static normalizeShapePoints(points, normalizeBoardPoint, mirrorY) {
+        return (Array.isArray(points) ? points : [])
+            .map((point) =>
+                PcbScene3dShapePathFactory.#normalizeShapePoint(
+                    point,
+                    normalizeBoardPoint,
+                    mirrorY
+                )
+            )
+            .filter(
+                (point) => Number.isFinite(point.x) && Number.isFinite(point.y)
+            )
+    }
+
+    /**
+     * Builds one filled shape from normalized contour points.
+     * @param {any} THREE
+     * @param {object[]} points
+     * @returns {any}
+     */
+    static buildShape(THREE, points) {
+        const shape = new THREE.Shape()
+        PcbScene3dShapePathFactory.#appendClosedContour(shape, points)
+        return shape
+    }
+
+    /**
+     * Builds one hole path from normalized contour points.
+     * @param {any} THREE
+     * @param {object[]} points
+     * @returns {any}
+     */
+    static buildPath(THREE, points) {
+        const path = new THREE.Path()
+        PcbScene3dShapePathFactory.#appendClosedContour(path, points)
+        return path
+    }
+
+    /**
+     * Normalizes one point and optional arc center.
+     * @param {object} point
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @param {boolean} mirrorY
+     * @returns {object}
+     */
+    static #normalizeShapePoint(point, normalizeBoardPoint, mirrorY) {
+        const normalized = PcbScene3dShapePathFactory.#normalizePoint(
+            normalizeBoardPoint,
+            Number(point?.x || 0),
+            Number(point?.y || 0),
+            mirrorY
+        )
+        const output = {
+            ...point,
+            x: normalized.x,
+            y: normalized.y
+        }
+
+        if (point?.isArc) {
+            const center = PcbScene3dShapePathFactory.#normalizePoint(
+                normalizeBoardPoint,
+                Number(point.centerX || 0),
+                Number(point.centerY || 0),
+                mirrorY
+            )
+            output.centerX = center.x
+            output.centerY = center.y
+            output.arcYDirection = mirrorY ? -1 : 1
+        }
+
+        return output
+    }
+
+    /**
+     * Appends one closed contour to a shape or path.
+     * @param {{ moveTo: Function, lineTo: Function, closePath: Function }} path
+     * @param {object[]} points
+     * @returns {void}
+     */
+    static #appendClosedContour(path, points) {
+        const vertices =
+            PcbScene3dShapePathFactory.#withoutClosingDuplicate(points)
+
+        if (!vertices.length) {
+            return
+        }
+
+        path.moveTo(vertices[0].x, vertices[0].y)
+        for (let index = 0; index < vertices.length - 1; index += 1) {
+            PcbScene3dShapePathFactory.#appendSegment(
+                path,
+                vertices[index],
+                vertices[index + 1]
+            )
+        }
+        if (vertices.at(-1)?.isArc) {
+            PcbScene3dShapePathFactory.#appendArcSegment(
+                path,
+                vertices.at(-1),
+                vertices[0]
+            )
+        }
+        path.closePath()
+    }
+
+    /**
+     * Trims a duplicated closing point emitted by shape-based region streams.
+     * @param {object[]} points
+     * @returns {object[]}
+     */
+    static #withoutClosingDuplicate(points) {
+        if (!Array.isArray(points) || points.length < 2) {
+            return Array.isArray(points) ? points : []
+        }
+
+        const first = points[0]
+        const last = points[points.length - 1]
+
+        return PcbScene3dShapePathFactory.#samePoint(first, last)
+            ? points.slice(0, -1)
+            : points
+    }
+
+    /**
+     * Appends one line or arc segment.
+     * @param {{ lineTo: Function }} path
+     * @param {object} current
+     * @param {object} next
+     * @returns {void}
+     */
+    static #appendSegment(path, current, next) {
+        if (current?.isArc && Number(current.radius) > 0) {
+            PcbScene3dShapePathFactory.#appendArcSegment(path, current, next)
+            return
+        }
+
+        path.lineTo(next.x, next.y)
+    }
+
+    /**
+     * Appends a sampled circular arc matching Altium shape-region metadata.
+     * @param {{ lineTo: Function }} path
+     * @param {object} current
+     * @param {object} next
+     * @returns {void}
+     */
+    static #appendArcSegment(path, current, next) {
+        const startAngle = Number(current.startAngle || 0)
+        const deltaAngle = Number(current.endAngle || 0) - startAngle
+
+        if (!Number.isFinite(deltaAngle) || Math.abs(deltaAngle) < 0.001) {
+            path.lineTo(next.x, next.y)
+            return
+        }
+
+        const segments = Math.max(
+            4,
+            Math.ceil(
+                Math.abs(deltaAngle) /
+                    PcbScene3dShapePathFactory.#ARC_SEGMENT_DEGREES
+            )
+        )
+
+        for (let index = 1; index <= segments; index += 1) {
+            const angle =
+                ((startAngle + (deltaAngle * index) / segments) * Math.PI) / 180
+            path.lineTo(
+                Number(current.centerX) +
+                    Number(current.radius) * Math.cos(angle),
+                Number(current.centerY) +
+                    Number(current.arcYDirection || 1) *
+                        Number(current.radius) *
+                        Math.sin(angle)
+            )
+        }
+    }
+
+    /**
+     * Returns true when two points share the same coordinate.
+     * @param {{ x?: number, y?: number }} first
+     * @param {{ x?: number, y?: number }} second
+     * @returns {boolean}
+     */
+    static #samePoint(first, second) {
+        return (
+            Math.abs(Number(first?.x) - Number(second?.x)) <=
+                PcbScene3dShapePathFactory.#GEOMETRY_EPSILON &&
+            Math.abs(Number(first?.y) - Number(second?.y)) <=
+                PcbScene3dShapePathFactory.#GEOMETRY_EPSILON
+        )
+    }
+
+    /**
+     * Normalizes one board point and optionally mirrors underside primitives.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @param {number} x
+     * @param {number} y
+     * @param {boolean} mirrorY
+     * @returns {{ x: number, y: number }}
+     */
+    static #normalizePoint(normalizeBoardPoint, x, y, mirrorY) {
+        const point = normalizeBoardPoint(x, y)
+
+        return { x: point.x, y: mirrorY ? -point.y : point.y }
+    }
+}

package/src/PcbScene3dShellRenderer.mjs

@@ -0,0 +1,131 @@
+import { PcbScene3dText } from './PcbScene3dText.mjs'
+
+/**
+ * Renders the interactive 3D scene shell.
+ */
+export class PcbScene3dShellRenderer {
+    /**
+     * Renders the interactive 3D scene shell.
+     * @param {{ pcb?: { boardOutline: { widthMil: number, heightMil: number }, components: { designator: string }[] }, bom: { quantity: number }[] }} documentModel
+     * @param {((key: string) => string) | null} [translate] Translation lookup.
+     * @returns {string}
+     */
+    static render(documentModel, translate = null) {
+        const t = PcbScene3dText.createTranslator(translate)
+        const pcb = documentModel?.pcb
+        if (!pcb) {
+            return (
+                '<section class="viewer-empty">' +
+                PcbScene3dShellRenderer.#escapeHtml(t('scene3d.noPcb')) +
+                '</section>'
+            )
+        }
+
+        const widthMil = Math.round(pcb.boardOutline.widthMil || 0)
+        const heightMil = Math.round(pcb.boardOutline.heightMil || 0)
+        const componentCount = pcb.components.length
+        const bomRows = documentModel?.bom?.length || 0
+
+        return (
+            '<section class="scene-3d"><header class="svg-panel__header"><h3>' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.title')) +
+            '</h3><p>' +
+            widthMil +
+            ' x ' +
+            heightMil +
+            ' ' +
+            PcbScene3dShellRenderer.#escapeHtml(
+                t('scene3d.boardEnvelopeSuffix')
+            ) +
+            '</p></header>' +
+            '<div class="scene-3d__toolbar" aria-label="' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.toolbarAria')) +
+            '">' +
+            '<button class="scene-3d__preset" type="button" data-scene-3d-preset="top">' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.top')) +
+            '</button>' +
+            '<button class="scene-3d__preset" type="button" data-scene-3d-preset="bottom">' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.bottom')) +
+            '</button>' +
+            '<button class="scene-3d__preset" type="button" data-scene-3d-preset="isometric">' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.isometric')) +
+            '</button>' +
+            '<button class="scene-3d__preset scene-3d__action" type="button" data-scene-3d-export="models-zip">' +
+            PcbScene3dShellRenderer.#escapeHtml(
+                t('scene3d.downloadModelsZip')
+            ) +
+            '</button>' +
+            '</div>' +
+            '<div class="scene-3d__stage">' +
+            '<div class="scene-3d__viewport" aria-label="' +
+            PcbScene3dShellRenderer.#escapeHtml(
+                t('scene3d.interactiveViewAria')
+            ) +
+            '">' +
+            '<div class="scene-3d__canvas-mount" data-scene-3d-viewport></div>' +
+            '<div class="scene-3d__loading" data-scene-3d-loading aria-live="polite">' +
+            '<div class="scene-3d__loading-content"><div class="viewer-loading__pulse"></div><p>' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.loading')) +
+            '</p></div></div>' +
+            '</div>' +
+            '<aside class="scene-3d__controls" aria-label="' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.controlsAria')) +
+            '">' +
+            '<label class="scene-3d__toggle"><input type="checkbox" checked data-scene-3d-toggle="external-models" />' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.externalModels')) +
+            '</label>' +
+            '<label class="scene-3d__toggle"><input type="checkbox" data-scene-3d-toggle="fallback-bodies" />' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.fallbackBodies')) +
+            '</label>' +
+            '<label class="scene-3d__toggle"><input type="checkbox" checked data-scene-3d-toggle="copper" />' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.copperDetail')) +
+            '</label>' +
+            '<section class="scene-3d__selection" aria-live="polite"><h4 class="scene-3d__selection-title">' +
+            PcbScene3dShellRenderer.#escapeHtml(
+                t('scene3d.componentInspector')
+            ) +
+            '</h4><p class="scene-3d__selection-empty">' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.inspectPrompt')) +
+            '</p></section>' +
+            '</aside>' +
+            '</div>' +
+            '<div class="scene-3d__diagnostics" aria-live="polite">' +
+            PcbScene3dShellRenderer.#escapeHtml(
+                t('scene3d.companionModelsHint')
+            ) +
+            '</div>' +
+            '<dl class="scene-3d__stats"><div><dt>' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.footprint')) +
+            '</dt><dd>' +
+            widthMil +
+            ' x ' +
+            heightMil +
+            ' mil</dd></div><div><dt>' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.placements')) +
+            '</dt><dd>' +
+            componentCount +
+            ' ' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.componentsSuffix')) +
+            '</dd></div><div><dt>' +
+            PcbScene3dShellRenderer.#escapeHtml(t('scene3d.bomGroups')) +
+            '</dt><dd>' +
+            bomRows +
+            '</dd></div></dl></section>'
+        )
+    }
+
+    /**
+     * Escapes markup text.
+     * @param {string} value Raw text.
+     * @returns {string}
+     */
+    static #escapeHtml(value) {
+        return String(value)
+            .replaceAll('&', '&amp;')
+            .replaceAll('<', '&lt;')
+            .replaceAll('>', '&gt;')
+            .replaceAll('"', '&quot;')
+    }
+}
+
+export { PcbScene3dShellRenderer as Scene3dRenderer }