pcb-scene3d-viewer 1.1.0 → 1.1.2

package/src/PcbScene3dCircularCutoutOverlap.mjs

@@ -0,0 +1,167 @@
+import { PcbScene3dCutoutCircleDetector } from './PcbScene3dCutoutCircleDetector.mjs'
+
+/**
+ * Resolves analytic overlap checks for sampled circular drill cutouts.
+ */
+export class PcbScene3dCircularCutoutOverlap {
+    /**
+     * Returns true when one triangle overlaps a circular cutout.
+     * @param {{ x: number, y: number }[]} triangle
+     * @param {{ points?: { x: number, y: number }[], centerX?: number, centerY?: number, radius?: number }} cutout
+     * @param {number} [epsilon]
+     * @returns {boolean}
+     */
+    static overlapsTriangle(triangle, cutout, epsilon = 0.001) {
+        const radius = Number(cutout?.radius || 0) + Number(epsilon || 0)
+        if (!Number.isFinite(radius) || radius <= 0) {
+            return false
+        }
+
+        const center = {
+            x: Number(cutout?.centerX || 0),
+            y: Number(cutout?.centerY || 0)
+        }
+        const radiusSquared = radius * radius
+
+        for (const point of triangle) {
+            if (
+                PcbScene3dCutoutCircleDetector.distanceSquared(point, cutout) <=
+                radiusSquared
+            ) {
+                return true
+            }
+        }
+
+        if (
+            PcbScene3dCircularCutoutOverlap.#isPointInsideOrOnTriangle(
+                center,
+                triangle,
+                epsilon
+            )
+        ) {
+            return true
+        }
+
+        for (let index = 0; index < triangle.length; index += 1) {
+            const current = triangle[index]
+            const next = triangle[(index + 1) % triangle.length]
+
+            if (
+                PcbScene3dCircularCutoutOverlap.#distanceToSegmentSquared(
+                    center,
+                    current,
+                    next,
+                    epsilon
+                ) <= radiusSquared
+            ) {
+                return true
+            }
+        }
+
+        return PcbScene3dCircularCutoutOverlap.#hasSampledBoundaryOverlap(
+            triangle,
+            cutout,
+            epsilon
+        )
+    }
+
+    /**
+     * Returns true when a sampled cutout boundary point lies in the triangle.
+     * @param {{ x: number, y: number }[]} triangle
+     * @param {{ points?: { x: number, y: number }[] }} cutout
+     * @param {number} epsilon
+     * @returns {boolean}
+     */
+    static #hasSampledBoundaryOverlap(triangle, cutout, epsilon) {
+        const boundaryPoints = Array.isArray(cutout?.points)
+            ? cutout.points
+            : []
+        const step = Math.max(1, Math.floor(boundaryPoints.length / 8))
+
+        for (let index = 0; index < boundaryPoints.length; index += step) {
+            if (
+                PcbScene3dCircularCutoutOverlap.#isPointInsideOrOnTriangle(
+                    boundaryPoints[index],
+                    triangle,
+                    epsilon
+                )
+            ) {
+                return true
+            }
+        }
+
+        return false
+    }
+
+    /**
+     * Returns true when a point is inside or on one triangle.
+     * @param {{ x: number, y: number }} point
+     * @param {{ x: number, y: number }[]} triangle
+     * @param {number} epsilon
+     * @returns {boolean}
+     */
+    static #isPointInsideOrOnTriangle(point, triangle, epsilon) {
+        let hasNegative = false
+        let hasPositive = false
+
+        for (let index = 0; index < triangle.length; index += 1) {
+            const current = triangle[index]
+            const next = triangle[(index + 1) % triangle.length]
+            const sign = PcbScene3dCircularCutoutOverlap.#cross(
+                point,
+                current,
+                next
+            )
+
+            hasNegative = hasNegative || sign < -epsilon
+            hasPositive = hasPositive || sign > epsilon
+        }
+
+        return !(hasNegative && hasPositive)
+    }
+
+    /**
+     * Resolves the squared distance from one point to a finite segment.
+     * @param {{ x: number, y: number }} point
+     * @param {{ x: number, y: number }} start
+     * @param {{ x: number, y: number }} end
+     * @param {number} epsilon
+     * @returns {number}
+     */
+    static #distanceToSegmentSquared(point, start, end, epsilon) {
+        const dx = end.x - start.x
+        const dy = end.y - start.y
+        const lengthSquared = dx * dx + dy * dy
+
+        if (lengthSquared <= epsilon) {
+            return (point.x - start.x) ** 2 + (point.y - start.y) ** 2
+        }
+
+        const ratio = Math.max(
+            0,
+            Math.min(
+                1,
+                ((point.x - start.x) * dx + (point.y - start.y) * dy) /
+                    lengthSquared
+            )
+        )
+        const projectedX = start.x + ratio * dx
+        const projectedY = start.y + ratio * dy
+
+        return (point.x - projectedX) ** 2 + (point.y - projectedY) ** 2
+    }
+
+    /**
+     * Resolves the signed area for three points.
+     * @param {{ x: number, y: number }} first
+     * @param {{ x: number, y: number }} second
+     * @param {{ x: number, y: number }} third
+     * @returns {number}
+     */
+    static #cross(first, second, third) {
+        return (
+            (second.x - first.x) * (third.y - first.y) -
+            (second.y - first.y) * (third.x - first.x)
+        )
+    }
+}

package/src/PcbScene3dComponentAdjustment.mjs

@@ -0,0 +1,174 @@
+/**
+ * Normalizes and applies live 3D component transform adjustments.
+ */
+export class PcbScene3dComponentAdjustment {
+    /**
+     * Finds transform adjustment targets beneath one scene object.
+     * @param {any} rootObject Root object.
+     * @returns {any[]}
+     */
+    static findTargets(rootObject) {
+        if (!rootObject) {
+            return []
+        }
+
+        const targets = rootObject?.userData?.scene3dAdjustmentTarget
+            ? [rootObject]
+            : []
+        ;(rootObject?.children || []).forEach((child) => {
+            targets.push(...PcbScene3dComponentAdjustment.findTargets(child))
+        })
+
+        return targets
+    }
+
+    /**
+     * Applies one live transform to a target relative to its original baseline.
+     * @param {any} THREE Three.js namespace.
+     * @param {any} target Target object.
+     * @param {{ scale?: { x?: number, y?: number, z?: number }, rotationDeg?: { x?: number, y?: number, z?: number }, offsetMil?: { x?: number, y?: number, z?: number } }} adjustment Adjustment.
+     * @returns {void}
+     */
+    static applyToTarget(THREE, target, adjustment) {
+        const current = PcbScene3dComponentAdjustment.normalize(adjustment)
+        const baseline = PcbScene3dComponentAdjustment.normalize(
+            target?.userData?.scene3dAdjustmentBaseline ||
+                PcbScene3dComponentAdjustment.neutral()
+        )
+        const delta = {
+            scale: {
+                x: PcbScene3dComponentAdjustment.#scaleRatio(
+                    current.scale.x,
+                    baseline.scale.x
+                ),
+                y: PcbScene3dComponentAdjustment.#scaleRatio(
+                    current.scale.y,
+                    baseline.scale.y
+                ),
+                z: PcbScene3dComponentAdjustment.#scaleRatio(
+                    current.scale.z,
+                    baseline.scale.z
+                )
+            },
+            rotationDeg: {
+                x: current.rotationDeg.x - baseline.rotationDeg.x,
+                y: current.rotationDeg.y - baseline.rotationDeg.y,
+                z: current.rotationDeg.z - baseline.rotationDeg.z
+            },
+            offsetMil: {
+                x: current.offsetMil.x - baseline.offsetMil.x,
+                y: current.offsetMil.y - baseline.offsetMil.y,
+                z: current.offsetMil.z - baseline.offsetMil.z
+            }
+        }
+
+        target?.position?.set?.(
+            delta.offsetMil.x,
+            delta.offsetMil.y,
+            delta.offsetMil.z
+        )
+        target?.scale?.set?.(delta.scale.x, delta.scale.y, delta.scale.z)
+        PcbScene3dComponentAdjustment.#applyRotation(THREE, target, delta)
+    }
+
+    /**
+     * Normalizes one adjustment object.
+     * @param {{ scale?: { x?: number, y?: number, z?: number }, rotationDeg?: { x?: number, y?: number, z?: number }, offsetMil?: { x?: number, y?: number, z?: number }, dxMil?: number, dyMil?: number, dzMil?: number } | null | undefined} adjustment Raw adjustment.
+     * @returns {{ scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }}
+     */
+    static normalize(adjustment) {
+        const scale = adjustment?.scale || {}
+        const rotationDeg = adjustment?.rotationDeg || {}
+        const offsetMil = adjustment?.offsetMil || {}
+
+        return {
+            scale: {
+                x: PcbScene3dComponentAdjustment.#numberOr(scale.x, 1),
+                y: PcbScene3dComponentAdjustment.#numberOr(scale.y, 1),
+                z: PcbScene3dComponentAdjustment.#numberOr(scale.z, 1)
+            },
+            rotationDeg: {
+                x: PcbScene3dComponentAdjustment.#numberOr(rotationDeg.x, 0),
+                y: PcbScene3dComponentAdjustment.#numberOr(rotationDeg.y, 0),
+                z: PcbScene3dComponentAdjustment.#numberOr(rotationDeg.z, 0)
+            },
+            offsetMil: {
+                x: PcbScene3dComponentAdjustment.#numberOr(
+                    offsetMil.x ?? adjustment?.dxMil,
+                    0
+                ),
+                y: PcbScene3dComponentAdjustment.#numberOr(
+                    offsetMil.y ?? adjustment?.dyMil,
+                    0
+                ),
+                z: PcbScene3dComponentAdjustment.#numberOr(
+                    offsetMil.z ?? adjustment?.dzMil,
+                    0
+                )
+            }
+        }
+    }
+
+    /**
+     * Returns a neutral transform adjustment.
+     * @returns {{ scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }}
+     */
+    static neutral() {
+        return {
+            scale: { x: 1, y: 1, z: 1 },
+            rotationDeg: { x: 0, y: 0, z: 0 },
+            offsetMil: { x: 0, y: 0, z: 0 }
+        }
+    }
+
+    /**
+     * Applies KiCad-style model-local rotation order to an adjustment target.
+     * @param {any} THREE Three.js namespace.
+     * @param {any} target Target object.
+     * @param {{ rotationDeg: { x: number, y: number, z: number } }} adjustment Rotation adjustment.
+     * @returns {void}
+     */
+    static #applyRotation(THREE, target, adjustment) {
+        const x = (-Number(adjustment.rotationDeg.x || 0) * Math.PI) / 180
+        const y = (-Number(adjustment.rotationDeg.y || 0) * Math.PI) / 180
+        const z = (-Number(adjustment.rotationDeg.z || 0) * Math.PI) / 180
+
+        if (THREE?.Matrix4 && target?.quaternion?.setFromRotationMatrix) {
+            const rotationMatrix = new THREE.Matrix4()
+                .makeRotationZ(z)
+                .multiply(new THREE.Matrix4().makeRotationY(y))
+                .multiply(new THREE.Matrix4().makeRotationX(x))
+            target.quaternion.setFromRotationMatrix(rotationMatrix)
+            return
+        }
+
+        if (!target?.rotation) {
+            return
+        }
+
+        target.rotation.x = x
+        target.rotation.y = y
+        target.rotation.z = z
+    }
+
+    /**
+     * Returns a finite number or a fallback.
+     * @param {unknown} value Source value.
+     * @param {number} fallback Fallback value.
+     * @returns {number}
+     */
+    static #numberOr(value, fallback) {
+        const numericValue = Number(value)
+        return Number.isFinite(numericValue) ? numericValue : fallback
+    }
+
+    /**
+     * Computes a safe scale ratio.
+     * @param {number} value Current value.
+     * @param {number} baseline Baseline value.
+     * @returns {number}
+     */
+    static #scaleRatio(value, baseline) {
+        return baseline === 0 ? value : value / baseline
+    }
+}

package/src/PcbScene3dComponentAdjustmentRegistry.mjs

@@ -0,0 +1,95 @@
+import { PcbScene3dComponentAdjustment } from './PcbScene3dComponentAdjustment.mjs'
+
+/**
+ * Tracks live transform adjustments and applies them to registered targets.
+ */
+export class PcbScene3dComponentAdjustmentRegistry {
+    /** @type {() => any} */
+    #resolveThree
+    /** @type {Map<string, Set<any>>} */
+    #targets
+    /** @type {Map<string, { scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }>} */
+    #adjustments
+
+    /**
+     * @param {() => any} resolveThree Three.js namespace resolver.
+     */
+    constructor(resolveThree) {
+        this.#resolveThree = resolveThree
+        this.#targets = new Map()
+        this.#adjustments = new Map()
+    }
+
+    /** @returns {void} */
+    clear() {
+        this.#targets.clear()
+        this.#adjustments.clear()
+    }
+
+    /**
+     * Applies a live model-local adjustment to one component.
+     * @param {string} designator Component designator.
+     * @param {{ scale?: { x?: number, y?: number, z?: number }, rotationDeg?: { x?: number, y?: number, z?: number }, offsetMil?: { x?: number, y?: number, z?: number } }} adjustment Transform adjustment.
+     * @returns {boolean}
+     */
+    set(designator, adjustment) {
+        const normalizedDesignator = String(designator || '').trim()
+        if (!normalizedDesignator) {
+            return false
+        }
+
+        const normalizedAdjustment =
+            PcbScene3dComponentAdjustment.normalize(adjustment)
+        this.#adjustments.set(normalizedDesignator, normalizedAdjustment)
+        this.#apply(normalizedDesignator, normalizedAdjustment)
+        return true
+    }
+
+    /**
+     * Registers one model-local transform adjustment target.
+     * @param {string | undefined} designator Component designator.
+     * @param {any} target Target object.
+     * @returns {void}
+     */
+    register(designator, target) {
+        const normalizedDesignator = String(designator || '').trim()
+        if (!normalizedDesignator || !target) {
+            return
+        }
+
+        if (!this.#targets.has(normalizedDesignator)) {
+            this.#targets.set(normalizedDesignator, new Set())
+        }
+
+        this.#targets.get(normalizedDesignator)?.add(target)
+        const pendingAdjustment = this.#adjustments.get(normalizedDesignator)
+        if (pendingAdjustment) {
+            PcbScene3dComponentAdjustment.applyToTarget(
+                this.#resolveThree(),
+                target,
+                pendingAdjustment
+            )
+        }
+    }
+
+    /**
+     * Applies one adjustment to all known targets for a component.
+     * @param {string} designator Component designator.
+     * @param {{ scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }} adjustment Adjustment.
+     * @returns {void}
+     */
+    #apply(designator, adjustment) {
+        const targets = this.#targets.get(designator)
+        if (!targets) {
+            return
+        }
+
+        targets.forEach((target) => {
+            PcbScene3dComponentAdjustment.applyToTarget(
+                this.#resolveThree(),
+                target,
+                adjustment
+            )
+        })
+    }
+}