pcb-scene3d-viewer 1.2.2 → 1.3.1

package/src/PcbScene3dViaFactory.mjs

@@ -1,4 +1,5 @@
 import { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
+import { PcbScene3dViaLayerSpan } from './PcbScene3dViaLayerSpan.mjs'
 
 /**
  * Builds annular via barrels for the interactive 3D PCB scene.
@@ -7,14 +8,16 @@ export class PcbScene3dViaFactory {
     static #PAD_BARREL_OUTER_RADIUS_SCALE = 0.98
     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.
      * @param {any} THREE
-     * @param {{ diameter?: number, holeDiameter?: number, x?: number, y?: number, barrelOnly?: boolean }[]} vias
+     * @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(
@@ -25,26 +28,48 @@ 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)
+            if (!renderMode) return
+
             const geometry = PcbScene3dViaFactory.#resolveGeometry(
                 THREE,
                 geometryCache,
                 via,
-                thicknessMil
+                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)
             )
-            mesh.position.set(point.x, point.y, 0)
+            mesh.position.set(
+                point.x,
+                point.y,
+                PcbScene3dViaFactory.#centerZ(renderMode, thicknessMil)
+            )
             if (geometry.type === 'CylinderGeometry') {
                 mesh.rotation.x = Math.PI / 2
             }
             group.add(mesh)
+            PcbScene3dViaFactory.#appendMaskSurfaceMeshes(
+                THREE,
+                group,
+                surfaceGeometryCache,
+                via,
+                renderMode,
+                thicknessMil,
+                point,
+                options?.surfaceMaterial
+            )
         })
 
         return group
@@ -68,18 +93,152 @@ 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
      * @param {Map<string, any>} geometryCache
      * @param {{ diameter?: number, holeDiameter?: number, barrelOnly?: boolean }} via
      * @param {number} thicknessMil
+     * @param {'through' | 'top' | 'bottom'} renderMode Via geometry mode.
      * @returns {any}
      */
-    static #resolveGeometry(THREE, geometryCache, via, thicknessMil) {
+    static #resolveGeometry(
+        THREE,
+        geometryCache,
+        via,
+        thicknessMil,
+        renderMode
+    ) {
         const outerRadius = Math.max(Number(via?.diameter || 0) / 2, 1.2)
         const holeDiameter = Math.max(Number(via?.holeDiameter || 0), 0)
-        const depth = thicknessMil + 2
+        const depth = PcbScene3dViaFactory.#geometryDepth(
+            renderMode,
+            thicknessMil
+        )
         const isBarrelOnly = Boolean(via?.barrelOnly)
         const cacheKey = [
             isBarrelOnly ? 'barrel' : 'annulus',
@@ -131,6 +290,32 @@ export class PcbScene3dViaFactory {
         return geometry
     }
 
+    /**
+     * Resolves copper geometry depth without extending blind vias through-board.
+     * @param {'through' | 'top' | 'bottom'} renderMode Via geometry mode.
+     * @param {number} thicknessMil Board thickness in mil.
+     * @returns {number}
+     */
+    static #geometryDepth(renderMode, thicknessMil) {
+        if (renderMode !== 'through') {
+            return PcbScene3dViaFactory.#SURFACE_COPPER_DEPTH_MIL
+        }
+        return Math.max(Number(thicknessMil) || 0, 0) + 2
+    }
+
+    /**
+     * Resolves the world-space Z center for one via geometry mode.
+     * @param {'through' | 'top' | 'bottom'} renderMode Via geometry mode.
+     * @param {number} thicknessMil Board thickness in mil.
+     * @returns {number}
+     */
+    static #centerZ(renderMode, thicknessMil) {
+        const halfThickness = Math.max(Number(thicknessMil) || 0, 0) / 2
+        if (renderMode === 'top') return halfThickness
+        if (renderMode === 'bottom') return -halfThickness
+        return 0
+    }
+
     /**
      * Builds a visible copper sleeve for through-hole pads.
      * @param {any} THREE

package/src/PcbScene3dViaLayerSpan.mjs

@@ -0,0 +1,126 @@
+import { PcbScene3dCircuitJsonLayer } from './PcbScene3dCircuitJsonLayer.mjs'
+
+/**
+ * Resolves authored via layer spans for surface-aware scene geometry.
+ */
+export class PcbScene3dViaLayerSpan {
+    /**
+     * Preserves an authored span in normalized scene-detail fields.
+     * Explicit layer lists take precedence over legacy default endpoints.
+     * @param {object} via CircuitJSON via or normalized scene via.
+     * @returns {{ layers: unknown[], fromLayer: unknown | null, toLayer: unknown | null }}
+     */
+    static fields(via) {
+        const span = PcbScene3dViaLayerSpan.#resolve(via)
+        return {
+            layers: span.layers,
+            fromLayer: span.fromLayer,
+            toLayer: span.toLayer
+        }
+    }
+
+    /**
+     * Resolves the outer board faces reached by one via.
+     * @param {object} via CircuitJSON via or normalized scene via.
+     * @returns {('top' | 'bottom')[]}
+     */
+    static surfaceSides(via) {
+        const sides = PcbScene3dViaLayerSpan.#resolve(via)
+            .layers.map((layer) =>
+                PcbScene3dCircuitJsonLayer.surfaceSide(layer)
+            )
+            .filter(Boolean)
+        return [...new Set(sides)]
+    }
+
+    /**
+     * Returns true when one via reaches the requested board face.
+     * Vias without authored span metadata retain legacy through-board behavior.
+     * @param {object} via CircuitJSON via or normalized scene via.
+     * @param {'top' | 'bottom'} side Board face.
+     * @returns {boolean}
+     */
+    static reachesSide(via, side) {
+        const span = PcbScene3dViaLayerSpan.#resolve(via)
+        if (!span.hasAuthoredSpan) return true
+
+        return span.layers.some(
+            (layer) => PcbScene3dCircuitJsonLayer.surfaceSide(layer) === side
+        )
+    }
+
+    /**
+     * Resolves the physical surface geometry mode for one via.
+     * Inner-only vias have no outer-surface geometry and return null.
+     * @param {object} via CircuitJSON via or normalized scene via.
+     * @returns {'through' | 'top' | 'bottom' | null}
+     */
+    static renderMode(via) {
+        const span = PcbScene3dViaLayerSpan.#resolve(via)
+        if (!span.hasAuthoredSpan) return 'through'
+
+        const sides = span.layers
+            .map((layer) => PcbScene3dCircuitJsonLayer.surfaceSide(layer))
+            .filter(Boolean)
+        const reachesTop = sides.includes('top')
+        const reachesBottom = sides.includes('bottom')
+        if (reachesTop && reachesBottom) return 'through'
+        if (reachesTop) return 'top'
+        if (reachesBottom) return 'bottom'
+        return null
+    }
+
+    /**
+     * Resolves one via span while retaining whether it was explicitly authored.
+     * @param {object} via CircuitJSON via or normalized scene via.
+     * @returns {{ layers: unknown[], fromLayer: unknown | null, toLayer: unknown | null, hasAuthoredSpan: boolean }}
+     */
+    static #resolve(via) {
+        const explicitLayers = PcbScene3dViaLayerSpan.#explicitLayers(
+            via?.layers
+        )
+        const fromLayer =
+            explicitLayers[0] ??
+            via?.fromLayer ??
+            via?.from_layer ??
+            via?.layer ??
+            null
+        const toLayer =
+            explicitLayers[explicitLayers.length - 1] ??
+            via?.toLayer ??
+            via?.to_layer ??
+            via?.layer ??
+            null
+        const layers = explicitLayers.length
+            ? [...explicitLayers]
+            : [fromLayer, toLayer].filter(
+                  (layer, index, values) =>
+                      layer !== null && values.indexOf(layer) === index
+              )
+
+        return {
+            layers,
+            fromLayer,
+            toLayer,
+            hasAuthoredSpan: layers.length > 0
+        }
+    }
+
+    /**
+     * Normalizes an explicit via layer list without interpreting layer names.
+     * @param {unknown} layers CircuitJSON layer list.
+     * @returns {unknown[]}
+     */
+    static #explicitLayers(layers) {
+        const values = Array.isArray(layers)
+            ? layers
+            : typeof layers === 'string'
+              ? layers.split(',')
+              : []
+        return values
+            .map((layer) => (typeof layer === 'string' ? layer.trim() : layer))
+            .filter(
+                (layer) => layer !== undefined && layer !== null && layer !== ''
+            )
+    }
+}