pcb-scene3d-viewer 1.1.21 → 1.1.31

package/src/PcbScene3dCopperDrillCutoutBuilder.mjs

@@ -0,0 +1,258 @@
+import { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
+
+/**
+ * Builds normalized board drill cutouts for copper surface meshes.
+ */
+export class PcbScene3dCopperDrillCutoutBuilder {
+    static #DRILL_CUTOUT_SEGMENTS = 48
+    static #SLOT_CAP_SEGMENTS = 12
+
+    /**
+     * Resolves board drill cutouts for copper fill apertures.
+     * @param {{ pads?: any[], vias?: any[] }} detail Copper detail.
+     * @param {(x: number, y: number) => { x: number, y: number }} [normalizeBoardPoint]
+     * @param {boolean} [mirrorY] Whether to mirror underside primitives.
+     * @returns {{ x: number, y: number }[][]}
+     */
+    static resolve(
+        detail,
+        normalizeBoardPoint = (x, y) => ({ x, y }),
+        mirrorY = false
+    ) {
+        return PcbScene3dDrillPathFactory.resolveBoardDrillSpecs(detail)
+            .map((drillSpec) =>
+                PcbScene3dCopperDrillCutoutBuilder.#resolveCutoutPoints(
+                    drillSpec,
+                    normalizeBoardPoint,
+                    mirrorY
+                )
+            )
+            .filter((points) => points.length >= 3)
+    }
+
+    /**
+     * Resolves cutouts from explicit options or fallback drill detail.
+     * @param {{ drillCutouts?: any[], drillDetail?: object } | undefined} options
+     * @param {{ pads?: any[], vias?: any[] }} fallbackDetail Fallback detail.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @param {boolean} mirrorY Whether to mirror underside primitives.
+     * @returns {{ x: number, y: number }[][]}
+     */
+    static resolveFromOptions(
+        options,
+        fallbackDetail,
+        normalizeBoardPoint,
+        mirrorY
+    ) {
+        if (Array.isArray(options?.drillCutouts)) {
+            return PcbScene3dCopperDrillCutoutBuilder.#normalizeCutouts(
+                options.drillCutouts,
+                normalizeBoardPoint,
+                mirrorY
+            )
+        }
+
+        return PcbScene3dCopperDrillCutoutBuilder.resolve(
+            options?.drillDetail || fallbackDetail,
+            normalizeBoardPoint,
+            mirrorY
+        )
+    }
+
+    /**
+     * Resolves one drill cutout point loop.
+     * @param {{ x: number, y: number, diameter: number, slotLength?: number | null, rotationDeg?: number | null }} drillSpec
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @param {boolean} mirrorY Whether to mirror underside primitives.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #resolveCutoutPoints(drillSpec, normalizeBoardPoint, mirrorY) {
+        const points =
+            Number(drillSpec?.slotLength || 0) >
+            Number(drillSpec?.diameter || 0) + 0.001
+                ? PcbScene3dCopperDrillCutoutBuilder.#buildSlotPoints(drillSpec)
+                : PcbScene3dCopperDrillCutoutBuilder.#buildCirclePoints(
+                      drillSpec
+                  )
+
+        return points.map((point) =>
+            PcbScene3dCopperDrillCutoutBuilder.#normalizePoint(
+                point,
+                normalizeBoardPoint,
+                mirrorY
+            )
+        )
+    }
+
+    /**
+     * Normalizes cutout point loops.
+     * @param {{ x?: number, y?: number }[][]} cutouts Cutout loops.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @param {boolean} mirrorY Whether to mirror underside primitives.
+     * @returns {{ x: number, y: number }[][]}
+     */
+    static #normalizeCutouts(cutouts, normalizeBoardPoint, mirrorY) {
+        return cutouts
+            .map((cutout) =>
+                (Array.isArray(cutout) ? cutout : []).map((point) =>
+                    PcbScene3dCopperDrillCutoutBuilder.#normalizePoint(
+                        point,
+                        normalizeBoardPoint,
+                        mirrorY
+                    )
+                )
+            )
+            .filter((cutout) => cutout.length >= 3)
+    }
+
+    /**
+     * Normalizes one cutout point.
+     * @param {{ x?: number, y?: number }} point Source point.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @param {boolean} mirrorY Whether to mirror underside primitives.
+     * @returns {{ x: number, y: number }}
+     */
+    static #normalizePoint(point, normalizeBoardPoint, mirrorY) {
+        const normalized = normalizeBoardPoint(
+            Number(point?.x || 0),
+            Number(point?.y || 0)
+        )
+
+        return {
+            x: Number(normalized?.x || 0),
+            y: mirrorY
+                ? -Number(normalized?.y || 0)
+                : Number(normalized?.y || 0)
+        }
+    }
+
+    /**
+     * Builds one sampled circular drill loop.
+     * @param {{ x: number, y: number, diameter: number }} drillSpec Drill spec.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #buildCirclePoints(drillSpec) {
+        const radius = Math.max(Number(drillSpec?.diameter || 0) / 2, 0.6)
+        const centerX = Number(drillSpec?.x || 0)
+        const centerY = Number(drillSpec?.y || 0)
+
+        return Array.from(
+            {
+                length: PcbScene3dCopperDrillCutoutBuilder
+                    .#DRILL_CUTOUT_SEGMENTS
+            },
+            (_, index) => {
+                const angle =
+                    (Math.PI * 2 * index) /
+                    PcbScene3dCopperDrillCutoutBuilder.#DRILL_CUTOUT_SEGMENTS
+
+                return {
+                    x: centerX + Math.cos(angle) * radius,
+                    y: centerY + Math.sin(angle) * radius
+                }
+            }
+        )
+    }
+
+    /**
+     * Builds one sampled slotted drill loop.
+     * @param {{ x: number, y: number, diameter: number, slotLength?: number | null, rotationDeg?: number | null }} drillSpec Drill spec.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #buildSlotPoints(drillSpec) {
+        const diameter = Math.max(Number(drillSpec?.diameter || 0), 1.2)
+        const radius = Math.max(diameter / 2, 0.6)
+        const slotLength = Math.max(
+            Number(drillSpec?.slotLength || 0),
+            diameter
+        )
+        const straightHalf = Math.max(slotLength / 2 - radius, 0)
+        const rotationRad =
+            (Number(drillSpec?.rotationDeg || 0) * Math.PI) / 180
+        const points = []
+
+        PcbScene3dCopperDrillCutoutBuilder.#appendArcPoints(
+            points,
+            straightHalf,
+            0,
+            radius,
+            -Math.PI / 2,
+            Math.PI / 2
+        )
+        PcbScene3dCopperDrillCutoutBuilder.#appendArcPoints(
+            points,
+            -straightHalf,
+            0,
+            radius,
+            Math.PI / 2,
+            (Math.PI * 3) / 2,
+            true
+        )
+
+        return points.map((point) =>
+            PcbScene3dCopperDrillCutoutBuilder.#rotateAndTranslatePoint(
+                point,
+                rotationRad,
+                Number(drillSpec?.x || 0),
+                Number(drillSpec?.y || 0)
+            )
+        )
+    }
+
+    /**
+     * Appends sampled points for one slot cap arc.
+     * @param {{ x: number, y: number }[]} points Output point list.
+     * @param {number} cx Arc center X.
+     * @param {number} cy Arc center Y.
+     * @param {number} radius Arc radius.
+     * @param {number} startAngle Start angle in radians.
+     * @param {number} endAngle End angle in radians.
+     * @param {boolean} [skipFirst] Whether to skip the first sample.
+     * @returns {void}
+     */
+    static #appendArcPoints(
+        points,
+        cx,
+        cy,
+        radius,
+        startAngle,
+        endAngle,
+        skipFirst = false
+    ) {
+        for (
+            let index = 0;
+            index <= PcbScene3dCopperDrillCutoutBuilder.#SLOT_CAP_SEGMENTS;
+            index += 1
+        ) {
+            if (skipFirst && index === 0) {
+                continue
+            }
+
+            const t =
+                index / PcbScene3dCopperDrillCutoutBuilder.#SLOT_CAP_SEGMENTS
+            const angle = startAngle + (endAngle - startAngle) * t
+            points.push({
+                x: cx + Math.cos(angle) * radius,
+                y: cy + Math.sin(angle) * radius
+            })
+        }
+    }
+
+    /**
+     * Rotates one local point around the origin and translates it into place.
+     * @param {{ x: number, y: number }} point Local point.
+     * @param {number} rotationRad Rotation in radians.
+     * @param {number} dx Translation X.
+     * @param {number} dy Translation Y.
+     * @returns {{ x: number, y: number }}
+     */
+    static #rotateAndTranslatePoint(point, rotationRad, dx, dy) {
+        const cos = Math.cos(rotationRad)
+        const sin = Math.sin(rotationRad)
+
+        return {
+            x: point.x * cos - point.y * sin + dx,
+            y: point.x * sin + point.y * cos + dy
+        }
+    }
+}

package/src/PcbScene3dCopperFactory.mjs

@@ -2,9 +2,11 @@ import { PcbScene3dArcUtils } from './PcbScene3dArcUtils.mjs'
 import { PcbScene3dPadFactory } from './PcbScene3dPadFactory.mjs'
 import { PcbScene3dCopperTextFactory } from './PcbScene3dCopperTextFactory.mjs'
 import { PcbScene3dMaskCoveredCopperMaterial } from './PcbScene3dMaskCoveredCopperMaterial.mjs'
-import { PcbScene3dGeometryZCompressor } from './PcbScene3dGeometryZCompressor.mjs'
 import { PcbScene3dCopperOcclusionClipper } from './PcbScene3dCopperOcclusionClipper.mjs'
 import { PcbScene3dCopperLayerFilter } from './PcbScene3dCopperLayerFilter.mjs'
+import { PcbScene3dCopperFillMeshBuilder } from './PcbScene3dCopperFillMeshBuilder.mjs'
+import { PcbScene3dMaskCoveredCopperSideGroupBuilder } from './PcbScene3dMaskCoveredCopperSideGroupBuilder.mjs'
+import { PcbScene3dCopperDrillCutoutBuilder } from './PcbScene3dCopperDrillCutoutBuilder.mjs'
 
 /**
  * Builds copper-detail meshes for the interactive 3D PCB scene.
@@ -27,11 +29,11 @@ export class PcbScene3dCopperFactory {
     /**
      * Builds the combined top and bottom copper group.
      * @param {any} THREE
-     * @param {{ tracks?: any[], arcs?: any[], pads?: any[], vias?: any[], copperTexts?: any[] }} detail
+     * @param {{ tracks?: any[], arcs?: any[], fills?: any[], polygons?: any[], pads?: any[], vias?: any[], copperTexts?: any[] }} detail
      * @param {number} topZ
      * @param {number} bottomZ
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
-     * @param {{ coordinateSystem?: string }} [options]
+     * @param {{ coordinateSystem?: string, drillCutouts?: any[], drillDetail?: object }} [options]
      * @returns {any}
      */
     static buildGroup(
@@ -51,6 +53,10 @@ export class PcbScene3dCopperFactory {
                     'top'
                 ),
                 arcs: PcbScene3dCopperLayerFilter.arcs(detail?.arcs, 'top'),
+                fills: PcbScene3dCopperLayerFilter.fills(
+                    [...(detail?.fills || []), ...(detail?.polygons || [])],
+                    'top'
+                ),
                 pads: detail?.pads || [],
                 vias: detail?.vias || [],
                 copperTexts: detail?.copperTexts || []
@@ -68,6 +74,10 @@ export class PcbScene3dCopperFactory {
                     'bottom'
                 ),
                 arcs: PcbScene3dCopperLayerFilter.arcs(detail?.arcs, 'bottom'),
+                fills: PcbScene3dCopperLayerFilter.fills(
+                    [...(detail?.fills || []), ...(detail?.polygons || [])],
+                    'bottom'
+                ),
                 pads: detail?.pads || [],
                 vias: detail?.vias || [],
                 copperTexts: detail?.copperTexts || []
@@ -78,24 +88,20 @@ export class PcbScene3dCopperFactory {
             options
         )
 
-        if (topGroup.children.length) {
-            group.add(topGroup)
-        }
-        if (bottomGroup.children.length) {
-            group.add(bottomGroup)
-        }
+        if (topGroup.children.length) group.add(topGroup)
+        if (bottomGroup.children.length) group.add(bottomGroup)
 
         return group
     }
 
     /**
-     * Builds top and bottom traces that are covered by solder mask.
+     * Builds top and bottom copper detail that is covered by solder mask.
      * @param {any} THREE
-     * @param {{ tracks?: any[], arcs?: any[] }} detail Mask-covered detail.
+     * @param {{ tracks?: any[], arcs?: any[], fills?: any[], polygons?: any[] }} detail Mask-covered detail.
      * @param {number} topZ
      * @param {number} bottomZ
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
-     * @param {{ solderMaskColor?: number, occlusionCutouts?: { top?: { x: number, y: number }[][], bottom?: { x: number, y: number }[][] } }} [options]
+     * @param {{ solderMaskColor?: number, occlusionCutouts?: object, drillCutouts?: any[], drillDetail?: object }} [options]
      * @returns {any}
      */
     static buildMaskCoveredGroup(
@@ -111,6 +117,21 @@ export class PcbScene3dCopperFactory {
             THREE,
             options
         )
+        const drillCutouts = Array.isArray(options?.drillCutouts)
+            ? options.drillCutouts
+            : PcbScene3dCopperDrillCutoutBuilder.resolve(
+                  options?.drillDetail || detail
+              )
+        const topCutouts = PcbScene3dCopperOcclusionClipper.normalizeCutouts(
+            [...(options?.occlusionCutouts?.top || []), ...drillCutouts],
+            normalizeBoardPoint,
+            false
+        )
+        const bottomCutouts = PcbScene3dCopperOcclusionClipper.normalizeCutouts(
+            [...(options?.occlusionCutouts?.bottom || []), ...drillCutouts],
+            normalizeBoardPoint,
+            true
+        )
         const topGroup = PcbScene3dCopperFactory.#buildMaskCoveredSideGroup(
             THREE,
             {
@@ -118,17 +139,17 @@ export class PcbScene3dCopperFactory {
                     detail?.tracks,
                     'top'
                 ),
-                arcs: PcbScene3dCopperLayerFilter.arcs(detail?.arcs, 'top')
+                arcs: PcbScene3dCopperLayerFilter.arcs(detail?.arcs, 'top'),
+                fills: PcbScene3dCopperLayerFilter.fills(
+                    [...(detail?.fills || []), ...(detail?.polygons || [])],
+                    'top'
+                )
             },
             Math.abs(Number(topZ || 0)),
             normalizeBoardPoint,
             false,
             material,
-            PcbScene3dCopperOcclusionClipper.normalizeCutouts(
-                options?.occlusionCutouts?.top,
-                normalizeBoardPoint,
-                false
-            )
+            topCutouts
         )
         const bottomGroup = PcbScene3dCopperFactory.#buildMaskCoveredSideGroup(
             THREE,
@@ -137,25 +158,21 @@ export class PcbScene3dCopperFactory {
                     detail?.tracks,
                     'bottom'
                 ),
-                arcs: PcbScene3dCopperLayerFilter.arcs(detail?.arcs, 'bottom')
+                arcs: PcbScene3dCopperLayerFilter.arcs(detail?.arcs, 'bottom'),
+                fills: PcbScene3dCopperLayerFilter.fills(
+                    [...(detail?.fills || []), ...(detail?.polygons || [])],
+                    'bottom'
+                )
             },
             Math.abs(Number(bottomZ || 0)),
             normalizeBoardPoint,
             true,
             material,
-            PcbScene3dCopperOcclusionClipper.normalizeCutouts(
-                options?.occlusionCutouts?.bottom,
-                normalizeBoardPoint,
-                true
-            )
+            bottomCutouts
         )
 
-        if (topGroup.children.length) {
-            group.add(topGroup)
-        }
-        if (bottomGroup.children.length) {
-            group.add(bottomGroup)
-        }
+        if (topGroup.children.length) group.add(topGroup)
+        if (bottomGroup.children.length) group.add(bottomGroup)
 
         return group
     }
@@ -163,11 +180,11 @@ export class PcbScene3dCopperFactory {
     /**
      * Builds one side-specific copper group.
      * @param {any} THREE
-     * @param {{ tracks?: any[], arcs?: any[], pads?: any[], vias?: any[], copperTexts?: any[] }} detail
+     * @param {{ tracks?: any[], arcs?: any[], fills?: any[], pads?: any[], vias?: any[], copperTexts?: any[] }} detail
      * @param {number} z
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
      * @param {boolean} mirrorY
-     * @param {{ coordinateSystem?: string }} [options]
+     * @param {{ coordinateSystem?: string, drillCutouts?: any[], drillDetail?: object }} [options]
      * @returns {any}
      */
     static #buildSideGroup(
@@ -179,6 +196,13 @@ export class PcbScene3dCopperFactory {
         options = {}
     ) {
         const group = new THREE.Group()
+        const drillCutouts =
+            PcbScene3dCopperDrillCutoutBuilder.resolveFromOptions(
+                options,
+                detail,
+                normalizeBoardPoint,
+                mirrorY
+            )
         const trackMesh = PcbScene3dCopperFactory.#buildTrackMesh(
             THREE,
             detail?.tracks || [],
@@ -193,6 +217,16 @@ export class PcbScene3dCopperFactory {
             normalizeBoardPoint,
             mirrorY
         )
+        const fillMesh = PcbScene3dCopperFillMeshBuilder.build(
+            THREE,
+            detail?.fills || [],
+            z,
+            PcbScene3dCopperFactory.#COPPER_THICKNESS_MIL,
+            normalizeBoardPoint,
+            mirrorY,
+            PcbScene3dCopperFactory.#buildMaterial(THREE),
+            drillCutouts
+        )
         const padGroup = PcbScene3dPadFactory.buildGroup(
             THREE,
             detail?.pads || [],
@@ -215,29 +249,20 @@ export class PcbScene3dCopperFactory {
             }
         )
 
-        if (trackMesh) {
-            group.add(trackMesh)
-        }
-        if (arcMesh) {
-            group.add(arcMesh)
-        }
-        if (padGroup.children.length) {
-            group.add(padGroup)
-        }
-        if (textGroup.children.length) {
-            group.add(textGroup)
-        }
-        if (mirrorY && group.children.length) {
-            group.rotation.x = Math.PI
-        }
+        if (trackMesh) group.add(trackMesh)
+        if (arcMesh) group.add(arcMesh)
+        if (fillMesh) group.add(fillMesh)
+        if (padGroup.children.length) group.add(padGroup)
+        if (textGroup.children.length) group.add(textGroup)
+        if (mirrorY && group.children.length) group.rotation.x = Math.PI
 
         return group
     }
 
     /**
-     * Builds one side of the mask-covered trace relief.
+     * Builds one side of the mask-covered copper relief.
      * @param {any} THREE
-     * @param {{ tracks?: any[], arcs?: any[] }} detail Mask-covered detail.
+     * @param {{ tracks?: any[], arcs?: any[], fills?: any[] }} detail Mask-covered detail.
      * @param {number} z
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
      * @param {boolean} mirrorY
@@ -254,7 +279,6 @@ export class PcbScene3dCopperFactory {
         material,
         occlusionCutouts
     ) {
-        const group = new THREE.Group()
         const trackMesh = PcbScene3dCopperFactory.#buildTrackMesh(
             THREE,
             detail?.tracks || [],
@@ -273,28 +297,23 @@ export class PcbScene3dCopperFactory {
             material,
             occlusionCutouts
         )
-
-        if (trackMesh) {
-            PcbScene3dGeometryZCompressor.compressMaskCoveredCopperMesh(
-                trackMesh,
-                z
-            )
-            trackMesh.name = 'mask-covered-copper-tracks'
-            group.add(trackMesh)
-        }
-        if (arcMesh) {
-            PcbScene3dGeometryZCompressor.compressMaskCoveredCopperMesh(
-                arcMesh,
-                z
-            )
-            arcMesh.name = 'mask-covered-copper-arcs'
-            group.add(arcMesh)
-        }
-        if (mirrorY && group.children.length) {
-            group.rotation.x = Math.PI
-        }
-
-        return group
+        const fillMesh = PcbScene3dCopperFillMeshBuilder.build(
+            THREE,
+            detail?.fills || [],
+            z,
+            PcbScene3dCopperFactory.#COPPER_THICKNESS_MIL,
+            normalizeBoardPoint,
+            mirrorY,
+            material,
+            occlusionCutouts
+        )
+        return PcbScene3dMaskCoveredCopperSideGroupBuilder.build(THREE, {
+            trackMesh,
+            arcMesh,
+            fillMesh,
+            z,
+            mirrorY
+        })
     }
 
     /**
@@ -309,7 +328,7 @@ export class PcbScene3dCopperFactory {
     /**
      * Builds one widened copper-track mesh for one face.
      * @param {any} THREE
-     * @param {{ x1?: number, y1?: number, x2?: number, y2?: number, width?: number, capStartRound?: boolean, capEndRound?: boolean, capStartSideWall?: boolean, capEndSideWall?: boolean }[]} tracks
+     * @param {any[]} tracks
      * @param {number} z
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
      * @param {boolean} mirrorY
@@ -362,7 +381,7 @@ export class PcbScene3dCopperFactory {
     /**
      * Builds one widened copper-arc mesh for one face.
      * @param {any} THREE
-     * @param {{ x?: number, y?: number, radius?: number, startAngle?: number, endAngle?: number, width?: number }[]} arcs
+     * @param {any[]} arcs
      * @param {number} z
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
      * @param {boolean} mirrorY
@@ -463,7 +482,7 @@ export class PcbScene3dCopperFactory {
      * @param {{ x: number, y: number }} end
      * @param {number} width
      * @param {number} z
-     * @param {{ capStartRound?: boolean, capEndRound?: boolean, capStartSideWall?: boolean, capEndSideWall?: boolean }} [options]
+     * @param {object} [options]
      * @returns {void}
      */
     static #appendTrackTriangles(
@@ -705,9 +724,7 @@ export class PcbScene3dCopperFactory {
      */
     static #appendDiscTriangles(positions, center, radius, z) {
         const safeRadius = Math.max(Number(radius || 0), 0)
-        if (safeRadius <= 0) {
-            return
-        }
+        if (safeRadius <= 0) return
 
         for (
             let index = 0;
@@ -755,9 +772,9 @@ export class PcbScene3dCopperFactory {
      * @param {{ x: number, y: number }} center Cap center.
      * @param {number} radius Cap radius.
      * @param {number} z Center Z position.
-     * @param {number} outwardX Unit X direction pointing out of the stroke.
-     * @param {number} outwardY Unit Y direction pointing out of the stroke.
-     * @param {boolean} [includeSideWall] Whether to emit the cap perimeter wall.
+     * @param {number} outwardX Outward unit X.
+     * @param {number} outwardY Outward unit Y.
+     * @param {boolean} [includeSideWall] Emits cap perimeter wall.
      * @returns {void}
      */
     static #appendRoundCapTriangles(
@@ -771,9 +788,7 @@ export class PcbScene3dCopperFactory {
     ) {
         const safeRadius = Math.max(Number(radius || 0), 0)
         const outwardLength = Math.hypot(outwardX, outwardY)
-        if (safeRadius <= 0) {
-            return
-        }
+        if (safeRadius <= 0) return
         if (outwardLength <= 0.001) {
             PcbScene3dCopperFactory.#appendDiscTriangles(
                 positions,
@@ -916,7 +931,6 @@ export class PcbScene3dCopperFactory {
         const halfThickness = PcbScene3dCopperFactory.#COPPER_THICKNESS_MIL / 2
         const topZ = z + halfThickness
         const bottomZ = z - halfThickness
-
         positions.push(
             a.x,
             a.y,