okgeometry-api 1.11.0 → 1.14.0

package/src/Brep.ts

@@ -26,6 +26,30 @@ export interface BrepParametricBooleanOptions {
   tolerance?: number;
 }
 
+/** Options for mesh → BREP conversion ({@link Brep.fromMesh}). */
+export interface MeshToBrepConversionOptions {
+  /**
+   * Max angle (degrees) between triangle normals for facets to group into one
+   * planar face. Default ≈0.057° — far below any real dihedral in tessellated
+   * curved regions, far above float noise on genuinely planar faces.
+   */
+  normalAngleToleranceDeg?: number;
+  /**
+   * Face-count guard: conversion fails when planar-face recognition would
+   * produce more faces than this (densely tessellated curved meshes do not
+   * belong in a planar-face BREP). Default 4096; 0 keeps the default.
+   */
+  maxFaces?: number;
+}
+
+/** Both halves of a solid ÷ sheet split ({@link Brep.splitBySheet}). */
+export interface BrepSplitSolidResult {
+  /** The half BEHIND the sheet normal, capped by the exact trimmed sheet (null when empty). */
+  negative: Brep | null;
+  /** The half the sheet normal points into (null when empty). */
+  positive: Brep | null;
+}
+
 /** Validation report for a BREP body. */
 export interface BrepValidationReport {
   isClosed: boolean;
@@ -236,6 +260,11 @@ export class Brep {
   /**
    * Exact backing surface of a face: a NurbsSurface for curved faces, a Plane
    * for planar faces.
+   *
+   * NOTE: this is the UNTRIMMED underlying surface — for the face of a
+   * boolean/split result it spans the whole original input surface. Use
+   * {@link extractFace} for the actual trimmed face, or
+   * {@link faceSurfaceCropped} for the surface cropped to the face's extent.
    */
   faceSurface(faceIndex: number): NurbsSurface | Plane {
     ensureInit();
@@ -252,6 +281,88 @@ export class Brep {
     return NurbsSurface.fromData(buf.slice(1));
   }
 
+  /**
+   * Extract one face as a standalone single-face TRIMMED sheet Brep: trim
+   * loops, pcurves, edges and vertices are preserved exactly — this is the
+   * actual cropped face, not the untrimmed backing surface. The result
+   * tessellates, transforms and participates in booleans like any sheet Brep.
+   */
+  extractFace(faceIndex: number): Brep {
+    ensureInit();
+    const json = wasm.brep_extract_face(this.json, faceIndex);
+    if (!json) throw new Error(`Brep.extractFace(${faceIndex}) failed`);
+    return new Brep(json);
+  }
+
+  /**
+   * ALL faces as standalone single-face trimmed sheet Breps, in ONE WASM
+   * crossing (the body is parsed once kernel-side — much faster than calling
+   * {@link extractFace} per face). Faces that fail to extract (corrupt
+   * topology) are skipped.
+   */
+  faces(): Brep[] {
+    ensureInit();
+    const arrayJson = wasm.brep_extract_faces(this.json);
+    if (!arrayJson) throw new Error("Brep.faces failed");
+    const parsed = JSON.parse(arrayJson) as unknown[];
+    const out: Brep[] = [];
+    for (const item of parsed) {
+      if (item != null) out.push(new Brep(JSON.stringify(item)));
+    }
+    return out;
+  }
+
+  /**
+   * The face's underlying surface CROPPED to its trim extent, ALWAYS as a
+   * NurbsSurface: curved faces get an exact sub-patch of the backing surface
+   * over the trim's UV bounding box; planar faces become exact degree-1
+   * patches spanning the face (never a raw infinite Plane). Non-rectangular
+   * trim regions stay rectangular-cropped here — use {@link extractFace} when
+   * the exact trim boundary matters.
+   */
+  faceSurfaceCropped(faceIndex: number): NurbsSurface {
+    ensureInit();
+    const buf = wasm.brep_face_surface_cropped(this.json, faceIndex);
+    if (buf.length < 4) throw new Error(`Brep.faceSurfaceCropped(${faceIndex}) failed`);
+    return NurbsSurface.fromData(buf);
+  }
+
+  /**
+   * Batch variant of {@link faceSurfaceCropped} for all faces in ONE WASM
+   * crossing. The result is aligned with face indices; a face whose trim
+   * region is degenerate yields null.
+   */
+  faceSurfacesCropped(): (NurbsSurface | null)[] {
+    ensureInit();
+    const buf = wasm.brep_face_surfaces_cropped(this.json);
+    if (buf.length < 1) throw new Error("Brep.faceSurfacesCropped failed");
+    const count = Number(buf[0]);
+    const out: (NurbsSurface | null)[] = [];
+    let offset = 1;
+    for (let i = 0; i < count && offset < buf.length; i++) {
+      const len = Number(buf[offset]);
+      offset += 1;
+      if (len < 4) {
+        out.push(null);
+        continue;
+      }
+      out.push(NurbsSurface.fromData(buf.subarray(offset, offset + len)));
+      offset += len;
+    }
+    return out;
+  }
+
+  /**
+   * UV bounding box of a face's trim loops in the surface's parameter space
+   * (knot domain for NURBS faces, frame coordinates for planar faces).
+   */
+  faceTrimBounds(faceIndex: number): { u0: number; u1: number; v0: number; v1: number } {
+    ensureInit();
+    const buf = wasm.brep_face_trim_bounds(this.json, faceIndex);
+    if (buf.length < 4) throw new Error(`Brep.faceTrimBounds(${faceIndex}) failed`);
+    return { u0: buf[0], u1: buf[1], v0: buf[2], v1: buf[3] };
+  }
+
   /**
    * Exact iso-parametric curve of a curved face's backing surface.
    * Returns null for planar faces.
@@ -265,6 +376,115 @@ export class Brep {
     return NurbsCurve.fromData(buf);
   }
 
+  /**
+   * Tessellate with per-face triangle ranges for face-level picking.
+   * `tolerance = 0` selects the deterministic auto display tolerance (derived
+   * from the BREP's own extent), so triangle indices stay valid across calls
+   * that also use the auto tolerance.
+   */
+  tessellateWithFaces(tolerance = 0): {
+    mesh: Mesh;
+    /** Flat (faceIndex, firstTriangle, triangleCount) triples. */
+    faceRanges: Uint32Array;
+  } {
+    ensureInit();
+    const buf = wasm.brep_tessellate_with_face_ranges(this.json, tolerance);
+    if (buf.length < 3) throw new Error("Brep.tessellateWithFaces failed");
+    const vc = Number(buf[0]);
+    const ic = Number(buf[1]);
+    const rc = Number(buf[2]);
+    const meshBuf = new Float64Array(1 + vc * 3 + ic);
+    meshBuf[0] = vc;
+    meshBuf.set(buf.subarray(3, 3 + vc * 3 + ic), 1);
+    const ranges = new Uint32Array(rc * 3);
+    const base = 3 + vc * 3 + ic;
+    for (let i = 0; i < rc * 3; i++) ranges[i] = Number(buf[base + i]);
+    return { mesh: Mesh.fromBuffer(meshBuf), faceRanges: ranges };
+  }
+
+  /**
+   * Closest face to a 3D point, with the exact surface (u, v) in the KNOT
+   * domain. Returns null when the BREP is empty.
+   */
+  closestFace(point: Point): {
+    faceIndex: number;
+    u: number;
+    v: number;
+    distance: number;
+    isNurbs: boolean;
+  } | null {
+    ensureInit();
+    const buf = wasm.brep_closest_face(this.json, point.x, point.y, point.z);
+    if (buf.length < 5) return null;
+    return {
+      faceIndex: Number(buf[0]),
+      u: buf[1],
+      v: buf[2],
+      distance: buf[3],
+      isNurbs: buf[4] > 0.5,
+    };
+  }
+
+  /**
+   * Exact (u, v) of a point on a SPECIFIC face (closest-point Newton for
+   * NURBS, frame projection for planes).
+   */
+  faceClosestUv(
+    faceIndex: number,
+    point: Point,
+  ): { u: number; v: number; distance: number; isNurbs: boolean } | null {
+    ensureInit();
+    const buf = wasm.brep_face_closest_uv(this.json, faceIndex, point.x, point.y, point.z);
+    if (buf.length < 4) return null;
+    return { u: buf[0], v: buf[1], distance: buf[2], isNurbs: buf[3] > 0.5 };
+  }
+
+  /**
+   * Exact isocurve(s) of a face at KNOT-domain parameter `t`, CLIPPED to the
+   * face's trimmed region (unlike {@link faceIsoCurve}, which spans the full
+   * backing surface). Planar faces yield straight (degree-1) pieces across
+   * the region; curved faces yield exact rational sub-curves. Multiple pieces
+   * come back when the region is non-convex or holed along the iso line.
+   * @param direction - "u" runs along u at constant v = t; "v" the converse
+   */
+  faceIsoCurvesTrimmed(faceIndex: number, t: number, direction: "u" | "v"): NurbsCurve[] {
+    ensureInit();
+    return Brep.parseCurveList(
+      wasm.brep_face_iso_curves_trimmed(this.json, faceIndex, t, direction === "u"),
+    );
+  }
+
+  /**
+   * Like {@link faceIsoCurvesTrimmed}, but `t` is a NORMALIZED [0, 1]
+   * parameter mapped across the face's trim extent in the fixed direction —
+   * no knot-domain knowledge needed. t = 0.5 is the middle of the face.
+   */
+  faceIsoCurvesTrimmedNormalized(
+    faceIndex: number,
+    t: number,
+    direction: "u" | "v",
+  ): NurbsCurve[] {
+    ensureInit();
+    return Brep.parseCurveList(
+      wasm.brep_face_iso_curves_trimmed_normalized(this.json, faceIndex, t, direction === "u"),
+    );
+  }
+
+  /** Parse [count, (bufLen, curveData…)·count] into NurbsCurves. */
+  private static parseCurveList(buf: Float64Array): NurbsCurve[] {
+    if (buf.length < 1) return [];
+    const out: NurbsCurve[] = [];
+    let offset = 1;
+    const count = Number(buf[0]);
+    for (let k = 0; k < count && offset < buf.length; k++) {
+      const len = Number(buf[offset]);
+      offset += 1;
+      out.push(NurbsCurve.fromData(buf.subarray(offset, offset + len)));
+      offset += len;
+    }
+    return out;
+  }
+
   // ── Transforms ──
 
   /** Apply a row-major 4x4 matrix to all geometry (exact). */
@@ -430,6 +650,95 @@ export class Brep {
     return this.runParametricBoolean(other, "intersect", options);
   }
 
+  // ── Mesh → BREP and solid ÷ sheet split ──
+
+  /**
+   * Convert a closed manifold triangle mesh into a planar-face BREP: coplanar
+   * connected facet groups become single trimmed planar faces (with hole
+   * loops), shared boundaries weld into exact line edges. A mesh box becomes
+   * the same 6-face / 12-edge / 8-vertex topology as {@link Brep.box}.
+   *
+   * The mesh's winding is authoritative (inside-out input is re-oriented);
+   * open or non-manifold meshes are rejected. Intended for planar-faceted
+   * solids (boxes, extrusions, mesh-boolean results) — densely tessellated
+   * curved meshes fail the `maxFaces` guard instead of producing a
+   * pathological BREP.
+   */
+  static fromMesh(mesh: Mesh, options?: MeshToBrepConversionOptions): Brep {
+    ensureInit();
+    const json = wasm.brep_from_mesh_buffer(
+      mesh.vertexCount,
+      mesh.rawBuffer,
+      options?.normalAngleToleranceDeg ?? 0,
+      options?.maxFaces ?? 0,
+    );
+    if (!json) throw new Error("Brep.fromMesh failed");
+    if (json.startsWith('{"error"')) {
+      const parsed = JSON.parse(json) as { error: string };
+      throw new Error(`Brep.fromMesh failed: ${parsed.error}`);
+    }
+    return new Brep(json);
+  }
+
+  /**
+   * PARAMETRIC split of this CLOSED solid by a sheet (an open Brep — e.g.
+   * {@link Brep.fromSurface} — or a NurbsSurface directly): BOTH halves are
+   * returned as closed BREPs, each keeping the solid's exact faces on its
+   * side plus the sheet region inside the solid as an exact trimmed-surface
+   * cap (opposite orientations on the two halves).
+   *
+   * Sides follow the sheet's orientation — `negative` is the half behind the
+   * sheet normal — matching `Mesh.splitSolidBySurface`. When the sheet does
+   * not fully cut through, the whole solid comes back on one side and the
+   * other is null.
+   */
+  splitBySheet(
+    sheet: Brep | NurbsSurface,
+    options?: BrepParametricBooleanOptions,
+  ): BrepSplitSolidResult {
+    ensureInit();
+    const cutter = sheet instanceof Brep ? sheet : Brep.fromSurface(sheet);
+    const tolerance = options?.tolerance ?? 1e-6;
+    const json = wasm.brep_split_solid_by_sheet_op(this.json, cutter.json, tolerance);
+    return Brep.parseSplitResult(json, "Brep.splitBySheet");
+  }
+
+  /**
+   * One-shot production path for "mesh − NURBS surface → BREP": converts the
+   * closed triangle mesh to a planar-face BREP, builds the sheet, and runs the
+   * parametric split — all in a single WASM crossing. Equivalent to
+   * `Brep.fromMesh(mesh, options).splitBySheet(surface, options)` but without
+   * intermediate JSON round-trips.
+   */
+  static splitMeshBySurface(
+    mesh: Mesh,
+    surface: NurbsSurface,
+    options?: BrepParametricBooleanOptions & MeshToBrepConversionOptions,
+  ): BrepSplitSolidResult {
+    ensureInit();
+    const json = wasm.mesh_split_by_surface_to_brep(
+      mesh.vertexCount,
+      mesh.rawBuffer,
+      surface.data,
+      options?.tolerance ?? 1e-6,
+      options?.normalAngleToleranceDeg ?? 0,
+      options?.maxFaces ?? 0,
+    );
+    return Brep.parseSplitResult(json, "Brep.splitMeshBySurface");
+  }
+
+  private static parseSplitResult(json: string, label: string): BrepSplitSolidResult {
+    if (!json) throw new Error(`${label} failed`);
+    if (json.startsWith('{"error"')) {
+      const parsed = JSON.parse(json) as { error: string };
+      throw new Error(`${label} failed: ${parsed.error}`);
+    }
+    const parsed = JSON.parse(json) as { negative: unknown; positive: unknown };
+    const side = (v: unknown): Brep | null =>
+      v == null ? null : new Brep(JSON.stringify(v));
+    return { negative: side(parsed.negative), positive: side(parsed.positive) };
+  }
+
   /** JSON representation (persistence). */
   toJson(): string {
     return this.json;

package/src/Mesh.ts

@@ -1277,7 +1277,12 @@ export class Mesh {
 
   /**
    * Build a planar arc from center, start, and end points.
-   * Uses the shortest signed sweep between start and end around `normal`.
+   * Without `sweepHint` the shortest signed sweep between start and end
+   * around `normal` is used. With `sweepHint` (signed radians, typically the
+   * sweep from the previous interactive update or a stored arc parameter),
+   * the sweep candidate closest to the hint is chosen instead — this tracks
+   * the user's winding direction continuously through 180° and up to just
+   * under a full circle.
    */
   static buildPlanarArcCenterStartEnd(
     center: Point,
@@ -1285,6 +1290,7 @@ export class Mesh {
     endPoint: Point,
     normal: Vec3,
     segments = 64,
+    sweepHint?: number,
   ): PlanarArc {
     const n = normal.normalize();
     const minSegments = Math.max(2, Math.floor(segments));
@@ -1311,7 +1317,8 @@ export class Mesh {
     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);
+    const shortestSweep = Mesh.normalizeSignedAngle(endAngleRaw - startAngle);
+    const sweepAngle = Mesh.resolveSweepWithHint(shortestSweep, sweepHint);
     if (Math.abs(sweepAngle) < 1e-9) {
       return {
         points: [],
@@ -1440,6 +1447,93 @@ export class Mesh {
     };
   }
 
+  /**
+   * Build a planar arc through three points: `startPoint`, a point the arc
+   * passes through, and `endPoint`. All points are projected to the plane
+   * through `startPoint` orthogonal to `normal`; the circle is the
+   * circumcircle of the projected points and the sweep direction is the one
+   * that passes through `throughPoint` (any sweep up to a full circle).
+   * Returns null when the points are (near) collinear or coincident.
+   */
+  static buildPlanarArcThreePoint(
+    startPoint: Point,
+    throughPoint: Point,
+    endPoint: Point,
+    normal: Vec3,
+    segments = 64,
+  ): PlanarArc | null {
+    const n = normal.normalize();
+    const minSegments = Math.max(2, Math.floor(segments));
+    const a = Mesh.projectPointToPlane(startPoint, startPoint, n);
+    const b = Mesh.projectPointToPlane(throughPoint, startPoint, n);
+    const c = Mesh.projectPointToPlane(endPoint, startPoint, n);
+
+    const ab = b.sub(a);
+    const ac = c.sub(a);
+    const scale = Math.max(ab.length(), ac.length());
+    const cross = ab.cross(ac);
+    const crossLen = cross.length();
+    if (scale < 1e-12 || crossLen < 1e-9 * scale * scale) {
+      return null;
+    }
+
+    // Circumcenter: A + ((|ab|²·ac − |ac|²·ab) × (ab × ac)) / (2·|ab × ac|²)
+    const numerator = ac.scale(ab.dot(ab)).sub(ab.scale(ac.dot(ac)));
+    const center = a.add(numerator.cross(cross).scale(1 / (2 * cross.dot(cross))));
+    const radius = a.sub(center).length();
+    if (radius < 1e-12) {
+      return null;
+    }
+
+    const basis = Mesh.resolveArcBasis(center, radius, n);
+    const twoPi = Math.PI * 2;
+    const startAngle = Mesh.angleOnBasis(a.sub(center), basis.uAxis, basis.vAxis);
+    const throughAngle = Mesh.angleOnBasis(b.sub(center), basis.uAxis, basis.vAxis);
+    const endAngleRaw = Mesh.angleOnBasis(c.sub(center), basis.uAxis, basis.vAxis);
+
+    const ccwSweep = ((endAngleRaw - startAngle) % twoPi + twoPi) % twoPi;
+    const ccwThrough = ((throughAngle - startAngle) % twoPi + twoPi) % twoPi;
+    if (ccwSweep < 1e-9 || twoPi - ccwSweep < 1e-9) {
+      return null;
+    }
+    const sweepAngle = ccwThrough <= ccwSweep ? ccwSweep : ccwSweep - twoPi;
+    const endAngle = startAngle + sweepAngle;
+    const arc = new Arc(center, radius, startAngle, endAngle, n);
+    return {
+      points: arc.sample(minSegments),
+      center,
+      radius,
+      startAngle,
+      endAngle,
+      sweepAngle,
+    };
+  }
+
+  /** Largest supported arc sweep — just under a full circle keeps arcs open. */
+  private static readonly MAX_ARC_SWEEP = Math.PI * 2 - 1e-4;
+
+  /**
+   * Pick the sweep equivalent (shortest, +2π, or −2π) closest to `hint`,
+   * clamped to just under a full circle. Without a hint the shortest sweep
+   * is kept.
+   */
+  private static resolveSweepWithHint(shortestSweep: number, hint?: number): number {
+    if (hint === undefined || !Number.isFinite(hint)) {
+      return shortestSweep;
+    }
+    const twoPi = Math.PI * 2;
+    let best = shortestSweep;
+    let bestDistance = Math.abs(shortestSweep - hint);
+    for (const candidate of [shortestSweep + twoPi, shortestSweep - twoPi]) {
+      const distance = Math.abs(candidate - hint);
+      if (distance < bestDistance) {
+        best = candidate;
+        bestDistance = distance;
+      }
+    }
+    return Math.max(-Mesh.MAX_ARC_SWEEP, Math.min(Mesh.MAX_ARC_SWEEP, best));
+  }
+
   private static resolveArcBasis(
     center: Point,
     radius: number,
@@ -3116,6 +3210,37 @@ export class Mesh {
     return new Point(r[0], r[1], r[2]);
   }
 
+  /**
+   * Boundary loops of the coplanar edge-connected face group containing
+   * faceIndex. Each loop is a closed polygon (winding preserved, collinear
+   * subdivision points collapsed); the closing edge back to the first point
+   * is implicit.
+   */
+  getFaceBoundaryLoops(faceIndex: number): Point[][] {
+    ensureInit();
+    if (!Number.isFinite(faceIndex) || faceIndex < 0) return [];
+    const r = wasm.mesh_get_face_boundary_loops(
+      this._vertexCount,
+      this._buffer,
+      Math.floor(faceIndex),
+    );
+    if (!r || r.length < 1) return [];
+    const loopCount = Math.floor(r[0]);
+    const loops: Point[][] = [];
+    let offset = 1;
+    for (let l = 0; l < loopCount && offset < r.length; l++) {
+      const pointCount = Math.floor(r[offset]);
+      offset += 1;
+      const loop: Point[] = [];
+      for (let i = 0; i < pointCount && offset + 2 < r.length; i++) {
+        loop.push(new Point(r[offset], r[offset + 1], r[offset + 2]));
+        offset += 3;
+      }
+      if (loop.length >= 3) loops.push(loop);
+    }
+    return loops;
+  }
+
   /**
    * Unique edge count for this triangulated mesh.
    */

package/src/NurbsSurface.ts

@@ -176,11 +176,19 @@ export class NurbsSurface implements Surface {
     // Step 0: Convert all curves to NurbsCurve
     const nurbsCurves = curves.map(c => NurbsSurface.toNurbs(c));
 
-    // Step 1: Make curves compatible (unified knot vectors, same CP count)
+    // Step 1: Make curves compatible (same degree, unified knot vectors,
+    // same CP count). Mixed degrees are fine — the kernel degree-elevates
+    // lower-degree curves to the max degree exactly (a 2-point line lofts
+    // with a cubic).
     let loftCurves = nurbsCurves;
     if (nurbsCurves.length >= 2) {
-      const cpCounts = nurbsCurves.map(c => c.controlPoints.length);
-      const allSame = cpCounts.every(n => n === cpCounts[0]);
+      const ref = nurbsCurves[0];
+      const matchesRef = (c: NurbsCurve) =>
+        c.degree === ref.degree &&
+        c.controlPoints.length === ref.controlPoints.length &&
+        c.knots.length === ref.knots.length &&
+        c.knots.every((k, i) => Math.abs(k - (ref.knots[i] as number)) < 1e-12);
+      const allSame = nurbsCurves.every(matchesRef);
       if (!allSame) {
         const compatParts: number[] = [nurbsCurves.length];
         for (const c of nurbsCurves) {
@@ -190,19 +198,20 @@ export class NurbsSurface implements Surface {
           for (const k of c.knots) { compatParts.push(k); }
         }
         const compatBuf = wasm.make_nurbs_curves_compatible(new Float64Array(compatParts));
-        if (compatBuf.length > 0) {
-          const count = Number(compatBuf[0] ?? 0);
-          const decoded: NurbsCurve[] = [];
-          let off = 1;
-          for (let i = 0; i < count; i++) {
-            const deg = Number(compatBuf[off] ?? 0);
-            const n = Number(compatBuf[off + 1] ?? 0);
-            const curveLen = 2 + n * 3 + n + (n + deg + 1);
-            decoded.push(NurbsCurve.fromData(compatBuf.slice(off, off + curveLen)));
-            off += curveLen;
-          }
-          loftCurves = decoded;
+        if (compatBuf.length === 0) {
+          throw new Error("NurbsSurface loft: profile curves could not be made compatible");
         }
+        const count = Number(compatBuf[0] ?? 0);
+        const decoded: NurbsCurve[] = [];
+        let off = 1;
+        for (let i = 0; i < count; i++) {
+          const deg = Number(compatBuf[off] ?? 0);
+          const n = Number(compatBuf[off + 1] ?? 0);
+          const curveLen = 2 + n * 3 + n + (n + deg + 1);
+          decoded.push(NurbsCurve.fromData(compatBuf.slice(off, off + curveLen)));
+          off += curveLen;
+        }
+        loftCurves = decoded;
       }
     }
 

package/src/index.ts

@@ -43,6 +43,8 @@ export type {
   BrepValidationReport,
   BrepBooleanOptions,
   BrepParametricBooleanOptions,
+  MeshToBrepConversionOptions,
+  BrepSplitSolidResult,
 } from "./Brep.js";
 
 // Mesh and operations