okgeometry-api 0.4.3 → 0.4.5

package/dist/Mesh.js

@@ -9,7 +9,10 @@ import { Polygon } from "./Polygon.js";
 import { NurbsCurve } from "./NurbsCurve.js";
 import { PolyCurve } from "./PolyCurve.js";
 import { pointsToCoords, parsePolylineBuffer as parsePolylineBuf } from "./BufferCodec.js";
+import { configureDefaultMeshBooleanWorkerPool, disposeMeshBooleanWorkerPools, runMeshBooleanInWorkerPool, } from "./mesh-boolean.pool.js";
+import { MeshBooleanExecutionError } from "./mesh-boolean.protocol.js";
 import * as wasm from "../wasm/okgeometrycore_bg.js";
+export { MeshBooleanExecutionError };
 /**
  * Buffer-backed triangle mesh with GPU-ready accessors.
  * All geometry lives in a Float64Array from WASM.
@@ -27,6 +30,72 @@ export class Mesh {
         this._buffer = buffer;
         this._vertexCount = buffer.length > 0 ? buffer[0] : 0;
     }
+    /**
+     * Configure default size for the shared boolean worker pool.
+     */
+    static configureBooleanWorkerPool(options) {
+        configureDefaultMeshBooleanWorkerPool(options);
+    }
+    /**
+     * Dispose all shared boolean worker pools.
+     */
+    static disposeBooleanWorkerPools() {
+        disposeMeshBooleanWorkerPools();
+    }
+    static resolveBooleanLimits(overrides) {
+        const defaults = Mesh.DEFAULT_BOOLEAN_LIMITS;
+        return {
+            maxInputFacesPerMesh: overrides?.maxInputFacesPerMesh ?? defaults.maxInputFacesPerMesh,
+            maxCombinedInputFaces: overrides?.maxCombinedInputFaces ?? defaults.maxCombinedInputFaces,
+            maxFaceProduct: overrides?.maxFaceProduct ?? defaults.maxFaceProduct,
+        };
+    }
+    static computeRawBounds(mesh) {
+        if (mesh._vertexCount <= 0)
+            return null;
+        const data = mesh._buffer;
+        const limit = 1 + mesh._vertexCount * 3;
+        let minX = data[1];
+        let minY = data[2];
+        let minZ = data[3];
+        let maxX = minX;
+        let maxY = minY;
+        let maxZ = minZ;
+        for (let i = 4; i < limit; i += 3) {
+            const x = data[i];
+            const y = data[i + 1];
+            const z = data[i + 2];
+            if (x < minX)
+                minX = x;
+            if (y < minY)
+                minY = y;
+            if (z < minZ)
+                minZ = z;
+            if (x > maxX)
+                maxX = x;
+            if (y > maxY)
+                maxY = y;
+            if (z > maxZ)
+                maxZ = z;
+        }
+        return { minX, minY, minZ, maxX, maxY, maxZ };
+    }
+    static boundsOverlap(a, b, eps = 1e-9) {
+        if (!a || !b)
+            return false;
+        return a.minX <= b.maxX + eps
+            && a.maxX + eps >= b.minX
+            && a.minY <= b.maxY + eps
+            && a.maxY + eps >= b.minY
+            && a.minZ <= b.maxZ + eps
+            && a.maxZ + eps >= b.minZ;
+    }
+    static cloneMesh(mesh) {
+        return Mesh.fromBuffer(new Float64Array(mesh._buffer));
+    }
+    static emptyMesh() {
+        return Mesh.fromBuffer(new Float64Array(0));
+    }
     // ── GPU-ready buffers ──────────────────────────────────────────
     /**
      * Float32 xyz positions for Three.js BufferGeometry.
@@ -110,6 +179,226 @@ export class Mesh {
     static fromBuffer(buffer) {
         return new Mesh(buffer);
     }
+    /**
+     * Build an axis-aligned rectangle on a plane basis from opposite corners.
+     * The resulting corners are ordered [p0, p1, p2, p3] and form a closed loop.
+     */
+    static buildPlanarRectangle(startPoint, endPoint, uAxis, vAxis) {
+        const delta = endPoint.sub(startPoint);
+        const uLen = delta.dot(uAxis);
+        const vLen = delta.dot(vAxis);
+        const p0 = startPoint;
+        const p1 = startPoint.add(uAxis.scale(uLen));
+        const p3 = startPoint.add(vAxis.scale(vLen));
+        const p2 = p1.add(vAxis.scale(vLen));
+        return {
+            corners: [p0, p1, p2, p3],
+            width: Math.abs(uLen),
+            height: Math.abs(vLen),
+        };
+    }
+    /**
+     * Build a planar circle from center and a point on/near its radius direction.
+     * Radius is measured in the plane orthogonal to `normal`.
+     */
+    static buildPlanarCircle(center, radiusPoint, normal, segments = 64) {
+        const n = normal.normalize();
+        const radial = radiusPoint.sub(center);
+        const radialInPlane = radial.sub(n.scale(radial.dot(n)));
+        const radius = radialInPlane.length();
+        if (radius < 1e-12 || segments < 3) {
+            return { points: [], radius: 0 };
+        }
+        const circle = new Circle(center, radius, n);
+        return {
+            points: circle.sample(Math.floor(segments)),
+            radius,
+        };
+    }
+    /**
+     * Build a planar arc from center, start, and end points.
+     * Uses the shortest signed sweep between start and end around `normal`.
+     */
+    static buildPlanarArcCenterStartEnd(center, startPoint, endPoint, normal, segments = 64) {
+        const n = normal.normalize();
+        const minSegments = Math.max(2, Math.floor(segments));
+        const startRaw = startPoint.sub(center);
+        const endRaw = endPoint.sub(center);
+        const startVec = startRaw.sub(n.scale(startRaw.dot(n)));
+        const endVec = endRaw.sub(n.scale(endRaw.dot(n)));
+        const radius = startVec.length();
+        const endLen = endVec.length();
+        if (radius < 1e-12 || endLen < 1e-12) {
+            return {
+                points: [],
+                center,
+                radius: 0,
+                startAngle: 0,
+                endAngle: 0,
+                sweepAngle: 0,
+            };
+        }
+        const basis = Mesh.resolveArcBasis(center, radius, n);
+        const startAngle = Mesh.angleOnBasis(startVec, basis.uAxis, basis.vAxis);
+        const endAngleRaw = Mesh.angleOnBasis(endVec.scale(radius / endLen), basis.uAxis, basis.vAxis);
+        const sweepAngle = Mesh.normalizeSignedAngle(endAngleRaw - startAngle);
+        if (Math.abs(sweepAngle) < 1e-9) {
+            return {
+                points: [],
+                center,
+                radius: 0,
+                startAngle: 0,
+                endAngle: 0,
+                sweepAngle: 0,
+            };
+        }
+        const endAngle = startAngle + sweepAngle;
+        const arc = new Arc(center, radius, startAngle, endAngle, n);
+        return {
+            points: arc.sample(minSegments),
+            center,
+            radius,
+            startAngle,
+            endAngle,
+            sweepAngle,
+        };
+    }
+    /**
+     * Build a planar arc from start/end points and a radius control point.
+     * Radius is measured from start point to radiusPoint in the active plane.
+     * The best of 4 candidates (2 centers x minor/major sweeps) is selected by
+     * midpoint proximity to radiusPoint.
+     */
+    static buildPlanarArcStartEndRadius(startPoint, endPoint, radiusPoint, normal, segments = 64) {
+        const n = normal.normalize();
+        const minSegments = Math.max(2, Math.floor(segments));
+        const start = Mesh.projectPointToPlane(startPoint, startPoint, n);
+        const end = Mesh.projectPointToPlane(endPoint, startPoint, n);
+        const guide = Mesh.projectPointToPlane(radiusPoint, startPoint, n);
+        const chord = end.sub(start);
+        const chordLength = chord.length();
+        if (chordLength < 1e-9) {
+            return null;
+        }
+        const radius = guide.sub(start).length();
+        const halfChord = chordLength * 0.5;
+        if (!Number.isFinite(radius) || radius < halfChord + 1e-9) {
+            return null;
+        }
+        const chordDir = chord.scale(1 / chordLength);
+        const perpRaw = n.cross(chordDir);
+        const perpLen = perpRaw.length();
+        if (perpLen < 1e-12) {
+            return null;
+        }
+        const perp = perpRaw.scale(1 / perpLen);
+        const hSq = radius * radius - halfChord * halfChord;
+        if (hSq < 0) {
+            return null;
+        }
+        const h = Math.sqrt(Math.max(0, hSq));
+        const mid = start.add(chord.scale(0.5));
+        const centers = [mid.add(perp.scale(h)), mid.add(perp.scale(-h))];
+        const candidates = [];
+        for (const center of centers) {
+            const startVec = start.sub(center);
+            const endVec = end.sub(center);
+            if (startVec.length() < 1e-12 || endVec.length() < 1e-12) {
+                continue;
+            }
+            const basis = Mesh.resolveArcBasis(center, radius, n);
+            const startAngle = Mesh.angleOnBasis(startVec, basis.uAxis, basis.vAxis);
+            const endAngleRaw = Mesh.angleOnBasis(endVec, basis.uAxis, basis.vAxis);
+            const minorSweep = Mesh.normalizeSignedAngle(endAngleRaw - startAngle);
+            if (Math.abs(minorSweep) < 1e-9) {
+                continue;
+            }
+            const majorSweep = minorSweep > 0
+                ? minorSweep - Math.PI * 2
+                : minorSweep + Math.PI * 2;
+            const sweepOptions = [minorSweep];
+            if (Math.abs(majorSweep) > 1e-9) {
+                sweepOptions.push(majorSweep);
+            }
+            for (const sweepAngle of sweepOptions) {
+                const endAngle = startAngle + sweepAngle;
+                const arc = new Arc(center, radius, startAngle, endAngle, n);
+                const midPoint = arc.pointAt(0.5);
+                candidates.push({
+                    center,
+                    radius,
+                    startAngle,
+                    endAngle,
+                    sweepAngle,
+                    points: arc.sample(minSegments),
+                    score: midPoint.distanceTo(guide),
+                });
+            }
+        }
+        if (candidates.length === 0) {
+            return null;
+        }
+        candidates.sort((a, b) => a.score - b.score);
+        const winner = candidates[0];
+        return {
+            points: winner.points,
+            center: winner.center,
+            radius: winner.radius,
+            startAngle: winner.startAngle,
+            endAngle: winner.endAngle,
+            sweepAngle: winner.sweepAngle,
+        };
+    }
+    static resolveArcBasis(center, radius, normal) {
+        if (radius > 1e-12) {
+            const circle = new Circle(center, radius, normal);
+            const p0 = circle.pointAt(0);
+            const pQuarter = circle.pointAt(0.25);
+            const uRaw = p0.sub(center);
+            const vRaw = pQuarter.sub(center);
+            const uLen = uRaw.length();
+            const vLen = vRaw.length();
+            if (uLen > 1e-12 && vLen > 1e-12) {
+                return {
+                    uAxis: uRaw.scale(1 / uLen),
+                    vAxis: vRaw.scale(1 / vLen),
+                };
+            }
+        }
+        const n = normal.normalize();
+        const reference = Math.abs(n.z) < 0.9 ? Vec3.Z : Vec3.X;
+        const uRaw = n.cross(reference);
+        const uLen = uRaw.length();
+        if (uLen < 1e-12) {
+            return { uAxis: Vec3.X, vAxis: Vec3.Y };
+        }
+        const uAxis = uRaw.scale(1 / uLen);
+        const vRaw = n.cross(uAxis);
+        const vLen = vRaw.length();
+        if (vLen < 1e-12) {
+            return { uAxis, vAxis: Vec3.Y };
+        }
+        return { uAxis, vAxis: vRaw.scale(1 / vLen) };
+    }
+    static angleOnBasis(vector, uAxis, vAxis) {
+        return Math.atan2(vector.dot(vAxis), vector.dot(uAxis));
+    }
+    static normalizeSignedAngle(angle) {
+        const twoPi = Math.PI * 2;
+        let wrapped = angle % twoPi;
+        if (wrapped <= -Math.PI) {
+            wrapped += twoPi;
+        }
+        else if (wrapped > Math.PI) {
+            wrapped -= twoPi;
+        }
+        return wrapped;
+    }
+    static projectPointToPlane(point, planeOrigin, planeNormal) {
+        const offset = point.sub(planeOrigin);
+        const projected = offset.sub(planeNormal.scale(offset.dot(planeNormal)));
+        return planeOrigin.add(projected);
+    }
     /**
      * Create a planar patch mesh from boundary points using CDT (Constrained Delaunay Triangulation).
      * Correctly handles both convex and concave polygons.
@@ -371,6 +660,35 @@ export class Mesh {
     }
     static mergeMeshes(meshes) {
         ensureInit();
+        const packed = Mesh.packMeshes(meshes);
+        return Mesh.fromBuffer(wasm.mesh_merge(packed));
+    }
+    /**
+     * Raycast against many meshes and return all hits sorted by distance.
+     */
+    static raycastMany(meshes, origin, direction, maxDistance = Number.POSITIVE_INFINITY) {
+        ensureInit();
+        if (meshes.length === 0)
+            return [];
+        const packed = Mesh.packMeshes(meshes);
+        const raycastMany = wasm.mesh_raycast_many;
+        const buf = raycastMany(packed, origin.x, origin.y, origin.z, direction.x, direction.y, direction.z, maxDistance);
+        const count = Math.max(0, Math.floor(buf[0] ?? 0));
+        const hits = [];
+        let off = 1;
+        for (let i = 0; i < count; i++) {
+            hits.push({
+                meshIndex: Math.floor(buf[off]),
+                point: new Point(buf[off + 1], buf[off + 2], buf[off + 3]),
+                normal: new Vec3(buf[off + 4], buf[off + 5], buf[off + 6]),
+                faceIndex: Math.floor(buf[off + 7]),
+                distance: buf[off + 8],
+            });
+            off += 9;
+        }
+        return hits;
+    }
+    static packMeshes(meshes) {
         const totalLen = meshes.reduce((sum, m) => sum + 1 + m.rawBuffer.length, 1);
         const packed = new Float64Array(totalLen);
         packed[0] = meshes.length;
@@ -381,7 +699,7 @@ export class Mesh {
             packed.set(raw, off);
             off += raw.length;
         }
-        return Mesh.fromBuffer(wasm.mesh_merge(packed));
+        return packed;
     }
     /**
      * Unique undirected triangle edges as vertex-index pairs.
@@ -451,33 +769,107 @@ export class Mesh {
         ensureInit();
         return new Mesh(wasm.mesh_scale(this._vertexCount, this._buffer, sx, sy, sz));
     }
+    runBoolean(other, operation, invoke, options) {
+        const faceCountA = this.faceCount;
+        const faceCountB = other.faceCount;
+        if (operation === "union") {
+            if (faceCountA === 0)
+                return Mesh.cloneMesh(other);
+            if (faceCountB === 0)
+                return Mesh.cloneMesh(this);
+        }
+        else if (operation === "intersection") {
+            if (faceCountA === 0 || faceCountB === 0)
+                return Mesh.emptyMesh();
+        }
+        else {
+            if (faceCountA === 0)
+                return Mesh.emptyMesh();
+            if (faceCountB === 0)
+                return Mesh.cloneMesh(this);
+        }
+        const boundsA = Mesh.computeRawBounds(this);
+        const boundsB = Mesh.computeRawBounds(other);
+        if (!Mesh.boundsOverlap(boundsA, boundsB)) {
+            if (operation === "union")
+                return Mesh.mergeMeshes([this, other]);
+            if (operation === "intersection")
+                return Mesh.emptyMesh();
+            return Mesh.cloneMesh(this);
+        }
+        if (!options?.allowUnsafe) {
+            const limits = Mesh.resolveBooleanLimits(options?.limits);
+            const maxInputFaces = Math.max(faceCountA, faceCountB);
+            const combinedInputFaces = faceCountA + faceCountB;
+            const faceProduct = faceCountA * faceCountB;
+            if (maxInputFaces > limits.maxInputFacesPerMesh
+                || combinedInputFaces > limits.maxCombinedInputFaces
+                || faceProduct > limits.maxFaceProduct) {
+                throw new Error(`Boolean ${operation} blocked by safety limits `
+                    + `(A faces=${faceCountA}, B faces=${faceCountB}, faceProduct=${faceProduct}). `
+                    + "Simplify inputs, run in a Worker, or pass allowUnsafe: true to force execution.");
+            }
+        }
+        const result = invoke();
+        if (operation === "union" && result.length === 0) {
+            throw new Error("Boolean union failed and returned an empty mesh buffer.");
+        }
+        return Mesh.fromBuffer(result);
+    }
     // ── Booleans ───────────────────────────────────────────────────
     /**
      * Compute boolean union with another mesh.
      * @param other - Mesh to union with
+     * @param options - Optional safety overrides
      * @returns New mesh containing volume of both inputs
      */
-    union(other) {
+    union(other, options) {
         ensureInit();
-        return new Mesh(wasm.mesh_boolean_union(this._vertexCount, this._buffer, other._vertexCount, other._buffer));
+        return this.runBoolean(other, "union", () => wasm.mesh_boolean_union(this._vertexCount, this._buffer, other._vertexCount, other._buffer), options);
     }
     /**
      * Compute boolean subtraction with another mesh.
      * @param other - Mesh to subtract
+     * @param options - Optional safety overrides
      * @returns New mesh with other's volume removed from this
      */
-    subtract(other) {
+    subtract(other, options) {
         ensureInit();
-        return new Mesh(wasm.mesh_boolean_subtraction(this._vertexCount, this._buffer, other._vertexCount, other._buffer));
+        return this.runBoolean(other, "subtraction", () => wasm.mesh_boolean_subtraction(this._vertexCount, this._buffer, other._vertexCount, other._buffer), options);
     }
     /**
      * Compute boolean intersection with another mesh.
      * @param other - Mesh to intersect with
+     * @param options - Optional safety overrides
      * @returns New mesh containing only the overlapping volume
      */
-    intersect(other) {
+    intersect(other, options) {
         ensureInit();
-        return new Mesh(wasm.mesh_boolean_intersection(this._vertexCount, this._buffer, other._vertexCount, other._buffer));
+        return this.runBoolean(other, "intersection", () => wasm.mesh_boolean_intersection(this._vertexCount, this._buffer, other._vertexCount, other._buffer), options);
+    }
+    /**
+     * Compute boolean union in a dedicated Web Worker (non-blocking).
+     * Defaults to allowUnsafe=true so high-poly jobs can run off the UI thread.
+     */
+    async unionAsync(other, options) {
+        const result = await runMeshBooleanInWorkerPool("union", this._buffer, other._buffer, options);
+        return Mesh.fromBuffer(result);
+    }
+    /**
+     * Compute boolean subtraction in a dedicated Web Worker (non-blocking).
+     * Defaults to allowUnsafe=true so high-poly jobs can run off the UI thread.
+     */
+    async subtractAsync(other, options) {
+        const result = await runMeshBooleanInWorkerPool("subtraction", this._buffer, other._buffer, options);
+        return Mesh.fromBuffer(result);
+    }
+    /**
+     * Compute boolean intersection in a dedicated Web Worker (non-blocking).
+     * Defaults to allowUnsafe=true so high-poly jobs can run off the UI thread.
+     */
+    async intersectAsync(other, options) {
+        const result = await runMeshBooleanInWorkerPool("intersection", this._buffer, other._buffer, options);
+        return Mesh.fromBuffer(result);
     }
     // ── Intersection queries ───────────────────────────────────────
     /**
@@ -613,6 +1005,18 @@ export class Mesh {
             vMax: r[off + 3],
         };
     }
+    /**
+     * Centroid of the coplanar edge-connected face group containing faceIndex.
+     */
+    getCoplanarFaceGroupCentroid(faceIndex) {
+        ensureInit();
+        if (!Number.isFinite(faceIndex) || faceIndex < 0)
+            return null;
+        const r = wasm.mesh_get_coplanar_face_group_centroid(this._vertexCount, this._buffer, Math.floor(faceIndex));
+        if (!r || r.length < 3)
+            return null;
+        return new Point(r[0], r[1], r[2]);
+    }
     /**
      * Unique edge count for this triangulated mesh.
      */
@@ -703,66 +1107,28 @@ export class Mesh {
     findFaceByTriangleIndex(triangleIndex) {
         if (!Number.isFinite(triangleIndex) || triangleIndex < 0)
             return null;
-        const groups = this.buildCoplanarConnectedFaceGroups();
-        for (const group of groups) {
-            if (group.triangleIndices.includes(Math.floor(triangleIndex))) {
-                return { centroid: group.centroid, normal: group.normal };
-            }
-        }
-        return null;
+        ensureInit();
+        const r = wasm.mesh_find_face_group_by_triangle_index(this._vertexCount, this._buffer, Math.floor(triangleIndex));
+        if (!r || r.length < 6)
+            return null;
+        return {
+            centroid: new Point(r[0], r[1], r[2]),
+            normal: new Vec3(r[3], r[4], r[5]),
+        };
     }
     /**
      * Find the best matching coplanar + edge-connected face group by normal
      * similarity and optional point proximity.
      */
     findFaceByNormal(targetNormal, nearPoint) {
-        const groups = this.buildCoplanarConnectedFaceGroups();
-        if (groups.length === 0)
-            return null;
-        let best = null;
-        let bestScore = Number.NEGATIVE_INFINITY;
-        for (const group of groups) {
-            const normal = group.normal;
-            const centroid = group.centroid;
-            const normalScore = Math.max(0, normal.dot(targetNormal));
-            let score;
-            if (nearPoint) {
-                const dx = centroid.x - nearPoint.x;
-                const dy = centroid.y - nearPoint.y;
-                const dz = centroid.z - nearPoint.z;
-                const distSq = dx * dx + dy * dy + dz * dz;
-                const proximityScore = 1.0 / (1.0 + distSq);
-                score = proximityScore * (0.5 + 0.5 * normalScore);
-            }
-            else {
-                score = normalScore;
-            }
-            if (score > bestScore) {
-                bestScore = score;
-                best = { centroid, normal };
-            }
-        }
-        return best;
-    }
-    buildCoplanarConnectedFaceGroups() {
         ensureInit();
-        const buf = wasm.mesh_build_coplanar_connected_face_groups(this._vertexCount, this._buffer);
-        const groupCount = Math.max(0, Math.floor(buf[0] ?? 0));
-        const groups = [];
-        let off = 1;
-        for (let g = 0; g < groupCount; g++) {
-            const triCount = Math.max(0, Math.floor(buf[off++] ?? 0));
-            const triangleIndices = [];
-            for (let i = 0; i < triCount; i++) {
-                triangleIndices.push(Math.floor(buf[off++] ?? 0));
-            }
-            const centroid = new Point(buf[off], buf[off + 1], buf[off + 2]);
-            off += 3;
-            const normal = new Vec3(buf[off], buf[off + 1], buf[off + 2]);
-            off += 3;
-            groups.push({ triangleIndices, centroid, normal });
-        }
-        return groups;
+        const r = wasm.mesh_find_face_group_by_normal(this._vertexCount, this._buffer, targetNormal.x, targetNormal.y, targetNormal.z, nearPoint?.x ?? 0, nearPoint?.y ?? 0, nearPoint?.z ?? 0, nearPoint !== undefined);
+        if (!r || r.length < 6)
+            return null;
+        return {
+            centroid: new Point(r[0], r[1], r[2]),
+            normal: new Vec3(r[3], r[4], r[5]),
+        };
     }
     // ── Export ──────────────────────────────────────────────────────
     /**
@@ -774,4 +1140,9 @@ export class Mesh {
         return wasm.mesh_export_obj(this._vertexCount, this._buffer);
     }
 }
+Mesh.DEFAULT_BOOLEAN_LIMITS = {
+    maxInputFacesPerMesh: 120000,
+    maxCombinedInputFaces: 180000,
+    maxFaceProduct: 500000000,
+};
 //# sourceMappingURL=Mesh.js.map