okgeometry-api 1.11.1 → 1.15.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). */
@@ -384,6 +604,155 @@ export class Brep {
     return lhs.intersectMesh(rhs);
   }
 
+  // ── Exact intersections (parametric) ──
+
+  /**
+   * TRIM-EXACT intersection curves with another Brep or a NurbsSurface,
+   * returned as exact fitted NURBS curves.
+   *
+   * Unlike {@link intersectCurves} (tessellation-based, returns polylines at
+   * the tessellation density), this runs the parametric boolean's SSI →
+   * clip → convergence stages on the EXACT surfaces and clips each
+   * intersection curve to BOTH faces' trimmed regions — no classification or
+   * assembly, just the fitted intersection edges.
+   *
+   * Operands need NOT be closed: sheet Breps are valid on either side, and a
+   * NurbsSurface operand is converted via {@link Brep.fromSurface}. A closed
+   * intersection loop may come back as several contiguous pieces (split at
+   * surface seams and face-boundary crossings); the pieces chain end-to-end
+   * exactly. Coincident (overlapping) face pairs contribute no curves.
+   *
+   * `options.tolerance` is the absolute geometric tolerance of the fitted
+   * intersection curves (default 1e-6).
+   */
+  intersectionCurves(other: Brep | NurbsSurface, options?: { tolerance?: number }): NurbsCurve[] {
+    ensureInit();
+    const rhs = other instanceof Brep ? other : Brep.fromSurface(other);
+    const tolerance = options?.tolerance ?? 1e-6;
+    const buf = wasm.brep_intersection_curves_op(this.json, rhs.json, tolerance);
+    // An EMPTY buffer signals a kernel error (invalid BREP / pipeline
+    // failure); "no intersections" is the non-empty `[0]` packing.
+    if (buf.length < 1) {
+      throw new Error(
+        "Brep.intersectionCurves failed — invalid BREP operands or kernel error",
+      );
+    }
+    return Brep.parseCurveList(buf);
+  }
+
+  /**
+   * All points where a NURBS curve pierces this BREP's faces.
+   *
+   * Per face, the curve is intersected with the face's EXACT surface
+   * (analytic + bisection for planes, full Newton for NURBS faces) and a hit
+   * is kept only when it lies INSIDE the face's trimmed region. Crossings on
+   * an edge shared by two faces are deduplicated (smallest face index kept).
+   *
+   * Hits are sorted by `curveParam` (normalized [0, 1] —
+   * `curve.pointAt(curveParam)` reproduces `point` to convergence accuracy);
+   * (u, v) are in the pierced face's OWN parameter space (knot domain for
+   * NURBS faces, plane-frame coordinates for planar faces). Curve segments
+   * lying ON a face (coincident runs) yield no hits.
+   */
+  intersectCurve(
+    curve: NurbsCurve,
+  ): { point: Point; curveParam: number; faceIndex: number; u: number; v: number }[] {
+    ensureInit();
+    const buf = wasm.brep_curve_intersection_op(this.json, curve.data);
+    if (buf.length < 1) return [];
+    const count = Number(buf[0]);
+    const hits: { point: Point; curveParam: number; faceIndex: number; u: number; v: number }[] =
+      [];
+    for (let i = 0; i < count; i++) {
+      const off = 1 + i * 7;
+      hits.push({
+        point: new Point(buf[off], buf[off + 1], buf[off + 2]),
+        curveParam: buf[off + 3],
+        faceIndex: Number(buf[off + 4]),
+        u: buf[off + 5],
+        v: buf[off + 6],
+      });
+    }
+    return hits;
+  }
+
+  /**
+   * Boolean-intersection clip of an exact NURBS curve against this CLOSED
+   * solid: the curve is split EXACTLY (knot insertion) at every boundary
+   * crossing and each piece is classified by containment, so every returned
+   * piece lies exactly on the input curve.
+   *
+   * Closed curves merge the run spanning the parameter seam (a closed curve
+   * that never crosses comes back as ONE closed piece on the containing
+   * side). Throws when this BREP is not a closed solid — sheet operands have
+   * no interior (use {@link intersectCurve} for the crossing points instead).
+   */
+  clipCurve(curve: NurbsCurve): { inside: NurbsCurve[]; outside: NurbsCurve[] } {
+    ensureInit();
+    if (!this.isClosed()) {
+      throw new Error(
+        "Brep.clipCurve requires a CLOSED solid BREP (sheet operands have no interior)",
+      );
+    }
+    const buf = wasm.brep_clip_curve_op(curve.data, this.json);
+    if (buf.length < 2) throw new Error("Brep.clipCurve failed");
+    // Packing: two concatenated multi-curve lists — inside then outside.
+    const insideCount = Number(buf[0]);
+    let offset = 1;
+    const readGroup = (count: number): NurbsCurve[] => {
+      const out: NurbsCurve[] = [];
+      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;
+    };
+    const inside = readGroup(insideCount);
+    const outsideCount = Number(buf[offset]);
+    offset += 1;
+    const outside = readGroup(outsideCount);
+    return { inside, outside };
+  }
+
+  /**
+   * Intersection curves with a triangle mesh.
+   *
+   * TESSELLATION-BASED (documented approximation): the BREP is tessellated at
+   * `tolerance` and intersected with the mesh via BVH-pruned tri-tri crossing
+   * + chaining, so the polylines approximate the true intersection to the
+   * chordal tessellation tolerance on the BREP side — exact where both sides
+   * are planar.
+   *
+   * @param mesh - Triangle mesh operand
+   * @param tolerance - BREP tessellation tolerance; `0` (default) selects the
+   *   deterministic auto display tolerance from the BREP's own extent
+   */
+  intersectMesh(mesh: Mesh, tolerance = 0): Polyline[] {
+    ensureInit();
+    const buf = wasm.brep_mesh_intersection_curves_op(
+      this.json,
+      mesh.vertexCount,
+      mesh.rawBuffer,
+      tolerance,
+    );
+    if (buf.length < 1) return [];
+    const out: Polyline[] = [];
+    let idx = 1;
+    const count = Number(buf[0]);
+    for (let i = 0; i < count; i++) {
+      const n = Number(buf[idx++]);
+      const pts: Point[] = [];
+      for (let k = 0; k < n; k++) {
+        pts.push(new Point(buf[idx], buf[idx + 1], buf[idx + 2]));
+        idx += 3;
+      }
+      if (pts.length >= 2) out.push(new Polyline(pts));
+    }
+    return out;
+  }
+
   // ── Parametric booleans (BREP → BREP) ──
 
   private runParametricBoolean(
@@ -430,6 +799,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;