pcb-scene3d-viewer 1.1.19 → 1.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.1.19",
+    "version": "1.1.21",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -51,9 +51,10 @@
         "check:format": "prettier --check ."
     },
     "dependencies": {
+        "@sunbox/occt-import-js": "^0.0.25",
         "circuitjson-toolkit": "^1.0.1",
+        "earcut": "^3.0.2",
         "fflate": "^0.8.2",
-        "@sunbox/occt-import-js": "^0.0.25",
         "three": "^0.183.2"
     },
     "devDependencies": {

package/src/PcbAssemblyBoardSubstrateBuilder.mjs

@@ -0,0 +1,467 @@
+import earcut from 'earcut'
+import { PcbAssemblyMeshUtils } from './PcbAssemblyMeshUtils.mjs'
+
+const MAX_HOLE_POINTS = 48
+const MIN_HOLE_POINTS = 8
+const GEOMETRY_EPSILON = 0.001
+
+/**
+ * Builds PCB substrate meshes, including through-board drill cutouts.
+ */
+export class PcbAssemblyBoardSubstrateBuilder {
+    /**
+     * Builds a board prism from an outer outline and available drill holes.
+     * @param {string} name Mesh name.
+     * @param {number[][]} outlinePoints Board outline points in mils.
+     * @param {object} sceneDescription Prepared scene description.
+     * @param {number} thickness Board thickness in mils.
+     * @param {number[]} color Board RGB color.
+     * @returns {object | null}
+     */
+    static build(name, outlinePoints, sceneDescription, thickness, color) {
+        const outer = PcbAssemblyMeshUtils.cleanLoop(outlinePoints)
+        if (outer.length < 3) {
+            return null
+        }
+
+        const holes = PcbAssemblyBoardSubstrateBuilder.#boardHoleLoops(
+            sceneDescription,
+            outer
+        )
+        if (!holes.length) {
+            return PcbAssemblyMeshUtils.prism(name, outer, 0, thickness, color)
+        }
+
+        return PcbAssemblyBoardSubstrateBuilder.#prismWithHoles(
+            name,
+            outer,
+            holes,
+            thickness,
+            color
+        )
+    }
+
+    /**
+     * Builds an extruded board polygon with inner drill walls.
+     * @param {string} name Mesh name.
+     * @param {number[][]} outer Outer board loop.
+     * @param {number[][][]} holes Inner hole loops.
+     * @param {number} thickness Board thickness in mils.
+     * @param {number[]} color Board RGB color.
+     * @returns {object | null}
+     */
+    static #prismWithHoles(name, outer, holes, thickness, color) {
+        const loops = [outer, ...holes]
+        const holeIndexes = []
+        const points = []
+        const flat = []
+
+        for (const loop of loops) {
+            if (points.length) {
+                holeIndexes.push(points.length)
+            }
+            for (const point of loop) {
+                points.push(point)
+                flat.push(point[0], point[1])
+            }
+        }
+
+        const triangles = earcut(flat, holeIndexes, 2)
+        if (!triangles.length) {
+            return PcbAssemblyMeshUtils.prism(name, outer, 0, thickness, color)
+        }
+
+        const halfThickness = Math.max(Number(thickness || 0), 0.001) / 2
+        const bottomZ = -halfThickness
+        const topZ = halfThickness
+        const topOffset = points.length
+        const vertices = [
+            ...points.map((point) => [point[0], point[1], bottomZ]),
+            ...points.map((point) => [point[0], point[1], topZ])
+        ]
+        const faces = []
+
+        for (let index = 0; index + 2 < triangles.length; index += 3) {
+            const a = triangles[index]
+            const b = triangles[index + 1]
+            const c = triangles[index + 2]
+            faces.push([c, b, a])
+            faces.push([a + topOffset, b + topOffset, c + topOffset])
+        }
+
+        let loopStart = 0
+        PcbAssemblyBoardSubstrateBuilder.#appendLoopWalls(
+            faces,
+            loopStart,
+            outer.length,
+            topOffset,
+            false
+        )
+        loopStart += outer.length
+        for (const hole of holes) {
+            PcbAssemblyBoardSubstrateBuilder.#appendLoopWalls(
+                faces,
+                loopStart,
+                hole.length,
+                topOffset,
+                true
+            )
+            loopStart += hole.length
+        }
+
+        return {
+            name,
+            vertices,
+            faces,
+            ...(Array.isArray(color) ? { color } : {})
+        }
+    }
+
+    /**
+     * Appends side-wall faces for one polygon loop.
+     * @param {number[][]} faces Mutable face list.
+     * @param {number} start Loop start index.
+     * @param {number} length Loop length.
+     * @param {number} topOffset Top vertex offset.
+     * @param {boolean} reverse Whether to reverse wall orientation.
+     * @returns {void}
+     */
+    static #appendLoopWalls(faces, start, length, topOffset, reverse) {
+        for (let index = 0; index < length; index += 1) {
+            const current = start + index
+            const next = start + ((index + 1) % length)
+            faces.push(
+                reverse
+                    ? [next, current, current + topOffset, next + topOffset]
+                    : [current, next, next + topOffset, current + topOffset]
+            )
+        }
+    }
+
+    /**
+     * Resolves all usable board hole loops.
+     * @param {object} sceneDescription Prepared scene description.
+     * @param {number[][]} outer Board outline loop.
+     * @returns {number[][][]}
+     */
+    static #boardHoleLoops(sceneDescription, outer) {
+        const contourLoops =
+            PcbAssemblyBoardSubstrateBuilder.#drillCutoutLoops(sceneDescription)
+        const rawLoops = contourLoops.length
+            ? contourLoops
+            : PcbAssemblyBoardSubstrateBuilder.#primitiveHoleLoops(
+                  sceneDescription
+              )
+        const seen = new Set()
+        const holes = []
+
+        for (const loop of rawLoops) {
+            const normalized =
+                PcbAssemblyBoardSubstrateBuilder.#normalizeHoleLoop(loop)
+            if (
+                normalized.length < 3 ||
+                Math.abs(
+                    PcbAssemblyBoardSubstrateBuilder.#signedArea(normalized)
+                ) <= GEOMETRY_EPSILON
+            ) {
+                continue
+            }
+
+            const center =
+                PcbAssemblyBoardSubstrateBuilder.#centroid(normalized)
+            if (
+                !PcbAssemblyBoardSubstrateBuilder.#pointInPolygon(center, outer)
+            ) {
+                continue
+            }
+
+            const signature =
+                PcbAssemblyBoardSubstrateBuilder.#holeSignature(normalized)
+            if (seen.has(signature)) {
+                continue
+            }
+            seen.add(signature)
+            holes.push(normalized)
+        }
+
+        return holes
+    }
+
+    /**
+     * Reads existing drill cutout contours from scene silkscreen details.
+     * @param {object} sceneDescription Prepared scene description.
+     * @returns {Array<Array<object | number[]>>}
+     */
+    static #drillCutoutLoops(sceneDescription) {
+        const silkscreen = sceneDescription?.detail?.silkscreen || {}
+        return ['top', 'bottom'].flatMap((side) =>
+            Array.isArray(silkscreen?.[side]?.drillCutouts)
+                ? silkscreen[side].drillCutouts
+                : []
+        )
+    }
+
+    /**
+     * Builds fallback hole contours from pads and vias.
+     * @param {object} sceneDescription Prepared scene description.
+     * @returns {number[][][]}
+     */
+    static #primitiveHoleLoops(sceneDescription) {
+        const detail = sceneDescription?.detail || {}
+        return [
+            ...PcbAssemblyBoardSubstrateBuilder.#array(detail.pads).map((pad) =>
+                PcbAssemblyBoardSubstrateBuilder.#padHoleLoop(pad)
+            ),
+            ...PcbAssemblyBoardSubstrateBuilder.#array(detail.vias).map((via) =>
+                PcbAssemblyBoardSubstrateBuilder.#viaHoleLoop(via)
+            )
+        ].filter(Boolean)
+    }
+
+    /**
+     * Builds a fallback pad drill loop.
+     * @param {object} pad Pad primitive.
+     * @returns {number[][] | null}
+     */
+    static #padHoleLoop(pad) {
+        const diameter = PcbAssemblyBoardSubstrateBuilder.#firstPositive([
+            pad?.holeDiameter,
+            pad?.drillDiameter,
+            pad?.holeSize,
+            pad?.drill,
+            pad?.holeGeometry?.diameter,
+            pad?.holeGeometry?.width
+        ])
+        if (!diameter) {
+            return null
+        }
+
+        const x = Number(pad?.x)
+        const y = Number(pad?.y)
+        if (!Number.isFinite(x) || !Number.isFinite(y)) {
+            return null
+        }
+
+        const slotLength = PcbAssemblyBoardSubstrateBuilder.#firstPositive([
+            pad?.holeSlotLength,
+            pad?.slotLength,
+            pad?.holeGeometry?.slotLength,
+            pad?.holeGeometry?.length
+        ])
+        if (slotLength > diameter) {
+            return PcbAssemblyBoardSubstrateBuilder.#rotatedPoints(
+                PcbAssemblyMeshUtils.capsulePoints(
+                    x - (slotLength - diameter) / 2,
+                    y,
+                    x + (slotLength - diameter) / 2,
+                    y,
+                    diameter / 2
+                ),
+                x,
+                y,
+                Number(pad?.holeRotation ?? pad?.rotation ?? 0)
+            )
+        }
+
+        return PcbAssemblyMeshUtils.circlePoints(x, y, diameter / 2, 24)
+    }
+
+    /**
+     * Builds a fallback via drill loop.
+     * @param {object} via Via primitive.
+     * @returns {number[][] | null}
+     */
+    static #viaHoleLoop(via) {
+        const diameter = PcbAssemblyBoardSubstrateBuilder.#firstPositive([
+            via?.holeDiameter,
+            via?.drillDiameter,
+            via?.holeSize,
+            via?.drill
+        ])
+        const x = Number(via?.x)
+        const y = Number(via?.y)
+
+        return diameter && Number.isFinite(x) && Number.isFinite(y)
+            ? PcbAssemblyMeshUtils.circlePoints(x, y, diameter / 2, 24)
+            : null
+    }
+
+    /**
+     * Normalizes one candidate hole contour.
+     * @param {Array<object | number[]>} loop Candidate loop.
+     * @returns {number[][]}
+     */
+    static #normalizeHoleLoop(loop) {
+        const points = PcbAssemblyMeshUtils.cleanLoop(
+            PcbAssemblyBoardSubstrateBuilder.#array(loop).map((point) => [
+                Number(point?.x ?? point?.[0]),
+                Number(point?.y ?? point?.[1])
+            ])
+        )
+
+        return PcbAssemblyBoardSubstrateBuilder.#simplifyLoop(points)
+    }
+
+    /**
+     * Reduces very dense circular cutouts to export-friendly loops.
+     * @param {number[][]} loop Source loop.
+     * @returns {number[][]}
+     */
+    static #simplifyLoop(loop) {
+        if (loop.length <= MAX_HOLE_POINTS) {
+            return loop
+        }
+
+        const target = Math.max(MAX_HOLE_POINTS, MIN_HOLE_POINTS)
+        const step = loop.length / target
+        return PcbAssemblyMeshUtils.cleanLoop(
+            Array.from({ length: target }, (_entry, index) => {
+                return loop[Math.floor(index * step)]
+            })
+        )
+    }
+
+    /**
+     * Rotates points around a center.
+     * @param {number[][]} points Source points.
+     * @param {number} centerX Center X.
+     * @param {number} centerY Center Y.
+     * @param {number} rotationDeg Rotation in degrees.
+     * @returns {number[][]}
+     */
+    static #rotatedPoints(points, centerX, centerY, rotationDeg) {
+        if (Math.abs(Number(rotationDeg || 0)) < GEOMETRY_EPSILON) {
+            return points
+        }
+
+        const angle = (Number(rotationDeg || 0) * Math.PI) / 180
+        const cos = Math.cos(angle)
+        const sin = Math.sin(angle)
+        return points.map((point) => {
+            const dx = point[0] - centerX
+            const dy = point[1] - centerY
+            return [
+                centerX + dx * cos - dy * sin,
+                centerY + dx * sin + dy * cos
+            ]
+        })
+    }
+
+    /**
+     * Builds a stable duplicate key for one hole loop.
+     * @param {number[][]} loop Hole loop.
+     * @returns {string}
+     */
+    static #holeSignature(loop) {
+        const bounds = PcbAssemblyBoardSubstrateBuilder.#bounds(loop)
+        return [bounds.minX, bounds.minY, bounds.maxX, bounds.maxY]
+            .map((value) => String(Math.round(value * 10) / 10))
+            .join(':')
+    }
+
+    /**
+     * Computes point bounds.
+     * @param {number[][]} points Points.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number }}
+     */
+    static #bounds(points) {
+        return points.reduce(
+            (bounds, point) => ({
+                minX: Math.min(bounds.minX, point[0]),
+                minY: Math.min(bounds.minY, point[1]),
+                maxX: Math.max(bounds.maxX, point[0]),
+                maxY: Math.max(bounds.maxY, point[1])
+            }),
+            {
+                minX: Infinity,
+                minY: Infinity,
+                maxX: -Infinity,
+                maxY: -Infinity
+            }
+        )
+    }
+
+    /**
+     * Computes a polygon centroid approximation.
+     * @param {number[][]} points Polygon points.
+     * @returns {number[]}
+     */
+    static #centroid(points) {
+        return [
+            points.reduce((sum, point) => sum + point[0], 0) / points.length,
+            points.reduce((sum, point) => sum + point[1], 0) / points.length
+        ]
+    }
+
+    /**
+     * Computes signed polygon area.
+     * @param {number[][]} points Polygon points.
+     * @returns {number}
+     */
+    static #signedArea(points) {
+        let area = 0
+        for (let index = 0; index < points.length; index += 1) {
+            const current = points[index]
+            const next = points[(index + 1) % points.length]
+            area += current[0] * next[1] - next[0] * current[1]
+        }
+        return area / 2
+    }
+
+    /**
+     * Tests whether a point lies inside a polygon.
+     * @param {number[]} point Candidate point.
+     * @param {number[][]} polygon Polygon points.
+     * @returns {boolean}
+     */
+    static #pointInPolygon(point, polygon) {
+        let inside = false
+
+        for (
+            let index = 0, previous = polygon.length - 1;
+            index < polygon.length;
+            previous = index, index += 1
+        ) {
+            const currentPoint = polygon[index]
+            const previousPoint = polygon[previous]
+            const crosses =
+                currentPoint[1] > point[1] !== previousPoint[1] > point[1]
+            const xAtY =
+                ((previousPoint[0] - currentPoint[0]) *
+                    (point[1] - currentPoint[1])) /
+                    (previousPoint[1] - currentPoint[1]) +
+                currentPoint[0]
+
+            if (crosses && point[0] < xAtY) {
+                inside = !inside
+            }
+        }
+
+        return inside
+    }
+
+    /**
+     * Returns the first positive finite number.
+     * @param {unknown[]} values Candidate values.
+     * @returns {number}
+     */
+    static #firstPositive(values) {
+        for (const value of values) {
+            const number = Number(value)
+            if (Number.isFinite(number) && number > 0) {
+                return number
+            }
+        }
+
+        return 0
+    }
+
+    /**
+     * Normalizes a value to an array.
+     * @param {unknown} value Candidate value.
+     * @returns {any[]}
+     */
+    static #array(value) {
+        return Array.isArray(value) ? value : []
+    }
+}

package/src/PcbAssemblyExportCoordinateFrame.mjs

@@ -0,0 +1,19 @@
+const MIL_TO_MM = 0.0254
+
+/**
+ * Maps internal PCB Z-up mesh coordinates into the exported viewer frame.
+ */
+export class PcbAssemblyExportCoordinateFrame {
+    /**
+     * Converts one internal vertex from mils into exported millimetres.
+     * @param {number[]} vertex Internal mesh vertex in mils.
+     * @returns {number[]}
+     */
+    static vertexMilToMm(vertex) {
+        const x = Number(vertex?.[0] || 0)
+        const y = Number(vertex?.[1] || 0)
+        const z = Number(vertex?.[2] || 0)
+
+        return [x * MIL_TO_MM, z * MIL_TO_MM, -y * MIL_TO_MM]
+    }
+}

package/src/PcbAssemblyGeometryBuildProgress.mjs

@@ -0,0 +1,201 @@
+/**
+ * Tracks measured progress while PCB assembly meshes are built.
+ */
+export class PcbAssemblyGeometryBuildProgress {
+    /** @type {((progress: { value: number, message: string }) => void) | null} */
+    #onProgress
+
+    /** @type {number} */
+    #totalUnits
+
+    /** @type {number} */
+    #completedUnits
+
+    /** @type {number} */
+    #lastValue
+
+    /** @type {number} */
+    #startValue
+
+    /** @type {number} */
+    #endValue
+
+    /**
+     * @param {{ totalUnits?: number, onProgress?: (progress: { value: number, message: string }) => void, startValue?: number, endValue?: number }} options Progress options.
+     */
+    constructor(options = {}) {
+        this.#onProgress =
+            typeof options.onProgress === 'function' ? options.onProgress : null
+        this.#totalUnits = Math.max(Number(options.totalUnits || 1), 1)
+        this.#completedUnits = 0
+        this.#lastValue = -1
+        this.#startValue = PcbAssemblyGeometryBuildProgress.#clampPercent(
+            options.startValue ?? 10
+        )
+        this.#endValue = Math.max(
+            this.#startValue,
+            PcbAssemblyGeometryBuildProgress.#clampPercent(
+                options.endValue ?? 75
+            )
+        )
+    }
+
+    /**
+     * Creates a progress tracker sized to the prepared scene detail.
+     * @param {{ detail?: object, externalPlacements?: object[] }} sceneDescription Prepared scene description.
+     * @param {((progress: { value: number, message: string }) => void) | undefined} onProgress Progress callback.
+     * @param {{ startValue?: number, endValue?: number }} [options] Progress range options.
+     * @returns {PcbAssemblyGeometryBuildProgress}
+     */
+    static create(sceneDescription, onProgress, options = {}) {
+        return new PcbAssemblyGeometryBuildProgress({
+            onProgress,
+            startValue: options.startValue,
+            endValue: options.endValue,
+            totalUnits:
+                1 +
+                PcbAssemblyGeometryBuildProgress.#countCopperUnits(
+                    sceneDescription?.detail || {}
+                ) +
+                PcbAssemblyGeometryBuildProgress.#countSilkscreenUnits(
+                    sceneDescription?.detail?.silkscreen || {}
+                ) +
+                PcbAssemblyGeometryBuildProgress.#countComponentUnits(
+                    sceneDescription
+                )
+        })
+    }
+
+    /**
+     * Advances progress by measured build units.
+     * @param {number} units Completed units.
+     * @param {string} message Progress message.
+     * @returns {Promise<void>}
+     */
+    async advance(units, message) {
+        this.#completedUnits += Math.max(Number(units || 0), 0)
+        await this.#emit(
+            Math.min(
+                this.#scaledValue(this.#completedUnits / this.#totalUnits),
+                this.#endValue - 1
+            ),
+            message
+        )
+    }
+
+    /**
+     * Marks geometry building complete.
+     * @param {string} message Completion message.
+     * @returns {Promise<void>}
+     */
+    async finish(message) {
+        this.#completedUnits = this.#totalUnits
+        await this.#emit(this.#endValue, message)
+    }
+
+    /**
+     * Emits progress when the visible integer value changes.
+     * @param {number} value Progress value.
+     * @param {string} message Progress message.
+     * @returns {Promise<void>}
+     */
+    async #emit(value, message) {
+        if (!this.#onProgress || value === this.#lastValue) {
+            return
+        }
+
+        this.#lastValue = value
+        this.#onProgress({
+            value,
+            message
+        })
+        await PcbAssemblyGeometryBuildProgress.#yieldToBrowser()
+    }
+
+    /**
+     * Maps a unit completion ratio into the configured progress range.
+     * @param {number} ratio Completion ratio.
+     * @returns {number}
+     */
+    #scaledValue(ratio) {
+        const clampedRatio = Math.max(Math.min(Number(ratio || 0), 1), 0)
+        return Math.round(
+            this.#startValue +
+                clampedRatio * (this.#endValue - this.#startValue)
+        )
+    }
+
+    /**
+     * Counts measured copper work units.
+     * @param {object} detail Scene detail.
+     * @returns {number}
+     */
+    static #countCopperUnits(detail) {
+        return (
+            PcbAssemblyGeometryBuildProgress.#array(detail.tracks).length +
+            PcbAssemblyGeometryBuildProgress.#array(detail.arcs).length +
+            PcbAssemblyGeometryBuildProgress.#array(detail.fills).length +
+            PcbAssemblyGeometryBuildProgress.#array(detail.polygons).length +
+            PcbAssemblyGeometryBuildProgress.#array(detail.pads).length * 2 +
+            PcbAssemblyGeometryBuildProgress.#array(detail.vias).length +
+            PcbAssemblyGeometryBuildProgress.#array(detail.copperTexts).length
+        )
+    }
+
+    /**
+     * Counts measured silkscreen work units.
+     * @param {object} silkscreen Scene silkscreen detail.
+     * @returns {number}
+     */
+    static #countSilkscreenUnits(silkscreen) {
+        return ['top', 'bottom'].reduce((total, side) => {
+            const detail = silkscreen?.[side] || {}
+            return (
+                total +
+                PcbAssemblyGeometryBuildProgress.#array(detail.tracks).length +
+                PcbAssemblyGeometryBuildProgress.#array(detail.arcs).length +
+                PcbAssemblyGeometryBuildProgress.#array(detail.fills).length +
+                PcbAssemblyGeometryBuildProgress.#array(detail.texts).length
+            )
+        }, 0)
+    }
+
+    /**
+     * Counts component model loading work units.
+     * @param {{ externalPlacements?: object[] }} sceneDescription Prepared scene description.
+     * @returns {number}
+     */
+    static #countComponentUnits(sceneDescription) {
+        return PcbAssemblyGeometryBuildProgress.#array(
+            sceneDescription?.externalPlacements
+        ).filter((placement) => placement?.externalModel).length
+    }
+
+    /**
+     * Normalizes a value to an array.
+     * @param {unknown} value Candidate value.
+     * @returns {any[]}
+     */
+    static #array(value) {
+        return Array.isArray(value) ? value : []
+    }
+
+    /**
+     * Clamps a progress percentage.
+     * @param {number} value Candidate percentage.
+     * @returns {number}
+     */
+    static #clampPercent(value) {
+        return Math.max(Math.min(Number(value || 0), 100), 0)
+    }
+
+    /**
+     * Yields control so browsers can paint the progress dialog.
+     * @returns {Promise<void>}
+     */
+    static #yieldToBrowser() {
+        return new Promise((resolve) => {
+            globalThis.setTimeout?.(resolve, 0) || resolve()
+        })
+    }
+}