pcb-scene3d-viewer 1.3.0 → 1.3.1

package/README.md

@@ -28,6 +28,12 @@ surface-aware blind/buried vias, collision-safe model assets, and a consistent
 light FR-4 substrate edge. See the
 [1.3.0 release notes](docs/release-notes-v1.3.0.md).
 
+Version 1.3.1 renders side-specific tented Gerber vias without recoloring the
+plated drill wall. Covered surfaces receive a solder-mask ring above the copper
+annulus, mixed top/bottom states remain independent, and fully open Gerber vias
+retain the exposed-copper path. See the
+[1.3.1 release notes](docs/release-notes-v1.3.1.md).
+
 ## CircuitJSON 1.1 convergence
 
 Version 1.2.2 accepts the common document and prepared-context shapes returned
@@ -136,6 +142,7 @@ const controller = new PcbScene3dController(viewportNode, document)
 
 - [API](docs/api.md)
 - [CircuitJSON usage](docs/circuitjson.md)
+- [1.3.1 release notes](docs/release-notes-v1.3.1.md)
 - [1.2.2 release notes](docs/release-notes-v1.2.2.md)
 - [1.3.0 release notes](docs/release-notes-v1.3.0.md)
 - [1.2.1 release notes](docs/release-notes-v1.2.1.md)

package/docs/model-format.md

@@ -220,3 +220,9 @@ Rounded SMT pads set `hasRoundedRect`, the side-specific
 Route-derived vias use the same `detail.vias` shape as standalone vias, and
 surface route segments use `layerId: 1` for top copper or `layerId: 32` for
 bottom copper.
+
+Via surfaces can set `isTentingTop` and `isTentingBottom` independently. A
+truthy field adds a solder-mask ring on that board surface while the plated
+through-hole barrel remains copper. A mixed via therefore renders one covered
+annulus and one exposed annulus; a via with both fields explicitly false stays
+on the exposed-copper path. The source toolkit owns this classification.

package/docs/release-notes-v1.3.1.md

@@ -0,0 +1,23 @@
+# pcb-scene3d-viewer 1.3.1
+
+Version 1.3.1 renders source-classified via solder mask as a surface treatment
+without replacing the plated copper barrel material.
+
+## Via rendering
+
+- Gerber vias with either `isTentingTop` or `isTentingBottom` use the covered
+  via rendering path; both fields explicitly false retain the exposed path.
+- Each tented board surface receives its own solder-mask ring above the copper
+  annulus. Mixed top/bottom tenting is preserved.
+- The mask ring keeps the authored drill opening clear and leaves the plated
+  through-hole wall copper-colored.
+- Blind and buried surface reachability remains authoritative, so mask geometry
+  is added only where a via actually reaches the corresponding board surface.
+
+## Compatibility and verification
+
+- Existing CircuitJSON default-tenting and explicit-opening behavior is
+  unchanged.
+- Scene, controller, runtime, export, and package entrypoints are unchanged.
+- Tests cover fully tented, mixed, and fully open Gerber classification plus
+  copper-barrel and one-sided mask-ring material routing.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.3.0",
+    "version": "1.3.1",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -37,6 +37,7 @@
         "docs/release-notes-v1.2.1.md",
         "docs/release-notes-v1.2.2.md",
         "docs/release-notes-v1.3.0.md",
+        "docs/release-notes-v1.3.1.md",
         "docs/model-format.md",
         "docs/testing.md",
         "spec",

package/src/PcbScene3dCopperDetailFilter.mjs

@@ -266,24 +266,37 @@ export class PcbScene3dCopperDetailFilter {
      * @returns {any[]}
      */
     static #filterExposedVias(vias, sceneDescription) {
+        if (PcbScene3dCopperDetailFilter.#isGerberScene(sceneDescription)) {
+            return (vias || []).filter(
+                (via) =>
+                    via?.isTentingTop === false &&
+                    via?.isTentingBottom === false
+            )
+        }
+
         return (vias || []).filter((via) =>
             PcbScene3dCopperDetailFilter.#isViaExplicitlyOpen(via)
         )
     }
 
     /**
-     * Keeps KiCad via annuli that are covered by solder mask.
+     * Keeps KiCad and Gerber via annuli that are covered by solder mask.
      * @param {any[] | undefined} vias Via list.
      * @param {object} sceneDescription 3D scene description.
      * @returns {any[]}
      */
     static #filterMaskCoveredVias(vias, sceneDescription) {
-        if (!PcbScene3dCopperDetailFilter.#isKiCadScene(sceneDescription)) {
+        if (
+            !PcbScene3dCopperDetailFilter.#isKiCadScene(sceneDescription) &&
+            !PcbScene3dCopperDetailFilter.#isGerberScene(sceneDescription)
+        ) {
             return []
         }
 
-        return (vias || []).filter(
-            (via) => !PcbScene3dCopperDetailFilter.#isViaExplicitlyOpen(via)
+        return (vias || []).filter((via) =>
+            PcbScene3dCopperDetailFilter.#isGerberScene(sceneDescription)
+                ? PcbScene3dCopperDetailFilter.#isViaExplicitlyTented(via)
+                : !PcbScene3dCopperDetailFilter.#isViaExplicitlyOpen(via)
         )
     }
 
@@ -296,6 +309,15 @@ export class PcbScene3dCopperDetailFilter {
         return via?.isTentingTop === false || via?.isTentingBottom === false
     }
 
+    /**
+     * Checks whether one via explicitly carries mask on either board side.
+     * @param {object} via Via primitive.
+     * @returns {boolean}
+     */
+    static #isViaExplicitlyTented(via) {
+        return via?.isTentingTop === true || via?.isTentingBottom === true
+    }
+
     /**
      * Appends copper barrels for through-hole pads with copper annuli.
      * @param {any[]} vias Visible via list.
@@ -487,6 +509,19 @@ export class PcbScene3dCopperDetailFilter {
         )
     }
 
+    /**
+     * Checks whether one scene was built from Gerber fabrication artwork.
+     * @param {object} sceneDescription Scene description.
+     * @returns {boolean}
+     */
+    static #isGerberScene(sceneDescription) {
+        return (
+            String(sceneDescription?.sourceFormat || '')
+                .trim()
+                .toLowerCase() === 'gerber'
+        )
+    }
+
     /**
      * Checks whether one text primitive belongs to a solder-mask layer.
      * @param {object} text Text primitive.

package/src/PcbScene3dCopperDetailGroupBuilder.mjs

@@ -130,7 +130,7 @@ export class PcbScene3dCopperDetailGroupBuilder {
             sceneDescription?.board?.thicknessMil,
             normalizePoint,
             {
-                material: PcbScene3dMaskCoveredCopperMaterial.build(
+                surfaceMaterial: PcbScene3dMaskCoveredCopperMaterial.build(
                     THREE,
                     PcbScene3dCopperDetailGroupBuilder.#coveredCopperMaterialOptions(
                         sceneDescription

package/src/PcbScene3dViaFactory.mjs

@@ -9,6 +9,7 @@ export class PcbScene3dViaFactory {
     static #PAD_BARREL_MIN_WALL_MIL = 1.2
     static #PAD_BARREL_WALL_FRACTION = 0.09
     static #SURFACE_COPPER_DEPTH_MIL = 2
+    static #SURFACE_MASK_Z_OFFSET_MIL = 1.3
 
     /**
      * Builds the via mesh group for one scene.
@@ -16,7 +17,7 @@ export class PcbScene3dViaFactory {
      * @param {{ diameter?: number, holeDiameter?: number, x?: number, y?: number, barrelOnly?: boolean, layers?: unknown[], fromLayer?: unknown, toLayer?: unknown, from_layer?: unknown, to_layer?: unknown }[]} vias
      * @param {number} thicknessMil
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
-     * @param {{ material?: any }} [options]
+     * @param {{ material?: any, surfaceMaterial?: any }} [options]
      * @returns {any}
      */
     static buildGroup(
@@ -27,8 +28,12 @@ export class PcbScene3dViaFactory {
         options = {}
     ) {
         const group = new THREE.Group()
-        const material = PcbScene3dViaFactory.#resolveMaterial(THREE, options)
+        const copperMaterial = PcbScene3dViaFactory.#resolveMaterial(
+            THREE,
+            options
+        )
         const geometryCache = new Map()
+        const surfaceGeometryCache = new Map()
 
         ;(vias || []).forEach((via) => {
             const renderMode = PcbScene3dViaLayerSpan.renderMode(via)
@@ -41,7 +46,7 @@ export class PcbScene3dViaFactory {
                 thicknessMil,
                 renderMode
             )
-            const mesh = new THREE.Mesh(geometry, material)
+            const mesh = new THREE.Mesh(geometry, copperMaterial)
             const point = normalizeBoardPoint(
                 Number(via?.x || 0),
                 Number(via?.y || 0)
@@ -55,6 +60,16 @@ export class PcbScene3dViaFactory {
                 mesh.rotation.x = Math.PI / 2
             }
             group.add(mesh)
+            PcbScene3dViaFactory.#appendMaskSurfaceMeshes(
+                THREE,
+                group,
+                surfaceGeometryCache,
+                via,
+                renderMode,
+                thicknessMil,
+                point,
+                options?.surfaceMaterial
+            )
         })
 
         return group
@@ -78,6 +93,130 @@ export class PcbScene3dViaFactory {
         )
     }
 
+    /**
+     * Adds side-specific solder-mask rings above the copper via surface.
+     * @param {any} THREE Three.js namespace.
+     * @param {any} group Output group.
+     * @param {Map<string, any>} geometryCache Surface geometry cache.
+     * @param {object} via Via primitive.
+     * @param {'through' | 'top' | 'bottom'} renderMode Via geometry mode.
+     * @param {number} thicknessMil Board thickness in mil.
+     * @param {{ x: number, y: number }} point Normalized board point.
+     * @param {any | undefined} material Solder-mask material.
+     * @returns {void}
+     */
+    static #appendMaskSurfaceMeshes(
+        THREE,
+        group,
+        geometryCache,
+        via,
+        renderMode,
+        thicknessMil,
+        point,
+        material
+    ) {
+        if (!material) {
+            return
+        }
+
+        const geometry = PcbScene3dViaFactory.#resolveSurfaceGeometry(
+            THREE,
+            geometryCache,
+            via
+        )
+        if (!geometry) {
+            return
+        }
+
+        for (const side of ['top', 'bottom']) {
+            if (
+                !PcbScene3dViaFactory.#renderModeTouchesSide(
+                    renderMode,
+                    side
+                ) ||
+                !PcbScene3dViaFactory.#isSideTented(via, side)
+            ) {
+                continue
+            }
+
+            const mesh = new THREE.Mesh(geometry, material)
+            mesh.position.set(
+                point.x,
+                point.y,
+                PcbScene3dViaFactory.#surfaceZ(side, thicknessMil)
+            )
+            group.add(mesh)
+        }
+    }
+
+    /**
+     * Resolves one reusable annular surface geometry.
+     * @param {any} THREE Three.js namespace.
+     * @param {Map<string, any>} geometryCache Surface geometry cache.
+     * @param {object} via Via primitive.
+     * @returns {any | null}
+     */
+    static #resolveSurfaceGeometry(THREE, geometryCache, via) {
+        const diameter = Number(via?.diameter || 0)
+        const holeDiameter = Number(via?.holeDiameter || 0)
+        if (diameter <= 0 || holeDiameter < 0 || diameter <= holeDiameter) {
+            return null
+        }
+
+        const key = `${diameter.toFixed(4)}:${holeDiameter.toFixed(4)}`
+        const cached = geometryCache.get(key)
+        if (cached) {
+            return cached
+        }
+
+        const shape = PcbScene3dViaFactory.#buildCircleShape(
+            THREE,
+            diameter / 2
+        )
+        if (holeDiameter > 0) {
+            shape.holes.push(
+                PcbScene3dViaFactory.#buildCirclePath(THREE, holeDiameter / 2)
+            )
+        }
+        const geometry = new THREE.ShapeGeometry(shape, 24)
+        geometryCache.set(key, geometry)
+        return geometry
+    }
+
+    /**
+     * Checks whether one rendered via span reaches a board side.
+     * @param {'through' | 'top' | 'bottom'} renderMode Via geometry mode.
+     * @param {'top' | 'bottom'} side Board side.
+     * @returns {boolean}
+     */
+    static #renderModeTouchesSide(renderMode, side) {
+        return renderMode === 'through' || renderMode === side
+    }
+
+    /**
+     * Checks whether one via surface is tented on a board side.
+     * @param {object} via Via primitive.
+     * @param {'top' | 'bottom'} side Board side.
+     * @returns {boolean}
+     */
+    static #isSideTented(via, side) {
+        const fieldName = side === 'bottom' ? 'isTentingBottom' : 'isTentingTop'
+        return via?.[fieldName] !== false
+    }
+
+    /**
+     * Resolves the solder-mask surface Z above the exposed copper stack.
+     * @param {'top' | 'bottom'} side Board side.
+     * @param {number} thicknessMil Board thickness in mil.
+     * @returns {number}
+     */
+    static #surfaceZ(side, thicknessMil) {
+        const distance =
+            Math.max(Number(thicknessMil) || 0, 0) / 2 +
+            PcbScene3dViaFactory.#SURFACE_MASK_Z_OFFSET_MIL
+        return side === 'bottom' ? -distance : distance
+    }
+
     /**
      * Resolves one reusable via geometry from the via drill spec.
      * @param {any} THREE