okgeometry-api 1.15.0 → 1.17.0

package/package.json

@@ -1,54 +1,58 @@
-{
-  "name": "okgeometry-api",
-  "version": "1.15.0",
-  "description": "Geometry engine API for AEC applications — NURBS, meshes, booleans, intersections. Powered by Rust/WASM.",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist/",
-    "src/"
-  ],
-  "scripts": {
-    "build:wasm": "node -e \"require('fs').rmSync('wasm',{recursive:true,force:true})\" && cd .. && wasm-pack build --target web --out-dir okgeometry-api/wasm",
-    "sync:wasm-bindings": "node scripts/sync-wasm-bindings.mjs",
-    "inline-wasm": "tsx scripts/inline-wasm.ts",
-    "build": "npm run build:wasm && npm run sync:wasm-bindings && npm run inline-wasm && tsc",
-    "bench:boolean-heavy": "npm run build && tsx scripts/bench-boolean-heavy.ts",
-    "bench:boolean-ab": "npm run build && tsx scripts/bench-boolean-ab.ts",
-    "bench:boolean-batch": "npm run build && tsx scripts/bench-boolean-batch.ts",
-    "smoke:brep-boolean": "tsx scripts/smoke-brep-boolean.ts",
-    "prepublishOnly": "npm run build",
-    "smoke:brep-parametric": "tsx scripts/smoke-brep-parametric.ts",
-    "smoke:brep-from-mesh": "tsx scripts/smoke-brep-from-mesh.ts",
-    "smoke:brep-faces": "tsx scripts/smoke-brep-faces.ts",
-    "smoke:curve-intersections": "tsx scripts/smoke-curve-intersections.ts",
-    "smoke:brep-intersections": "tsx scripts/smoke-brep-intersections.ts"
-  },
-  "keywords": [
-    "geometry",
-    "wasm",
-    "nurbs",
-    "mesh",
-    "boolean",
-    "cad",
-    "aec",
-    "3d"
-  ],
-  "author": "Mostafa El Ayoubi",
-  "license": "Proprietary License",
-  "repository": {
-    "type": "git",
-    "url": "https://www.orkestra.online"
-  },
-  "devDependencies": {
-    "tsx": "^4.7.0",
-    "typescript": "^5.4.0"
-  }
-}
+{
+  "name": "okgeometry-api",
+  "version": "1.17.0",
+  "description": "Geometry engine API for AEC applications - NURBS, meshes, booleans, intersections. Powered by Rust/WASM.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "scripts": {
+    "build:wasm": "node -e \"require('fs').rmSync('wasm',{recursive:true,force:true})\" && cd .. && wasm-pack build --target web --out-dir okgeometry-api/wasm",
+    "sync:wasm-bindings": "node scripts/sync-wasm-bindings.mjs",
+    "inline-wasm": "tsx scripts/inline-wasm.ts",
+    "build": "npm run build:wasm && npm run sync:wasm-bindings && npm run inline-wasm && tsc",
+    "bench:boolean-heavy": "npm run build && tsx scripts/bench-boolean-heavy.ts",
+    "bench:boolean-ab": "npm run build && tsx scripts/bench-boolean-ab.ts",
+    "bench:boolean-batch": "npm run build && tsx scripts/bench-boolean-batch.ts",
+    "bench:boolean-matrix": "tsx scripts/bench-boolean-matrix.ts",
+    "smoke:brep-boolean": "tsx scripts/smoke-brep-boolean.ts",
+    "prepublishOnly": "npm run build",
+    "smoke:brep-parametric": "tsx scripts/smoke-brep-parametric.ts",
+    "smoke:brep-from-mesh": "tsx scripts/smoke-brep-from-mesh.ts",
+    "smoke:brep-faces": "tsx scripts/smoke-brep-faces.ts",
+    "smoke:curve-intersections": "tsx scripts/smoke-curve-intersections.ts",
+    "smoke:brep-intersections": "tsx scripts/smoke-brep-intersections.ts",
+    "smoke:brep-sheet-boolean": "tsx scripts/smoke-brep-sheet-boolean.ts",
+    "smoke:geometry-boolean": "tsx scripts/smoke-geometry-boolean.ts",
+    "smoke:curve-region": "tsx scripts/smoke-curve-region.ts"
+  },
+  "keywords": [
+    "geometry",
+    "wasm",
+    "nurbs",
+    "mesh",
+    "boolean",
+    "cad",
+    "aec",
+    "3d"
+  ],
+  "author": "Mostafa El Ayoubi",
+  "license": "Proprietary License",
+  "repository": {
+    "type": "git",
+    "url": "https://www.orkestra.online"
+  },
+  "devDependencies": {
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/Brep.ts

@@ -50,6 +50,21 @@ export interface BrepSplitSolidResult {
   positive: Brep | null;
 }
 
+/**
+ * Both sides of a sheet split ({@link Brep.splitSheetBySolid} /
+ * {@link Brep.splitSheetBySheet}), each an OPEN Brep preserving the sheet's
+ * exact trimmed faces, pcurves and edges.
+ *
+ * `inside` follows the oriented-sheet convention ("inside" = FRONT, the side
+ * a sheet's normal points toward): pieces CONTAINED in the solid cutter, or
+ * pieces in FRONT of the sheet cutter's normal. A side is null when no
+ * material lands on it.
+ */
+export interface BrepSheetSplitResult {
+  inside: Brep | null;
+  outside: Brep | null;
+}
+
 /** Validation report for a BREP body. */
 export interface BrepValidationReport {
   isClosed: boolean;
@@ -624,12 +639,27 @@ export class Brep {
    *
    * `options.tolerance` is the absolute geometric tolerance of the fitted
    * intersection curves (default 1e-6).
+   *
+   * `options.join` (default false) JOINS the chained pieces into maximal
+   * curves: greedy reversal-aware endpoint chaining, exact degree elevation
+   * to the chain maximum, exact knot-vector concatenation (junction
+   * multiplicity = degree, no re-parameterization), and a per-curve
+   * verification gate — every joined curve is sampled densely and must stay
+   * within 5·tolerance of BOTH operands' surfaces, otherwise that chain's
+   * pieces come back unjoined (never a corrupted joined curve). A closed
+   * intersection loop (e.g. a plane through a cylinder) comes back as ONE
+   * closed curve with `pointAt(0)` equal to `pointAt(1)`.
    */
-  intersectionCurves(other: Brep | NurbsSurface, options?: { tolerance?: number }): NurbsCurve[] {
+  intersectionCurves(
+    other: Brep | NurbsSurface,
+    options?: { tolerance?: number; join?: boolean },
+  ): 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);
+    const buf = options?.join
+      ? wasm.brep_intersection_curves_joined_op(this.json, rhs.json, tolerance)
+      : 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) {
@@ -755,14 +785,34 @@ export class Brep {
 
   // ── Parametric booleans (BREP → BREP) ──
 
+  /**
+   * Resolve a parametric-boolean operand: Breps pass through; Meshes are
+   * converted via {@link Brep.fromMesh} (planar-faceted meshes only) so the
+   * EXACT pipeline can run. Curved/dense meshes fail conversion with
+   * guidance to use the tessellated union()/subtract()/intersect() instead.
+   */
+  private static resolveParametricOperand(other: Brep | Mesh): Brep {
+    if (other instanceof Brep) return other;
+    try {
+      return Brep.fromMesh(other);
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e);
+      throw new Error(
+        `Parametric boolean operand mesh could not be converted to a BREP (${reason}); ` +
+          "use the tessellated union()/subtract()/intersect() for mesh operands instead",
+      );
+    }
+  }
+
   private runParametricBoolean(
-    other: Brep,
+    other: Brep | Mesh,
     op: "union" | "subtract" | "intersect",
     options?: BrepParametricBooleanOptions,
   ): Brep {
     ensureInit();
+    const rhs = Brep.resolveParametricOperand(other);
     const tolerance = options?.tolerance ?? 1e-6;
-    const json = wasm.brep_boolean_op(this.json, other.json, op, tolerance);
+    const json = wasm.brep_boolean_op(this.json, rhs.json, op, tolerance);
     if (!json) throw new Error(`Brep.${op}Brep failed`);
     if (json.startsWith('{"error"')) {
       const parsed = JSON.parse(json) as { error: string };
@@ -776,7 +826,30 @@ export class Brep {
    * 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.
+   * adjacent faces.
+   *
+   * Operands may be CLOSED solids or OPEN sheets — the kernel dispatches on
+   * closedness, following the oriented-sheet convention used across the API
+   * (a sheet's "inside" is the FRONT of its normal):
+   * - closed × closed — full volumetric boolean.
+   * - sheet × solid — `subtract` keeps the sheet's pieces OUTSIDE the solid,
+   *   `intersect` the pieces INSIDE (open trimmed sheets).
+   * - solid × sheet — `subtract` keeps the capped half of the solid BEHIND
+   *   the sheet normal, `intersect` the FRONT half (closed solids).
+   * - sheet × sheet — a sheet's material is its FRONT half-space, so
+   *   `union` = ∂(matA ∪ matB): this sheet's BACK-of-other pieces joined
+   *   with the other's BACK-of-this pieces into ONE open Brep stitched at
+   *   the shared exact intersection edges (pieces in FRONT of the other
+   *   sheet are interior to the union material and are dropped; faces the
+   *   other operand never cuts are kept whole, coincident overlaps keep
+   *   this sheet's copy); `subtract` keeps this sheet's BACK pieces;
+   *   `intersect` its FRONT pieces.
+   * - `union` of a solid and a sheet (either order) is NOT defined and
+   *   throws — trim the sheet with subtract/intersect instead.
+   *
+   * A Mesh operand is converted via {@link Brep.fromMesh} (planar-faceted
+   * meshes only); if conversion fails, use the tessellated
+   * union()/subtract()/intersect() instead.
    *
    * `options.tolerance` is the absolute geometric tolerance of intersection
    * edges and coincident-face classification (default 1e-6).
@@ -785,17 +858,27 @@ export class Brep {
    * 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 {
+  unionBrep(other: Brep | Mesh, options?: BrepParametricBooleanOptions): Brep {
     return this.runParametricBoolean(other, "union", options);
   }
 
-  /** PARAMETRIC boolean subtraction (this − other). See {@link unionBrep}. */
-  subtractBrep(other: Brep, options?: BrepParametricBooleanOptions): Brep {
+  /**
+   * PARAMETRIC boolean subtraction (this − other). See {@link unionBrep} for
+   * the full open/closed dispatch table: sheet − solid trims the sheet to
+   * the OUTSIDE of the solid; solid − sheet keeps the capped half BEHIND the
+   * sheet normal; sheet − sheet keeps this sheet's BACK pieces.
+   */
+  subtractBrep(other: Brep | Mesh, options?: BrepParametricBooleanOptions): Brep {
     return this.runParametricBoolean(other, "subtract", options);
   }
 
-  /** PARAMETRIC boolean intersection. See {@link unionBrep}. */
-  intersectBrep(other: Brep, options?: BrepParametricBooleanOptions): Brep {
+  /**
+   * PARAMETRIC boolean intersection. See {@link unionBrep} for the full
+   * open/closed dispatch table: sheet ∩ solid trims the sheet to the INSIDE
+   * of the solid; solid ∩ sheet keeps the capped half in FRONT of the sheet
+   * normal; sheet ∩ sheet keeps this sheet's FRONT pieces.
+   */
+  intersectBrep(other: Brep | Mesh, options?: BrepParametricBooleanOptions): Brep {
     return this.runParametricBoolean(other, "intersect", options);
   }
 
@@ -888,6 +971,60 @@ export class Brep {
     return { negative: side(parsed.negative), positive: side(parsed.positive) };
   }
 
+  /**
+   * PARAMETRIC split of this OPEN sheet by a CLOSED solid: the sheet's faces
+   * are imprinted with the exact intersection curves and every face piece is
+   * classified by containment in the solid. `inside` = the pieces contained
+   * in the solid (ON-boundary pieces count as inside), `outside` = the rest.
+   * Both sides are open Breps preserving the sheet's exact trimmed faces,
+   * pcurves and edges.
+   *
+   * The counterpart of {@link splitBySheet} with the roles swapped: use that
+   * one to split a closed solid BY a sheet (capped halves); use this one to
+   * split a sheet BY a solid (trimmed sheet pieces).
+   */
+  splitSheetBySolid(
+    solid: Brep,
+    options?: BrepParametricBooleanOptions,
+  ): BrepSheetSplitResult {
+    ensureInit();
+    const tolerance = options?.tolerance ?? 1e-6;
+    const json = wasm.brep_split_sheet_by_solid_op(this.json, solid.json, tolerance);
+    return Brep.parseSheetSplitResult(json, "Brep.splitSheetBySolid");
+  }
+
+  /**
+   * PARAMETRIC split of this OPEN sheet by another OPEN sheet (a sheet Brep
+   * or a NurbsSurface, converted via {@link Brep.fromSurface}): the mutual
+   * exact intersection curves are imprinted onto this sheet's faces and each
+   * piece is assigned to the FRONT (`inside`) or BACK (`outside`) of the
+   * other sheet's oriented normal — the same seam-vote classification as
+   * {@link splitBySheet}. Faces the cutter never crosses classify wholesale
+   * by their side of the cutter; coincident-overlap pieces land in `inside`.
+   */
+  splitSheetBySheet(
+    other: Brep | NurbsSurface,
+    options?: BrepParametricBooleanOptions,
+  ): BrepSheetSplitResult {
+    ensureInit();
+    const cutter = other instanceof Brep ? other : Brep.fromSurface(other);
+    const tolerance = options?.tolerance ?? 1e-6;
+    const json = wasm.brep_split_sheet_by_sheet_op(this.json, cutter.json, tolerance);
+    return Brep.parseSheetSplitResult(json, "Brep.splitSheetBySheet");
+  }
+
+  private static parseSheetSplitResult(json: string, label: string): BrepSheetSplitResult {
+    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 { inside: unknown; outside: unknown };
+    const side = (v: unknown): Brep | null =>
+      v == null ? null : new Brep(JSON.stringify(v));
+    return { inside: side(parsed.inside), outside: side(parsed.outside) };
+  }
+
   /** JSON representation (persistence). */
   toJson(): string {
     return this.json;