pcb-scene3d-viewer 1.2.2 → 1.3.0

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,11 +8,12 @@ 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
 
     /**
      * 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]
@@ -29,18 +31,26 @@ export class PcbScene3dViaFactory {
         const geometryCache = 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 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
             }
@@ -74,12 +84,22 @@ export class PcbScene3dViaFactory {
      * @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 +151,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 !== ''
+            )
+    }
+}