pcb-scene3d-viewer 1.3.3 → 1.3.4

package/docs/api.md

@@ -365,3 +365,18 @@ The package also exports focused factories used by the runtime:
 These factories accept Three.js constructors and normalized scene-detail
 objects. They are exported for tests and advanced hosts, but most applications
 should use `PcbScene3dRuntime` or `PcbScene3dController`.
+
+### Copper occlusion geometry
+
+Covered copper is clipped against vertical occlusion prisms at the contour
+boundaries. Convex contours are clipped directly; concave contours are
+triangulated into convex pieces. Intersection vertices interpolate all three
+coordinates, preserving sloped surfaces and vertical relief walls without
+recursive mesh subdivision. Sampled circular openings use tangent planes with
+at least 32 segments (or the source contour resolution when greater), preventing
+copper slivers inside the analytic circle. This keeps mesh growth tied to the
+opening boundaries rather than board dimensions or a subdivision depth.
+
+Repeated external-model package placement uses ownership indexes scoped to one
+repair invocation. Input scenes remain mutable: subsequent applications rebuild
+the indexes and observe edits to pad and component rows.

package/docs/model-format.md

@@ -233,3 +233,8 @@ 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.
+
+Filled `contours` may contain point loops or line/arc segment loops. Segment
+records are recognized by their type or start endpoint before point conversion;
+arc `x`/`y` fields describe centers, not vertices. Arc segments can provide an
+explicit signed `sweepAngle` to preserve direction and sweeps across zero.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.3.3",
+    "version": "1.3.4",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -61,7 +61,7 @@
     },
     "dependencies": {
         "@sunbox/occt-import-js": "^0.0.28",
-        "circuitjson-toolkit": "^1.4.1",
+        "circuitjson-toolkit": "^1.4.3",
         "earcut": "3.0.2",
         "fflate": "^0.8.2",
         "polygon-clipping": "^0.15.7",

package/src/PcbAssemblyFillGeometryResolver.mjs

@@ -378,6 +378,22 @@ export class PcbAssemblyFillGeometryResolver {
             return []
         }
 
+        // Segment x/y fields can denote arc centers. Do not reinterpret them
+        // as contour vertices before checking the segment's explicit shape.
+        if (
+            list.some(
+                (entry) =>
+                    ['line', 'arc'].includes(
+                        String(entry?.type || '').toLowerCase()
+                    ) ||
+                    (entry?.x1 != null && entry?.y1 != null) ||
+                    (entry?.startX != null && entry?.startY != null) ||
+                    entry?.start != null
+            )
+        ) {
+            return PcbAssemblyFillGeometryResolver.#segmentLoop(list)
+        }
+
         const pointLoop = PcbAssemblyFillGeometryResolver.#pointLoop(list)
         if (pointLoop.length >= 3) {
             return pointLoop

package/src/PcbScene3dCopperOcclusionClipper.mjs

@@ -1,4 +1,4 @@
-import { PcbScene3dCutoutGeometryFilter } from './PcbScene3dCutoutGeometryFilter.mjs'
+import { PcbScene3dCopperOcclusionGeometry } from './PcbScene3dCopperOcclusionGeometry.mjs'
 
 /**
  * Clips mask-covered copper relief where opaque overlay artwork covers it.
@@ -12,13 +12,12 @@ export class PcbScene3dCopperOcclusionClipper {
      * @returns {any | null}
      */
     static filter(THREE, geometry, cutouts) {
-        geometry.computeVertexNormals?.()
-        const clippedGeometry = PcbScene3dCutoutGeometryFilter.filter(
+        const clippedGeometry = PcbScene3dCopperOcclusionGeometry.filter(
             THREE,
             geometry,
-            cutouts,
-            { maxDepth: 12, maxEdgeLength: 2, discardTerminalOverlaps: true }
+            cutouts
         )
+        clippedGeometry.computeVertexNormals?.()
 
         return clippedGeometry.getAttribute?.('position')?.count
             ? clippedGeometry

package/src/PcbScene3dCopperOcclusionGeometry.mjs

@@ -0,0 +1,182 @@
+import { PcbScene3dAabbIndex } from './PcbScene3dAabbIndex.mjs'
+import { PcbScene3dCopperOcclusionPlanes } from './PcbScene3dCopperOcclusionPlanes.mjs'
+
+/** Subtracts vertical occlusion prisms without recursive triangle subdivision. */
+export class PcbScene3dCopperOcclusionGeometry {
+    /**
+     * Clips every triangle, interpolating XYZ on its original plane.
+     * @param {any} THREE Three.js namespace.
+     * @param {any} geometry Source triangle geometry.
+     * @param {object[][]} cutouts Normalized occlusion contours.
+     * @returns {any} Clipped or unchanged geometry.
+     */
+    static filter(THREE, geometry, cutouts) {
+        if (
+            !Array.isArray(cutouts) ||
+            !cutouts.length ||
+            !geometry?.getAttribute ||
+            !THREE.BufferGeometry ||
+            !THREE.Float32BufferAttribute
+        )
+            return geometry
+        const source = geometry.index ? geometry.toNonIndexed() : geometry
+        const position = source.getAttribute('position')
+        if (!position?.count) return geometry
+        const prisms = PcbScene3dCopperOcclusionPlanes.prepare(cutouts)
+        const index = new PcbScene3dAabbIndex(prisms)
+        const positions = []
+        let changed = false
+        for (let i = 0; i + 2 < position.count; i += 3) {
+            const triangle = [0, 1, 2].map((offset) => ({
+                x: position.getX(i + offset),
+                y: position.getY(i + offset),
+                z: position.getZ(i + offset)
+            }))
+            let polygons = [triangle]
+            for (const prism of index.query(this.#bounds(triangle))) {
+                const remaining = []
+                for (const polygon of polygons) {
+                    const pieces = this.#subtract(polygon, prism)
+                    if (pieces.length !== 1 || pieces[0] !== polygon)
+                        changed = true
+                    for (const piece of pieces) remaining.push(piece)
+                }
+                polygons = remaining
+                if (!polygons.length) break
+            }
+            for (const polygon of polygons) {
+                for (let vertex = 1; vertex + 1 < polygon.length; vertex += 1) {
+                    const a = polygon[0],
+                        b = polygon[vertex],
+                        c = polygon[vertex + 1]
+                    positions.push(a.x, a.y, a.z, b.x, b.y, b.z, c.x, c.y, c.z)
+                }
+            }
+        }
+        if (source !== geometry) source.dispose?.()
+        if (!changed) return geometry
+        const result = new THREE.BufferGeometry()
+        result.setAttribute(
+            'position',
+            new THREE.Float32BufferAttribute(positions, 3)
+        )
+        return result
+    }
+
+    /**
+     * Subtracts a convex prism, retaining convex outside pieces for triangulation.
+     * @param {object[]} polygon Convex polygon on a 3D plane.
+     * @param {object} prism Inward half planes and XY bounds.
+     * @returns {object[][]} Visible polygons.
+     */
+    static #subtract(polygon, prism) {
+        const bounds = this.#bounds(polygon)
+        if (
+            bounds.minX > prism.bounds.maxX ||
+            bounds.maxX < prism.bounds.minX ||
+            bounds.minY > prism.bounds.maxY ||
+            bounds.maxY < prism.bounds.minY
+        )
+            return [polygon]
+        let inside = polygon
+        const outside = []
+        for (const plane of prism.planes) {
+            const split = this.#split(inside, plane)
+            // No intersection means all tentative pieces together are the input.
+            if (split.inside.length < 3) return [polygon]
+            if (split.outside.length >= 3) outside.push(split.outside)
+            inside = split.inside
+        }
+        return this.#hasArea(inside) ? outside : [polygon]
+    }
+
+    /**
+     * Splits a planar polygon using an XY half plane, including vertical walls.
+     * @param {object[]} polygon Convex source polygon.
+     * @param {{ x: number, y: number, offset: number }} plane Inward half plane.
+     * @returns {{ inside: object[], outside: object[] }} Split polygon sides.
+     */
+    static #split(polygon, plane) {
+        const inside = [],
+            outside = []
+        let hasOutside = false
+        let previous = polygon[polygon.length - 1]
+        let previousDistance =
+            plane.x * previous.x + plane.y * previous.y - plane.offset
+        for (const point of polygon) {
+            const distance =
+                plane.x * point.x + plane.y * point.y - plane.offset
+            if (
+                (distance > 0 && previousDistance < 0) ||
+                (distance < 0 && previousDistance > 0)
+            ) {
+                const fraction =
+                    previousDistance / (previousDistance - distance)
+                const crossing = {
+                    x: previous.x + fraction * (point.x - previous.x),
+                    y: previous.y + fraction * (point.y - previous.y),
+                    z: previous.z + fraction * (point.z - previous.z)
+                }
+                inside.push(crossing)
+                outside.push(crossing)
+            }
+            if (distance >= 0) inside.push(point)
+            if (distance <= 0) outside.push(point)
+            if (distance < 0) hasOutside = true
+            previous = point
+            previousDistance = distance
+        }
+        return {
+            inside,
+            outside: hasOutside && this.#hasArea(outside) ? outside : []
+        }
+    }
+
+    /**
+     * Rejects boundary-only intersections without dropping vertical surfaces.
+     * @param {object[]} polygon Convex planar polygon.
+     * @returns {boolean} Whether at least one triangle has nonzero 3D area.
+     */
+    static #hasArea(polygon) {
+        if (polygon.length < 3) return false
+        const a = polygon[0]
+        for (let i = 1; i + 1 < polygon.length; i += 1) {
+            const b = polygon[i],
+                c = polygon[i + 1]
+            const ux = b.x - a.x,
+                uy = b.y - a.y,
+                uz = b.z - a.z
+            const vx = c.x - a.x,
+                vy = c.y - a.y,
+                vz = c.z - a.z
+            if (
+                Math.hypot(
+                    uy * vz - uz * vy,
+                    uz * vx - ux * vz,
+                    ux * vy - uy * vx
+                ) > 1e-10
+            )
+                return true
+        }
+        return false
+    }
+
+    /**
+     * Resolves XY bounds for a planar polygon.
+     * @param {object[]} points Polygon vertices.
+     * @returns {object} Axis-aligned bounds.
+     */
+    static #bounds(points) {
+        let minX = Infinity,
+            maxX = -Infinity,
+            minY = Infinity,
+            maxY = -Infinity
+        for (const { x, y } of points) {
+            minX = Math.min(minX, x)
+            maxX = Math.max(maxX, x)
+            minY = Math.min(minY, y)
+            maxY = Math.max(maxY, y)
+        }
+        return { minX, maxX, minY, maxY }
+    }
+}

package/src/PcbScene3dCopperOcclusionPlanes.mjs

@@ -0,0 +1,145 @@
+import earcut from 'earcut'
+import { PcbScene3dCutoutCircleDetector } from './PcbScene3dCutoutCircleDetector.mjs'
+
+/** Prepares convex vertical prisms for copper occlusion subtraction. */
+export class PcbScene3dCopperOcclusionPlanes {
+    /**
+     * Decomposes simple concave contours while retaining convex contours whole.
+     * @param {{ x: number, y: number }[][]} cutouts Occlusion contours.
+     * @returns {object[]} Convex prisms with bounds and inward half planes.
+     */
+    static prepare(cutouts) {
+        const result = []
+        for (const cutout of cutouts) {
+            const points = []
+            for (const point of Array.isArray(cutout) ? cutout : []) {
+                const x = Number(point?.x || 0)
+                const y = Number(point?.y || 0)
+                const previous = points[points.length - 1]
+                if (
+                    Number.isFinite(x) &&
+                    Number.isFinite(y) &&
+                    (!previous || x !== previous.x || y !== previous.y)
+                ) {
+                    points.push({ x, y })
+                }
+            }
+            if (
+                points.length > 1 &&
+                points[0].x === points.at(-1).x &&
+                points[0].y === points.at(-1).y
+            )
+                points.pop()
+            if (points.length < 3) continue
+            const circle = PcbScene3dCutoutCircleDetector.resolve(points)
+            if (circle) {
+                result.push(this.#circle(circle, points.length))
+                continue
+            }
+            if (this.#isConvex(points)) {
+                result.push(this.#polygon(points))
+                continue
+            }
+            const indices = earcut(points.flatMap(({ x, y }) => [x, y]))
+            for (let i = 0; i < indices.length; i += 3) {
+                result.push(
+                    this.#polygon([
+                        points[indices[i]],
+                        points[indices[i + 1]],
+                        points[indices[i + 2]]
+                    ])
+                )
+            }
+        }
+        return result.filter((entry) => entry.planes.length >= 3)
+    }
+
+    /**
+     * Checks turn orientation, including collinear vertices.
+     * @param {object[]} points Contour vertices.
+     * @returns {boolean} Whether the contour is convex.
+     */
+    static #isConvex(points) {
+        let direction = 0
+        for (let i = 0; i < points.length; i += 1) {
+            const a = points[i],
+                b = points[(i + 1) % points.length],
+                c = points[(i + 2) % points.length]
+            const cross = (b.x - a.x) * (c.y - b.y) - (b.y - a.y) * (c.x - b.x)
+            if (cross === 0) continue
+            if (direction && Math.sign(cross) !== direction) return false
+            direction = Math.sign(cross)
+        }
+        return direction !== 0
+    }
+
+    /**
+     * Builds normalized inward half planes for either contour winding.
+     * @param {object[]} points Convex contour vertices.
+     * @returns {object} Prepared prism.
+     */
+    static #polygon(points) {
+        let area = 0
+        const origin = points[0]
+        for (let i = 1; i + 1 < points.length; i += 1) {
+            area +=
+                (points[i].x - origin.x) * (points[i + 1].y - origin.y) -
+                (points[i].y - origin.y) * (points[i + 1].x - origin.x)
+        }
+        const direction = Math.sign(area)
+        const planes = []
+        const bounds = {
+            minX: Infinity,
+            minY: Infinity,
+            maxX: -Infinity,
+            maxY: -Infinity
+        }
+        for (let i = 0; i < points.length; i += 1) {
+            const a = points[i],
+                b = points[(i + 1) % points.length]
+            const length = Math.hypot(b.x - a.x, b.y - a.y)
+            if (length && direction) {
+                const x = (direction * (a.y - b.y)) / length
+                const y = (direction * (b.x - a.x)) / length
+                planes.push({ x, y, offset: x * a.x + y * a.y })
+            }
+            bounds.minX = Math.min(bounds.minX, a.x)
+            bounds.maxX = Math.max(bounds.maxX, a.x)
+            bounds.minY = Math.min(bounds.minY, a.y)
+            bounds.maxY = Math.max(bounds.maxY, a.y)
+        }
+        return { planes, bounds }
+    }
+
+    /**
+     * Uses tangents so sampled circles never leave copper slivers inside a pad.
+     * @param {object} circle Analytic circle metadata.
+     * @param {number} pointCount Source contour resolution.
+     * @returns {object} Conservative circular prism.
+     */
+    static #circle(circle, pointCount) {
+        const count = Math.max(32, pointCount)
+        const { centerX, centerY, radius } = circle
+        const planes = []
+        for (let i = 0; i < count; i += 1) {
+            const angle = (2 * Math.PI * i) / count
+            const x = Math.cos(angle),
+                y = Math.sin(angle)
+            planes.push({
+                x: -x,
+                y: -y,
+                offset: -x * centerX - y * centerY - radius
+            })
+        }
+        const extent = radius / Math.cos(Math.PI / count)
+        return {
+            planes,
+            bounds: {
+                minX: centerX - extent,
+                maxX: centerX + extent,
+                minY: centerY - extent,
+                maxY: centerY + extent
+            }
+        }
+    }
+}

package/src/PcbScene3dCopperTextFactory.mjs

@@ -45,7 +45,7 @@ export class PcbScene3dCopperTextFactory {
      * @param {any[]} texts
      * @param {number} z
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
-     * @param {{ side?: 'top' | 'bottom', mirrorY?: boolean, materialColor?: number, materialProperties?: { materialKind?: 'basic' | 'standard', roughness?: number, metalness?: number, transparent?: boolean, opacity?: number, toneMapped?: boolean, fog?: boolean }, filterSide?: boolean, glyphYUp?: boolean, drillCutouts?: { x: number, y: number }[][], preparedPolygonCache?: Map }} [options]
+     * @param {{ side?: 'top' | 'bottom', mirrorY?: boolean, materialColor?: number, materialProperties?: { materialKind?: 'basic' | 'standard', roughness?: number, metalness?: number, transparent?: boolean, opacity?: number, toneMapped?: boolean, fog?: boolean }, filterSide?: boolean, glyphYUp?: boolean, drillCutouts?: { x: number, y: number }[][], preparedPolygonCache?: Map, preparedCutoutCache?: WeakMap }} [options]
      * @returns {any}
      */
     static buildGroup(THREE, texts, z, normalizeBoardPoint, options = {}) {
@@ -88,7 +88,7 @@ export class PcbScene3dCopperTextFactory {
                 THREE,
                 geometry,
                 options?.drillCutouts,
-                options?.preparedPolygonCache
+                options
             )
 
         if (
@@ -117,21 +117,19 @@ export class PcbScene3dCopperTextFactory {
      * @param {any} THREE
      * @param {any} geometry
      * @param {{ x: number, y: number }[][] | undefined} drillCutouts
-     * @param {Map | undefined} preparedPolygonCache Request-scoped prepared cache.
+     * @param {{ preparedPolygonCache?: Map, preparedCutoutCache?: WeakMap }} options Build-scoped cutout caches.
      * @returns {any}
      */
-    static #filterDrillCutouts(
-        THREE,
-        geometry,
-        drillCutouts,
-        preparedPolygonCache
-    ) {
+    static #filterDrillCutouts(THREE, geometry, drillCutouts, options) {
         return Array.isArray(drillCutouts) && drillCutouts.length
             ? PcbScene3dCutoutGeometryFilter.filter(
                   THREE,
                   geometry,
                   drillCutouts,
-                  { preparedPolygonCache }
+                  {
+                      preparedPolygonCache: options?.preparedPolygonCache,
+                      preparedCutoutCache: options?.preparedCutoutCache
+                  }
               )
             : geometry
     }

package/src/PcbScene3dCutoutGeometryFilter.mjs

@@ -16,7 +16,7 @@ export class PcbScene3dCutoutGeometryFilter {
      * @param {any} THREE
      * @param {any} geometry
      * @param {{ x: number, y: number }[][]} cutouts
-     * @param {{ maxDepth?: number, maxEdgeLength?: number, discardTerminalOverlaps?: boolean, preparedPolygonCache?: Map }} [options]
+     * @param {{ maxDepth?: number, maxEdgeLength?: number, discardTerminalOverlaps?: boolean, preparedPolygonCache?: Map, preparedCutoutCache?: WeakMap }} [options]
      * @returns {any}
      */
     static filter(THREE, geometry, cutouts, options = {}) {
@@ -36,10 +36,12 @@ export class PcbScene3dCutoutGeometryFilter {
         if (!position?.count) {
             return geometry
         }
-        const preparedCutouts = PcbScene3dCutoutGeometryFilter.#prepareCutouts(
-            cutouts,
-            PcbScene3dCutoutGeometryFilter.#resolvePreparedPolygonCache(options)
-        )
+        const queryContext =
+            PcbScene3dCutoutGeometryFilter.#resolveQueryContext(
+                cutouts,
+                options
+            )
+        const { preparedCutouts } = queryContext
         if (
             PcbScene3dGeometryBoundsResolver.missesAllPositionBounds(
                 position,
@@ -48,7 +50,8 @@ export class PcbScene3dCutoutGeometryFilter {
             )
         )
             return geometry
-        const cutoutIndex = new PcbScene3dCutoutGridIndex(preparedCutouts)
+        const cutoutIndex = (queryContext.cutoutIndex ||=
+            new PcbScene3dCutoutGridIndex(preparedCutouts))
         const settings =
             PcbScene3dCutoutGeometryFilter.#resolveSettings(options)
         const positions = []
@@ -80,9 +83,38 @@ export class PcbScene3dCutoutGeometryFilter {
         filteredGeometry.computeVertexNormals?.()
         return filteredGeometry
     }
+    /**
+     * Resolves preparation and a lazily built query index for an immutable
+     * cutout collection. Cache ownership belongs to one caller build; calls
+     * without a cache always observe the current source coordinates.
+     * @param {object[][]} cutouts Source cutout collection.
+     * @param {{ preparedPolygonCache?: Map, preparedCutoutCache?: WeakMap }} options Build-scoped options.
+     * @returns {{ preparedCutouts: PcbScene3dPreparedPolygon[], cutoutIndex: PcbScene3dCutoutGridIndex | null }}
+     */
+    static #resolveQueryContext(cutouts, options) {
+        const cache =
+            options?.preparedCutoutCache instanceof WeakMap
+                ? options.preparedCutoutCache
+                : null
+        const cached = cache?.get(cutouts)
+        if (cached) return cached
+
+        const context = {
+            preparedCutouts: PcbScene3dCutoutGeometryFilter.#prepareCutouts(
+                cutouts,
+                PcbScene3dCutoutGeometryFilter.#resolvePreparedPolygonCache(
+                    options
+                )
+            ),
+            cutoutIndex: null
+        }
+        cache?.set(cutouts, context)
+        return context
+    }
+
     /**
      * Resolves clipping settings.
-     * @param {{ maxDepth?: number, maxEdgeLength?: number, discardTerminalOverlaps?: boolean, preparedPolygonCache?: Map }} options
+     * @param {{ maxDepth?: number, maxEdgeLength?: number, discardTerminalOverlaps?: boolean, preparedPolygonCache?: Map, preparedCutoutCache?: WeakMap }} options
      * @returns {{ maxDepth: number, maxEdgeLength: number, maxEdgeLengthSquared: number, discardTerminalOverlaps: boolean }}
      */
     static #resolveSettings(options) {
@@ -106,7 +138,7 @@ export class PcbScene3dCutoutGeometryFilter {
     }
     /**
      * Resolves a supported request-scoped prepared polygon cache.
-     * @param {{ preparedPolygonCache?: Map }} options Request options.
+     * @param {{ preparedPolygonCache?: Map, preparedCutoutCache?: WeakMap }} options Request options.
      * @returns {Map | null}
      */
     static #resolvePreparedPolygonCache(options) {