okgeometry-api 1.16.0 → 1.17.1

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;
@@ -770,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 };
@@ -791,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).
@@ -800,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);
   }
 
@@ -903,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;

package/src/Circle.ts

@@ -63,9 +63,12 @@ export class Circle {
   }
 
   /**
-   * Sample the circle into evenly-spaced points.
+   * Sample the circle into evenly-spaced points across the full closed
+   * parameter range INCLUSIVE of both ends: the last point coincides with
+   * the first (the seam). Consumers building a closed polygon from a circle
+   * must drop the final duplicate (see Mesh.buildPlanarCircle).
    * @param n - Number of points to generate
-   * @returns Array of n points around the circle
+   * @returns Array of n points around the circle, first == last
    */
   sample(n: number): Point[] {
     ensureInit();
@@ -139,25 +142,25 @@ export class Circle {
    * @param caps - Whether to cap the ends (default true)
    * @returns Mesh representing the extruded cylinder
    */
-  extrude(direction: Vec3, segments = 16, caps = true): Mesh {
-    ensureInit();
-    const buf = wasm.extrude_circle(
-      this.center.x, this.center.y, this.center.z,
-      this.normal.x, this.normal.y, this.normal.z,
+  extrude(direction: Vec3, segments = 16, caps = true): Mesh {
+    ensureInit();
+    const buf = wasm.extrude_circle(
+      this.center.x, this.center.y, this.center.z,
+      this.normal.x, this.normal.y, this.normal.z,
       this.radius,
       direction.x, direction.y, direction.z,
       segments, caps
-    );
-    return Mesh.fromBuffer(buf);
-  }
-
-  /**
-   * Extrude this closed circle into a trusted solid suitable for booleans.
-   * @param direction - Extrusion direction and magnitude
-   * @param segments - Number of boundary samples used for tessellation (default 32)
-   * @returns Closed mesh solid ready for boolean operations
-   */
-  extrudeAsSolid(direction: Vec3, segments = 32): Mesh {
-    return Mesh.extrudeCurveAsSolid(this, direction, segments);
-  }
-}
+    );
+    return Mesh.fromBuffer(buf);
+  }
+
+  /**
+   * Extrude this closed circle into a trusted solid suitable for booleans.
+   * @param direction - Extrusion direction and magnitude
+   * @param segments - Number of boundary samples used for tessellation (default 32)
+   * @returns Closed mesh solid ready for boolean operations
+   */
+  extrudeAsSolid(direction: Vec3, segments = 32): Mesh {
+    return Mesh.extrudeCurveAsSolid(this, direction, segments);
+  }
+}