okgeometry-api 0.4.1 → 0.4.3

package/dist/Mesh.js

@@ -23,10 +23,11 @@ export class Mesh {
         this._indexBuffer = null;
         this._vertices = null;
         this._faces = null;
+        this._edgeVertexPairs = null;
         this._buffer = buffer;
         this._vertexCount = buffer.length > 0 ? buffer[0] : 0;
     }
-    // ── GPU-ready buffers ──────────────────────────────────────────
+    // ── GPU-ready buffers ──────────────────────────────────────────
     /**
      * Float32 xyz positions for Three.js BufferGeometry.
      * Lazy-computed and cached.
@@ -64,7 +65,7 @@ export class Mesh {
     get faceCount() {
         return this.indexBuffer.length / 3;
     }
-    // ── High-level accessors (lazy) ────────────────────────────────
+    // ── High-level accessors (lazy) ────────────────────────────────
     /**
      * Get all vertices as Point objects.
      * Lazy-computed and cached.
@@ -100,7 +101,7 @@ export class Mesh {
     get rawBuffer() {
         return this._buffer;
     }
-    // ── Static factories ───────────────────────────────────────────
+    // ── Static factories ───────────────────────────────────────────
     /**
      * Create a Mesh from a raw WASM buffer.
      * @param buffer - Float64Array in mesh buffer format
@@ -238,6 +239,42 @@ export class Mesh {
         ensureInit();
         return new Mesh(wasm.sweep_polylines(pointsToCoords(profilePoints), pointsToCoords(pathPoints), caps));
     }
+    /**
+     * Compute a stable planar normal from ordered curve points.
+     * Closed curves use Newell's method; open curves use first non-collinear triple.
+     */
+    static computePlanarCurveNormal(points, closed) {
+        ensureInit();
+        const r = wasm.mesh_compute_planar_curve_normal(pointsToCoords(points), closed);
+        return new Vec3(r[0] ?? 0, r[1] ?? 1, r[2] ?? 0);
+    }
+    /**
+     * Extrude a planar curve along a direction.
+     * Open curves return an uncapped polysurface; closed curves are capped solids.
+     */
+    static extrudePlanarCurve(points, normal, height, closed) {
+        ensureInit();
+        const buf = wasm.mesh_extrude_planar_curve(pointsToCoords(points), normal.x, normal.y, normal.z, height, closed);
+        return Mesh.fromBuffer(buf);
+    }
+    /**
+     * Shift a closed cutter profile slightly opposite to travel direction and
+     * compensate height so the distal end remains at the user-intended depth.
+     */
+    static prepareBooleanCutterCurve(points, closed, normal, height) {
+        ensureInit();
+        const buf = wasm.mesh_prepare_boolean_cutter_curve(pointsToCoords(points), closed, normal.x, normal.y, normal.z, height);
+        const outHeight = buf[0] ?? height;
+        const epsilon = buf[1] ?? 0;
+        const count = Math.max(0, Math.floor(buf[2] ?? 0));
+        const shifted = [];
+        let off = 3;
+        for (let i = 0; i < count; i++) {
+            shifted.push(new Point(buf[off], buf[off + 1], buf[off + 2]));
+            off += 3;
+        }
+        return { points: shifted, height: outHeight, epsilon };
+    }
     /**
      * Sweep any curve type along any curve type.
      * Passes exact curve data to WASM for native evaluation (no pre-sampling).
@@ -332,7 +369,42 @@ export class Mesh {
         data.set(coords, 2);
         return data;
     }
-    // ── Transforms ────────────────────────────────────────────────
+    static mergeMeshes(meshes) {
+        ensureInit();
+        const totalLen = meshes.reduce((sum, m) => sum + 1 + m.rawBuffer.length, 1);
+        const packed = new Float64Array(totalLen);
+        packed[0] = meshes.length;
+        let off = 1;
+        for (const mesh of meshes) {
+            const raw = mesh.rawBuffer;
+            packed[off++] = raw.length;
+            packed.set(raw, off);
+            off += raw.length;
+        }
+        return Mesh.fromBuffer(wasm.mesh_merge(packed));
+    }
+    /**
+     * Unique undirected triangle edges as vertex-index pairs.
+     */
+    getUniqueEdgeVertexPairs() {
+        if (this._edgeVertexPairs)
+            return this._edgeVertexPairs;
+        ensureInit();
+        const packed = wasm.mesh_get_edge_vertex_pairs(this._vertexCount, this._buffer);
+        const edgeCount = Math.max(0, Math.floor(packed[0] ?? 0));
+        const pairs = [];
+        let off = 1;
+        for (let i = 0; i < edgeCount; i++) {
+            const a = Math.floor(packed[off++] ?? -1);
+            const b = Math.floor(packed[off++] ?? -1);
+            if (a < 0 || b < 0)
+                break;
+            pairs.push([a, b]);
+        }
+        this._edgeVertexPairs = pairs;
+        return this._edgeVertexPairs;
+    }
+    // ── Transforms ────────────────────────────────────────────────
     /**
      * Translate this mesh by an offset vector.
      * @param offset - Translation vector
@@ -379,7 +451,7 @@ export class Mesh {
         ensureInit();
         return new Mesh(wasm.mesh_scale(this._vertexCount, this._buffer, sx, sy, sz));
     }
-    // ── Booleans ───────────────────────────────────────────────────
+    // ── Booleans ───────────────────────────────────────────────────
     /**
      * Compute boolean union with another mesh.
      * @param other - Mesh to union with
@@ -407,7 +479,7 @@ export class Mesh {
         ensureInit();
         return new Mesh(wasm.mesh_boolean_intersection(this._vertexCount, this._buffer, other._vertexCount, other._buffer));
     }
-    // ── Intersection queries ───────────────────────────────────────
+    // ── Intersection queries ───────────────────────────────────────
     /**
      * Compute intersection curves with a plane.
      * @param plane - Cutting plane
@@ -439,7 +511,7 @@ export class Mesh {
     }
     /**
      * Evaluate a point on the mesh surface at parametric coordinates.
-     * Maps u ∈ [0,1] and v ∈ [0,1] across the mesh's bounding box and
+     * Maps u ∈ [0,1] and v ∈ [0,1] across the mesh's bounding box and
      * finds the corresponding surface point via ray casting.
      *
      * @param u - Parameter in first surface direction [0, 1]
@@ -462,196 +534,237 @@ export class Mesh {
         return parsePolylineBuf(buf).map(pts => new Polyline(pts));
     }
     /**
-     * Check if this triangulated mesh represents a closed volume.
-     * Returns true when no topological boundary edges are found.
-     *
-     * Uses kernel boundary extraction first, then falls back to a welded
-     * edge-incidence pass to tolerate duplicated seam vertices.
+     * Axis-aligned bounds of this mesh.
      */
-    isClosedVolume() {
-        if (this.indexBuffer.length < 3)
-            return false;
-        try {
-            if (this.boundaryPolylines().length === 0)
-                return true;
+    getBounds() {
+        ensureInit();
+        const b = wasm.mesh_get_bounds(this._vertexCount, this._buffer);
+        return {
+            min: new Point(b[0] ?? 0, b[1] ?? 0, b[2] ?? 0),
+            max: new Point(b[3] ?? 0, b[4] ?? 0, b[5] ?? 0),
+        };
+    }
+    /**
+     * Unit normal of a triangle face.
+     */
+    getFaceNormal(faceIndex) {
+        ensureInit();
+        if (!Number.isFinite(faceIndex) || faceIndex < 0)
+            return Vec3.Y;
+        const n = wasm.mesh_get_face_normal(this._vertexCount, this._buffer, Math.floor(faceIndex));
+        return new Vec3(n[0] ?? 0, n[1] ?? 1, n[2] ?? 0);
+    }
+    /**
+     * Centroid of a triangle face.
+     */
+    getFaceCentroid(faceIndex) {
+        ensureInit();
+        if (!Number.isFinite(faceIndex) || faceIndex < 0)
+            return Point.ORIGIN;
+        const c = wasm.mesh_get_face_centroid(this._vertexCount, this._buffer, Math.floor(faceIndex));
+        return new Point(c[0] ?? 0, c[1] ?? 0, c[2] ?? 0);
+    }
+    /**
+     * Area of a triangle face.
+     */
+    getFaceArea(faceIndex) {
+        ensureInit();
+        if (!Number.isFinite(faceIndex) || faceIndex < 0)
+            return 0;
+        return wasm.mesh_get_face_area(this._vertexCount, this._buffer, Math.floor(faceIndex));
+    }
+    /**
+     * Find edge-connected coplanar triangles that belong to the same planar face.
+     */
+    getCoplanarFaceIndices(faceIndex) {
+        ensureInit();
+        if (!Number.isFinite(faceIndex) || faceIndex < 0)
+            return [];
+        const r = wasm.mesh_get_coplanar_face_indices(this._vertexCount, this._buffer, Math.floor(faceIndex));
+        const count = Math.max(0, Math.floor(r[0] ?? 0));
+        const out = [];
+        for (let i = 0; i < count; i++) {
+            out.push(Math.floor(r[1 + i] ?? 0));
         }
-        catch {
-            // Fall through to welded index analysis.
+        return out;
+    }
+    /**
+     * Coplanar connected face region and its projection bounds on a plane basis.
+     * Returns null for invalid inputs or empty regions.
+     */
+    getCoplanarFaceRegion(faceIndex, origin, uAxis, vAxis, marginScale = 0.1, minMargin = 0.2) {
+        ensureInit();
+        if (!Number.isFinite(faceIndex) || faceIndex < 0)
+            return null;
+        const r = wasm.mesh_get_coplanar_face_region(this._vertexCount, this._buffer, Math.floor(faceIndex), origin.x, origin.y, origin.z, uAxis.x, uAxis.y, uAxis.z, vAxis.x, vAxis.y, vAxis.z, marginScale, minMargin);
+        const count = Math.max(0, Math.floor(r[0] ?? 0));
+        if (count <= 0 || r.length < 1 + count + 4)
+            return null;
+        const faceIndices = [];
+        for (let i = 0; i < count; i++) {
+            faceIndices.push(Math.floor(r[1 + i] ?? 0));
         }
-        const welded = this.buildWeldedVertexIndexMap();
-        const edgeCounts = new Map();
-        const idx = this.indexBuffer;
-        for (let i = 0; i + 2 < idx.length; i += 3) {
-            const ai = idx[i];
-            const bi = idx[i + 1];
-            const ci = idx[i + 2];
-            if (ai >= welded.length || bi >= welded.length || ci >= welded.length) {
-                return false;
-            }
-            const a = welded[ai];
-            const b = welded[bi];
-            const c = welded[ci];
-            if (a === b || b === c || c === a)
-                continue;
-            const edges = [[a, b], [b, c], [c, a]];
-            for (const [u, v] of edges) {
-                const lo = Math.min(u, v);
-                const hi = Math.max(u, v);
-                const key = `${lo}_${hi}`;
-                edgeCounts.set(key, (edgeCounts.get(key) ?? 0) + 1);
-            }
+        const off = 1 + count;
+        return {
+            faceIndices,
+            uMin: r[off],
+            uMax: r[off + 1],
+            vMin: r[off + 2],
+            vMax: r[off + 3],
+        };
+    }
+    /**
+     * Unique edge count for this triangulated mesh.
+     */
+    getEdgeCount() {
+        return this.getUniqueEdgeVertexPairs().length;
+    }
+    /**
+     * Return edge endpoints by edge index in the unique edge list.
+     */
+    getEdgeVertices(edgeIndex) {
+        const pairs = this.getUniqueEdgeVertexPairs();
+        if (!Number.isFinite(edgeIndex) || edgeIndex < 0 || edgeIndex >= pairs.length) {
+            return [Point.ORIGIN, Point.ORIGIN];
         }
-        for (const count of edgeCounts.values()) {
-            if (count === 1)
-                return false;
+        const [i0, i1] = pairs[Math.floor(edgeIndex)];
+        const pos = this.positionBuffer;
+        const off0 = i0 * 3;
+        const off1 = i1 * 3;
+        return [
+            new Point(pos[off0], pos[off0 + 1], pos[off0 + 2]),
+            new Point(pos[off1], pos[off1 + 1], pos[off1 + 2]),
+        ];
+    }
+    /**
+     * Raycast against this mesh and return nearest hit.
+     */
+    raycast(origin, direction, maxDistance = Number.POSITIVE_INFINITY) {
+        ensureInit();
+        const r = wasm.mesh_raycast(this._vertexCount, this._buffer, origin.x, origin.y, origin.z, direction.x, direction.y, direction.z, maxDistance);
+        if (!r || r.length < 8)
+            return null;
+        return {
+            point: new Point(r[0], r[1], r[2]),
+            normal: new Vec3(r[3], r[4], r[5]),
+            faceIndex: Math.floor(r[6]),
+            distance: r[7],
+        };
+    }
+    /**
+     * Raycast against this mesh and return all hits sorted by distance.
+     */
+    raycastAll(origin, direction, maxDistance = Number.POSITIVE_INFINITY) {
+        ensureInit();
+        const buf = wasm.mesh_raycast_all(this._vertexCount, this._buffer, 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({
+                point: new Point(buf[off], buf[off + 1], buf[off + 2]),
+                normal: new Vec3(buf[off + 3], buf[off + 4], buf[off + 5]),
+                faceIndex: Math.floor(buf[off + 6]),
+                distance: buf[off + 7],
+            });
+            off += 8;
+        }
+        return hits;
+    }
+    /**
+     * Push/pull a planar face set by moving its coplanar connected region.
+     */
+    extrudeFace(faceIndex, distance) {
+        ensureInit();
+        if (!Number.isFinite(faceIndex) || faceIndex < 0) {
+            return Mesh.fromBuffer(new Float64Array(this._buffer));
         }
-        return true;
+        return Mesh.fromBuffer(wasm.mesh_extrude_face(this._vertexCount, this._buffer, Math.floor(faceIndex), distance));
+    }
+    /**
+     * Check if this triangulated mesh represents a closed volume.
+     * Returns true when no welded topological boundary edges are found.
+     */
+    isClosedVolume() {
+        ensureInit();
+        return wasm.mesh_is_closed_volume(this._vertexCount, this._buffer);
     }
     /**
      * Odd/even point containment test against a closed mesh.
      * Uses majority vote across multiple ray directions for robustness.
      */
     containsPoint(point) {
-        const directions = [
-            new Vec3(0.329292779969071, 0.5488212999484517, 0.7683498199278324),
-            new Vec3(0.6227991553292184, -0.2075997184430728, 0.7547910549471614),
-            new Vec3(-0.1708715315433522, 0.9405985944884371, 0.29377431425456585),
-        ];
-        let insideVotes = 0;
-        for (const dir of directions) {
-            const crossings = this.countRayCrossings(point, dir);
-            if ((crossings & 1) === 1)
-                insideVotes += 1;
-        }
-        return insideVotes >= Math.ceil(directions.length / 2);
-    }
-    /**
-     * Count unique ray/triangle crossings from origin along direction.
-     * Distances are deduplicated to collapse paired hits on triangulated quads.
-     */
-    countRayCrossings(origin, direction) {
-        const MIN_DISTANCE = 1e-6;
-        const MERGE_DISTANCE = 1e-5;
-        const distances = [];
-        const idx = this.indexBuffer;
-        const verts = this.positionBuffer;
-        for (let i = 0; i + 2 < idx.length; i += 3) {
-            const i0 = idx[i];
-            const i1 = idx[i + 1];
-            const i2 = idx[i + 2];
-            const off0 = i0 * 3;
-            const off1 = i1 * 3;
-            const off2 = i2 * 3;
-            const t = Mesh.rayTriangleDistance(origin.x, origin.y, origin.z, direction.x, direction.y, direction.z, verts[off0], verts[off0 + 1], verts[off0 + 2], verts[off1], verts[off1 + 1], verts[off1 + 2], verts[off2], verts[off2 + 1], verts[off2 + 2]);
-            if (t !== null && Number.isFinite(t) && t > MIN_DISTANCE) {
-                distances.push(t);
+        ensureInit();
+        return wasm.mesh_contains_point(this._vertexCount, this._buffer, point.x, point.y, point.z);
+    }
+    /**
+     * Find the coplanar + edge-connected face group containing a triangle.
+     */
+    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 };
             }
         }
-        if (distances.length === 0)
-            return 0;
-        distances.sort((a, b) => a - b);
-        let crossings = 0;
-        let lastDistance = -Infinity;
-        for (const d of distances) {
-            if (Math.abs(d - lastDistance) <= MERGE_DISTANCE)
-                continue;
-            crossings += 1;
-            lastDistance = d;
-        }
-        return crossings;
+        return null;
     }
     /**
-     * Map each raw vertex index to a welded topological vertex index.
-     * Uses scale-aware quantization to merge duplicate seam vertices.
+     * Find the best matching coplanar + edge-connected face group by normal
+     * similarity and optional point proximity.
      */
-    buildWeldedVertexIndexMap() {
-        const pos = this.positionBuffer;
-        const vertexCount = pos.length / 3;
-        const map = new Uint32Array(vertexCount);
-        if (vertexCount === 0)
-            return map;
-        let minX = Number.POSITIVE_INFINITY;
-        let minY = Number.POSITIVE_INFINITY;
-        let minZ = Number.POSITIVE_INFINITY;
-        let maxX = Number.NEGATIVE_INFINITY;
-        let maxY = Number.NEGATIVE_INFINITY;
-        let maxZ = Number.NEGATIVE_INFINITY;
-        for (let i = 0; i < vertexCount; i++) {
-            const x = pos[i * 3];
-            const y = pos[i * 3 + 1];
-            const z = pos[i * 3 + 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;
+    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 };
+            }
         }
-        const dx = maxX - minX;
-        const dy = maxY - minY;
-        const dz = maxZ - minZ;
-        const diag = Math.sqrt(dx * dx + dy * dy + dz * dz);
-        const tol = Math.max(1e-9, diag * 1e-8);
-        const invTol = 1 / tol;
-        const weldedByKey = new Map();
-        let nextWelded = 0;
-        for (let i = 0; i < vertexCount; i++) {
-            const x = pos[i * 3];
-            const y = pos[i * 3 + 1];
-            const z = pos[i * 3 + 2];
-            const qx = Math.round(x * invTol);
-            const qy = Math.round(y * invTol);
-            const qz = Math.round(z * invTol);
-            const key = `${qx}_${qy}_${qz}`;
-            let welded = weldedByKey.get(key);
-            if (welded === undefined) {
-                welded = nextWelded++;
-                weldedByKey.set(key, welded);
+        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));
             }
-            map[i] = welded;
+            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 map;
-    }
-    /**
-     * Moller-Trumbore ray/triangle intersection distance.
-     */
-    static rayTriangleDistance(ox, oy, oz, dx, dy, dz, v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z) {
-        const EPSILON = 1e-7;
-        const e1x = v1x - v0x;
-        const e1y = v1y - v0y;
-        const e1z = v1z - v0z;
-        const e2x = v2x - v0x;
-        const e2y = v2y - v0y;
-        const e2z = v2z - v0z;
-        const hx = dy * e2z - dz * e2y;
-        const hy = dz * e2x - dx * e2z;
-        const hz = dx * e2y - dy * e2x;
-        const a = e1x * hx + e1y * hy + e1z * hz;
-        if (a > -EPSILON && a < EPSILON)
-            return null;
-        const f = 1 / a;
-        const sx = ox - v0x;
-        const sy = oy - v0y;
-        const sz = oz - v0z;
-        const u = f * (sx * hx + sy * hy + sz * hz);
-        if (u < 0 || u > 1)
-            return null;
-        const qx = sy * e1z - sz * e1y;
-        const qy = sz * e1x - sx * e1z;
-        const qz = sx * e1y - sy * e1x;
-        const v = f * (dx * qx + dy * qy + dz * qz);
-        if (v < 0 || u + v > 1)
-            return null;
-        const t = f * (e2x * qx + e2y * qy + e2z * qz);
-        return t > EPSILON ? t : null;
+        return groups;
     }
-    // ── Export ──────────────────────────────────────────────────────
+    // ── Export ──────────────────────────────────────────────────────
     /**
      * Export this mesh to OBJ format.
      * @returns OBJ file content as string