okgeometry-api 1.2.0 → 1.2.1

package/dist/Mesh.js

@@ -7,6 +7,7 @@ import { Line } from "./Line.js";
 import { Circle } from "./Circle.js";
 import { Arc } from "./Arc.js";
 import { Polygon } from "./Polygon.js";
+import { MeshSurface } from "./MeshSurface.js";
 import { NurbsCurve } from "./NurbsCurve.js";
 import { PolyCurve } from "./PolyCurve.js";
 import { pointsToCoords, parsePolylineBuffer as parsePolylineBuf } from "./BufferCodec.js";
@@ -34,6 +35,10 @@ export class Mesh {
         this._indexBuffer = null;
         this._vertices = null;
         this._faces = null;
+        this._planarFaces = null;
+        this._planarFacesByTriangleIndex = null;
+        this._surfaces = null;
+        this._surfacesByTriangleIndex = null;
         this._edgeVertexPairs = null;
         this._topologyMetricsCache = null;
         this._isClosedVolumeCache = null;
@@ -117,6 +122,55 @@ export class Mesh {
         const diag = Math.hypot(dx, dy, dz);
         return Number.isFinite(diag) && diag > 0 ? diag : 1;
     }
+    static computeSignedVolumeFromBuffer(buffer) {
+        const vertexCount = Math.max(0, Math.floor(buffer[0] ?? 0));
+        if (vertexCount <= 0)
+            return 0;
+        const indexStart = 1 + vertexCount * 3;
+        let signedVolume = 0;
+        for (let i = indexStart; i + 2 < buffer.length; i += 3) {
+            const ia = Math.floor(buffer[i] ?? -1);
+            const ib = Math.floor(buffer[i + 1] ?? -1);
+            const ic = Math.floor(buffer[i + 2] ?? -1);
+            if (ia < 0 || ib < 0 || ic < 0 || ia >= vertexCount || ib >= vertexCount || ic >= vertexCount)
+                continue;
+            const ax = buffer[1 + ia * 3];
+            const ay = buffer[1 + ia * 3 + 1];
+            const az = buffer[1 + ia * 3 + 2];
+            const bx = buffer[1 + ib * 3];
+            const by = buffer[1 + ib * 3 + 1];
+            const bz = buffer[1 + ib * 3 + 2];
+            const cx = buffer[1 + ic * 3];
+            const cy = buffer[1 + ic * 3 + 1];
+            const cz = buffer[1 + ic * 3 + 2];
+            signedVolume += ax * (by * cz - bz * cy)
+                - ay * (bx * cz - bz * cx)
+                + az * (bx * cy - by * cx);
+        }
+        return signedVolume / 6;
+    }
+    static reverseTriangleWinding(buffer) {
+        const flipped = new Float64Array(buffer);
+        const vertexCount = Math.max(0, Math.floor(flipped[0] ?? 0));
+        const indexStart = 1 + vertexCount * 3;
+        for (let i = indexStart; i + 2 < flipped.length; i += 3) {
+            const tmp = flipped[i + 1];
+            flipped[i + 1] = flipped[i + 2];
+            flipped[i + 2] = tmp;
+        }
+        return flipped;
+    }
+    static normalizeClosedVolumeOrientation(mesh) {
+        if (mesh.faceCount === 0 || mesh._vertexCount <= 0)
+            return mesh;
+        const topology = mesh.topologyMetrics();
+        if (topology.boundaryEdges !== 0 || topology.nonManifoldEdges !== 0)
+            return mesh;
+        const signedVolume = Mesh.computeSignedVolumeFromBuffer(mesh._buffer);
+        if (!Number.isFinite(signedVolume) || signedVolume >= 0)
+            return mesh;
+        return new Mesh(Mesh.reverseTriangleWinding(mesh._buffer), mesh._trustedBooleanInput);
+    }
     static booleanContactTolerance(a, b) {
         const scale = Math.max(Mesh.boundsDiag(a), Mesh.boundsDiag(b));
         return Math.min(1e-4, Math.max(1e-9, scale * 1e-6));
@@ -532,7 +586,7 @@ export class Mesh {
     get vertexCount() {
         return this._vertexCount;
     }
-    /** Number of triangular faces in this mesh */
+    /** Number of triangular faces in this mesh. Use `planarFaceCount` for logical planar faces. */
     get faceCount() {
         const start = 1 + this._vertexCount * 3;
         if (this._buffer.length <= start)
@@ -558,6 +612,7 @@ export class Mesh {
     /**
      * Get all faces as arrays of vertex indices.
      * Each face is [i0, i1, i2] for the three triangle vertices.
+     * For coplanar edge-connected logical faces, use `planarFaces`.
      * Lazy-computed and cached.
      */
     get faces() {
@@ -571,6 +626,42 @@ export class Mesh {
         }
         return this._faces;
     }
+    /**
+     * Alias for triangle faces, mirroring `faces`.
+     * Use `planarFaces` when you want logical mesh faces such as the 6 faces of a box.
+     */
+    get triangles() {
+        return this.faces;
+    }
+    /**
+     * Number of coplanar edge-connected planar faces in this mesh.
+     * Examples: a box has 6, an L-shaped extrusion has 8.
+     */
+    get planarFaceCount() {
+        return this.planarFaces.length;
+    }
+    /**
+     * Logical mesh faces built by grouping coplanar edge-connected triangles.
+     * Cached after the first query to keep repeated face access cheap.
+     */
+    get planarFaces() {
+        this.ensurePlanarFaceCache();
+        return this._planarFaces ?? [];
+    }
+    /**
+     * Number of logical planar surfaces in this mesh.
+     * Mirrors `planarFaceCount`, but returns wrapper objects with surface queries.
+     */
+    get surfaceCount() {
+        return this.surfaces.length;
+    }
+    /**
+     * Logical planar mesh surfaces with `evaluate(u, v)` and `normal(u, v)` methods.
+     */
+    get surfaces() {
+        this.ensureSurfaceCache();
+        return this._surfaces ?? [];
+    }
     /** Raw WASM buffer (for advanced use / re-passing to WASM) */
     get rawBuffer() {
         return this._buffer;
@@ -585,11 +676,111 @@ export class Mesh {
         return new Mesh(buffer, options?.trustedBooleanInput ?? false);
     }
     static fromTrustedBuffer(buffer) {
-        return new Mesh(buffer, true);
+        return Mesh.normalizeClosedVolumeOrientation(new Mesh(buffer, true));
     }
     get trustedBooleanInput() {
         return this._trustedBooleanInput;
     }
+    getTriangleVertexIndices(faceIndex) {
+        if (!Number.isFinite(faceIndex) || faceIndex < 0 || faceIndex >= this.faceCount)
+            return null;
+        const indexBuffer = this.indexBuffer;
+        const offset = Math.floor(faceIndex) * 3;
+        if (offset + 2 >= indexBuffer.length)
+            return null;
+        return [indexBuffer[offset], indexBuffer[offset + 1], indexBuffer[offset + 2]];
+    }
+    computeTriangleAreaByIndex(faceIndex) {
+        const tri = this.getTriangleVertexIndices(faceIndex);
+        if (!tri)
+            return 0;
+        const [i0, i1, i2] = tri;
+        const base = 1;
+        const off0 = base + i0 * 3;
+        const off1 = base + i1 * 3;
+        const off2 = base + i2 * 3;
+        const ax = this._buffer[off0] ?? 0;
+        const ay = this._buffer[off0 + 1] ?? 0;
+        const az = this._buffer[off0 + 2] ?? 0;
+        const bx = this._buffer[off1] ?? 0;
+        const by = this._buffer[off1 + 1] ?? 0;
+        const bz = this._buffer[off1 + 2] ?? 0;
+        const cx = this._buffer[off2] ?? 0;
+        const cy = this._buffer[off2 + 1] ?? 0;
+        const cz = this._buffer[off2 + 2] ?? 0;
+        const abx = bx - ax;
+        const aby = by - ay;
+        const abz = bz - az;
+        const acx = cx - ax;
+        const acy = cy - ay;
+        const acz = cz - az;
+        const crossX = aby * acz - abz * acy;
+        const crossY = abz * acx - abx * acz;
+        const crossZ = abx * acy - aby * acx;
+        return 0.5 * Math.sqrt(crossX * crossX + crossY * crossY + crossZ * crossZ);
+    }
+    ensurePlanarFaceCache() {
+        if (this._planarFaces && this._planarFacesByTriangleIndex)
+            return;
+        ensureInit();
+        const raw = wasm.mesh_build_coplanar_connected_face_groups(this._vertexCount, this._buffer);
+        const declaredGroupCount = Math.max(0, Math.floor(raw[0] ?? 0));
+        const planarFaces = [];
+        const planarFacesByTriangleIndex = new Array(this.faceCount).fill(null);
+        let offset = 1;
+        for (let groupIndex = 0; groupIndex < declaredGroupCount && offset < raw.length; groupIndex++) {
+            const declaredTriangleCount = Math.max(0, Math.floor(raw[offset] ?? 0));
+            offset += 1;
+            const triangleIndices = [];
+            let area = 0;
+            for (let i = 0; i < declaredTriangleCount && offset < raw.length; i++, offset++) {
+                const triangleIndex = Math.floor(raw[offset] ?? -1);
+                if (triangleIndex < 0 || triangleIndex >= this.faceCount)
+                    continue;
+                triangleIndices.push(triangleIndex);
+                area += this.computeTriangleAreaByIndex(triangleIndex);
+            }
+            if (offset + 5 >= raw.length)
+                break;
+            const centroid = new Point(raw[offset] ?? 0, raw[offset + 1] ?? 0, raw[offset + 2] ?? 0);
+            const normal = new Vec3(raw[offset + 3] ?? 0, raw[offset + 4] ?? 0, raw[offset + 5] ?? 0).normalize();
+            offset += 6;
+            if (triangleIndices.length === 0)
+                continue;
+            const planarFace = {
+                index: planarFaces.length,
+                seedTriangleIndex: triangleIndices[0],
+                triangleIndices,
+                triangleCount: triangleIndices.length,
+                centroid,
+                normal,
+                area,
+            };
+            planarFaces.push(planarFace);
+            for (const triangleIndex of triangleIndices) {
+                planarFacesByTriangleIndex[triangleIndex] = planarFace;
+            }
+        }
+        this._planarFaces = planarFaces;
+        this._planarFacesByTriangleIndex = planarFacesByTriangleIndex;
+        this._surfaces = null;
+        this._surfacesByTriangleIndex = null;
+    }
+    ensureSurfaceCache() {
+        if (this._surfaces && this._surfacesByTriangleIndex)
+            return;
+        const surfaces = this.planarFaces.map(face => new MeshSurface(this, face));
+        const surfacesByTriangleIndex = new Array(this.faceCount).fill(null);
+        for (const surface of surfaces) {
+            for (const triangleIndex of surface.triangleIndices) {
+                if (triangleIndex >= 0 && triangleIndex < surfacesByTriangleIndex.length) {
+                    surfacesByTriangleIndex[triangleIndex] = surface;
+                }
+            }
+        }
+        this._surfaces = surfaces;
+        this._surfacesByTriangleIndex = surfacesByTriangleIndex;
+    }
     debugSummary() {
         const bounds = Mesh.toDebugBounds(this.getBounds());
         const topology = this.topologyMetrics();
@@ -1298,6 +1489,34 @@ export class Mesh {
         }
         return Mesh.fromTrustedBuffer(result);
     }
+    static mergeMeshComponents(meshes) {
+        if (meshes.length === 0)
+            return Mesh.emptyMesh();
+        if (meshes.length === 1)
+            return Mesh.cloneMesh(meshes[0]);
+        return Mesh.mergeMeshes(meshes);
+    }
+    static createUnsupportedOpenMeshBooleanError(operation, aClosed, bClosed) {
+        const topology = `A=${aClosed ? "closed" : "open"}, B=${bClosed ? "closed" : "open"}`;
+        if (operation === "union") {
+            return new Error(`Boolean union requires both inputs to be closed volumes (${topology}). `
+                + "Close or cap the open mesh before calling union().");
+        }
+        return new Error(`Boolean ${operation} with open meshes is only supported when A is open and B is closed `
+            + `(surface trim mode). Got ${topology}. Use Mesh.split(...) and choose outside/inside explicitly `
+            + "for other open-mesh combinations.");
+    }
+    resolveOpenMeshBooleanFallback(other, operation, options) {
+        const aClosed = this.isClosedVolume();
+        const bClosed = other.isClosedVolume();
+        if (aClosed && bClosed)
+            return null;
+        if (!aClosed && bClosed && (operation === "subtraction" || operation === "intersection")) {
+            const split = this.splitWithMesh(other, options);
+            return Mesh.mergeMeshComponents(operation === "subtraction" ? split.outside : split.inside);
+        }
+        throw Mesh.createUnsupportedOpenMeshBooleanError(operation, aClosed, bClosed);
+    }
     static encodeBooleanOperationToken(operation, a, b, options) {
         const tokens = [operation];
         if (a._trustedBooleanInput && b._trustedBooleanInput) {
@@ -1321,36 +1540,54 @@ export class Mesh {
     // ── Booleans ───────────────────────────────────────────────────
     /**
      * Compute boolean union with another mesh.
+     * Requires both inputs to be closed volumes.
      * @param other - Mesh to union with
      * @param options - Optional safety overrides
      * @returns New mesh containing volume of both inputs
      */
     union(other, options) {
         ensureInit();
-        const operationToken = Mesh.encodeBooleanOperationToken("union", this, other, options);
-        return this.runBoolean(other, "union", () => wasm.mesh_boolean_operation(this._vertexCount, this._buffer, other._vertexCount, other._buffer, operationToken), options);
+        const lhs = Mesh.normalizeClosedVolumeOrientation(this);
+        const rhs = Mesh.normalizeClosedVolumeOrientation(other);
+        lhs.resolveOpenMeshBooleanFallback(rhs, "union", options);
+        const operationToken = Mesh.encodeBooleanOperationToken("union", lhs, rhs, options);
+        return lhs.runBoolean(rhs, "union", () => wasm.mesh_boolean_operation(lhs._vertexCount, lhs._buffer, rhs._vertexCount, rhs._buffer, operationToken), options);
     }
     /**
      * Compute boolean subtraction with another mesh.
+     * If this mesh is open and `other` is a closed cutter, this trims the open
+     * host via `split()` and returns the outside surface pieces merged together.
      * @param other - Mesh to subtract
      * @param options - Optional safety overrides
      * @returns New mesh with other's volume removed from this
      */
     subtract(other, options) {
         ensureInit();
-        const operationToken = Mesh.encodeBooleanOperationToken("subtraction", this, other, options);
-        return this.runBoolean(other, "subtraction", () => wasm.mesh_boolean_operation(this._vertexCount, this._buffer, other._vertexCount, other._buffer, operationToken), options);
+        const lhs = Mesh.normalizeClosedVolumeOrientation(this);
+        const rhs = Mesh.normalizeClosedVolumeOrientation(other);
+        const fallback = lhs.resolveOpenMeshBooleanFallback(rhs, "subtraction", options);
+        if (fallback)
+            return fallback;
+        const operationToken = Mesh.encodeBooleanOperationToken("subtraction", lhs, rhs, options);
+        return lhs.runBoolean(rhs, "subtraction", () => wasm.mesh_boolean_operation(lhs._vertexCount, lhs._buffer, rhs._vertexCount, rhs._buffer, operationToken), options);
     }
     /**
      * Compute boolean intersection with another mesh.
+     * If this mesh is open and `other` is a closed cutter, this trims the open
+     * host via `split()` and returns the inside surface pieces merged together.
      * @param other - Mesh to intersect with
      * @param options - Optional safety overrides
      * @returns New mesh containing only the overlapping volume
      */
     intersect(other, options) {
         ensureInit();
-        const operationToken = Mesh.encodeBooleanOperationToken("intersection", this, other, options);
-        return this.runBoolean(other, "intersection", () => wasm.mesh_boolean_operation(this._vertexCount, this._buffer, other._vertexCount, other._buffer, operationToken), options);
+        const lhs = Mesh.normalizeClosedVolumeOrientation(this);
+        const rhs = Mesh.normalizeClosedVolumeOrientation(other);
+        const fallback = lhs.resolveOpenMeshBooleanFallback(rhs, "intersection", options);
+        if (fallback)
+            return fallback;
+        const operationToken = Mesh.encodeBooleanOperationToken("intersection", lhs, rhs, options);
+        return lhs.runBoolean(rhs, "intersection", () => wasm.mesh_boolean_operation(lhs._vertexCount, lhs._buffer, rhs._vertexCount, rhs._buffer, operationToken), options);
     }
     splitWithMesh(other, options) {
         ensureInit();
@@ -1841,6 +2078,88 @@ export class Mesh {
             nonManifoldEdges,
         };
     }
+    /**
+     * Get a logical planar face by its planar-face index.
+     */
+    getPlanarFace(index) {
+        if (!Number.isFinite(index) || index < 0)
+            return null;
+        const planarFaces = this.planarFaces;
+        return planarFaces[Math.floor(index)] ?? null;
+    }
+    /**
+     * Get a logical planar surface wrapper by its planar-face index.
+     */
+    getSurface(index) {
+        if (!Number.isFinite(index) || index < 0)
+            return null;
+        const surfaces = this.surfaces;
+        return surfaces[Math.floor(index)] ?? null;
+    }
+    /**
+     * Get the logical planar face that contains a triangle face index.
+     */
+    getPlanarFaceByTriangleIndex(triangleIndex) {
+        if (!Number.isFinite(triangleIndex) || triangleIndex < 0)
+            return null;
+        this.ensurePlanarFaceCache();
+        return this._planarFacesByTriangleIndex?.[Math.floor(triangleIndex)] ?? null;
+    }
+    /**
+     * Get the logical planar surface wrapper that contains a triangle face index.
+     */
+    getSurfaceByTriangleIndex(triangleIndex) {
+        if (!Number.isFinite(triangleIndex) || triangleIndex < 0)
+            return null;
+        this.ensureSurfaceCache();
+        return this._surfacesByTriangleIndex?.[Math.floor(triangleIndex)] ?? null;
+    }
+    /**
+     * Find the best matching logical planar face by normal and optional centroid proximity.
+     */
+    findPlanarFaceByNormal(targetNormal, nearPoint) {
+        const planarFaces = this.planarFaces;
+        if (planarFaces.length === 0)
+            return null;
+        const normalizedTarget = targetNormal.normalize();
+        if (normalizedTarget.length() < 1e-12)
+            return null;
+        const alignmentEps = 1e-9;
+        const distanceEps = 1e-9;
+        let best = null;
+        let bestAlignment = -Infinity;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        let bestArea = -Infinity;
+        for (const planarFace of planarFaces) {
+            const alignment = planarFace.normal.dot(normalizedTarget);
+            const distance = nearPoint ? planarFace.centroid.distanceTo(nearPoint) : 0;
+            const betterAlignment = alignment > bestAlignment + alignmentEps;
+            const similarAlignment = Math.abs(alignment - bestAlignment) <= alignmentEps;
+            const betterDistance = nearPoint !== undefined && distance < bestDistance - distanceEps;
+            const similarDistance = Math.abs(distance - bestDistance) <= distanceEps;
+            const betterArea = planarFace.area > bestArea + distanceEps;
+            if (best === null
+                || betterAlignment
+                || (similarAlignment && betterDistance)
+                || (similarAlignment && (!nearPoint || similarDistance) && betterArea)) {
+                best = planarFace;
+                bestAlignment = alignment;
+                bestDistance = distance;
+                bestArea = planarFace.area;
+            }
+        }
+        return best;
+    }
+    /**
+     * Find the best matching logical planar surface wrapper by normal
+     * similarity and optional point proximity.
+     */
+    findSurfaceByNormal(targetNormal, nearPoint) {
+        const face = this.findPlanarFaceByNormal(targetNormal, nearPoint);
+        if (!face)
+            return null;
+        return this.getSurface(face.index);
+    }
     /**
      * Odd/even point containment test against a closed mesh.
      * Uses majority vote across multiple ray directions for robustness.
@@ -1853,30 +2172,14 @@ export class Mesh {
      * Find the coplanar + edge-connected face group containing a triangle.
      */
     findFaceByTriangleIndex(triangleIndex) {
-        if (!Number.isFinite(triangleIndex) || triangleIndex < 0)
-            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]),
-        };
+        return this.getPlanarFaceByTriangleIndex(triangleIndex);
     }
     /**
      * Find the best matching coplanar + edge-connected face group by normal
      * similarity and optional point proximity.
      */
     findFaceByNormal(targetNormal, nearPoint) {
-        ensureInit();
-        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]),
-        };
+        return this.findPlanarFaceByNormal(targetNormal, nearPoint);
     }
     // ── Export ──────────────────────────────────────────────────────
     /**