pcb-scene3d-viewer 1.1.49 → 1.1.50

package/package.json

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

package/src/PcbScene3dBoardAssemblyPresentation.mjs

@@ -420,7 +420,7 @@ export class PcbScene3dBoardAssemblyPresentation {
      * @returns {number}
      */
     static #resolveSurfaceColor(board, options) {
-        return PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
+        return PcbScene3dBoardMaterialPalette.resolveBoardSurfaceColor(board, {
             hasBoardAssemblyModel: true,
             sourceFormat: options?.sourceFormat
         })

package/src/PcbScene3dBoardMaterialPalette.mjs

@@ -3,6 +3,7 @@
  */
 export class PcbScene3dBoardMaterialPalette {
     static #DEFAULT_SURFACE_COLOR = 0x2a5f27
+    static #BOARD_SURFACE_DARKEN_RATIO = 0.88
 
     /**
      * Resolves the solder-mask face color for the generated board shell.
@@ -25,6 +26,19 @@ export class PcbScene3dBoardMaterialPalette {
             : PcbScene3dBoardMaterialPalette.#DEFAULT_SURFACE_COLOR
     }
 
+    /**
+     * Resolves the darker display color for visible board solder-mask faces.
+     * @param {{ surfaceColor?: number } | undefined} board Board metadata.
+     * @param {{ hasBoardAssemblyModel?: boolean, sourceFormat?: string }} [options] Scene options.
+     * @returns {number}
+     */
+    static resolveBoardSurfaceColor(board, options = {}) {
+        return PcbScene3dBoardMaterialPalette.#darkenHexColor(
+            PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, options),
+            PcbScene3dBoardMaterialPalette.#BOARD_SURFACE_DARKEN_RATIO
+        )
+    }
+
     /**
      * Returns true when the source format supplies display-stable board colors.
      * @param {{ sourceFormat?: string }} options Scene options.
@@ -52,4 +66,19 @@ export class PcbScene3dBoardMaterialPalette {
     static isGeneratedBodyVisible(options = {}) {
         return true
     }
+
+    /**
+     * Darkens a packed RGB color while preserving its hue.
+     * @param {number} color Packed RGB color.
+     * @param {number} ratio Channel multiplier.
+     * @returns {number}
+     */
+    static #darkenHexColor(color, ratio) {
+        const multiplier = Math.min(Math.max(Number(ratio || 0), 0), 1)
+
+        return [16, 8, 0].reduce((output, shift) => {
+            const channel = Math.round(((color >> shift) & 255) * multiplier)
+            return output | (channel << shift)
+        }, 0)
+    }
 }

package/src/PcbScene3dBoardSolderMaskFactory.mjs

@@ -609,10 +609,13 @@ export class PcbScene3dBoardSolderMaskFactory {
      */
     static #buildMaterial(THREE, board, side, sourceFormat) {
         return new THREE.MeshStandardMaterial({
-            color: PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
-                hasBoardAssemblyModel: true,
-                sourceFormat
-            }),
+            color: PcbScene3dBoardMaterialPalette.resolveBoardSurfaceColor(
+                board,
+                {
+                    hasBoardAssemblyModel: true,
+                    sourceFormat
+                }
+            ),
             ...PcbScene3dMaterialFinish.semiMatteSolderMaskProperties(),
             polygonOffset: true,
             polygonOffsetFactor: -1,

package/src/PcbScene3dDrillVoidFactory.mjs

@@ -1,4 +1,5 @@
 import { PcbScene3dBoardShapeFactory } from './PcbScene3dBoardShapeFactory.mjs'
+import { PcbScene3dBoardMaterialPalette } from './PcbScene3dBoardMaterialPalette.mjs'
 import { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
 
 /**
@@ -16,7 +17,7 @@ export class PcbScene3dDrillVoidFactory {
      * @param {number} [topZ]
      * @param {number} [bottomZ]
      * @param {(x: number, y: number) => { x: number, y: number }} [normalizeBoardPoint]
-     * @param {{ enabled?: boolean, color?: number, board?: object }} [options]
+     * @param {{ enabled?: boolean, color?: number, board?: object, hasBoardAssemblyModel?: boolean, sourceFormat?: string }} [options]
      * @returns {any}
      */
     static buildGroup(
@@ -113,20 +114,43 @@ export class PcbScene3dDrillVoidFactory {
     /**
      * Builds the shared drill-interior material.
      * @param {any} THREE
-     * @param {{ color?: number }} options
+     * @param {{ color?: number, board?: object, hasBoardAssemblyModel?: boolean, sourceFormat?: string }} options
      * @returns {any}
      */
     static #buildInteriorMaterial(THREE, options) {
         return new THREE.MeshStandardMaterial({
-            color: Number.isInteger(options?.color)
-                ? options.color
-                : PcbScene3dDrillVoidFactory.#DEFAULT_INTERIOR_COLOR,
+            color: PcbScene3dDrillVoidFactory.#resolveInteriorColor(options),
             roughness: 0.82,
             metalness: 0,
             side: THREE.DoubleSide
         })
     }
 
+    /**
+     * Resolves the drill-interior display color.
+     * @param {{ color?: number, board?: object, hasBoardAssemblyModel?: boolean, sourceFormat?: string }} options
+     * @returns {number}
+     */
+    static #resolveInteriorColor(options) {
+        if (Number.isInteger(options?.color)) {
+            return options.color
+        }
+
+        if (options?.board) {
+            return PcbScene3dBoardMaterialPalette.resolveBoardSurfaceColor(
+                options.board,
+                {
+                    hasBoardAssemblyModel: Boolean(
+                        options?.hasBoardAssemblyModel
+                    ),
+                    sourceFormat: options?.sourceFormat
+                }
+            )
+        }
+
+        return PcbScene3dDrillVoidFactory.#DEFAULT_INTERIOR_COLOR
+    }
+
     /**
      * Checks whether one drill is a routed slot.
      * @param {{ diameter?: number, slotLength?: number | null }} drillSpec Drill spec.

package/src/PcbScene3dGeometryZCompressor.mjs

@@ -9,7 +9,7 @@ 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.
+     * @param {{ centerOffsetMil?: number, thicknessMil?: number }} [options] Compression options.
      * @returns {void}
      */
     static compressMaskCoveredCopperMesh(mesh, sourceCenterZ, options = {}) {
@@ -19,7 +19,9 @@ export class PcbScene3dGeometryZCompressor {
             sourceCenterZ +
                 MASK_COVERED_CENTER_OFFSET_MIL +
                 Number(options?.centerOffsetMil || 0),
-            MASK_COVERED_THICKNESS_MIL
+            Number.isFinite(Number(options?.thicknessMil))
+                ? Math.max(Number(options.thicknessMil), 0)
+                : MASK_COVERED_THICKNESS_MIL
         )
     }
 

package/src/PcbScene3dMaskCoveredCopperSideGroupBuilder.mjs

@@ -10,7 +10,8 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
     static #TRACK_COPPER_BLEND = 0.7
     static #FILL_RENDER_ORDER = 10
     static #TRACK_RENDER_ORDER = 12
-    static #TRACK_CENTER_OFFSET_MIL = 0.16
+    static #TRACK_CENTER_OFFSET_MIL = 0.25
+    static #TRACK_THICKNESS_MIL = 1.05
 
     /**
      * Builds one side group from prepared mask-covered copper meshes.
@@ -39,6 +40,10 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
                 centerOffsetMil:
                     PcbScene3dMaskCoveredCopperSideGroupBuilder
                         .#TRACK_CENTER_OFFSET_MIL,
+                thicknessMil:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_THICKNESS_MIL,
+                keepSideWalls: true,
                 copperBlend:
                     PcbScene3dMaskCoveredCopperSideGroupBuilder
                         .#TRACK_COPPER_BLEND,
@@ -56,6 +61,10 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
                 centerOffsetMil:
                     PcbScene3dMaskCoveredCopperSideGroupBuilder
                         .#TRACK_CENTER_OFFSET_MIL,
+                thicknessMil:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_THICKNESS_MIL,
+                keepSideWalls: true,
                 copperBlend:
                     PcbScene3dMaskCoveredCopperSideGroupBuilder
                         .#TRACK_COPPER_BLEND,
@@ -92,7 +101,7 @@ 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.
+     * @param {{ centerOffsetMil?: number, thicknessMil?: number, keepSideWalls?: boolean, copperBlend?: number, renderOrder?: number }} [options] Presentation options.
      * @returns {void}
      */
     static #addCompressedMesh(group, mesh, name, z, options = {}) {
@@ -100,9 +109,14 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
             return
         }
         PcbScene3dGeometryZCompressor.compressMaskCoveredCopperMesh(mesh, z, {
-            centerOffsetMil: options.centerOffsetMil
+            centerOffsetMil: options.centerOffsetMil,
+            thicknessMil: options.thicknessMil
         })
-        PcbScene3dMaskCoveredCopperSurfaceFilter.keepOuterSurface(mesh)
+        if (options.keepSideWalls === true) {
+            PcbScene3dMaskCoveredCopperSurfaceFilter.keepOuterRelief(mesh)
+        } else {
+            PcbScene3dMaskCoveredCopperSurfaceFilter.keepOuterSurface(mesh)
+        }
         mesh.name = name
         mesh.renderOrder = Number(options.renderOrder || 0)
         PcbScene3dMaskCoveredCopperSideGroupBuilder.#applyCopperTint(

package/src/PcbScene3dMaskCoveredCopperSurfaceFilter.mjs

@@ -10,6 +10,29 @@ export class PcbScene3dMaskCoveredCopperSurfaceFilter {
      * @returns {void}
      */
     static keepOuterSurface(mesh) {
+        PcbScene3dMaskCoveredCopperSurfaceFilter.#filterOuterTriangles(mesh, {
+            keepSideWalls: false
+        })
+    }
+
+    /**
+     * Removes the hidden underside while keeping shallow edge walls.
+     * @param {any | null} mesh Copper relief mesh.
+     * @returns {void}
+     */
+    static keepOuterRelief(mesh) {
+        PcbScene3dMaskCoveredCopperSurfaceFilter.#filterOuterTriangles(mesh, {
+            keepSideWalls: true
+        })
+    }
+
+    /**
+     * Keeps only triangles that are visible above the solder mask.
+     * @param {any | null} mesh Copper relief mesh.
+     * @param {{ keepSideWalls?: boolean }} options Filter options.
+     * @returns {void}
+     */
+    static #filterOuterTriangles(mesh, options) {
         const geometry = mesh?.geometry
         const position = geometry?.getAttribute?.('position')
         const source = position?.array
@@ -17,14 +40,16 @@ export class PcbScene3dMaskCoveredCopperSurfaceFilter {
             return
         }
 
-        const maxZ = PcbScene3dMaskCoveredCopperSurfaceFilter.#maxZ(source)
+        const zBounds =
+            PcbScene3dMaskCoveredCopperSurfaceFilter.#zBounds(source)
         const filtered = []
         for (let index = 0; index + 8 < source.length; index += 9) {
             if (
-                [2, 5, 8].every(
-                    (offset) =>
-                        Math.abs(source[index + offset] - maxZ) <=
-                        PcbScene3dMaskCoveredCopperSurfaceFilter.#Z_EPSILON
+                PcbScene3dMaskCoveredCopperSurfaceFilter.#keepsTriangle(
+                    source,
+                    index,
+                    zBounds,
+                    options
                 )
             ) {
                 filtered.push(...source.slice(index, index + 9))
@@ -50,15 +75,55 @@ export class PcbScene3dMaskCoveredCopperSurfaceFilter {
     }
 
     /**
-     * Resolves the highest Z plane in one packed XYZ buffer.
+     * Checks whether one triangle should stay in the visible relief mesh.
+     * @param {ArrayLike<number>} source Position buffer.
+     * @param {number} index Triangle start index.
+     * @param {{ minZ: number, maxZ: number }} zBounds Geometry Z bounds.
+     * @param {{ keepSideWalls?: boolean }} options Filter options.
+     * @returns {boolean}
+     */
+    static #keepsTriangle(source, index, zBounds, options) {
+        const zValues = [2, 5, 8].map((offset) => source[index + offset])
+        const hasTop = zValues.some((z) =>
+            PcbScene3dMaskCoveredCopperSurfaceFilter.#matchesZ(z, zBounds.maxZ)
+        )
+        const hasBottom = zValues.some((z) =>
+            PcbScene3dMaskCoveredCopperSurfaceFilter.#matchesZ(z, zBounds.minZ)
+        )
+
+        if (hasTop && !hasBottom) {
+            return true
+        }
+
+        return options?.keepSideWalls === true && hasTop && hasBottom
+    }
+
+    /**
+     * Checks whether a Z value matches one target plane.
+     * @param {number} value Candidate Z.
+     * @param {number} target Target Z.
+     * @returns {boolean}
+     */
+    static #matchesZ(value, target) {
+        return (
+            Math.abs(Number(value) - Number(target)) <=
+            PcbScene3dMaskCoveredCopperSurfaceFilter.#Z_EPSILON
+        )
+    }
+
+    /**
+     * Resolves the lowest and highest Z planes in one packed XYZ buffer.
      * @param {ArrayLike<number>} source Position buffer.
-     * @returns {number}
+     * @returns {{ minZ: number, maxZ: number }}
      */
-    static #maxZ(source) {
+    static #zBounds(source) {
+        let minZ = Infinity
         let maxZ = -Infinity
         for (let index = 2; index < source.length; index += 3) {
-            maxZ = Math.max(maxZ, Number(source[index]))
+            const z = Number(source[index])
+            minZ = Math.min(minZ, z)
+            maxZ = Math.max(maxZ, z)
         }
-        return maxZ
+        return { minZ, maxZ }
     }
 }

package/src/PcbScene3dRuntime.mjs

@@ -264,7 +264,6 @@ export class PcbScene3dRuntime {
             this.#settleReady()
             return
         }
-
         try {
             const { THREE, OrbitControls } =
                 (await this.#hooks.loadRuntimeModules?.()) ||
@@ -274,7 +273,6 @@ export class PcbScene3dRuntime {
             if (this.#isDisposed || !this.#viewportNode) {
                 return
             }
-
             this.#createRenderer()
             this.#createSceneGraph()
             this.#createControls()
@@ -299,7 +297,6 @@ export class PcbScene3dRuntime {
     #createRenderer() {
         const THREE = this.#three
         const size = PcbScene3dViewportResize.resolveSize(this.#viewportNode)
-
         this.#renderer = new THREE.WebGLRenderer({
             antialias: true,
             alpha: true,
@@ -310,7 +307,6 @@ export class PcbScene3dRuntime {
         this.#renderer.domElement.className = 'scene-3d__canvas'
         this.#renderer.domElement.style.width = '100%'
         this.#renderer.domElement.style.height = '100%'
-
         this.#scene = new THREE.Scene()
         this.#camera = new THREE.PerspectiveCamera(
             38,
@@ -368,7 +364,11 @@ export class PcbScene3dRuntime {
                 (x, y) => this.#normalizeDetailPoint(x, y),
                 {
                     enabled: true,
-                    board
+                    board,
+                    hasBoardAssemblyModel: Boolean(
+                        this.#sceneDescription.boardAssemblyModel
+                    ),
+                    sourceFormat: this.#sceneDescription.sourceFormat
                 }
             )
         )

package/src/PcbScene3dRuntimeBoardMeshes.mjs

@@ -97,7 +97,7 @@ export class PcbScene3dRuntimeBoardMeshes {
             : 0xc9ca78
         const surfaceColor = hasBoardAssemblyModel
             ? resolvedEdgeColor
-            : PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
+            : PcbScene3dBoardMaterialPalette.resolveBoardSurfaceColor(board, {
                   hasBoardAssemblyModel
               })