pcb-scene3d-viewer 1.1.2 → 1.1.10

package/package.json

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

package/src/PcbScene3dArcUtils.mjs

@@ -4,6 +4,24 @@
 export class PcbScene3dArcUtils {
     static #FULL_CIRCLE_EPSILON = 0.001
 
+    /**
+     * Resolves one arc record's sweep, preserving explicit long-arc sweeps.
+     * @param {{ startAngle?: number, endAngle?: number, sweepAngle?: number }} arc
+     * Arc record.
+     * @returns {number}
+     */
+    static resolveArcSweepDelta(arc) {
+        const sweepAngle = Number(arc?.sweepAngle)
+        if (Number.isFinite(sweepAngle)) {
+            return sweepAngle
+        }
+
+        return PcbScene3dArcUtils.resolveSweepDelta(
+            Number(arc?.startAngle || 0),
+            Number(arc?.endAngle || 0)
+        )
+    }
+
     /**
      * Normalizes one PCB arc delta to the intended short wrapped sweep.
      * @param {number} startAngle Start angle in degrees.

package/src/PcbScene3dBoardAssemblyPresentation.mjs

@@ -1,4 +1,5 @@
 import { PcbScene3dBoardMaterialPalette } from './PcbScene3dBoardMaterialPalette.mjs'
+import { PcbScene3dMaterialFinish } from './PcbScene3dMaterialFinish.mjs'
 
 /**
  * Applies display-only material adjustments to full-board assembly models.
@@ -155,6 +156,7 @@ export class PcbScene3dBoardAssemblyPresentation {
             object?.material,
             surfaceColor
         )
+        PcbScene3dMaterialFinish.applySemiMatteSolderMask(object?.material)
     }
 
     /**
@@ -192,6 +194,7 @@ export class PcbScene3dBoardAssemblyPresentation {
             surfaceMaterial,
             surfaceColor
         )
+        PcbScene3dMaterialFinish.applySemiMatteSolderMask(surfaceMaterial)
         PcbScene3dBoardAssemblyPresentation.#applyMaterialColor(
             edgeMaterial,
             edgeColor

package/src/PcbScene3dBoardSolderMaskFactory.mjs

@@ -1,6 +1,7 @@
 import { PcbScene3dBoardMaterialPalette } from './PcbScene3dBoardMaterialPalette.mjs'
 import { PcbScene3dCutoutGeometryFilter } from './PcbScene3dCutoutGeometryFilter.mjs'
 import { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
+import { PcbScene3dMaterialFinish } from './PcbScene3dMaterialFinish.mjs'
 import { PcbScene3dOutlineBuilder } from './PcbScene3dOutlineBuilder.mjs'
 
 /**
@@ -602,8 +603,7 @@ export class PcbScene3dBoardSolderMaskFactory {
             color: PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
                 hasBoardAssemblyModel: true
             }),
-            roughness: 0.68,
-            metalness: 0.08,
+            ...PcbScene3dMaterialFinish.semiMatteSolderMaskProperties(),
             polygonOffset: true,
             polygonOffsetFactor: -1,
             polygonOffsetUnits: -1,

package/src/PcbScene3dCameraRig.mjs

@@ -48,7 +48,7 @@ export class PcbScene3dCameraRig {
             return {
                 radius,
                 target,
-                up: { x: 0, y: -1, z: 0 },
+                up: PcbScene3dCameraRig.#bottomUpVector(sceneDescription),
                 position: {
                     x: target.x,
                     y: target.y,
@@ -165,4 +165,19 @@ export class PcbScene3dCameraRig {
             z: Number(controls?.target?.z || 0)
         }
     }
+
+    /**
+     * Resolves screen-up for bottom views from the scene coordinate contract.
+     * @param {{ coordinateSystem?: string }} sceneDescription Scene metadata.
+     * @returns {{ x: number, y: number, z: number }}
+     */
+    static #bottomUpVector(sceneDescription) {
+        const coordinateSystem = String(
+            sceneDescription?.coordinateSystem || ''
+        ).toLowerCase()
+
+        return coordinateSystem === 'kicad-3d-y-up'
+            ? { x: 0, y: 1, z: 0 }
+            : { x: 0, y: -1, z: 0 }
+    }
 }

package/src/PcbScene3dCopperDetailFilter.mjs

@@ -39,6 +39,41 @@ export class PcbScene3dCopperDetailFilter {
         }
     }
 
+    /**
+     * Resolves trace-like copper that should be visible through solder mask.
+     * @param {object} sceneDescription 3D scene description.
+     * @returns {{ tracks: any[], arcs: any[], copperTexts: any[], vias: any[] }}
+     */
+    static resolveCoveredByMask(sceneDescription) {
+        const detail = sceneDescription?.detail || {}
+
+        if (
+            !PcbScene3dCopperDetailFilter.#usesRealisticMasking(
+                sceneDescription
+            )
+        ) {
+            return { tracks: [], arcs: [], copperTexts: [], vias: [] }
+        }
+
+        const defaultCovered =
+            PcbScene3dCopperDetailFilter.#usesDefaultCoveredCopper(
+                sceneDescription
+            )
+
+        return {
+            tracks: PcbScene3dCopperDetailFilter.#filterMaskCoveredPrimitives(
+                detail.tracks,
+                defaultCovered
+            ),
+            arcs: PcbScene3dCopperDetailFilter.#filterMaskCoveredPrimitives(
+                detail.arcs,
+                defaultCovered
+            ),
+            copperTexts: [],
+            vias: []
+        }
+    }
+
     /**
      * Checks whether standalone via annuli should be rendered.
      * @param {object} sceneDescription 3D scene description.
@@ -101,6 +136,24 @@ export class PcbScene3dCopperDetailFilter {
         )
     }
 
+    /**
+     * Checks whether tracks are considered mask-covered without per-primitive
+     * mask metadata.
+     * @param {object} sceneDescription 3D scene description.
+     * @returns {boolean}
+     */
+    static #usesDefaultCoveredCopper(sceneDescription) {
+        const sourceFormat = String(sceneDescription?.sourceFormat || '')
+            .trim()
+            .toLowerCase()
+
+        return (
+            sourceFormat === 'altium' ||
+            sourceFormat === 'kicad' ||
+            sceneDescription?.coordinateSystem === 'kicad-3d-y-up'
+        )
+    }
+
     /**
      * Checks whether parsed copper detail carries explicit solder-mask data.
      * @param {object | undefined} detail Scene detail.
@@ -132,6 +185,25 @@ export class PcbScene3dCopperDetailFilter {
         )
     }
 
+    /**
+     * Keeps trace-like copper primitives that are covered by solder mask.
+     * @param {any[] | undefined} primitives Copper primitive list.
+     * @param {boolean} defaultCovered Whether missing metadata means covered.
+     * @returns {any[]}
+     */
+    static #filterMaskCoveredPrimitives(primitives, defaultCovered) {
+        return (primitives || []).filter((primitive) => {
+            if (PcbScene3dCopperDetailFilter.#hasMaskOpening(primitive)) {
+                return false
+            }
+
+            return (
+                defaultCovered ||
+                PcbScene3dCopperDetailFilter.#hasMaskMetadata(primitive)
+            )
+        })
+    }
+
     /**
      * Keeps vias only when they are explicitly not tented.
      * @param {any[] | undefined} vias Via list.
@@ -243,7 +315,7 @@ export class PcbScene3dCopperDetailFilter {
      * @returns {boolean}
      */
     static #hasMaskOpening(primitive, maskMatcher = null) {
-        if (primitive?.hasSolderMask === true) {
+        if (primitive?.hasSolderMask === false) {
             return true
         }
 

package/src/PcbScene3dCopperDetailGroupBuilder.mjs

@@ -0,0 +1,120 @@
+import { PcbScene3dBoardMaterialPalette } from './PcbScene3dBoardMaterialPalette.mjs'
+import { PcbScene3dCopperDetailFilter } from './PcbScene3dCopperDetailFilter.mjs'
+import { PcbScene3dCopperFactory } from './PcbScene3dCopperFactory.mjs'
+import { PcbScene3dViaFactory } from './PcbScene3dViaFactory.mjs'
+
+/**
+ * Builds deferred copper-detail groups for the 3D runtime.
+ */
+export class PcbScene3dCopperDetailGroupBuilder {
+    /**
+     * Builds visible exposed and mask-covered copper detail.
+     * @param {any} THREE Three.js namespace.
+     * @param {object} sceneDescription Scene description.
+     * @param {number} topZ Top copper center Z.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizePoint
+     * @returns {any}
+     */
+    static build(THREE, sceneDescription, topZ, normalizePoint) {
+        const group = new THREE.Group()
+        const coveredGroup =
+            PcbScene3dCopperDetailGroupBuilder.#buildCoveredGroup(
+                THREE,
+                sceneDescription,
+                topZ,
+                normalizePoint
+            )
+        const exposedGroup =
+            PcbScene3dCopperDetailGroupBuilder.#buildExposedGroup(
+                THREE,
+                sceneDescription,
+                topZ,
+                normalizePoint
+            )
+        const viaGroup = PcbScene3dCopperDetailGroupBuilder.#buildViaGroup(
+            THREE,
+            sceneDescription,
+            normalizePoint
+        )
+
+        ;[coveredGroup, exposedGroup, viaGroup]
+            .filter((child) => child.children.length)
+            .forEach((child) => group.add(child))
+
+        return group
+    }
+
+    /**
+     * Builds traces covered by solder mask.
+     * @param {any} THREE Three.js namespace.
+     * @param {object} sceneDescription Scene description.
+     * @param {number} topZ Top copper center Z.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizePoint
+     * @returns {any}
+     */
+    static #buildCoveredGroup(THREE, sceneDescription, topZ, normalizePoint) {
+        return PcbScene3dCopperFactory.buildMaskCoveredGroup(
+            THREE,
+            PcbScene3dCopperDetailFilter.resolveCoveredByMask(sceneDescription),
+            topZ,
+            -topZ,
+            normalizePoint,
+            {
+                solderMaskColor:
+                    PcbScene3dBoardMaterialPalette.resolveSurfaceColor(
+                        sceneDescription?.board,
+                        {
+                            hasBoardAssemblyModel: Boolean(
+                                sceneDescription?.boardAssemblyModel
+                            )
+                        }
+                    )
+            }
+        )
+    }
+
+    /**
+     * Builds exposed copper detail.
+     * @param {any} THREE Three.js namespace.
+     * @param {object} sceneDescription Scene description.
+     * @param {number} topZ Top copper center Z.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizePoint
+     * @returns {any}
+     */
+    static #buildExposedGroup(THREE, sceneDescription, topZ, normalizePoint) {
+        return PcbScene3dCopperFactory.buildGroup(
+            THREE,
+            PcbScene3dCopperDetailFilter.resolve(sceneDescription),
+            topZ,
+            -topZ,
+            normalizePoint,
+            { coordinateSystem: sceneDescription?.coordinateSystem }
+        )
+    }
+
+    /**
+     * Builds exposed via and through-hole barrel detail.
+     * @param {any} THREE Three.js namespace.
+     * @param {object} sceneDescription Scene description.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizePoint
+     * @returns {any}
+     */
+    static #buildViaGroup(THREE, sceneDescription, normalizePoint) {
+        if (
+            !PcbScene3dCopperDetailFilter.shouldRenderStandaloneVias(
+                sceneDescription
+            )
+        ) {
+            return new THREE.Group()
+        }
+
+        return PcbScene3dViaFactory.buildGroup(
+            THREE,
+            PcbScene3dCopperDetailFilter.resolveStandaloneVias(
+                sceneDescription
+            ),
+            sceneDescription?.board?.thicknessMil,
+            normalizePoint
+        )
+    }
+}