pcb-scene3d-viewer 1.0.1

package/src/PcbScene3dDetailCoordinateNormalizer.mjs

@@ -0,0 +1,65 @@
+/**
+ * Normalizes PCB detail primitive coordinates into the runtime board plane.
+ */
+export class PcbScene3dDetailCoordinateNormalizer {
+    /**
+     * Creates a reusable normalizer for one scene description.
+     * @param {{ board?: { centerX?: number, centerY?: number }, boardAssemblyModel?: any, coordinateSystem?: string, sourceFormat?: string } | null} sceneDescription Scene metadata.
+     * @returns {(x: number, y: number) => { x: number, y: number }}
+     */
+    static create(sceneDescription) {
+        return (x, y) =>
+            PcbScene3dDetailCoordinateNormalizer.normalize(
+                sceneDescription,
+                x,
+                y
+            )
+    }
+
+    /**
+     * Normalizes one source detail coordinate into centered scene space.
+     * @param {{ board?: { centerX?: number, centerY?: number }, boardAssemblyModel?: any, coordinateSystem?: string, sourceFormat?: string } | null} sceneDescription Scene metadata.
+     * @param {number} x Source X coordinate.
+     * @param {number} y Source Y coordinate.
+     * @returns {{ x: number, y: number }}
+     */
+    static normalize(sceneDescription, x, y) {
+        const board = sceneDescription?.board || {}
+        const centerX = Number(board.centerX || 0)
+        const centerY = Number(board.centerY || 0)
+        const sourceX = Number(x || 0)
+        const sourceY = Number(y || 0)
+
+        return {
+            x: sourceX - centerX,
+            y: PcbScene3dDetailCoordinateNormalizer.#usesAssemblyModelPcbY(
+                sceneDescription
+            )
+                ? centerY - sourceY
+                : sourceY - centerY
+        }
+    }
+
+    /**
+     * Checks whether detail primitives are being aligned to an assembly model
+     * that still uses the source PCB Y axis.
+     * @param {{ boardAssemblyModel?: any, coordinateSystem?: string, sourceFormat?: string } | null} sceneDescription Scene metadata.
+     * @returns {boolean}
+     */
+    static #usesAssemblyModelPcbY(sceneDescription) {
+        if (
+            String(sceneDescription?.coordinateSystem || '') === 'kicad-3d-y-up'
+        ) {
+            return false
+        }
+
+        const sourceFormat = String(
+            sceneDescription?.sourceFormat || ''
+        ).toLowerCase()
+
+        return (
+            sourceFormat === 'altium' &&
+            Boolean(sceneDescription?.boardAssemblyModel)
+        )
+    }
+}

package/src/PcbScene3dDrillCutoutFilter.mjs

@@ -0,0 +1,224 @@
+/**
+ * Filters drill cutout polygons before they are applied to filled artwork.
+ */
+export class PcbScene3dDrillCutoutFilter {
+    static #GEOMETRY_EPSILON = 0.001
+
+    /**
+     * Removes drill cutouts that are already covered by authored fill holes.
+     * @param {{ x: number, y: number }[][]} drillCutouts
+     * @param {{ x: number, y: number }[][]} fillHoles
+     * @returns {{ x: number, y: number }[][]}
+     */
+    static removeCoveredCutouts(drillCutouts, fillHoles) {
+        return PcbScene3dDrillCutoutFilter.partitionFillHoles(
+            drillCutouts,
+            fillHoles
+        ).uncoveredCutouts
+    }
+
+    /**
+     * Splits authored holes from physical drill holes already copied to a fill.
+     * @param {{ x: number, y: number }[][]} drillCutouts
+     * @param {{ x: number, y: number }[][]} fillHoles
+     * @returns {{ authoredHoles: { x: number, y: number }[][], drillHoles: { x: number, y: number }[][], uncoveredCutouts: { x: number, y: number }[][] }}
+     */
+    static partitionFillHoles(drillCutouts, fillHoles) {
+        const cutouts = Array.isArray(drillCutouts) ? drillCutouts : []
+        const holes = Array.isArray(fillHoles) ? fillHoles : []
+
+        if (!holes.length) {
+            return {
+                authoredHoles: [],
+                drillHoles: [],
+                uncoveredCutouts: cutouts
+            }
+        }
+
+        if (!cutouts.length) {
+            return {
+                authoredHoles: holes,
+                drillHoles: [],
+                uncoveredCutouts: []
+            }
+        }
+
+        const authoredHoles = []
+        const drillHoles = []
+        for (const hole of holes) {
+            if (PcbScene3dDrillCutoutFilter.#isDrillHole(hole, cutouts)) {
+                drillHoles.push(hole)
+            } else {
+                authoredHoles.push(hole)
+            }
+        }
+
+        return {
+            authoredHoles,
+            drillHoles,
+            uncoveredCutouts: cutouts.filter(
+                (cutout) =>
+                    !holes.some((hole) =>
+                        PcbScene3dDrillCutoutFilter.#doesHoleCoverCutout(
+                            hole,
+                            cutout
+                        )
+                    )
+            )
+        }
+    }
+
+    /**
+     * Returns true when a fill hole represents one known drill cutout.
+     * @param {{ x: number, y: number }[]} hole
+     * @param {{ x: number, y: number }[][]} drillCutouts
+     * @returns {boolean}
+     */
+    static #isDrillHole(hole, drillCutouts) {
+        return drillCutouts.some((cutout) =>
+            PcbScene3dDrillCutoutFilter.#doesHoleCoverCutout(hole, cutout)
+        )
+    }
+
+    /**
+     * Returns true when an authored hole already clears one drill cutout.
+     * @param {{ x: number, y: number }[]} hole
+     * @param {{ x: number, y: number }[]} cutout
+     * @returns {boolean}
+     */
+    static #doesHoleCoverCutout(hole, cutout) {
+        return (
+            Array.isArray(hole) &&
+            hole.length >= 3 &&
+            Array.isArray(cutout) &&
+            cutout.length >= 3 &&
+            PcbScene3dDrillCutoutFilter.#isPointInsideOrOnPolygon(
+                PcbScene3dDrillCutoutFilter.#resolvePolygonCentroid(cutout),
+                hole
+            ) &&
+            cutout.every((point) =>
+                PcbScene3dDrillCutoutFilter.#isPointInsideOrOnPolygon(
+                    point,
+                    hole
+                )
+            )
+        )
+    }
+
+    /**
+     * Resolves the average center of one polygon.
+     * @param {{ x: number, y: number }[]} points
+     * @returns {{ x: number, y: number }}
+     */
+    static #resolvePolygonCentroid(points) {
+        const totals = points.reduce(
+            (accumulator, point) => ({
+                x: accumulator.x + Number(point.x || 0),
+                y: accumulator.y + Number(point.y || 0)
+            }),
+            { x: 0, y: 0 }
+        )
+        const count = Math.max(points.length, 1)
+
+        return {
+            x: totals.x / count,
+            y: totals.y / count
+        }
+    }
+
+    /**
+     * Returns true when a point is inside or on one polygon.
+     * @param {{ x: number, y: number }} point
+     * @param {{ x: number, y: number }[]} polygon
+     * @returns {boolean}
+     */
+    static #isPointInsideOrOnPolygon(point, polygon) {
+        return (
+            PcbScene3dDrillCutoutFilter.#isPointOnPolygonBoundary(
+                point,
+                polygon
+            ) ||
+            PcbScene3dDrillCutoutFilter.#isPointStrictlyInsidePolygon(
+                point,
+                polygon
+            )
+        )
+    }
+
+    /**
+     * Returns true when a point lies inside a polygon and away from its border.
+     * @param {{ x: number, y: number }} point
+     * @param {{ x: number, y: number }[]} polygon
+     * @returns {boolean}
+     */
+    static #isPointStrictlyInsidePolygon(point, polygon) {
+        let inside = false
+        for (
+            let index = 0, previousIndex = polygon.length - 1;
+            index < polygon.length;
+            previousIndex = index, index += 1
+        ) {
+            const current = polygon[index]
+            const previous = polygon[previousIndex]
+            const intersects =
+                current.y > point.y !== previous.y > point.y &&
+                point.x <
+                    ((previous.x - current.x) * (point.y - current.y)) /
+                        (previous.y - current.y) +
+                        current.x
+
+            if (intersects) {
+                inside = !inside
+            }
+        }
+
+        return inside
+    }
+
+    /**
+     * Returns true when a point lies on any polygon edge.
+     * @param {{ x: number, y: number }} point
+     * @param {{ x: number, y: number }[]} polygon
+     * @returns {boolean}
+     */
+    static #isPointOnPolygonBoundary(point, polygon) {
+        return polygon.some((start, index) =>
+            PcbScene3dDrillCutoutFilter.#isPointOnSegment(
+                point,
+                start,
+                polygon[(index + 1) % polygon.length]
+            )
+        )
+    }
+
+    /**
+     * Returns true when a point lies on one finite segment.
+     * @param {{ x: number, y: number }} point
+     * @param {{ x: number, y: number }} start
+     * @param {{ x: number, y: number }} end
+     * @returns {boolean}
+     */
+    static #isPointOnSegment(point, start, end) {
+        const cross =
+            (point.y - start.y) * (end.x - start.x) -
+            (point.x - start.x) * (end.y - start.y)
+
+        if (Math.abs(cross) > PcbScene3dDrillCutoutFilter.#GEOMETRY_EPSILON) {
+            return false
+        }
+
+        const dot =
+            (point.x - start.x) * (end.x - start.x) +
+            (point.y - start.y) * (end.y - start.y)
+
+        if (dot < -PcbScene3dDrillCutoutFilter.#GEOMETRY_EPSILON) {
+            return false
+        }
+
+        const lengthSquared = (end.x - start.x) ** 2 + (end.y - start.y) ** 2
+
+        return (
+            dot <= lengthSquared + PcbScene3dDrillCutoutFilter.#GEOMETRY_EPSILON
+        )
+    }
+}

package/src/PcbScene3dDrillPathFactory.mjs

@@ -0,0 +1,362 @@
+/**
+ * Builds reusable circular and slotted drill paths for the 3D PCB scene.
+ */
+export class PcbScene3dDrillPathFactory {
+    static #PAD_HOLE_SHAPE_SLOT = 2
+    static #ARC_SEGMENTS = 12
+
+    /**
+     * Appends all board drill holes from pads and vias to one board shape.
+     * @param {any} THREE
+     * @param {any} shape
+     * @param {{ pads?: any[], vias?: any[] }} detail
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @returns {void}
+     */
+    static appendBoardDrills(THREE, shape, detail, normalizeBoardPoint) {
+        for (const drillSpec of PcbScene3dDrillPathFactory.resolveBoardDrillSpecs(
+            detail
+        )) {
+            const point = normalizeBoardPoint(drillSpec.x, drillSpec.y)
+            const holePath = PcbScene3dDrillPathFactory.buildDrillPath(THREE, {
+                ...drillSpec,
+                x: point.x,
+                y: point.y
+            })
+            if (!holePath) {
+                continue
+            }
+
+            shape.holes.push(holePath)
+        }
+    }
+
+    /**
+     * Resolves deduped board-space drill specs from pads and vias.
+     * @param {{ pads?: any[], vias?: any[] }} detail
+     * @returns {{ x: number, y: number, diameter: number, slotLength?: number | null, rotationDeg?: number | null }[]}
+     */
+    static resolveBoardDrillSpecs(detail) {
+        const seen = new Set()
+        const drillSpecs = [
+            ...PcbScene3dDrillPathFactory.#resolveViaDrillSpecs(
+                detail?.vias || []
+            ),
+            ...PcbScene3dDrillPathFactory.#resolvePadDrillSpecs(
+                detail?.pads || []
+            )
+        ]
+        const output = []
+
+        for (const drillSpec of drillSpecs) {
+            const key = PcbScene3dDrillPathFactory.#buildCacheKey(drillSpec)
+            if (seen.has(key)) {
+                continue
+            }
+
+            seen.add(key)
+            output.push(drillSpec)
+        }
+
+        return output
+    }
+
+    /**
+     * Builds one local pad drill path centered on the pad origin.
+     * @param {any} THREE
+     * @param {{ holeDiameter?: number, holeShape?: number | null, holeSlotLength?: number | null, holeRotation?: number | null, rotation?: number | null }} pad
+     * @returns {any | null}
+     */
+    static buildPadHolePath(THREE, pad) {
+        const drillSpec = PcbScene3dDrillPathFactory.#resolvePadDrillSpec(pad)
+        return drillSpec
+            ? PcbScene3dDrillPathFactory.buildDrillPath(THREE, {
+                  ...drillSpec,
+                  x: 0,
+                  y: 0
+              })
+            : null
+    }
+
+    /**
+     * Builds one local via drill path centered on the via origin.
+     * @param {any} THREE
+     * @param {{ holeDiameter?: number }} via
+     * @returns {any | null}
+     */
+    static buildViaHolePath(THREE, via) {
+        const holeDiameter = Number(via?.holeDiameter || 0)
+        if (holeDiameter <= 0) {
+            return null
+        }
+
+        return PcbScene3dDrillPathFactory.buildDrillPath(THREE, {
+            x: 0,
+            y: 0,
+            diameter: holeDiameter,
+            slotLength: null,
+            rotationDeg: 0
+        })
+    }
+
+    /**
+     * Builds one drill path from a normalized drill descriptor.
+     * @param {any} THREE
+     * @param {{ x: number, y: number, diameter: number, slotLength?: number | null, rotationDeg?: number | null }} drillSpec
+     * @returns {any | null}
+     */
+    static buildDrillPath(THREE, drillSpec) {
+        const diameter = Number(drillSpec?.diameter || 0)
+        if (diameter <= 0) {
+            return null
+        }
+
+        if (Number(drillSpec?.slotLength || 0) > diameter + 0.001) {
+            return PcbScene3dDrillPathFactory.#buildSlotPath(THREE, drillSpec)
+        }
+
+        return PcbScene3dDrillPathFactory.#buildCirclePath(THREE, drillSpec)
+    }
+
+    /**
+     * Resolves board-space via drill specs from normalized via detail.
+     * @param {{ x?: number, y?: number, holeDiameter?: number }[]} vias
+     * @returns {{ x: number, y: number, diameter: number, slotLength: null, rotationDeg: 0 }[]}
+     */
+    static #resolveViaDrillSpecs(vias) {
+        return (vias || [])
+            .map((via) => {
+                const diameter = Number(via?.holeDiameter || 0)
+                if (diameter <= 0) {
+                    return null
+                }
+
+                return {
+                    x: Number(via?.x || 0),
+                    y: Number(via?.y || 0),
+                    diameter,
+                    slotLength: null,
+                    rotationDeg: 0
+                }
+            })
+            .filter(Boolean)
+    }
+
+    /**
+     * Resolves board-space pad drill specs from normalized pad detail.
+     * @param {any[]} pads
+     * @returns {{ x: number, y: number, diameter: number, slotLength?: number | null, rotationDeg?: number | null }[]}
+     */
+    static #resolvePadDrillSpecs(pads) {
+        return (pads || [])
+            .map((pad) => {
+                const drillSpec =
+                    PcbScene3dDrillPathFactory.#resolvePadDrillSpec(pad)
+                if (!drillSpec) {
+                    return null
+                }
+
+                return {
+                    ...drillSpec,
+                    x: Number(pad?.x || 0),
+                    y: Number(pad?.y || 0),
+                    rotationDeg:
+                        drillSpec.slotLength === null
+                            ? 0
+                            : PcbScene3dDrillPathFactory.#normalizeAngle(
+                                  Number(pad?.rotation || 0) +
+                                      Number(drillSpec.rotationDeg || 0)
+                              )
+                }
+            })
+            .filter(Boolean)
+    }
+
+    /**
+     * Resolves one pad-local drill spec when the pad is through-hole.
+     * @param {{ holeDiameter?: number, holeShape?: number | null, holeSlotLength?: number | null, holeRotation?: number | null }} pad
+     * @returns {{ diameter: number, slotLength?: number | null, rotationDeg?: number | null } | null}
+     */
+    static #resolvePadDrillSpec(pad) {
+        const diameter = Number(pad?.holeDiameter || 0)
+        if (diameter <= 0) {
+            return null
+        }
+
+        const slotLength =
+            Number(pad?.holeShape) ===
+                PcbScene3dDrillPathFactory.#PAD_HOLE_SHAPE_SLOT &&
+            Number(pad?.holeSlotLength || 0) > diameter
+                ? Number(pad?.holeSlotLength || 0)
+                : null
+
+        return {
+            diameter,
+            slotLength,
+            rotationDeg: Number(pad?.holeRotation || 0)
+        }
+    }
+
+    /**
+     * Builds one circular drill path.
+     * @param {any} THREE
+     * @param {{ x: number, y: number, diameter: number }} drillSpec
+     * @returns {any}
+     */
+    static #buildCirclePath(THREE, drillSpec) {
+        const radius = Math.max(Number(drillSpec.diameter || 0) / 2, 0.6)
+        const path = new THREE.Path()
+        const centerX = Number(drillSpec.x || 0)
+        const centerY = Number(drillSpec.y || 0)
+
+        path.moveTo(centerX + radius, centerY)
+        path.absarc(centerX, centerY, radius, 0, Math.PI, false)
+        path.absarc(centerX, centerY, radius, Math.PI, Math.PI * 2, false)
+        path.closePath()
+        return path
+    }
+
+    /**
+     * Builds one slotted drill path as a rotated rounded rectangle.
+     * @param {any} THREE
+     * @param {{ x: number, y: number, diameter: number, slotLength?: number | null, rotationDeg?: number | null }} drillSpec
+     * @returns {any}
+     */
+    static #buildSlotPath(THREE, drillSpec) {
+        const points = PcbScene3dDrillPathFactory.#buildSlotPoints(drillSpec)
+        const path = new THREE.Path()
+
+        if (!points.length) {
+            return path
+        }
+
+        path.moveTo(points[0].x, points[0].y)
+        for (let index = 1; index < points.length; index += 1) {
+            path.lineTo(points[index].x, points[index].y)
+        }
+        path.closePath()
+        return path
+    }
+
+    /**
+     * Builds one rotated slot outline as sampled points.
+     * @param {{ x: number, y: number, diameter: number, slotLength?: number | null, rotationDeg?: number | null }} drillSpec
+     * @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 sampledPoints = []
+
+        PcbScene3dDrillPathFactory.#appendArcPoints(
+            sampledPoints,
+            straightHalf,
+            0,
+            radius,
+            -Math.PI / 2,
+            Math.PI / 2
+        )
+        PcbScene3dDrillPathFactory.#appendArcPoints(
+            sampledPoints,
+            -straightHalf,
+            0,
+            radius,
+            Math.PI / 2,
+            (Math.PI * 3) / 2,
+            true
+        )
+
+        return sampledPoints.map((point) =>
+            PcbScene3dDrillPathFactory.#rotateAndTranslatePoint(
+                point,
+                rotationRad,
+                Number(drillSpec.x || 0),
+                Number(drillSpec.y || 0)
+            )
+        )
+    }
+
+    /**
+     * Appends sampled points for one drill-cap arc.
+     * @param {{ x: number, y: number }[]} points
+     * @param {number} cx
+     * @param {number} cy
+     * @param {number} radius
+     * @param {number} startAngle
+     * @param {number} endAngle
+     * @param {boolean} [skipFirst]
+     * @returns {void}
+     */
+    static #appendArcPoints(
+        points,
+        cx,
+        cy,
+        radius,
+        startAngle,
+        endAngle,
+        skipFirst = false
+    ) {
+        for (
+            let index = 0;
+            index <= PcbScene3dDrillPathFactory.#ARC_SEGMENTS;
+            index += 1
+        ) {
+            if (skipFirst && index === 0) {
+                continue
+            }
+
+            const t = index / PcbScene3dDrillPathFactory.#ARC_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
+     * @param {number} rotationRad
+     * @param {number} dx
+     * @param {number} dy
+     * @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
+        }
+    }
+
+    /**
+     * Builds one stable dedupe key for a board drill.
+     * @param {{ x: number, y: number, diameter: number, slotLength?: number | null, rotationDeg?: number | null }} drillSpec
+     * @returns {string}
+     */
+    static #buildCacheKey(drillSpec) {
+        return [
+            Number(drillSpec.x || 0).toFixed(4),
+            Number(drillSpec.y || 0).toFixed(4),
+            Number(drillSpec.diameter || 0).toFixed(4),
+            Number(drillSpec.slotLength || 0).toFixed(4),
+            Number(drillSpec.rotationDeg || 0).toFixed(4)
+        ].join(':')
+    }
+
+    /**
+     * Normalizes one angle into the inclusive `[0, 360)` range.
+     * @param {number} angleDeg
+     * @returns {number}
+     */
+    static #normalizeAngle(angleDeg) {
+        const normalized = Number(angleDeg || 0) % 360
+        return normalized < 0 ? normalized + 360 : normalized
+    }
+}