pcb-scene3d-viewer 1.2.2 → 1.3.0

package/src/PcbScene3dCircuitJsonPadCorner.mjs

@@ -0,0 +1,72 @@
+import { CircuitJsonUnits } from 'circuitjson-toolkit'
+
+const RECTANGULAR_PAD_SHAPE = 2
+
+/**
+ * Normalizes CircuitJSON rounded-pad metadata for scene pad faces.
+ */
+export class PcbScene3dCircuitJsonPadCorner {
+    /**
+     * Builds rounded-rectangle metadata for one or both pad faces.
+     * @param {object} pad Pad element.
+     * @param {{ width: number, height: number }} size Pad copper size in mils.
+     * @param {boolean | null} isBottom Bottom side, or null for both sides.
+     * @returns {object}
+     */
+    static metadata(pad, size, isBottom) {
+        if (
+            !String(pad?.shape || '').endsWith('pill') &&
+            !(PcbScene3dCircuitJsonPadCorner.#radius(pad) > 0)
+        ) {
+            return {}
+        }
+        const cornerRadius =
+            PcbScene3dCircuitJsonPadCorner.#cornerRadiusPercent(pad, size)
+        const hasTop = isBottom !== true
+        const hasBottom = isBottom !== false
+        return {
+            hasRoundedRect: true,
+            roundedRectShapeTop: hasTop ? RECTANGULAR_PAD_SHAPE : null,
+            roundedRectShapeBottom: hasBottom ? RECTANGULAR_PAD_SHAPE : null,
+            cornerRadiusTop: hasTop ? cornerRadius : null,
+            cornerRadiusBottom: hasBottom ? cornerRadius : null
+        }
+    }
+
+    /**
+     * Resolves a corner radius as a percentage of the shortest pad side.
+     * @param {object} pad Pad element.
+     * @param {{ width: number, height: number }} size Pad copper size in mils.
+     * @returns {number}
+     */
+    static #cornerRadiusPercent(pad, size) {
+        const width = CircuitJsonUnits.optionalLength(pad?.width)
+        const height = CircuitJsonUnits.optionalLength(pad?.height)
+        const radius = PcbScene3dCircuitJsonPadCorner.#radius(pad)
+        if (width > 0 && height > 0 && radius > 0) {
+            return Math.min((radius / Math.min(width, height)) * 100, 50)
+        }
+
+        const shortestSide = Math.min(Number(size.width), Number(size.height))
+        const radiusMil = CircuitJsonUnits.mmToMil(radius, 0)
+        if (shortestSide > 0 && radiusMil > 0) {
+            return Math.min((radiusMil / shortestSide) * 100, 50)
+        }
+
+        return 50
+    }
+
+    /**
+     * Resolves canonical and compatibility corner-radius fields.
+     * @param {object} pad Pad element.
+     * @returns {number}
+     */
+    static #radius(pad) {
+        return CircuitJsonUnits.optionalLength(
+            pad?.radius ??
+                pad?.corner_radius ??
+                pad?.rect_border_radius ??
+                pad?.cornerRadius
+        )
+    }
+}

package/src/PcbScene3dCircuitJsonSilkscreenBuilder.mjs

@@ -1,6 +1,7 @@
 import { CircuitJsonUnits } from 'circuitjson-toolkit'
 import { PcbScene3dCircuitJsonLayer } from './PcbScene3dCircuitJsonLayer.mjs'
 import { PcbScene3dCircuitJsonDocumentationArtworkBuilder } from './PcbScene3dCircuitJsonDocumentationArtworkBuilder.mjs'
+import { PcbScene3dCircuitJsonSourceLayer } from './PcbScene3dCircuitJsonSourceLayer.mjs'
 
 const CURVE_SEGMENTS = 32
 const CAP_SEGMENTS = 16
@@ -21,6 +22,12 @@ export class PcbScene3dCircuitJsonSilkscreenBuilder {
 
         PcbScene3dCircuitJsonSilkscreenBuilder.#appendLines(index, top, bottom)
         PcbScene3dCircuitJsonSilkscreenBuilder.#appendPaths(index, top, bottom)
+        PcbScene3dCircuitJsonDocumentationArtworkBuilder.append(
+            index,
+            top,
+            bottom,
+            { sourceLayerFilter: 'silkscreen' }
+        )
         PcbScene3dCircuitJsonSilkscreenBuilder.#appendCircles(
             index,
             top,
@@ -36,18 +43,32 @@ export class PcbScene3dCircuitJsonSilkscreenBuilder {
             top,
             bottom
         )
+        PcbScene3dCircuitJsonSilkscreenBuilder.#appendTexts(
+            (index.elementsByType.get('pcb_note_text') || []).filter(
+                PcbScene3dCircuitJsonSourceLayer.isSilkscreen
+            ),
+            top,
+            bottom
+        )
         if (options?.showPcbNotes === true) {
             PcbScene3dCircuitJsonDocumentationArtworkBuilder.append(
                 index,
                 top,
-                bottom
+                bottom,
+                { sourceLayerFilter: 'non-silkscreen' }
             )
             PcbScene3dCircuitJsonSilkscreenBuilder.#appendTexts(
                 [
                     ...(index.elementsByType.get('pcb_note_text') || []),
                     ...(index.elementsByType.get('pcb_fabrication_note_text') ||
                         [])
-                ],
+                ].filter(
+                    (text) =>
+                        !PcbScene3dCircuitJsonSourceLayer.isSilkscreen(text) &&
+                        !PcbScene3dCircuitJsonSourceLayer.isCopperOrSolderMask(
+                            text
+                        )
+                ),
                 top,
                 bottom
             )
@@ -92,34 +113,107 @@ export class PcbScene3dCircuitJsonSilkscreenBuilder {
      */
     static #appendPaths(index, top, bottom) {
         ;(index.elementsByType.get('pcb_silkscreen_path') || []).forEach(
-            (path) => {
+            (path, pathIndex) => {
                 const target =
                     PcbScene3dCircuitJsonSilkscreenBuilder.#sideDetail(
                         path?.layer,
                         top,
                         bottom
                     )
-                const route = PcbScene3dCircuitJsonSilkscreenBuilder.#array(
-                    path?.route
+                PcbScene3dCircuitJsonSilkscreenBuilder.#appendPath(
+                    target,
+                    path,
+                    PcbScene3dCircuitJsonSilkscreenBuilder.#sourceId(
+                        path,
+                        ['pcb_silkscreen_path_id', 'silkscreen_path_id'],
+                        'pcb_silkscreen_path',
+                        pathIndex
+                    )
                 )
-                for (let index = 0; index < route.length - 1; index += 1) {
-                    const start = route[index]
-                    const end = route[index + 1]
-                    target.tracks.push({
-                        x1: CircuitJsonUnits.mmToMil(start?.x, 0),
-                        y1: CircuitJsonUnits.mmToMil(start?.y, 0),
-                        x2: CircuitJsonUnits.mmToMil(end?.x, 0),
-                        y2: CircuitJsonUnits.mmToMil(end?.y, 0),
-                        width: CircuitJsonUnits.mmToMil(
-                            path?.stroke_width,
-                            0.12
-                        )
-                    })
-                }
             }
         )
     }
 
+    /**
+     * Appends one filled polygon or stroke path to a side detail container.
+     * @param {object} target Side-specific silkscreen detail.
+     * @param {object} path CircuitJSON path element.
+     * @param {string} sourceId Stable source ID.
+     * @returns {void}
+     */
+    static #appendPath(target, path, sourceId) {
+        const points = PcbScene3dCircuitJsonSilkscreenBuilder.#pathPoints(path)
+        if (points.length < 2) {
+            return
+        }
+
+        const fillPoints =
+            PcbScene3dCircuitJsonSilkscreenBuilder.#distinctPathPoints(points)
+        if (path?.fill === true && fillPoints.length >= 3) {
+            target.fills.push({
+                sourceId,
+                points: fillPoints
+            })
+            return
+        }
+
+        const width =
+            PcbScene3dCircuitJsonSilkscreenBuilder.#pathStrokeWidth(path)
+        for (let index = 0; index < points.length - 1; index += 1) {
+            const start = points[index]
+            const end = points[index + 1]
+            target.tracks.push({
+                sourceId,
+                x1: start.x,
+                y1: start.y,
+                x2: end.x,
+                y2: end.y,
+                width
+            })
+        }
+    }
+
+    /**
+     * Converts one path route into valid millimeter-to-mil points.
+     * @param {object} path CircuitJSON path element.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #pathPoints(path) {
+        return PcbScene3dCircuitJsonSilkscreenBuilder.#array(
+            path?.route || path?.points
+        )
+            .map((point) =>
+                PcbScene3dCircuitJsonSilkscreenBuilder.#point(point)
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Removes a duplicate closing point from one polygon route.
+     * @param {{ x: number, y: number }[]} points Route points.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #distinctPathPoints(points) {
+        if (points.length < 2) return points
+        const first = points[0]
+        const last = points[points.length - 1]
+        return first.x === last.x && first.y === last.y
+            ? points.slice(0, -1)
+            : points
+    }
+
+    /**
+     * Resolves a positive stroke width with the standard silkscreen fallback.
+     * @param {object} path CircuitJSON path element.
+     * @returns {number}
+     */
+    static #pathStrokeWidth(path) {
+        const width = Number(path?.stroke_width ?? path?.strokeWidth)
+        return Number.isFinite(width) && width > 0
+            ? CircuitJsonUnits.mmToMil(width, 0)
+            : CircuitJsonUnits.mmToMil(0.12, 0)
+    }
+
     /**
      * Appends circular silkscreen strokes as full-circle arcs.
      * @param {{ elementsByType: Map<string, object[]> }} index CircuitJSON index.
@@ -246,6 +340,7 @@ export class PcbScene3dCircuitJsonSilkscreenBuilder {
      */
     static #appendTexts(texts, top, bottom) {
         texts.forEach((text) => {
+            if (text?.is_hidden === true || text?.isHidden === true) return
             const target = PcbScene3dCircuitJsonSilkscreenBuilder.#sideDetail(
                 text?.layer,
                 top,
@@ -265,8 +360,22 @@ export class PcbScene3dCircuitJsonSilkscreenBuilder {
     static #textPrimitive(text) {
         const position =
             PcbScene3dCircuitJsonSilkscreenBuilder.#textPosition(text)
-        const size = CircuitJsonUnits.mmToMil(
-            text?.font_size ?? text?.fontSize ?? text?.height ?? text?.size,
+        const sizeX = CircuitJsonUnits.mmToMil(
+            text?.font_width ??
+                text?.fontWidth ??
+                text?.font_size ??
+                text?.fontSize ??
+                text?.height ??
+                text?.size,
+            1
+        )
+        const sizeY = CircuitJsonUnits.mmToMil(
+            text?.font_height ??
+                text?.fontHeight ??
+                text?.font_size ??
+                text?.fontSize ??
+                text?.height ??
+                text?.size,
             1
         )
         const strokeWidth = CircuitJsonUnits.mmToMil(
@@ -283,13 +392,17 @@ export class PcbScene3dCircuitJsonSilkscreenBuilder {
             x: position.x,
             y: position.y,
             rotation: Number(text?.ccw_rotation ?? text?.rotation ?? 0),
-            sizeX: size,
-            sizeY: size,
+            sizeX,
+            sizeY,
             width: strokeWidth,
             strokeWidth,
             thickness: strokeWidth,
             hAlign: alignment.hAlign,
-            vAlign: alignment.vAlign
+            vAlign: alignment.vAlign,
+            mirrored:
+                text?.is_mirrored === true ||
+                text?.is_mirrored_from_top_view === true ||
+                text?.mirrored === true
         }
     }
 
@@ -315,7 +428,9 @@ export class PcbScene3dCircuitJsonSilkscreenBuilder {
      * @returns {{ hAlign: 'left' | 'center' | 'right', vAlign: 'top' | 'center' | 'bottom' }}
      */
     static #textAlignment(text) {
-        const value = String(text?.anchor_alignment || '')
+        const value = String(
+            text?.source_anchor_alignment || text?.anchor_alignment || ''
+        )
             .trim()
             .toLowerCase()
             .replaceAll('-', '_')

package/src/PcbScene3dCircuitJsonSilkscreenDetailBuilder.mjs

@@ -0,0 +1,21 @@
+import { PcbScene3dCircuitJsonSilkscreenBuilder } from './PcbScene3dCircuitJsonSilkscreenBuilder.mjs'
+import { PcbScene3dSilkscreenCopperCutoutBuilder } from './PcbScene3dSilkscreenCopperCutoutBuilder.mjs'
+
+/**
+ * Builds complete CircuitJSON silkscreen detail with surface keepouts.
+ */
+export class PcbScene3dCircuitJsonSilkscreenDetailBuilder {
+    /**
+     * Builds and clips side-specific silkscreen detail.
+     * @param {{ elementsByType: Map<string, object[]> }} index CircuitJSON index.
+     * @param {{ pads?: object[], vias?: object[], tracks?: object[], fills?: object[], polygons?: object[], copperTexts?: object[] }} detail Scene detail.
+     * @param {{ showPcbNotes?: boolean }} [options] Builder options.
+     * @returns {{ top: object, bottom: object }}
+     */
+    static build(index, detail, options = {}) {
+        return PcbScene3dSilkscreenCopperCutoutBuilder.apply(
+            PcbScene3dCircuitJsonSilkscreenBuilder.build(index, options),
+            detail
+        )
+    }
+}

package/src/PcbScene3dCircuitJsonSourceLayer.mjs

@@ -0,0 +1,124 @@
+const OUTER_COPPER_LAYER_SIDES = new Map([
+    ['f.cu', 'top'],
+    ['front copper', 'top'],
+    ['top copper', 'top'],
+    ['top layer', 'top'],
+    ['b.cu', 'bottom'],
+    ['back copper', 'bottom'],
+    ['bottom copper', 'bottom'],
+    ['bottom layer', 'bottom']
+])
+
+const SOLDER_MASK_LAYER_SIDES = new Map([
+    ['f.mask', 'top'],
+    ['front mask', 'top'],
+    ['top mask', 'top'],
+    ['front solder', 'top'],
+    ['top solder', 'top'],
+    ['front solder mask', 'top'],
+    ['top solder mask', 'top'],
+    ['b.mask', 'bottom'],
+    ['back mask', 'bottom'],
+    ['bottom mask', 'bottom'],
+    ['back solder', 'bottom'],
+    ['bottom solder', 'bottom'],
+    ['back solder mask', 'bottom'],
+    ['bottom solder mask', 'bottom']
+])
+
+/**
+ * Classifies source-layer metadata retained beside canonical CircuitJSON rows.
+ */
+export class PcbScene3dCircuitJsonSourceLayer {
+    /**
+     * Returns whether an element originated on a silkscreen layer.
+     * @param {object} element CircuitJSON element.
+     * @returns {boolean}
+     */
+    static isSilkscreen(element) {
+        return PcbScene3dCircuitJsonSourceLayer.#normalizedName(
+            element
+        ).includes('silk')
+    }
+
+    /**
+     * Resolves an outer-copper source layer to its board side.
+     * @param {object} element CircuitJSON element.
+     * @returns {'top' | 'bottom' | null}
+     */
+    static outerCopperSide(element) {
+        return (
+            OUTER_COPPER_LAYER_SIDES.get(
+                PcbScene3dCircuitJsonSourceLayer.#normalizedName(element)
+            ) || null
+        )
+    }
+
+    /**
+     * Returns whether an element originated on an outer copper layer.
+     * @param {object} element CircuitJSON element.
+     * @returns {boolean}
+     */
+    static isOuterCopper(element) {
+        return (
+            PcbScene3dCircuitJsonSourceLayer.outerCopperSide(element) !== null
+        )
+    }
+
+    /**
+     * Resolves a solder-mask source layer to its board side.
+     * @param {object} element CircuitJSON element.
+     * @returns {'top' | 'bottom' | null}
+     */
+    static solderMaskSide(element) {
+        return (
+            SOLDER_MASK_LAYER_SIDES.get(
+                PcbScene3dCircuitJsonSourceLayer.#normalizedName(element)
+            ) || null
+        )
+    }
+
+    /**
+     * Returns whether an element originated on a solder-mask layer.
+     * @param {object} element CircuitJSON element.
+     * @returns {boolean}
+     */
+    static isSolderMask(element) {
+        return PcbScene3dCircuitJsonSourceLayer.solderMaskSide(element) !== null
+    }
+
+    /**
+     * Returns whether an element belongs to copper or its mask aperture data.
+     * @param {object} element CircuitJSON element.
+     * @returns {boolean}
+     */
+    static isCopperOrSolderMask(element) {
+        return (
+            PcbScene3dCircuitJsonSourceLayer.isOuterCopper(element) ||
+            PcbScene3dCircuitJsonSourceLayer.isSolderMask(element)
+        )
+    }
+
+    /**
+     * Resolves a normalized source-layer name from one CircuitJSON element.
+     * @param {object} element CircuitJSON element.
+     * @returns {string}
+     */
+    static #normalizedName(element) {
+        return PcbScene3dCircuitJsonSourceLayer.#name(
+            element?.source_layer ?? element?.sourceLayer
+        ).toLowerCase()
+    }
+
+    /**
+     * Resolves a string layer name from scalar or object metadata.
+     * @param {unknown} layer Source-layer metadata.
+     * @returns {string}
+     */
+    static #name(layer) {
+        if (layer && typeof layer === 'object') {
+            return String(layer.name ?? layer.layer ?? '').trim()
+        }
+        return String(layer ?? '').trim()
+    }
+}

package/src/PcbScene3dCircuitJsonTraceRouteBuilder.mjs

@@ -1,5 +1,6 @@
 import { CircuitJsonUnits } from 'circuitjson-toolkit'
 import { PcbScene3dCircuitJsonLayer } from './PcbScene3dCircuitJsonLayer.mjs'
+import { PcbScene3dViaLayerSpan } from './PcbScene3dViaLayerSpan.mjs'
 
 /**
  * Converts CircuitJSON trace routes into scene copper tracks and vias.
@@ -114,7 +115,8 @@ export class PcbScene3dCircuitJsonTraceRouteBuilder {
                     0
                 ),
                 isTentingTop: isTented,
-                isTentingBottom: isTented
+                isTentingBottom: isTented,
+                ...PcbScene3dViaLayerSpan.fields(via)
             }
         })
     }
@@ -172,7 +174,8 @@ export class PcbScene3dCircuitJsonTraceRouteBuilder {
             diameter,
             holeDiameter,
             isTentingTop: isTented,
-            isTentingBottom: isTented
+            isTentingBottom: isTented,
+            ...PcbScene3dViaLayerSpan.fields(via)
         }
     }
 
@@ -290,11 +293,7 @@ export class PcbScene3dCircuitJsonTraceRouteBuilder {
      * @returns {boolean}
      */
     static #touchesSurface(via) {
-        return Boolean(
-            PcbScene3dCircuitJsonLayer.surfaceSide(via?.from_layer) ||
-            PcbScene3dCircuitJsonLayer.surfaceSide(via?.to_layer) ||
-            PcbScene3dCircuitJsonLayer.surfaceSide(via?.layer)
-        )
+        return PcbScene3dViaLayerSpan.surfaceSides(via).length > 0
     }
 
     /**

package/src/PcbScene3dCopperDetailFilter.mjs

@@ -93,7 +93,11 @@ export class PcbScene3dCopperDetailFilter {
                 detail.polygons,
                 defaultCovered
             ),
-            copperTexts: [],
+            copperTexts:
+                PcbScene3dCopperDetailFilter.#filterMaskCoveredPrimitives(
+                    detail.copperTexts,
+                    defaultCovered
+                ),
             vias: []
         }
     }

package/src/PcbScene3dCopperFactory.mjs

@@ -100,7 +100,7 @@ export class PcbScene3dCopperFactory {
     /**
      * Builds top and bottom copper detail that is covered by solder mask.
      * @param {any} THREE
-     * @param {{ tracks?: any[], arcs?: any[], fills?: any[], polygons?: any[] }} detail Mask-covered detail.
+     * @param {{ tracks?: any[], arcs?: any[], fills?: any[], polygons?: any[], copperTexts?: any[] }} detail Mask-covered detail.
      * @param {number} topZ
      * @param {number} bottomZ
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
@@ -146,7 +146,8 @@ export class PcbScene3dCopperFactory {
                 fills: PcbScene3dCopperLayerFilter.fills(
                     [...(detail?.fills || []), ...(detail?.polygons || [])],
                     'top'
-                )
+                ),
+                copperTexts: detail?.copperTexts || []
             },
             Math.abs(Number(topZ || 0)),
             normalizeBoardPoint,
@@ -166,7 +167,8 @@ export class PcbScene3dCopperFactory {
                 fills: PcbScene3dCopperLayerFilter.fills(
                     [...(detail?.fills || []), ...(detail?.polygons || [])],
                     'bottom'
-                )
+                ),
+                copperTexts: detail?.copperTexts || []
             },
             Math.abs(Number(bottomZ || 0)),
             normalizeBoardPoint,
@@ -267,7 +269,7 @@ export class PcbScene3dCopperFactory {
     /**
      * Builds one side of the mask-covered copper relief.
      * @param {any} THREE
-     * @param {{ tracks?: any[], arcs?: any[], fills?: any[] }} detail Mask-covered detail.
+     * @param {{ tracks?: any[], arcs?: any[], fills?: any[], copperTexts?: any[] }} detail Mask-covered detail.
      * @param {number} z
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
      * @param {boolean} mirrorY
@@ -353,10 +355,27 @@ export class PcbScene3dCopperFactory {
                 coverageContext
             }
         )
+        const textGroup = PcbScene3dCopperTextFactory.buildGroup(
+            THREE,
+            detail?.copperTexts || [],
+            z,
+            normalizeBoardPoint,
+            {
+                glyphYUp: PcbScene3dCopperFactory.#usesYUpGlyphs(options),
+                side: mirrorY ? 'bottom' : 'top',
+                mirrorY,
+                materialColor: PcbScene3dMaskCoveredCopperMaterial.resolveColor(
+                    options?.solderMaskColor
+                ),
+                drillCutouts: occlusionCutouts
+            }
+        )
+        const textMesh = textGroup.children[0] || null
         return PcbScene3dMaskCoveredCopperSideGroupBuilder.build(THREE, {
             trackMesh,
             arcMesh,
             fillMesh,
+            textMesh,
             z,
             mirrorY
         })