pcb-scene3d-viewer 1.1.47 → 1.1.49

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.1.47",
+    "version": "1.1.49",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -55,6 +55,7 @@
         "circuitjson-toolkit": "^1.0.10",
         "earcut": "^3.0.2",
         "fflate": "^0.8.2",
+        "polygon-clipping": "^0.15.7",
         "three": "^0.183.2"
     },
     "devDependencies": {

package/src/PcbScene3dBoardAssemblyPresentation.mjs

@@ -19,9 +19,10 @@ export class PcbScene3dBoardAssemblyPresentation {
      * PCB-derived substrate, copper, and silkscreen remain the visual source.
      * @param {any} modelGroup Loaded board assembly group.
      * @param {{ widthMil?: number, heightMil?: number, thicknessMil?: number } | null | undefined} board Board dimensions.
+     * @param {{ sourceFormat?: string }} [options] Presentation options.
      * @returns {void}
      */
-    static apply(modelGroup, board) {
+    static apply(modelGroup, board, options = {}) {
         const meshRecords =
             PcbScene3dBoardAssemblyPresentation.#collectMeshRecords(modelGroup)
         const boardBounds =
@@ -30,7 +31,10 @@ export class PcbScene3dBoardAssemblyPresentation {
                 board
             )
         const surfaceColor =
-            PcbScene3dBoardAssemblyPresentation.#resolveSurfaceColor(board)
+            PcbScene3dBoardAssemblyPresentation.#resolveSurfaceColor(
+                board,
+                options
+            )
         const edgeColor =
             PcbScene3dBoardAssemblyPresentation.#resolveEdgeColor(board)
         const importedSurfaceColor =
@@ -412,11 +416,13 @@ export class PcbScene3dBoardAssemblyPresentation {
     /**
      * Resolves the app-level substrate color for board assembly meshes.
      * @param {{ surfaceColor?: number } | null | undefined} board Board dimensions.
+     * @param {{ sourceFormat?: string }} options Presentation options.
      * @returns {number}
      */
-    static #resolveSurfaceColor(board) {
+    static #resolveSurfaceColor(board, options) {
         return PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
-            hasBoardAssemblyModel: true
+            hasBoardAssemblyModel: true,
+            sourceFormat: options?.sourceFormat
         })
     }
 

package/src/PcbScene3dBoardCutoutPathFactory.mjs

@@ -0,0 +1,83 @@
+/**
+ * Builds normalized Three.js paths for explicit board cutouts.
+ */
+export class PcbScene3dBoardCutoutPathFactory {
+    /**
+     * Resolves explicit board cutout paths.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ cutouts?: any[] }} board Board metadata.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @returns {{ path: any, points: { x: number, y: number }[] }[]}
+     */
+    static resolve(THREE, board, normalizeBoardPoint) {
+        return (Array.isArray(board?.cutouts) ? board.cutouts : [])
+            .map((cutout) =>
+                PcbScene3dBoardCutoutPathFactory.#buildPath(
+                    THREE,
+                    cutout,
+                    normalizeBoardPoint
+                )
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Builds one explicit board cutout path.
+     * @param {any} THREE Three.js namespace.
+     * @param {any} cutout Source cutout.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @returns {{ path: any, points: { x: number, y: number }[] } | null}
+     */
+    static #buildPath(THREE, cutout, normalizeBoardPoint) {
+        const points = PcbScene3dBoardCutoutPathFactory.#sourcePoints(cutout)
+            .map((point) =>
+                PcbScene3dBoardCutoutPathFactory.#normalizePoint(
+                    point,
+                    normalizeBoardPoint
+                )
+            )
+            .filter(Boolean)
+
+        if (points.length < 3) {
+            return null
+        }
+
+        const path = new THREE.Path()
+        path.moveTo(points[0].x, points[0].y)
+        for (let index = 1; index < points.length; index += 1) {
+            path.lineTo(points[index].x, points[index].y)
+        }
+        path.closePath()
+
+        return { path, points }
+    }
+
+    /**
+     * Resolves one cutout's point list.
+     * @param {any} cutout Source cutout.
+     * @returns {any[]}
+     */
+    static #sourcePoints(cutout) {
+        if (Array.isArray(cutout?.points)) {
+            return cutout.points
+        }
+
+        if (Array.isArray(cutout?.vertices)) {
+            return cutout.vertices
+        }
+
+        return Array.isArray(cutout) ? cutout : []
+    }
+
+    /**
+     * Normalizes one source point into local board shape coordinates.
+     * @param {any} point Source point.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @returns {{ x: number, y: number } | null}
+     */
+    static #normalizePoint(point, normalizeBoardPoint) {
+        const x = Number(point?.x ?? point?.[0])
+        const y = Number(point?.y ?? point?.[1])
+        return Number.isFinite(x + y) ? normalizeBoardPoint(x, y) : null
+    }
+}

package/src/PcbScene3dBoardMaterialPalette.mjs

@@ -7,11 +7,16 @@ export class PcbScene3dBoardMaterialPalette {
     /**
      * Resolves the solder-mask face color for the generated board shell.
      * @param {{ surfaceColor?: number } | undefined} board Board metadata.
-     * @param {{ hasBoardAssemblyModel?: boolean }} [options] Scene options.
+     * @param {{ hasBoardAssemblyModel?: boolean, sourceFormat?: string }} [options] Scene options.
      * @returns {number}
      */
     static resolveSurfaceColor(board, options = {}) {
-        if (options.hasBoardAssemblyModel) {
+        if (
+            options.hasBoardAssemblyModel &&
+            !PcbScene3dBoardMaterialPalette.#shouldPreserveAuthoredSurfaceColor(
+                options
+            )
+        ) {
             return PcbScene3dBoardMaterialPalette.#DEFAULT_SURFACE_COLOR
         }
 
@@ -20,6 +25,16 @@ export class PcbScene3dBoardMaterialPalette {
             : PcbScene3dBoardMaterialPalette.#DEFAULT_SURFACE_COLOR
     }
 
+    /**
+     * Returns true when the source format supplies display-stable board colors.
+     * @param {{ sourceFormat?: string }} options Scene options.
+     * @returns {boolean}
+     */
+    static #shouldPreserveAuthoredSurfaceColor(options) {
+        const sourceFormat = String(options?.sourceFormat || '').toLowerCase()
+        return sourceFormat === 'altium' || sourceFormat.startsWith('altium-')
+    }
+
     /**
      * Resolves whether the generated board face should render.
      * @param {{ hasBoardAssemblyModel?: boolean }} [options] Scene options.

package/src/PcbScene3dBoardShapeFactory.mjs

@@ -1,4 +1,5 @@
 import { PcbScene3dBoardEdgeCutoutBuilder } from './PcbScene3dBoardEdgeCutoutBuilder.mjs'
+import { PcbScene3dBoardCutoutPathFactory } from './PcbScene3dBoardCutoutPathFactory.mjs'
 import { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
 import { PcbScene3dOutlineBuilder } from './PcbScene3dOutlineBuilder.mjs'
 
@@ -36,6 +37,11 @@ export class PcbScene3dBoardShapeFactory {
         )
         const contourPoints =
             PcbScene3dBoardEdgeCutoutBuilder.resolveShapePoints(baseShape)
+        const boardCutouts = PcbScene3dBoardCutoutPathFactory.resolve(
+            THREE,
+            board,
+            normalizeBoardPoint
+        )
         const drillCutouts = PcbScene3dBoardShapeFactory.#resolveDrillCutouts(
             THREE,
             detail,
@@ -61,12 +67,20 @@ export class PcbScene3dBoardShapeFactory {
         const finalContourPoints = edgeCutouts.length
             ? PcbScene3dBoardEdgeCutoutBuilder.resolveShapePoints(shape)
             : contourPoints
-
+        for (const cutout of boardCutouts) {
+            if (
+                PcbScene3dBoardEdgeCutoutBuilder.isHoleInsideContour(
+                    cutout.points,
+                    finalContourPoints
+                )
+            ) {
+                shape.holes.push(cutout.path)
+            }
+        }
         for (const cutout of drillCutouts) {
             if (edgeCutouts.includes(cutout)) {
                 continue
             }
-
             if (
                 !cutout.isCircular ||
                 PcbScene3dBoardEdgeCutoutBuilder.isHoleInsideContour(
@@ -77,7 +91,6 @@ export class PcbScene3dBoardShapeFactory {
                 shape.holes.push(cutout.path)
             }
         }
-
         return shape
     }
 

package/src/PcbScene3dBoardSolderMaskFactory.mjs

@@ -1,4 +1,5 @@
 import { PcbScene3dBoardMaterialPalette } from './PcbScene3dBoardMaterialPalette.mjs'
+import { PcbScene3dBoardCutoutPathFactory } from './PcbScene3dBoardCutoutPathFactory.mjs'
 import { PcbScene3dCutoutGeometryFilter } from './PcbScene3dCutoutGeometryFilter.mjs'
 import { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
 import { PcbScene3dMaterialFinish } from './PcbScene3dMaterialFinish.mjs'
@@ -51,12 +52,14 @@ export class PcbScene3dBoardSolderMaskFactory {
         const topMaterial = PcbScene3dBoardSolderMaskFactory.#buildMaterial(
             THREE,
             board,
-            THREE.FrontSide
+            THREE.FrontSide,
+            sceneDescription?.sourceFormat
         )
         const bottomMaterial = PcbScene3dBoardSolderMaskFactory.#buildMaterial(
             THREE,
             board,
-            THREE.BackSide
+            THREE.BackSide,
+            sceneDescription?.sourceFormat
         )
         const z = Number(board?.thicknessMil || 0) / 2
 
@@ -148,6 +151,11 @@ export class PcbScene3dBoardSolderMaskFactory {
         )
         const contourPoints =
             PcbScene3dBoardSolderMaskFactory.#resolveShapePoints(shape)
+        const boardCutouts = PcbScene3dBoardCutoutPathFactory.resolve(
+            THREE,
+            board,
+            normalizeBoardPoint
+        )
         const drillCutouts =
             PcbScene3dBoardSolderMaskFactory.#resolveDrillCutouts(
                 THREE,
@@ -155,8 +163,8 @@ export class PcbScene3dBoardSolderMaskFactory {
                 normalizeBoardPoint
             )
         const { shapeHoles, clippingCutouts } =
-            PcbScene3dBoardSolderMaskFactory.#partitionDrillCutouts(
-                drillCutouts,
+            PcbScene3dBoardSolderMaskFactory.#partitionCutouts(
+                [...boardCutouts, ...drillCutouts],
                 contourPoints
             )
 
@@ -395,16 +403,16 @@ export class PcbScene3dBoardSolderMaskFactory {
     }
 
     /**
-     * Splits drill cutouts into safe shape holes and fallback clip polygons.
-     * @param {{ path: any, points: { x: number, y: number }[] }[]} drillCutouts
+     * Splits cutouts into safe shape holes and fallback clip polygons.
+     * @param {{ path: any, points: { x: number, y: number }[] }[]} cutouts
      * @param {{ x: number, y: number }[]} contourPoints
      * @returns {{ shapeHoles: { path: any, points: { x: number, y: number }[] }[], clippingCutouts: { path: any, points: { x: number, y: number }[] }[] }}
      */
-    static #partitionDrillCutouts(drillCutouts, contourPoints) {
+    static #partitionCutouts(cutouts, contourPoints) {
         const shapeHoles = []
         const clippingCutouts = []
 
-        for (const cutout of Array.isArray(drillCutouts) ? drillCutouts : []) {
+        for (const cutout of Array.isArray(cutouts) ? cutouts : []) {
             if (
                 PcbScene3dBoardSolderMaskFactory.#isHoleInsideContour(
                     cutout.points,
@@ -596,12 +604,14 @@ export class PcbScene3dBoardSolderMaskFactory {
      * @param {any} THREE
      * @param {{ surfaceColor?: number }} board Board metadata.
      * @param {number} side Rendered material side.
+     * @param {string | undefined} sourceFormat Scene source format.
      * @returns {any}
      */
-    static #buildMaterial(THREE, board, side) {
+    static #buildMaterial(THREE, board, side, sourceFormat) {
         return new THREE.MeshStandardMaterial({
             color: PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
-                hasBoardAssemblyModel: true
+                hasBoardAssemblyModel: true,
+                sourceFormat
             }),
             ...PcbScene3dMaterialFinish.semiMatteSolderMaskProperties(),
             polygonOffset: true,

package/src/PcbScene3dController.mjs

@@ -474,6 +474,7 @@ export class PcbScene3dController {
                 this.#handleRuntimeSelection(selection),
             translate: this.#translate
         })
+        this.#applyInitialToggles()
         if (!this.#autoSearchMissingModels) {
             this.#runtime?.setToggle?.('model-search-models', false)
         }
@@ -562,6 +563,25 @@ export class PcbScene3dController {
         })
     }
 
+    /**
+     * Synchronizes runtime visibility with the shell's initial checkbox state.
+     * @returns {void}
+     */
+    #applyInitialToggles() {
+        const toggles =
+            this.#rootNode?.querySelectorAll('[data-scene-3d-toggle]') || []
+
+        toggles.forEach((toggle) => {
+            const toggleName =
+                toggle?.getAttribute?.('data-scene-3d-toggle') || ''
+            if (!toggleName) {
+                return
+            }
+
+            this.#runtime?.setToggle?.(toggleName, Boolean(toggle.checked))
+        })
+    }
+
     /**
      * Binds the model archive export action.
      * @returns {void}

package/src/PcbScene3dCopperDetailGroupBuilder.mjs

@@ -25,9 +25,14 @@ export class PcbScene3dCopperDetailGroupBuilder {
      */
     static build(THREE, sceneDescription, topZ, normalizePoint) {
         const group = new THREE.Group()
-        const drillCutouts = PcbScene3dCopperDrillCutoutBuilder.resolve(
-            sceneDescription?.detail
-        )
+        const drillCutouts = [
+            ...PcbScene3dCopperDrillCutoutBuilder.resolve(
+                sceneDescription?.detail
+            ),
+            ...PcbScene3dCopperDetailGroupBuilder.#resolveBoardCutouts(
+                sceneDescription?.board
+            )
+        ]
         const coveredGroup =
             PcbScene3dCopperDetailGroupBuilder.#buildCoveredGroup(
                 THREE,
@@ -91,6 +96,10 @@ export class PcbScene3dCopperDetailGroupBuilder {
                 ),
                 drillCutouts,
                 drillDetail: sceneDescription?.detail,
+                unionCoveredLayerPrimitives:
+                    PcbScene3dCopperDetailGroupBuilder.#usesGerberLayerUnion(
+                        sceneDescription
+                    ),
                 occlusionCutouts:
                     PcbScene3dCopperDetailGroupBuilder.#resolveCoveredCopperOcclusions(
                         sceneDescription?.detail
@@ -131,6 +140,18 @@ export class PcbScene3dCopperDetailGroupBuilder {
         )
     }
 
+    /**
+     * Checks whether the source format represents copper as Gerber polarity union.
+     * @param {object | undefined} sceneDescription Scene description.
+     * @returns {boolean}
+     */
+    static #usesGerberLayerUnion(sceneDescription) {
+        return (
+            String(sceneDescription?.sourceFormat || '').toLowerCase() ===
+            'gerber'
+        )
+    }
+
     /**
      * Builds exposed copper detail.
      * @param {any} THREE Three.js namespace.
@@ -187,6 +208,43 @@ export class PcbScene3dCopperDetailGroupBuilder {
         )
     }
 
+    /**
+     * Resolves explicit through-board cutouts that copper detail must not cover.
+     * @param {{ cutouts?: any[] } | undefined} board Board metadata.
+     * @returns {{ x: number, y: number }[][]}
+     */
+    static #resolveBoardCutouts(board) {
+        return (Array.isArray(board?.cutouts) ? board.cutouts : [])
+            .map((cutout) =>
+                PcbScene3dCopperDetailGroupBuilder.#resolveBoardCutoutPoints(
+                    cutout
+                )
+            )
+            .filter((points) => points.length >= 3)
+    }
+
+    /**
+     * Resolves one explicit board cutout loop in source board coordinates.
+     * @param {any} cutout Cutout source.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #resolveBoardCutoutPoints(cutout) {
+        const points = Array.isArray(cutout?.points)
+            ? cutout.points
+            : Array.isArray(cutout?.vertices)
+              ? cutout.vertices
+              : Array.isArray(cutout)
+                ? cutout
+                : []
+
+        return points
+            .map((point) => ({
+                x: Number(point?.x ?? point?.[0]),
+                y: Number(point?.y ?? point?.[1])
+            }))
+            .filter((point) => Number.isFinite(point.x + point.y))
+    }
+
     /**
      * Resolves solder-mask material options for covered copper relief.
      * @param {object} sceneDescription Scene description.
@@ -199,7 +257,8 @@ export class PcbScene3dCopperDetailGroupBuilder {
                 {
                     hasBoardAssemblyModel: Boolean(
                         sceneDescription?.boardAssemblyModel
-                    )
+                    ),
+                    sourceFormat: sceneDescription?.sourceFormat
                 }
             )
         }