pcb-scene3d-viewer 1.1.47 → 1.1.48

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.1.47",
+    "version": "1.1.48",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",

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,
@@ -187,6 +192,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 +241,8 @@ export class PcbScene3dCopperDetailGroupBuilder {
                 {
                     hasBoardAssemblyModel: Boolean(
                         sceneDescription?.boardAssemblyModel
-                    )
+                    ),
+                    sourceFormat: sceneDescription?.sourceFormat
                 }
             )
         }

package/src/PcbScene3dDrillVoidFactory.mjs

@@ -33,15 +33,13 @@ export class PcbScene3dDrillVoidFactory {
             return group
         }
 
-        const material = PcbScene3dDrillVoidFactory.#buildMaterial(
+        const material = PcbScene3dDrillVoidFactory.#buildInteriorMaterial(
             THREE,
             options
         )
         const geometryCache = new Map()
         const depth = Math.max(Math.abs(Number(topZ) - Number(bottomZ)), 1)
         const centerZ = (Number(topZ || 0) + Number(bottomZ || 0)) / 2
-        const platedDrillKeys =
-            PcbScene3dDrillVoidFactory.#buildPlatedDrillKeySet(detail)
         const edgeDrillKeys = PcbScene3dDrillVoidFactory.#buildEdgeDrillKeySet(
             THREE,
             detail,
@@ -52,9 +50,7 @@ export class PcbScene3dDrillVoidFactory {
         PcbScene3dDrillPathFactory.resolveBoardDrillSpecs(detail).forEach(
             (drillSpec) => {
                 if (
-                    platedDrillKeys.has(
-                        PcbScene3dDrillVoidFactory.#drillKey(drillSpec)
-                    ) ||
+                    PcbScene3dDrillVoidFactory.#isSlottedDrill(drillSpec) ||
                     edgeDrillKeys.has(
                         PcbScene3dDrillVoidFactory.#drillKey(drillSpec)
                     )
@@ -101,63 +97,6 @@ export class PcbScene3dDrillVoidFactory {
         )
     }
 
-    /**
-     * Builds a lookup for drill holes that already have copper barrel geometry.
-     * @param {{ pads?: any[], vias?: any[] }} detail
-     * @returns {Set<string>}
-     */
-    static #buildPlatedDrillKeySet(detail) {
-        const platedDrills = new Set()
-
-        for (const via of detail?.vias || []) {
-            if (PcbScene3dDrillVoidFactory.#hasViaCopperAnnulus(via)) {
-                platedDrills.add(PcbScene3dDrillVoidFactory.#drillKey(via))
-            }
-        }
-
-        for (const pad of detail?.pads || []) {
-            if (PcbScene3dDrillVoidFactory.#hasPadCopperAnnulus(pad)) {
-                platedDrills.add(PcbScene3dDrillVoidFactory.#drillKey(pad))
-            }
-        }
-
-        return platedDrills
-    }
-
-    /**
-     * Checks whether one via has a copper annulus around its drill.
-     * @param {any} via Via primitive.
-     * @returns {boolean}
-     */
-    static #hasViaCopperAnnulus(via) {
-        const holeDiameter = Number(via?.holeDiameter || 0)
-        return (
-            holeDiameter > 0 &&
-            Number(via?.diameter || 0) > holeDiameter + 0.001
-        )
-    }
-
-    /**
-     * Checks whether one pad has copper larger than its drill aperture.
-     * @param {any} pad Pad primitive.
-     * @returns {boolean}
-     */
-    static #hasPadCopperAnnulus(pad) {
-        const holeDiameter = Number(pad?.holeDiameter || 0)
-        if (holeDiameter <= 0) {
-            return false
-        }
-
-        return [
-            pad?.sizeTopX,
-            pad?.sizeTopY,
-            pad?.sizeMidX,
-            pad?.sizeMidY,
-            pad?.sizeBottomX,
-            pad?.sizeBottomY
-        ].some((size) => Number(size || 0) > holeDiameter + 0.001)
-    }
-
     /**
      * Builds a stable lookup key for one circular drill.
      * @param {{ x?: number, y?: number, holeDiameter?: number, diameter?: number }} drill
@@ -177,7 +116,7 @@ export class PcbScene3dDrillVoidFactory {
      * @param {{ color?: number }} options
      * @returns {any}
      */
-    static #buildMaterial(THREE, options) {
+    static #buildInteriorMaterial(THREE, options) {
         return new THREE.MeshStandardMaterial({
             color: Number.isInteger(options?.color)
                 ? options.color
@@ -188,6 +127,18 @@ export class PcbScene3dDrillVoidFactory {
         })
     }
 
+    /**
+     * Checks whether one drill is a routed slot.
+     * @param {{ diameter?: number, slotLength?: number | null }} drillSpec Drill spec.
+     * @returns {boolean}
+     */
+    static #isSlottedDrill(drillSpec) {
+        return (
+            Number(drillSpec?.slotLength || 0) >
+            Number(drillSpec?.diameter || 0) + 0.001
+        )
+    }
+
     /**
      * Builds one open circular drill-interior mesh.
      * @param {any} THREE
@@ -208,13 +159,6 @@ export class PcbScene3dDrillVoidFactory {
         material,
         normalizeBoardPoint
     ) {
-        if (
-            Number(drillSpec?.slotLength || 0) >
-            Number(drillSpec?.diameter || 0) + 0.001
-        ) {
-            return null
-        }
-
         const point = normalizeBoardPoint(
             Number(drillSpec?.x || 0),
             Number(drillSpec?.y || 0)

package/src/PcbScene3dExternalModels.mjs

@@ -281,7 +281,8 @@ export class PcbScene3dExternalModels {
             return PcbScene3dExternalModels.#buildBoardAssemblyWrapper(
                 THREE,
                 placement,
-                modelGroup
+                modelGroup,
+                sceneDescription
             )
         }
 
@@ -371,13 +372,25 @@ export class PcbScene3dExternalModels {
      * @param {any} THREE
      * @param {{ positionMil?: { x?: number, y?: number, z?: number }, board?: { widthMil?: number, heightMil?: number, thicknessMil?: number }, sourceFrameScale?: { y?: number } }} placement
      * @param {any} modelGroup
+     * @param {{ sourceFormat?: string } | null | undefined} sceneDescription Scene description.
      * @returns {any}
      */
-    static #buildBoardAssemblyWrapper(THREE, placement, modelGroup) {
+    static #buildBoardAssemblyWrapper(
+        THREE,
+        placement,
+        modelGroup,
+        sceneDescription
+    ) {
         const wrapperGroup = new THREE.Group()
         const positionMil = placement?.positionMil || {}
 
-        PcbScene3dBoardAssemblyPresentation.apply(modelGroup, placement?.board)
+        PcbScene3dBoardAssemblyPresentation.apply(
+            modelGroup,
+            placement?.board,
+            {
+                sourceFormat: sceneDescription?.sourceFormat
+            }
+        )
         PcbScene3dBoardAssemblyTransform.apply(modelGroup, placement)
         wrapperGroup.position.set(
             Number(positionMil.x || 0),

package/src/PcbScene3dGeometryZCompressor.mjs

@@ -9,13 +9,16 @@ export class PcbScene3dGeometryZCompressor {
      * Rewrites mask-covered copper relief below exposed copper height.
      * @param {any | null} mesh Mesh with a position attribute.
      * @param {number} sourceCenterZ Original geometry center Z.
+     * @param {{ centerOffsetMil?: number }} [options] Compression options.
      * @returns {void}
      */
-    static compressMaskCoveredCopperMesh(mesh, sourceCenterZ) {
+    static compressMaskCoveredCopperMesh(mesh, sourceCenterZ, options = {}) {
         PcbScene3dGeometryZCompressor.compressMesh(
             mesh,
             sourceCenterZ,
-            sourceCenterZ + MASK_COVERED_CENTER_OFFSET_MIL,
+            sourceCenterZ +
+                MASK_COVERED_CENTER_OFFSET_MIL +
+                Number(options?.centerOffsetMil || 0),
             MASK_COVERED_THICKNESS_MIL
         )
     }

package/src/PcbScene3dMaskCoveredCopperMaterial.mjs

@@ -6,7 +6,7 @@ import { PcbScene3dMaterialFinish } from './PcbScene3dMaterialFinish.mjs'
 export class PcbScene3dMaskCoveredCopperMaterial {
     static #COPPER_COLOR = 0xd9a61d
     static #DEFAULT_SOLDER_MASK_COLOR = 0x2a5f27
-    static #COPPER_BLEND = 0.2
+    static #COPPER_BLEND = 0.04
 
     /**
      * Builds a mask-covered copper material.

package/src/PcbScene3dMaskCoveredCopperSideGroupBuilder.mjs

@@ -4,6 +4,13 @@ import { PcbScene3dGeometryZCompressor } from './PcbScene3dGeometryZCompressor.m
  * Builds side-specific copper relief groups that sit below solder mask.
  */
 export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
+    static #GREEN_MASKED_COPPER_TINT = 0x1f7a34
+    static #FILL_COPPER_BLEND = 0.45
+    static #TRACK_COPPER_BLEND = 0.7
+    static #FILL_RENDER_ORDER = 10
+    static #TRACK_RENDER_ORDER = 12
+    static #TRACK_CENTER_OFFSET_MIL = 0.16
+
     /**
      * Builds one side group from prepared mask-covered copper meshes.
      * @param {any} THREE Three.js namespace.
@@ -26,19 +33,49 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
             group,
             trackMesh,
             'mask-covered-copper-tracks',
-            z
+            z,
+            {
+                centerOffsetMil:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_CENTER_OFFSET_MIL,
+                copperBlend:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_COPPER_BLEND,
+                renderOrder:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_RENDER_ORDER
+            }
         )
         PcbScene3dMaskCoveredCopperSideGroupBuilder.#addCompressedMesh(
             group,
             arcMesh,
             'mask-covered-copper-arcs',
-            z
+            z,
+            {
+                centerOffsetMil:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_CENTER_OFFSET_MIL,
+                copperBlend:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_COPPER_BLEND,
+                renderOrder:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_RENDER_ORDER
+            }
         )
         PcbScene3dMaskCoveredCopperSideGroupBuilder.#addCompressedMesh(
             group,
             fillMesh,
             'mask-covered-copper-fills',
-            z
+            z,
+            {
+                copperBlend:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#FILL_COPPER_BLEND,
+                renderOrder:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#FILL_RENDER_ORDER
+            }
         )
 
         if (mirrorY && group.children.length) {
@@ -54,15 +91,145 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
      * @param {any | null} mesh Mesh to add.
      * @param {string} name Scene object name.
      * @param {number} z Source center Z.
+     * @param {{ centerOffsetMil?: number, copperBlend?: number, renderOrder?: number }} [options] Presentation options.
      * @returns {void}
      */
-    static #addCompressedMesh(group, mesh, name, z) {
+    static #addCompressedMesh(group, mesh, name, z, options = {}) {
         if (!mesh) {
             return
         }
 
-        PcbScene3dGeometryZCompressor.compressMaskCoveredCopperMesh(mesh, z)
+        PcbScene3dGeometryZCompressor.compressMaskCoveredCopperMesh(mesh, z, {
+            centerOffsetMil: options.centerOffsetMil
+        })
         mesh.name = name
+        mesh.renderOrder = Number(options.renderOrder || 0)
+        PcbScene3dMaskCoveredCopperSideGroupBuilder.#applyCopperTint(
+            mesh,
+            options.copperBlend
+        )
         group.add(mesh)
     }
+
+    /**
+     * Applies a role-specific covered-copper tint without mutating sibling meshes.
+     * @param {any} mesh Source mesh.
+     * @param {number | undefined} copperBlend Blend ratio.
+     * @returns {void}
+     */
+    static #applyCopperTint(mesh, copperBlend) {
+        const material = mesh?.material?.clone?.() || mesh?.material
+        const baseColor = material?.color?.getHex?.()
+        if (!material || !Number.isInteger(baseColor)) {
+            return
+        }
+
+        material.color.setHex(
+            PcbScene3dMaskCoveredCopperSideGroupBuilder.#blendHexColor(
+                baseColor,
+                PcbScene3dMaskCoveredCopperSideGroupBuilder.#resolveMaskedCopperTint(
+                    baseColor
+                ),
+                copperBlend
+            )
+        )
+        mesh.material = material
+    }
+
+    /**
+     * Resolves a mask-covered copper tint that stays in the solder-mask hue.
+     * @param {number} baseColor Base mask-covered copper color.
+     * @returns {number}
+     */
+    static #resolveMaskedCopperTint(baseColor) {
+        const channels =
+            PcbScene3dMaskCoveredCopperSideGroupBuilder.#rgbChannels(baseColor)
+        const dominant =
+            PcbScene3dMaskCoveredCopperSideGroupBuilder.#dominantChannel(
+                channels
+            )
+        if (dominant === 'green') {
+            return PcbScene3dMaskCoveredCopperSideGroupBuilder
+                .#GREEN_MASKED_COPPER_TINT
+        }
+
+        return PcbScene3dMaskCoveredCopperSideGroupBuilder.#rgbToHex({
+            red: PcbScene3dMaskCoveredCopperSideGroupBuilder.#tintChannel(
+                channels.red,
+                dominant === 'red'
+            ),
+            green: PcbScene3dMaskCoveredCopperSideGroupBuilder.#tintChannel(
+                channels.green,
+                dominant === 'green'
+            ),
+            blue: PcbScene3dMaskCoveredCopperSideGroupBuilder.#tintChannel(
+                channels.blue,
+                dominant === 'blue'
+            )
+        })
+    }
+
+    /**
+     * Resolves one RGB channel from a packed color.
+     * @param {number} color Packed hex color.
+     * @returns {{ red: number, green: number, blue: number }}
+     */
+    static #rgbChannels(color) {
+        return {
+            red: (color >> 16) & 255,
+            green: (color >> 8) & 255,
+            blue: color & 255
+        }
+    }
+
+    /**
+     * Resolves the dominant color channel.
+     * @param {{ red: number, green: number, blue: number }} channels RGB channels.
+     * @returns {'red' | 'green' | 'blue'}
+     */
+    static #dominantChannel(channels) {
+        return Object.entries(channels).sort(
+            (left, right) => right[1] - left[1]
+        )[0][0]
+    }
+
+    /**
+     * Builds a tint channel that preserves the source mask hue.
+     * @param {number} channel Source channel value.
+     * @param {boolean} dominant Whether this channel is dominant.
+     * @returns {number}
+     */
+    static #tintChannel(channel, dominant) {
+        const value = dominant ? channel * 1.25 + 16 : channel * 0.84
+        return Math.min(255, Math.max(0, Math.round(value)))
+    }
+
+    /**
+     * Packs RGB channels into a hex color.
+     * @param {{ red: number, green: number, blue: number }} channels RGB channels.
+     * @returns {number}
+     */
+    static #rgbToHex(channels) {
+        return (channels.red << 16) | (channels.green << 8) | channels.blue
+    }
+
+    /**
+     * Blends two integer RGB colors.
+     * @param {number} baseColor Base color.
+     * @param {number} overlayColor Overlay color.
+     * @param {number | undefined} overlayRatio Overlay ratio.
+     * @returns {number}
+     */
+    static #blendHexColor(baseColor, overlayColor, overlayRatio) {
+        const ratio = Math.min(Math.max(Number(overlayRatio || 0), 0), 1)
+        const inverse = 1 - ratio
+
+        return [16, 8, 0].reduce((output, shift) => {
+            const channel = Math.round(
+                ((baseColor >> shift) & 255) * inverse +
+                    ((overlayColor >> shift) & 255) * ratio
+            )
+            return output | (channel << shift)
+        }, 0)
+    }
 }

package/src/PcbScene3dOutlineBuilder.mjs

@@ -30,8 +30,29 @@ export class PcbScene3dOutlineBuilder {
                 y: firstPoint.y
             }
         ]
+        let currentPoint = firstPoint
 
         for (const segment of segments) {
+            const startPoint = PcbScene3dOutlineBuilder.#segmentStartPoint(
+                segment,
+                centerX,
+                centerY
+            )
+            if (
+                startPoint &&
+                PcbScene3dOutlineBuilder.#distanceBetween(
+                    currentPoint,
+                    startPoint
+                ) >= PcbScene3dOutlineBuilder.#DEGENERATE_LINE_EPSILON
+            ) {
+                commands.push({
+                    type: 'move',
+                    x: startPoint.x,
+                    y: startPoint.y
+                })
+                currentPoint = startPoint
+            }
+
             if (segment.type === 'arc') {
                 const arcCommand = PcbScene3dOutlineBuilder.#buildArcCommand(
                     segment,
@@ -40,6 +61,8 @@ export class PcbScene3dOutlineBuilder {
                 )
                 if (arcCommand) {
                     commands.push(arcCommand)
+                    currentPoint =
+                        PcbScene3dOutlineBuilder.#commandEndPoint(arcCommand)
                 }
                 continue
             }
@@ -51,12 +74,43 @@ export class PcbScene3dOutlineBuilder {
             )
             if (lineCommand) {
                 commands.push(lineCommand)
+                currentPoint =
+                    PcbScene3dOutlineBuilder.#commandEndPoint(lineCommand)
             }
         }
 
         return commands
     }
 
+    /**
+     * Converts one segment start into local centered scene coordinates.
+     * @param {Record<string, number | string>} segment Source segment.
+     * @param {number} centerX Board center X.
+     * @param {number} centerY Board center Y.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static #segmentStartPoint(segment, centerX, centerY) {
+        const x = Number(segment?.x1)
+        const y = Number(segment?.y1)
+        if (!Number.isFinite(x) || !Number.isFinite(y)) {
+            return null
+        }
+
+        return PcbScene3dOutlineBuilder.#toLocalPoint(x, y, centerX, centerY)
+    }
+
+    /**
+     * Resolves one generated command's endpoint.
+     * @param {Record<string, number | boolean>} command Outline command.
+     * @returns {{ x: number, y: number }}
+     */
+    static #commandEndPoint(command) {
+        return {
+            x: Number(command.endX ?? command.x ?? 0),
+            y: Number(command.endY ?? command.y ?? 0)
+        }
+    }
+
     /**
      * Converts one outline line segment into a local line command.
      * @param {Record<string, number | string>} segment

package/src/PcbScene3dRuntime.mjs

@@ -367,7 +367,7 @@ export class PcbScene3dRuntime {
                 -board.thicknessMil / 2,
                 (x, y) => this.#normalizeDetailPoint(x, y),
                 {
-                    enabled: Boolean(this.#sceneDescription.boardAssemblyModel),
+                    enabled: true,
                     board
                 }
             )

package/src/PcbScene3dShellRenderer.mjs

@@ -8,9 +8,10 @@ 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.
+     * @param {{ initialToggles?: { 'external-models'?: boolean, 'fallback-bodies'?: boolean, copper?: boolean } }} [options] Rendering options.
      * @returns {string}
      */
-    static render(documentModel, translate = null) {
+    static render(documentModel, translate = null, options = {}) {
         const t = PcbScene3dText.createTranslator(translate)
         const pcb = documentModel?.pcb
         if (!pcb) {
@@ -71,13 +72,27 @@ export class PcbScene3dShellRenderer {
             '<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" />' +
+            '<label class="scene-3d__toggle"><input type="checkbox"' +
+            PcbScene3dShellRenderer.#checkedAttribute(
+                options,
+                'external-models',
+                true
+            ) +
+            ' 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" />' +
+            '<label class="scene-3d__toggle"><input type="checkbox"' +
+            PcbScene3dShellRenderer.#checkedAttribute(
+                options,
+                'fallback-bodies',
+                false
+            ) +
+            ' 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" />' +
+            '<label class="scene-3d__toggle"><input type="checkbox"' +
+            PcbScene3dShellRenderer.#checkedAttribute(options, 'copper', true) +
+            ' 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">' +
@@ -114,6 +129,25 @@ export class PcbScene3dShellRenderer {
         )
     }
 
+    /**
+     * Returns the checkbox checked attribute for one scene toggle.
+     * @param {{ initialToggles?: Record<string, boolean> }} options Renderer options.
+     * @param {string} toggleName Toggle identifier.
+     * @param {boolean} defaultChecked Package default state.
+     * @returns {string}
+     */
+    static #checkedAttribute(options, toggleName, defaultChecked) {
+        const initialToggles = options?.initialToggles || {}
+        const checked = Object.prototype.hasOwnProperty.call(
+            initialToggles,
+            toggleName
+        )
+            ? initialToggles[toggleName] === true
+            : defaultChecked
+
+        return checked ? ' checked' : ''
+    }
+
     /**
      * Escapes markup text.
      * @param {string} value Raw text.