pcb-scene3d-viewer 1.0.1 → 1.1.1

package/package.json

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

package/src/PcbScene3dBoardAssemblyPlacement.mjs

@@ -4,7 +4,7 @@
 export class PcbScene3dBoardAssemblyPlacement {
     /**
      * Builds the synthetic placement for a full board assembly model.
-     * @param {{ board?: { widthMil?: number, heightMil?: number, thicknessMil?: number, surfaceColor?: number }, boardAssemblyModel?: any }} sceneDescription
+     * @param {{ board?: { widthMil?: number, heightMil?: number, thicknessMil?: number, surfaceColor?: number }, boardAssemblyModel?: any, sourceFormat?: string }} sceneDescription
      * @returns {any | null}
      */
     static build(sceneDescription) {
@@ -14,6 +14,15 @@ export class PcbScene3dBoardAssemblyPlacement {
         }
 
         const board = sceneDescription?.board || {}
+        const mirrorsSourceY =
+            String(sceneDescription?.sourceFormat || '').toLowerCase() ===
+            'altium'
+        const sourceFrameScale = {
+            x: 1,
+            y: mirrorsSourceY ? -1 : 1,
+            z: 1
+        }
+
         return {
             designator: 'Board assembly',
             sourceType: 'board-assembly',
@@ -21,9 +30,12 @@ export class PcbScene3dBoardAssemblyPlacement {
             rotationDeg: 0,
             positionMil: {
                 x: -Number(board.widthMil || 0) / 2,
-                y: -Number(board.heightMil || 0) / 2,
+                y:
+                    (mirrorsSourceY ? 1 : -1) *
+                    (Number(board.heightMil || 0) / 2),
                 z: 0
             },
+            sourceFrameScale,
             board: {
                 widthMil: Number(board.widthMil || 0),
                 heightMil: Number(board.heightMil || 0),

package/src/PcbScene3dBoardAssemblyTransform.mjs

@@ -0,0 +1,180 @@
+/**
+ * Applies source-frame transforms to full-board assembly STEP geometry.
+ */
+export class PcbScene3dBoardAssemblyTransform {
+    /**
+     * Applies the source-frame transform encoded by a board assembly placement.
+     * @param {any} modelGroup Loaded board assembly group.
+     * @param {{ sourceFrameScale?: { y?: number } }} placement Placement metadata.
+     * @returns {void}
+     */
+    static apply(modelGroup, placement) {
+        if (!PcbScene3dBoardAssemblyTransform.#shouldMirrorY(placement)) {
+            return
+        }
+
+        PcbScene3dBoardAssemblyTransform.#traverseModelObjects(
+            modelGroup,
+            (object) =>
+                PcbScene3dBoardAssemblyTransform.#mirrorGeometryY(
+                    object?.geometry
+                )
+        )
+        modelGroup.userData = modelGroup.userData || {}
+        modelGroup.userData.scene3dBoardAssemblyMirroredY = true
+    }
+
+    /**
+     * Checks whether the assembly source frame needs a Y mirror.
+     * @param {{ sourceFrameScale?: { y?: number } }} placement Placement metadata.
+     * @returns {boolean}
+     */
+    static #shouldMirrorY(placement) {
+        return Number(placement?.sourceFrameScale?.y ?? 1) < 0
+    }
+
+    /**
+     * Mirrors one geometry around the source Y origin.
+     * @param {any} geometry Buffer geometry.
+     * @returns {void}
+     */
+    static #mirrorGeometryY(geometry) {
+        const position = PcbScene3dBoardAssemblyTransform.#getAttribute(
+            geometry,
+            'position'
+        )
+        if (!position?.array?.length) {
+            return
+        }
+
+        PcbScene3dBoardAssemblyTransform.#mirrorAttributeY(position)
+        const normal = PcbScene3dBoardAssemblyTransform.#getAttribute(
+            geometry,
+            'normal'
+        )
+        PcbScene3dBoardAssemblyTransform.#mirrorAttributeY(normal)
+        PcbScene3dBoardAssemblyTransform.#reverseTriangleWinding(geometry)
+        geometry.computeBoundingBox?.()
+        geometry.computeBoundingSphere?.()
+    }
+
+    /**
+     * Mirrors the Y component of a vertex-like attribute.
+     * @param {{ array?: ArrayLike<number>, itemSize?: number, needsUpdate?: boolean } | null} attribute Geometry attribute.
+     * @returns {void}
+     */
+    static #mirrorAttributeY(attribute) {
+        const itemSize = Number(attribute?.itemSize || 0)
+        if (!attribute?.array?.length || itemSize < 2) {
+            return
+        }
+
+        for (let index = 1; index < attribute.array.length; index += itemSize) {
+            attribute.array[index] = -Number(attribute.array[index] || 0)
+        }
+        attribute.needsUpdate = true
+    }
+
+    /**
+     * Reverses triangle winding after a one-axis mirror.
+     * @param {any} geometry Buffer geometry.
+     * @returns {void}
+     */
+    static #reverseTriangleWinding(geometry) {
+        const index = geometry?.index
+        const indexArray = index?.array
+        if (!indexArray?.length) {
+            PcbScene3dBoardAssemblyTransform.#reverseUnindexedWinding(geometry)
+            return
+        }
+
+        for (let offset = 0; offset + 2 < indexArray.length; offset += 3) {
+            const next = indexArray[offset + 1]
+            indexArray[offset + 1] = indexArray[offset + 2]
+            indexArray[offset + 2] = next
+        }
+        index.needsUpdate = true
+    }
+
+    /**
+     * Reverses unindexed triangle winding across all geometry attributes.
+     * @param {any} geometry Buffer geometry.
+     * @returns {void}
+     */
+    static #reverseUnindexedWinding(geometry) {
+        Object.values(geometry?.attributes || {}).forEach((attribute) =>
+            PcbScene3dBoardAssemblyTransform.#swapTriangleVertices(
+                attribute,
+                1,
+                2
+            )
+        )
+    }
+
+    /**
+     * Swaps two vertices inside each unindexed triangle for one attribute.
+     * @param {{ array?: ArrayLike<number>, itemSize?: number, needsUpdate?: boolean }} attribute Geometry attribute.
+     * @param {number} leftVertex First vertex offset inside the triangle.
+     * @param {number} rightVertex Second vertex offset inside the triangle.
+     * @returns {void}
+     */
+    static #swapTriangleVertices(attribute, leftVertex, rightVertex) {
+        const itemSize = Number(attribute?.itemSize || 0)
+        const array = attribute?.array
+        if (!array?.length || itemSize <= 0) {
+            return
+        }
+
+        for (
+            let offset = 0;
+            offset + itemSize * 3 <= array.length;
+            offset += itemSize * 3
+        ) {
+            for (let item = 0; item < itemSize; item += 1) {
+                const left = offset + leftVertex * itemSize + item
+                const right = offset + rightVertex * itemSize + item
+                const value = array[left]
+                array[left] = array[right]
+                array[right] = value
+            }
+        }
+        attribute.needsUpdate = true
+    }
+
+    /**
+     * Returns a geometry attribute across Three.js-compatible shapes.
+     * @param {any} geometry Buffer geometry.
+     * @param {string} name Attribute name.
+     * @returns {any}
+     */
+    static #getAttribute(geometry, name) {
+        return typeof geometry?.getAttribute === 'function'
+            ? geometry.getAttribute(name)
+            : geometry?.attributes?.[name]
+    }
+
+    /**
+     * Traverses model objects.
+     * @param {any} root Root object.
+     * @param {(object: any) => void} visitor Visitor callback.
+     * @returns {void}
+     */
+    static #traverseModelObjects(root, visitor) {
+        if (!root) {
+            return
+        }
+
+        if (typeof root.traverse === 'function') {
+            root.traverse(visitor)
+            return
+        }
+
+        visitor(root)
+        ;(Array.isArray(root.children) ? root.children : []).forEach((child) =>
+            PcbScene3dBoardAssemblyTransform.#traverseModelObjects(
+                child,
+                visitor
+            )
+        )
+    }
+}

package/src/PcbScene3dBoardEdgeCutoutBuilder.mjs

@@ -1,3 +1,5 @@
+import { PcbScene3dCutoutCircleDetector } from './PcbScene3dCutoutCircleDetector.mjs'
+
 /**
  * Builds rounded outer-contour notches for drills that intersect board edges.
  */
@@ -5,6 +7,7 @@ export class PcbScene3dBoardEdgeCutoutBuilder {
     static #OUTER_SAMPLE_POINTS = 160
     static #EDGE_CUTOUT_SAMPLE_POINTS = 72
     static #GEOMETRY_EPSILON = 0.001
+    static #CONTOUR_CACHE = new WeakMap()
 
     /**
      * Resolves sampled points from one shape outline.
@@ -98,18 +101,128 @@ export class PcbScene3dBoardEdgeCutoutBuilder {
      * @returns {boolean}
      */
     static isHoleInsideContour(hole, contour) {
-        return (
-            Array.isArray(hole) &&
-            Array.isArray(contour) &&
-            hole.length >= 3 &&
-            contour.length >= 3 &&
-            hole.every((point) =>
-                PcbScene3dBoardEdgeCutoutBuilder.#isPointStrictlyInsidePolygon(
-                    point,
-                    contour
-                )
+        if (
+            !Array.isArray(hole) ||
+            !Array.isArray(contour) ||
+            hole.length < 3 ||
+            contour.length < 3
+        ) {
+            return false
+        }
+
+        const circularHole = PcbScene3dCutoutCircleDetector.resolve(
+            hole,
+            PcbScene3dBoardEdgeCutoutBuilder.#GEOMETRY_EPSILON
+        )
+        if (circularHole) {
+            return PcbScene3dBoardEdgeCutoutBuilder.#isCircularHoleInsideContour(
+                circularHole,
+                contour
+            )
+        }
+
+        return hole.every((point) =>
+            PcbScene3dBoardEdgeCutoutBuilder.#isPointStrictlyInsidePolygon(
+                point,
+                contour
+            )
+        )
+    }
+
+    /**
+     * Returns true when a circular hole lies fully inside a contour.
+     * @param {{ centerX: number, centerY: number, radius: number }} hole
+     * @param {{ x: number, y: number }[]} contour
+     * @returns {boolean}
+     */
+    static #isCircularHoleInsideContour(hole, contour) {
+        const center = { x: hole.centerX, y: hole.centerY }
+        if (
+            !PcbScene3dBoardEdgeCutoutBuilder.#isPointStrictlyInsidePolygon(
+                center,
+                contour
+            )
+        ) {
+            return false
+        }
+
+        const preparedContour =
+            PcbScene3dBoardEdgeCutoutBuilder.#resolvePreparedContour(contour)
+        const radius =
+            Number(hole.radius || 0) +
+            PcbScene3dBoardEdgeCutoutBuilder.#GEOMETRY_EPSILON
+        const radiusSquared = radius * radius
+
+        return preparedContour.segments.every(
+            (segment) =>
+                PcbScene3dBoardEdgeCutoutBuilder.#distanceSquaredToSegment(
+                    center,
+                    segment
+                ) > radiusSquared
+        )
+    }
+
+    /**
+     * Resolves cached contour segment metadata.
+     * @param {{ x: number, y: number }[]} contour
+     * @returns {{ segments: { start: { x: number, y: number }, dx: number, dy: number, lengthSquared: number }[] }}
+     */
+    static #resolvePreparedContour(contour) {
+        const cached =
+            PcbScene3dBoardEdgeCutoutBuilder.#CONTOUR_CACHE.get(contour)
+        if (cached) {
+            return cached
+        }
+
+        const prepared = {
+            segments: contour.map((start, index) => {
+                const end = contour[(index + 1) % contour.length]
+                const dx = end.x - start.x
+                const dy = end.y - start.y
+
+                return {
+                    start,
+                    dx,
+                    dy,
+                    lengthSquared: dx * dx + dy * dy
+                }
+            })
+        }
+        PcbScene3dBoardEdgeCutoutBuilder.#CONTOUR_CACHE.set(contour, prepared)
+        return prepared
+    }
+
+    /**
+     * Resolves squared distance from a point to a segment.
+     * @param {{ x: number, y: number }} point
+     * @param {{ start: { x: number, y: number }, dx: number, dy: number, lengthSquared: number }} segment
+     * @returns {number}
+     */
+    static #distanceSquaredToSegment(point, segment) {
+        if (
+            segment.lengthSquared <=
+            PcbScene3dBoardEdgeCutoutBuilder.#GEOMETRY_EPSILON
+        ) {
+            const dx = point.x - segment.start.x
+            const dy = point.y - segment.start.y
+            return dx * dx + dy * dy
+        }
+
+        const t = Math.max(
+            0,
+            Math.min(
+                1,
+                ((point.x - segment.start.x) * segment.dx +
+                    (point.y - segment.start.y) * segment.dy) /
+                    segment.lengthSquared
             )
         )
+        const closestX = segment.start.x + segment.dx * t
+        const closestY = segment.start.y + segment.dy * t
+        const dx = point.x - closestX
+        const dy = point.y - closestY
+
+        return dx * dx + dy * dy
     }
 
     /**

package/src/PcbScene3dBoardShapeFactory.mjs

@@ -6,7 +6,7 @@ import { PcbScene3dOutlineBuilder } from './PcbScene3dOutlineBuilder.mjs'
  * Builds the board solid profile, including drilled holes.
  */
 export class PcbScene3dBoardShapeFactory {
-    static #CURVE_SEGMENTS = 20
+    static #CURVE_SEGMENTS = 8
     static #PAD_HOLE_SHAPE_SLOT = 2
     static #PLATED_WALL_MATERIAL_INDEX = 2
     static #EDGE_WALL_MATERIAL_INDEX = 1
@@ -322,16 +322,32 @@ export class PcbScene3dBoardShapeFactory {
      * @param {any} THREE
      * @param {{ pads?: any[], vias?: any[] }} detail
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
-     * @returns {{ points: { x: number, y: number }[], segments: { start: { x: number, y: number }, end: { x: number, y: number }, dx: number, dy: number, lengthSquared: number, bounds: { minX: number, maxX: number, minY: number, maxY: number } }[], bounds: { minX: number, maxX: number, minY: number, maxY: number } }[]}
+     * @returns {{ points: { x: number, y: number }[], segments: { start: { x: number, y: number }, end: { x: number, y: number }, dx: number, dy: number, lengthSquared: number, bounds: { minX: number, maxX: number, minY: number, maxY: number } }[], bounds: { minX: number, maxX: number, minY: number, maxY: number }, isCircular?: boolean, centerX?: number, centerY?: number, radius?: number }[]}
      */
     static #resolvePlatedContours(THREE, detail, normalizeBoardPoint) {
         return PcbScene3dBoardShapeFactory.#resolvePlatedDrillSpecs(detail)
             .map((drillSpec) => {
                 const point = normalizeBoardPoint(drillSpec.x, drillSpec.y)
-                const path = PcbScene3dDrillPathFactory.buildDrillPath(THREE, {
+                const normalizedSpec = {
                     ...drillSpec,
                     x: point.x,
                     y: point.y
+                }
+
+                if (
+                    PcbScene3dBoardShapeFactory.#isCircularDrillSpec(
+                        normalizedSpec
+                    )
+                ) {
+                    return PcbScene3dBoardShapeFactory.#buildCircularContour(
+                        Number(normalizedSpec.x || 0),
+                        Number(normalizedSpec.y || 0),
+                        Number(normalizedSpec.diameter || 0) / 2
+                    )
+                }
+
+                const path = PcbScene3dDrillPathFactory.buildDrillPath(THREE, {
+                    ...normalizedSpec
                 })
                 const points =
                     path?.getPoints?.(
@@ -342,6 +358,51 @@ export class PcbScene3dBoardShapeFactory {
             .filter(Boolean)
     }
 
+    /**
+     * Returns true when a drill aperture can be matched as a circle.
+     * @param {{ diameter?: number, slotLength?: number | null }} drillSpec
+     * @returns {boolean}
+     */
+    static #isCircularDrillSpec(drillSpec) {
+        const diameter = Number(drillSpec?.diameter || 0)
+        const slotLength = Number(drillSpec?.slotLength || 0)
+
+        return diameter > 0 && slotLength <= diameter + 0.001
+    }
+
+    /**
+     * Builds a contour descriptor for circular plated holes.
+     * @param {number} centerX
+     * @param {number} centerY
+     * @param {number} radius
+     * @returns {{ points: { x: number, y: number }[], segments: any[], bounds: { minX: number, maxX: number, minY: number, maxY: number }, isCircular: boolean, centerX: number, centerY: number, radius: number } | null}
+     */
+    static #buildCircularContour(centerX, centerY, radius) {
+        if (
+            !Number.isFinite(centerX) ||
+            !Number.isFinite(centerY) ||
+            !Number.isFinite(radius) ||
+            radius <= 0
+        ) {
+            return null
+        }
+
+        return {
+            points: [],
+            segments: [],
+            bounds: {
+                minX: centerX - radius,
+                maxX: centerX + radius,
+                minY: centerY - radius,
+                maxY: centerY + radius
+            },
+            isCircular: true,
+            centerX,
+            centerY,
+            radius
+        }
+    }
+
     /**
      * Resolves deduped drill specs that represent plated holes.
      * @param {{ pads?: any[], vias?: any[] }} detail
@@ -707,7 +768,7 @@ export class PcbScene3dBoardShapeFactory {
     /**
      * Returns true when all triangle vertices lie on one drill contour.
      * @param {{ x: number, y: number }[]} points
-     * @param {{ points: { x: number, y: number }[], segments: { start: { x: number, y: number }, end: { x: number, y: number }, dx: number, dy: number, lengthSquared: number, bounds: { minX: number, maxX: number, minY: number, maxY: number } }[], bounds: { minX: number, maxX: number, minY: number, maxY: number } }} contour
+     * @param {{ points: { x: number, y: number }[], segments: { start: { x: number, y: number }, end: { x: number, y: number }, dx: number, dy: number, lengthSquared: number, bounds: { minX: number, maxX: number, minY: number, maxY: number } }[], bounds: { minX: number, maxX: number, minY: number, maxY: number }, isCircular?: boolean, centerX?: number, centerY?: number, radius?: number }} contour
      * @returns {boolean}
      */
     static #matchesContourPoints(points, contour) {
@@ -774,7 +835,7 @@ export class PcbScene3dBoardShapeFactory {
     /**
      * Returns true when a point is close to one contour boundary.
      * @param {{ x: number, y: number }} point
-     * @param {{ segments: { start: { x: number, y: number }, end: { x: number, y: number }, dx: number, dy: number, lengthSquared: number, bounds: { minX: number, maxX: number, minY: number, maxY: number } }[], bounds: { minX: number, maxX: number, minY: number, maxY: number } }} contour
+     * @param {{ segments: { start: { x: number, y: number }, end: { x: number, y: number }, dx: number, dy: number, lengthSquared: number, bounds: { minX: number, maxX: number, minY: number, maxY: number } }[], bounds: { minX: number, maxX: number, minY: number, maxY: number }, isCircular?: boolean, centerX?: number, centerY?: number, radius?: number }} contour
      * @returns {boolean}
      */
     static #isPointNearContour(point, contour) {
@@ -790,6 +851,14 @@ export class PcbScene3dBoardShapeFactory {
             return false
         }
 
+        if (contour.isCircular) {
+            return PcbScene3dBoardShapeFactory.#isPointNearCircularContour(
+                point,
+                contour,
+                tolerance
+            )
+        }
+
         for (const segment of contour.segments) {
             if (
                 point.x < segment.bounds.minX - tolerance ||
@@ -813,6 +882,27 @@ export class PcbScene3dBoardShapeFactory {
         return false
     }
 
+    /**
+     * Returns true when a point lies within the tolerance ring of a circle.
+     * @param {{ x: number, y: number }} point
+     * @param {{ centerX?: number, centerY?: number, radius?: number }} contour
+     * @param {number} tolerance
+     * @returns {boolean}
+     */
+    static #isPointNearCircularContour(point, contour, tolerance) {
+        const radius = Number(contour.radius || 0)
+        const minRadius = Math.max(0, radius - tolerance)
+        const maxRadius = radius + tolerance
+        const dx = point.x - Number(contour.centerX || 0)
+        const dy = point.y - Number(contour.centerY || 0)
+        const distanceSquared = dx * dx + dy * dy
+
+        return (
+            distanceSquared >= minRadius * minRadius &&
+            distanceSquared <= maxRadius * maxRadius
+        )
+    }
+
     /**
      * Appends or extends a contiguous material group.
      * @param {{ start: number, count: number, materialIndex: number }[]} groups

package/src/PcbScene3dBoardSolderMaskFactory.mjs

@@ -7,7 +7,7 @@ import { PcbScene3dOutlineBuilder } from './PcbScene3dOutlineBuilder.mjs'
  * Builds separate solder-mask face sheets for board-assembly rendering.
  */
 export class PcbScene3dBoardSolderMaskFactory {
-    static #CURVE_SEGMENTS = 20
+    static #CURVE_SEGMENTS = 8
     static #OUTER_SAMPLE_POINTS = 160
     static #DRILL_SAMPLE_POINTS = 72
     static #EDGE_CLEARANCE_MIL = 0

package/src/PcbScene3dBodyColor.mjs

@@ -0,0 +1,26 @@
+/**
+ * Resolves package body colors for generated fallback meshes.
+ */
+export class PcbScene3dBodyColor {
+    /**
+     * Resolves a simple body color by package family.
+     * @param {string} family Package family.
+     * @returns {number}
+     */
+    static resolve(family) {
+        if (family === 'radial-capacitor') {
+            return 0xa60f10
+        }
+        if (family === 'connector-block') {
+            return 0xd5d6da
+        }
+        if (family === 'test-point') {
+            return 0x0ea5a8
+        }
+        if (family === 'chip') {
+            return 0xf5f5ef
+        }
+
+        return 0x232428
+    }
+}