okgeometry-api 1.5.0 → 1.9.0

package/src/Brep.ts

@@ -0,0 +1,437 @@
+import { ensureInit } from "./engine.js";
+import { Point } from "./Point.js";
+import { Vec3 } from "./Vec3.js";
+import { Plane } from "./Plane.js";
+import { Mesh, type MeshBooleanOptions } from "./Mesh.js";
+import { Polyline } from "./Polyline.js";
+import { NurbsCurve } from "./NurbsCurve.js";
+import { NurbsSurface } from "./NurbsSurface.js";
+import * as wasm from "./wasm-bindings.js";
+
+/** Options for Brep boolean operations. */
+export interface BrepBooleanOptions extends MeshBooleanOptions {
+  /**
+   * Chordal deviation tolerance used to tessellate BREP operands before the
+   * boolean runs (model units). Defaults to 0.005, matching `toMesh()`.
+   */
+  tolerance?: number;
+}
+
+/** Options for PARAMETRIC Brep booleans (exact SSI, BREP result). */
+export interface BrepParametricBooleanOptions {
+  /**
+   * Absolute geometric tolerance for intersection edges and coincident-face
+   * classification (model units). Defaults to 1e-6.
+   */
+  tolerance?: number;
+}
+
+/** Validation report for a BREP body. */
+export interface BrepValidationReport {
+  isClosed: boolean;
+  boundaryEdgeCount: number;
+  maxCoherenceError: number;
+  issues: string[];
+}
+
+/** Structure summary of a BREP body. */
+export interface BrepInfo {
+  faceCount: number;
+  edgeCount: number;
+  vertexCount: number;
+  isClosed: boolean;
+}
+
+/**
+ * Boundary representation (BREP) solid or sheet backed by the WASM kernel.
+ *
+ * A Brep is a graph of faces (trimmed exact surfaces — planes or NURBS),
+ * edges (exact 3D curves shared between faces) and vertices. Unlike a Mesh,
+ * the geometry stays EXACT: a cylinder face is a true rational surface, and
+ * tessellation density is a display decision made at query time.
+ *
+ * Topology is carried as JSON (kernel-defined schema) so it can persist in
+ * documents; tessellation and queries are binary WASM calls.
+ */
+export class Brep {
+  private _info: BrepInfo | null = null;
+
+  private constructor(public readonly json: string) {
+    if (!json) throw new Error("Brep: empty body");
+  }
+
+  // ── Constructors ──
+
+  /** Restore a Brep from its JSON representation. */
+  static fromJson(json: string): Brep {
+    return new Brep(json);
+  }
+
+  /** Exact BREP box between two corners (6 planar faces, 12 edges, 8 vertices). */
+  static box(min: Point, max: Point): Brep {
+    ensureInit();
+    return Brep.fromPrimitive("box", [min.x, min.y, min.z, max.x, max.y, max.z]);
+  }
+
+  /** Exact BREP cylinder (rational side surface + planar caps). */
+  static cylinder(base: Point, axis: Vec3, radius: number, height: number): Brep {
+    ensureInit();
+    return Brep.fromPrimitive("cylinder", [
+      base.x, base.y, base.z, axis.x, axis.y, axis.z, radius, height,
+    ]);
+  }
+
+  /** Exact BREP sphere (single rational face, degenerate poles). */
+  static sphere(center: Point, radius: number): Brep {
+    ensureInit();
+    return Brep.fromPrimitive("sphere", [center.x, center.y, center.z, radius]);
+  }
+
+  /** Exact BREP cone or frustum (radius1 = 0 produces an apex). */
+  static cone(base: Point, axis: Vec3, radius0: number, radius1: number, height: number): Brep {
+    ensureInit();
+    return Brep.fromPrimitive("cone", [
+      base.x, base.y, base.z, axis.x, axis.y, axis.z, radius0, radius1, height,
+    ]);
+  }
+
+  /** Exact BREP torus (single rational face, axis +Z through center). */
+  static torus(center: Point, major: number, minor: number): Brep {
+    ensureInit();
+    return Brep.fromPrimitive("torus", [center.x, center.y, center.z, major, minor]);
+  }
+
+  private static fromPrimitive(kind: string, params: number[]): Brep {
+    const json = wasm.brep_primitive(kind, new Float64Array(params));
+    if (!json) throw new Error(`Brep.${kind} construction failed`);
+    return new Brep(json);
+  }
+
+  /**
+   * Extrude a planar profile curve. Closed profiles produce a capped solid
+   * with proper shared-edge topology; open profiles produce a sheet.
+   */
+  static extrude(profile: NurbsCurve, direction: Vec3, height: number): Brep {
+    ensureInit();
+    const json = wasm.brep_extrude_curve(profile.data, direction.x, direction.y, direction.z, height);
+    if (!json) throw new Error("Brep.extrude failed (profile must be planar)");
+    return new Brep(json);
+  }
+
+  /**
+   * Revolve a profile curve around an axis.
+   * Full revolutions of closed profiles produce torus-like single-face solids;
+   * open profiles with on-axis endpoints close at the poles (sphere/cone style);
+   * partial revolutions of closed planar profiles get planar caps.
+   */
+  static revolve(profile: NurbsCurve, origin: Point, axis: Vec3, angle: number): Brep {
+    ensureInit();
+    const json = wasm.brep_revolve_curve(
+      profile.data,
+      origin.x, origin.y, origin.z,
+      axis.x, axis.y, axis.z,
+      angle
+    );
+    if (!json) throw new Error("Brep.revolve failed");
+    return new Brep(json);
+  }
+
+  /** Loft through profile curves (compatibility handled automatically). */
+  static loft(profiles: NurbsCurve[]): Brep {
+    ensureInit();
+    if (profiles.length < 2) throw new Error("Brep.loft needs at least 2 profiles");
+    const parts: number[] = [profiles.length];
+    for (const c of profiles) {
+      const d = c.data;
+      for (let i = 0; i < d.length; i++) parts.push(d[i]);
+    }
+    const json = wasm.brep_loft_curves(new Float64Array(parts));
+    if (!json) throw new Error("Brep.loft failed");
+    return new Brep(json);
+  }
+
+  /** Untrimmed sheet BREP from a NURBS surface (4 boundary edges). */
+  static fromSurface(surface: NurbsSurface): Brep {
+    ensureInit();
+    const json = wasm.brep_sheet_from_surface(surface.data);
+    if (!json) throw new Error("Brep.fromSurface failed");
+    return new Brep(json);
+  }
+
+  // ── Structure ──
+
+  /** Face/edge/vertex counts and closedness (cached). */
+  get info(): BrepInfo {
+    if (!this._info) {
+      ensureInit();
+      const r = wasm.brep_info(this.json);
+      if (r.length < 4) throw new Error("Brep.info failed");
+      this._info = {
+        faceCount: Number(r[0]),
+        edgeCount: Number(r[1]),
+        vertexCount: Number(r[2]),
+        isClosed: r[3] > 0.5,
+      };
+    }
+    return this._info;
+  }
+
+  get faceCount(): number {
+    return this.info.faceCount;
+  }
+
+  get edgeCount(): number {
+    return this.info.edgeCount;
+  }
+
+  /** Whether every non-degenerate edge is shared by exactly two faces (solid). */
+  isClosed(): boolean {
+    return this.info.isClosed;
+  }
+
+  // ── Tessellation / display ──
+
+  /**
+   * Tessellate the whole body into a triangle mesh. Adjacent faces share the
+   * same edge samples, so the result is crack-free (watertight for solids).
+   * @param tolerance - Chordal deviation tolerance (model units)
+   */
+  tessellate(tolerance = 0.01): Mesh {
+    ensureInit();
+    const buf = wasm.brep_tessellate(this.json, tolerance);
+    if (buf.length < 1) throw new Error("Brep.tessellate failed");
+    return Mesh.fromBuffer(buf);
+  }
+
+  /** Tessellate a single face into a triangle mesh. */
+  tessellateFace(faceIndex: number, tolerance = 0.01): Mesh {
+    ensureInit();
+    const buf = wasm.brep_face_tessellate(this.json, faceIndex, tolerance);
+    if (buf.length < 1) throw new Error(`Brep.tessellateFace(${faceIndex}) failed`);
+    return Mesh.fromBuffer(buf);
+  }
+
+  /** Exact model edges sampled as polylines (feature curves for display/selection). */
+  edges(tolerance = 0.01): Polyline[] {
+    ensureInit();
+    const buf = wasm.brep_edges(this.json, 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;
+  }
+
+  // ── Face geometry ──
+
+  /**
+   * Exact backing surface of a face: a NurbsSurface for curved faces, a Plane
+   * for planar faces.
+   */
+  faceSurface(faceIndex: number): NurbsSurface | Plane {
+    ensureInit();
+    const buf = wasm.brep_face_surface(this.json, faceIndex);
+    if (buf.length < 1) throw new Error(`Brep.faceSurface(${faceIndex}) failed`);
+    if (Number(buf[0]) === 0) {
+      if (buf.length < 10) throw new Error("Brep.faceSurface: bad plane data");
+      const origin = new Point(buf[1], buf[2], buf[3]);
+      const uDir = new Vec3(buf[4], buf[5], buf[6]);
+      const vDir = new Vec3(buf[7], buf[8], buf[9]);
+      const normal = uDir.cross(vDir);
+      return new Plane(origin, normal, uDir);
+    }
+    return NurbsSurface.fromData(buf.slice(1));
+  }
+
+  /**
+   * Exact iso-parametric curve of a curved face's backing surface.
+   * Returns null for planar faces.
+   * @param t - Normalized parameter [0, 1]
+   * @param direction - "u" extracts along u at constant v=t; "v" the converse
+   */
+  faceIsoCurve(faceIndex: number, t: number, direction: "u" | "v"): NurbsCurve | null {
+    ensureInit();
+    const buf = wasm.brep_face_iso_curve(this.json, faceIndex, t, direction === "u");
+    if (buf.length < 2) return null;
+    return NurbsCurve.fromData(buf);
+  }
+
+  // ── Transforms ──
+
+  /** Apply a row-major 4x4 matrix to all geometry (exact). */
+  applyMatrix(matrix: number[] | Float64Array): Brep {
+    ensureInit();
+    if (matrix.length < 16) throw new Error("Brep.applyMatrix: need 16 entries");
+    const json = wasm.brep_transform(this.json, new Float64Array(matrix));
+    if (!json) throw new Error("Brep.applyMatrix failed");
+    return new Brep(json);
+  }
+
+  /** Translate the body. */
+  translate(offset: Vec3): Brep {
+    return this.applyMatrix([
+      1, 0, 0, offset.x,
+      0, 1, 0, offset.y,
+      0, 0, 1, offset.z,
+      0, 0, 0, 1,
+    ]);
+  }
+
+  // ── Analysis ──
+
+  /** Validate topology and trim coherence. */
+  validate(tolerance = 1e-7): BrepValidationReport {
+    ensureInit();
+    const json = wasm.brep_validate(this.json, tolerance);
+    if (!json) throw new Error("Brep.validate failed");
+    return JSON.parse(json) as BrepValidationReport;
+  }
+
+  /** Volume and surface area (from tessellation at the given tolerance). */
+  volumeArea(tolerance = 0.001): { volume: number; area: number } {
+    ensureInit();
+    const r = wasm.brep_volume_area(this.json, tolerance);
+    if (r.length < 2) throw new Error("Brep.volumeArea failed");
+    return { volume: r[0], area: r[1] };
+  }
+
+  /** Convert to a mesh body (e.g. for boolean operations with meshes). */
+  toMesh(tolerance = 0.005): Mesh {
+    return this.tessellate(tolerance);
+  }
+
+  // ── Booleans ──
+
+  private static resolveBooleanOperand(other: Brep | Mesh, tolerance: number): Mesh {
+    return other instanceof Mesh ? other : other.toMesh(tolerance);
+  }
+
+  private runBoolean(
+    other: Brep | Mesh,
+    op: "union" | "subtract" | "intersect",
+    options?: BrepBooleanOptions,
+  ): Mesh {
+    const tolerance = options?.tolerance ?? 0.005;
+    // The mesh CSG pipeline is sensitive to specific tessellation densities on
+    // curved (especially rational) surfaces; a failed run usually succeeds at
+    // a slightly perturbed density. Retry with nudged (coarser — finer risks
+    // the face-count safety limits) tolerances before giving up; accuracy
+    // stays within the requested band.
+    const attempts = [1.0, 1.12, 1.25, 1.4];
+    let lastError: unknown;
+    for (const factor of attempts) {
+      const tol = tolerance * factor;
+      try {
+        const lhs = this.toMesh(tol);
+        const rhs = Brep.resolveBooleanOperand(other, tol);
+        return lhs[op](rhs, options);
+      } catch (e) {
+        lastError = e;
+      }
+    }
+    throw lastError;
+  }
+
+  /**
+   * Boolean union with another Brep or Mesh.
+   *
+   * Both operands are tessellated at `options.tolerance` (BREP tessellation
+   * is crack-free, so closed bodies stay watertight) and combined with the
+   * mesh CSG pipeline. The result is a Mesh — exact trimmed-BREP boolean
+   * output is not supported. Requires both bodies to be closed solids.
+   */
+  union(other: Brep | Mesh, options?: BrepBooleanOptions): Mesh {
+    return this.runBoolean(other, "union", options);
+  }
+
+  /**
+   * Boolean subtraction (this − other) with another Brep or Mesh.
+   *
+   * Closed − closed runs full CSG; an open sheet Brep minus a closed solid
+   * trims the sheet (split, keep outside). The result is a Mesh.
+   */
+  subtract(other: Brep | Mesh, options?: BrepBooleanOptions): Mesh {
+    return this.runBoolean(other, "subtract", options);
+  }
+
+  /**
+   * Boolean intersection with another Brep or Mesh.
+   *
+   * Closed ∩ closed returns the shared volume; an open sheet Brep ∩ a closed
+   * solid trims the sheet (split, keep inside). The result is a Mesh.
+   */
+  intersect(other: Brep | Mesh, options?: BrepBooleanOptions): Mesh {
+    return this.runBoolean(other, "intersect", options);
+  }
+
+  /**
+   * Intersection CURVES with another Brep or Mesh — the polylines where the
+   * two surfaces cross (no volume classification). Tolerance controls the
+   * tessellation density of both operands.
+   */
+  intersectCurves(other: Brep | Mesh, tolerance = 0.005): Polyline[] {
+    const lhs = this.toMesh(tolerance);
+    const rhs = Brep.resolveBooleanOperand(other, tolerance);
+    return lhs.intersectMesh(rhs);
+  }
+
+  // ── Parametric booleans (BREP → BREP) ──
+
+  private runParametricBoolean(
+    other: Brep,
+    op: "union" | "subtract" | "intersect",
+    options?: BrepParametricBooleanOptions,
+  ): Brep {
+    ensureInit();
+    const tolerance = options?.tolerance ?? 1e-6;
+    const json = wasm.brep_boolean_op(this.json, other.json, op, tolerance);
+    if (!json) throw new Error(`Brep.${op}Brep failed`);
+    if (json.startsWith('{"error"')) {
+      const parsed = JSON.parse(json) as { error: string };
+      throw new Error(`Brep.${op}Brep failed: ${parsed.error}`);
+    }
+    return new Brep(json);
+  }
+
+  /**
+   * PARAMETRIC boolean union: exact surface–surface intersection curves with
+   * trimmed-surface output. Result faces keep their parents' exact surfaces
+   * (planes/NURBS, untessellated); intersection edges are Newton-refined SSI
+   * curves stored as tolerant NURBS edges with matched pcurves on both
+   * adjacent faces. Both operands must be CLOSED solids.
+   *
+   * `options.tolerance` is the absolute geometric tolerance of intersection
+   * edges and coincident-face classification (default 1e-6).
+   *
+   * Known limitation: exactly tangential surface contact (e.g. equal-radius
+   * cylinders touching along a line/point) is not resolved into pinch
+   * topology; transversal and coincident (coplanar) configurations are exact.
+   */
+  unionBrep(other: Brep, options?: BrepParametricBooleanOptions): Brep {
+    return this.runParametricBoolean(other, "union", options);
+  }
+
+  /** PARAMETRIC boolean subtraction (this − other). See {@link unionBrep}. */
+  subtractBrep(other: Brep, options?: BrepParametricBooleanOptions): Brep {
+    return this.runParametricBoolean(other, "subtract", options);
+  }
+
+  /** PARAMETRIC boolean intersection. See {@link unionBrep}. */
+  intersectBrep(other: Brep, options?: BrepParametricBooleanOptions): Brep {
+    return this.runParametricBoolean(other, "intersect", options);
+  }
+
+  /** JSON representation (persistence). */
+  toJson(): string {
+    return this.json;
+  }
+}

package/src/Mesh.ts

@@ -1879,7 +1879,12 @@ export class Mesh {
     data.set(coords, 2);
     return data;
   }
-  private static mergeMeshes(meshes: Mesh[]): Mesh {
+  /**
+   * Concatenate meshes into one multi-component mesh (buffer merge with
+   * index offsetting — no welding and no CSG). Useful for collecting split
+   * pieces back into a single body.
+   */
+  static mergeMeshes(meshes: Mesh[]): Mesh {
     ensureInit();
     const packed = Mesh.packMeshes(meshes);
     return Mesh.fromTrustedBuffer(wasm.mesh_merge(packed));
@@ -2296,7 +2301,8 @@ export class Mesh {
     if (cutters.length === 0) return Mesh.cloneMesh(host);
     if (cutters.length === 1) return host.subtract(cutters[0], options);
 
-    if (!host.isClosedVolume() || cutters.some((mesh) => !mesh.isClosedVolume())) {
+    if (cutters.some((mesh) => !mesh.isClosedVolume())) {
+      // Open cutters carry per-pair trim/error semantics — sequential only.
       return cutters.reduce((acc: Mesh, cutter) => acc.subtract(cutter, options), host);
     }
 
@@ -2314,6 +2320,15 @@ export class Mesh {
     const flags = host._trustedBooleanInput && relevant.every((mesh) => mesh._trustedBooleanInput)
       ? "trustedInput"
       : "";
+
+    if (!host.isClosedVolume()) {
+      // Open host + closed cutters: batched surface trim. One pass over the
+      // host with all cutters at once — replaces the sequential pairwise
+      // fold, which re-split (and degraded) the growing host once per cutter.
+      const result = wasm.mesh_surface_difference_all(Mesh.packMeshes([host, ...relevant]), flags);
+      return Mesh.decodeBatchBooleanResult("subtractAll", result);
+    }
+
     const result = wasm.mesh_boolean_difference_all(Mesh.packMeshes([host, ...relevant]), flags);
     return Mesh.decodeBatchBooleanResult("subtractAll", result);
   }
@@ -2752,6 +2767,62 @@ export class Mesh {
     return parsePolylineBuf(result).map(pts => new Polyline(pts));
   }
 
+  /**
+   * Clip a polyline against this CLOSED mesh volume — boolean intersection
+   * semantics for curves. The polyline is split at every crossing with the
+   * mesh surface; pieces inside the volume land in `inside`, the rest in
+   * `outside`. Closed loops merge the piece spanning the loop seam, and a
+   * loop that never crosses the mesh comes back as one closed polyline.
+   *
+   * @param polyline - Polyline (closedness inferred) or raw point list
+   * @param closed - Treat the points as a closed loop (defaults to the
+   *   polyline's own closedness; required when passing a raw point list)
+   */
+  clipPolyline(
+    polyline: Polyline | Point[],
+    closed?: boolean,
+  ): { inside: Polyline[]; outside: Polyline[] } {
+    ensureInit();
+    const pts = Array.isArray(polyline) ? polyline : polyline.points;
+    if (pts.length < 2) {
+      throw new Error("Mesh.clipPolyline needs at least 2 polyline points");
+    }
+    const isClosed = closed ?? (!Array.isArray(polyline) && polyline.isClosed());
+    const flat = new Float64Array(pts.length * 3);
+    for (let i = 0; i < pts.length; i++) {
+      flat[i * 3] = pts[i].x;
+      flat[i * 3 + 1] = pts[i].y;
+      flat[i * 3 + 2] = pts[i].z;
+    }
+
+    const buf = wasm.mesh_clip_polyline(this._vertexCount, this._buffer, flat, isClosed);
+    if (buf.length === 0) {
+      throw new Error(
+        "Mesh.clipPolyline failed — the mesh must be a closed volume and the polyline non-degenerate.",
+      );
+    }
+
+    // Two concatenated polyline groups: inside first, then outside.
+    let idx = 0;
+    const readGroup = (): Polyline[] => {
+      const group: Polyline[] = [];
+      const count = buf[idx++];
+      for (let i = 0; i < count; i++) {
+        const n = buf[idx++];
+        const points: Point[] = [];
+        for (let k = 0; k < n; k++) {
+          points.push(new Point(buf[idx], buf[idx + 1], buf[idx + 2]));
+          idx += 3;
+        }
+        if (points.length >= 2) group.push(new Polyline(points));
+      }
+      return group;
+    };
+    const inside = readGroup();
+    const outside = readGroup();
+    return { inside, outside };
+  }
+
   /**
    * Apply a 4x4 transformation matrix.
    * @param matrix - Row-major flat array of 16 numbers