okgeometry-api 1.14.0 → 1.16.0

package/src/Brep.ts

@@ -604,6 +604,170 @@ 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).
+   *
+   * `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; join?: boolean },
+  ): NurbsCurve[] {
+    ensureInit();
+    const rhs = other instanceof Brep ? other : Brep.fromSurface(other);
+    const tolerance = options?.tolerance ?? 1e-6;
+    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) {
+      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(

package/src/Mesh.ts

@@ -2995,6 +2995,179 @@ export class Mesh {
     return { inside, outside };
   }
 
+  /**
+   * Compute all transversal crossing points of a polyline with this mesh.
+   * Works on OPEN meshes (sheets) — unlike `clipPolyline`, the mesh is NOT
+   * required to be a closed volume.
+   *
+   * Hits are deduplicated (shared-edge / shared-vertex crossings merge into
+   * one, keeping the smallest triangle index) and sorted by
+   * (segmentIndex, segmentT). Coplanar sliding overlaps yield no hits.
+   * Segment `i` runs from point `i` to point `(i + 1) % n`; open polylines
+   * have n − 1 segments, closed ones n (the wrap segment).
+   *
+   * @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)
+   * @returns Crossings with the 3D point, segment index/parameter, and
+   *   triangle index
+   */
+  intersectPolyline(
+    polyline: Polyline | Point[],
+    closed?: boolean,
+  ): { point: Point; segmentIndex: number; segmentT: number; triangleIndex: number }[] {
+    ensureInit();
+    const { flat, isClosed } = Mesh.flattenPolylineArg(polyline, closed, "Mesh.intersectPolyline");
+    const buf = wasm.mesh_polyline_intersection_points(
+      this._vertexCount,
+      this._buffer,
+      flat,
+      isClosed,
+    );
+    if (buf.length === 0) {
+      throw new Error(
+        "Mesh.intersectPolyline failed — the mesh and polyline must be non-degenerate.",
+      );
+    }
+    const count = buf[0];
+    const hits: { point: Point; segmentIndex: number; segmentT: number; triangleIndex: number }[] = [];
+    for (let i = 0; i < count; i++) {
+      const off = 1 + i * 6;
+      hits.push({
+        point: new Point(buf[off], buf[off + 1], buf[off + 2]),
+        segmentIndex: buf[off + 3],
+        segmentT: buf[off + 4],
+        triangleIndex: buf[off + 5],
+      });
+    }
+    return hits;
+  }
+
+  /**
+   * Split a polyline into pieces at every crossing with this mesh (open
+   * sheets allowed). Hit points become the shared endpoints of adjacent
+   * pieces; a closed loop is opened at the first crossing (N crossings → N
+   * pieces), an open polyline yields N + 1 pieces. With no crossings the
+   * original polyline comes back as one piece. Pieces are NOT classified —
+   * use `clipPolyline` (closed volume, containment) or
+   * `clipPolylineBySheet` (oriented sheet, signed side) for classification.
+   *
+   * @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)
+   * @returns Polyline pieces in order along the input
+   */
+  splitPolyline(polyline: Polyline | Point[], closed?: boolean): Polyline[] {
+    ensureInit();
+    const { flat, isClosed } = Mesh.flattenPolylineArg(polyline, closed, "Mesh.splitPolyline");
+    const buf = wasm.mesh_split_polyline(this._vertexCount, this._buffer, flat, isClosed);
+    if (buf.length === 0) {
+      throw new Error(
+        "Mesh.splitPolyline failed — the mesh and polyline must be non-degenerate.",
+      );
+    }
+    return parsePolylineBuf(buf).map(pts => new Polyline(pts));
+  }
+
+  /**
+   * Clip a polyline by this mesh treated as an OPEN oriented sheet: the
+   * polyline is split at every crossing and each piece is classified by the
+   * SIGNED SIDE of the sheet — `inside` = in FRONT of the sheet normal,
+   * `outside` = behind it (the mesh's stored winding defines the normals).
+   *
+   * This is side classification, NOT containment — unlike `clipPolyline`,
+   * which requires a CLOSED volume: the sheet may be open, and pieces far
+   * from it still classify deterministically by the nearest facet's normal.
+   * Pieces lying ON the sheet default to `inside`. Adjacent same-side pieces
+   * (e.g. from a touch, not a crossing) merge back into one run; closed
+   * loops merge the run spanning the seam.
+   *
+   * @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)
+   */
+  clipPolylineBySheet(
+    polyline: Polyline | Point[],
+    closed?: boolean,
+  ): { inside: Polyline[]; outside: Polyline[] } {
+    ensureInit();
+    const { flat, isClosed } = Mesh.flattenPolylineArg(
+      polyline,
+      closed,
+      "Mesh.clipPolylineBySheet",
+    );
+    const buf = wasm.mesh_clip_polyline_by_sheet(this._vertexCount, this._buffer, flat, isClosed);
+    if (buf.length === 0) {
+      throw new Error(
+        "Mesh.clipPolylineBySheet failed — the sheet and polyline must be non-degenerate.",
+      );
+    }
+    // Two concatenated polyline groups: inside first, then outside — same
+    // packing as clipPolyline.
+    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 };
+  }
+
+  /**
+   * Flatten a Polyline-or-points argument into WASM coords + closed flag.
+   *
+   * Closed inputs following the duplicated-seam convention (terminal point
+   * repeating the first) have the duplicate STRIPPED before crossing the
+   * boundary — the kernel's closed-polyline encoding is seam-free (the wrap
+   * segment is implicit), and a duplicated seam would add a zero-length wrap
+   * segment / doubled seam vertex to split pieces.
+   */
+  private static flattenPolylineArg(
+    polyline: Polyline | Point[],
+    closed: boolean | undefined,
+    context: string,
+  ): { flat: Float64Array; isClosed: boolean } {
+    let pts = Array.isArray(polyline) ? polyline : polyline.points;
+    if (pts.length < 2) {
+      throw new Error(`${context} needs at least 2 polyline points`);
+    }
+    const isClosed = closed ?? (!Array.isArray(polyline) && polyline.isClosed());
+    if (isClosed && pts.length > 2) {
+      // Scale-relative epsilon for the duplicate-seam test.
+      let maxAbs = 0;
+      for (const p of pts) {
+        maxAbs = Math.max(maxAbs, Math.abs(p.x), Math.abs(p.y), Math.abs(p.z));
+      }
+      const eps = (1 + maxAbs) * 1e-12;
+      const first = pts[0];
+      const last = pts[pts.length - 1];
+      const dx = first.x - last.x;
+      const dy = first.y - last.y;
+      const dz = first.z - last.z;
+      if (Math.sqrt(dx * dx + dy * dy + dz * dz) <= eps) {
+        pts = pts.slice(0, -1);
+      }
+    }
+    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;
+    }
+    return { flat, isClosed };
+  }
+
   /**
    * Apply a 4x4 transformation matrix.
    * @param matrix - Row-major flat array of 16 numbers

package/src/NurbsCurve.ts

@@ -7,6 +7,8 @@ import { Polyline } from "./Polyline.js";
 import { PolyCurve } from "./PolyCurve.js";
 import type { Line } from "./Line.js";
 import type { Arc } from "./Arc.js";
+import type { NurbsSurface } from "./NurbsSurface.js";
+import type { Brep } from "./Brep.js";
 import type { CurveOffsetOptions, RotationAxis } from "./types.js";
 import * as wasm from "./wasm-bindings.js";
 
@@ -110,6 +112,133 @@ export class NurbsCurve {
     return pts;
   }
 
+  /**
+   * Find all intersections with another NURBS curve, with exact parameters.
+   *
+   * Parameters are normalized to [0, 1] (the same parameterization as
+   * `pointAt`), so `this.pointAt(paramA)` and `other.pointAt(paramB)` both
+   * reproduce `point` up to the convergence tolerance. Results are sorted by
+   * `paramA`. Coincident (overlapping) curve runs yield NO points — identical
+   * curves return an empty array.
+   *
+   * @param other - Other curve to intersect with
+   * @returns Intersections with the 3D point and the parameter on each curve
+   */
+  intersectCurveParams(other: NurbsCurve): { point: Point; paramA: number; paramB: number }[] {
+    ensureInit();
+    const buf = wasm.nurbs_curve_curve_intersect_params(this._data, other._data);
+    if (buf.length === 0) return [];
+    const count = buf[0];
+    const hits: { point: Point; paramA: number; paramB: number }[] = [];
+    for (let i = 0; i < count; i++) {
+      const off = 1 + i * 5;
+      hits.push({
+        point: new Point(buf[off], buf[off + 1], buf[off + 2]),
+        paramA: buf[off + 3],
+        paramB: buf[off + 4],
+      });
+    }
+    return hits;
+  }
+
+  /**
+   * Find all isolated intersections with a NURBS surface, with exact
+   * parameters.
+   *
+   * All parameters are normalized to [0, 1]: `this.pointAt(curveParam)` and
+   * `surface.evaluate(u, v)` both reproduce `point` up to the convergence
+   * tolerance. Results are sorted by `curveParam`. Curve segments lying ON
+   * the surface (coincident runs) yield no points — a line inside a planar
+   * surface returns an empty array.
+   *
+   * @param surface - Surface to intersect with
+   * @returns Intersections with the 3D point, curve parameter, and surface (u, v)
+   */
+  intersectSurfaceExact(
+    surface: NurbsSurface,
+  ): { point: Point; curveParam: number; u: number; v: number }[] {
+    ensureInit();
+    const buf = wasm.nurbs_curve_surface_intersect_exact(this._data, surface.data);
+    if (buf.length === 0) return [];
+    const count = buf[0];
+    const hits: { point: Point; curveParam: number; u: number; v: number }[] = [];
+    for (let i = 0; i < count; i++) {
+      const off = 1 + i * 6;
+      hits.push({
+        point: new Point(buf[off], buf[off + 1], buf[off + 2]),
+        curveParam: buf[off + 3],
+        u: buf[off + 4],
+        v: buf[off + 5],
+      });
+    }
+    return hits;
+  }
+
+  /**
+   * Find intersection points with a NURBS surface.
+   * Point-only convenience wrapper around `intersectSurfaceExact`.
+   * @param surface - Surface to intersect with
+   * @returns Array of intersection points, sorted along the curve
+   */
+  intersectSurface(surface: NurbsSurface): Point[] {
+    return this.intersectSurfaceExact(surface).map(hit => hit.point);
+  }
+
+  /**
+   * Boolean-intersection clip of this curve against a CLOSED solid Brep —
+   * delegate for {@link Brep.clipCurve}: 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 this curve. Throws
+   * when the Brep is not a closed solid.
+   *
+   * @param brep - Closed solid BREP to clip against
+   * @returns Exact sub-curves inside and outside the solid
+   */
+  clipByBrep(brep: Brep): { inside: NurbsCurve[]; outside: NurbsCurve[] } {
+    return brep.clipCurve(this);
+  }
+
+  /**
+   * Split this curve at multiple normalized parameters t in [0, 1].
+   *
+   * Splitting is exact (knot insertion), so every returned piece lies exactly
+   * on this curve. Parameters are sorted, deduplicated, and clamped
+   * internally. Closed curves are opened at the FIRST parameter (N interior
+   * parameters yield N pieces, the seam-spanning piece rejoined); open curves
+   * yield N + 1 pieces. With no valid parameters the (clamped) curve comes
+   * back as the single piece.
+   *
+   * @param params - Normalized split parameters in [0, 1]
+   * @param closed - Explicit topology override. `true` forces closed
+   *   (seam-rejoin) semantics; `false` forces open semantics — an open curve
+   *   whose endpoints merely coincide (a C-shape drawn back onto its start)
+   *   keeps its N + 1 pieces. Omit to infer closedness geometrically from the
+   *   endpoint distance (the historical behavior).
+   * @returns Curve pieces in parameter order
+   */
+  splitAtParams(params: number[], closed?: boolean): NurbsCurve[] {
+    ensureInit();
+    const closedHint = closed === undefined ? -1 : closed ? 1 : 0;
+    const buf = wasm.nurbs_curve_split_at_params(
+      this._data,
+      new Float64Array(params),
+      closedHint
+    );
+    if (buf.length === 0) {
+      throw new Error("NurbsCurve.splitAtParams failed — malformed curve data");
+    }
+    // Packing: [curveCount, (bufLen, curveData…)·curveCount]
+    const count = buf[0];
+    const pieces: NurbsCurve[] = [];
+    let idx = 1;
+    for (let i = 0; i < count; i++) {
+      const len = buf[idx++];
+      pieces.push(NurbsCurve.fromData(buf.subarray(idx, idx + len)));
+      idx += len;
+    }
+    return pieces;
+  }
+
   /**
    * Translate this curve by an offset vector.
    * @param offset - Translation vector

package/src/NurbsSurface.ts

@@ -147,6 +147,47 @@ export class NurbsSurface implements Surface {
     return parsePolylineBuf(buf).map(pts => new Polyline(pts));
   }
 
+  /**
+   * EXACT intersection curves with another NURBS surface.
+   *
+   * Unlike {@link intersectSurface} (tessellation-based, returns polylines at
+   * a fixed sampling resolution), this runs the parametric boolean's
+   * surface–surface intersection pipeline — seeded tri-tri detection,
+   * chaining, and Newton/tangent-plane relaxation of every point onto the
+   * true intersection — and fits each chain to an interpolating NURBS curve,
+   * densified until the fitted curve stays within `tolerance` of the exact
+   * intersection.
+   *
+   * Closed intersection loops (e.g. cylinder × plane) come back as ONE closed
+   * curve. Coincident (overlapping) surfaces return an empty array — their
+   * overlap is a 2D region, not a curve set.
+   *
+   * @param other - Other surface to intersect with
+   * @param tolerance - Absolute geometric tolerance of the fitted curves
+   *   (model units; floored relative to the combined model scale)
+   * @returns Exact fitted NURBS intersection curves
+   */
+  intersectSurfaceCurves(other: NurbsSurface, tolerance = 1e-6): NurbsCurve[] {
+    ensureInit();
+    const buf = wasm.nurbs_surface_surface_intersect_curves(this._data, other._data, tolerance);
+    return NurbsSurface.parseCurveList(buf);
+  }
+
+  /** Parse [count, (bufLen, curveData…)·count] into NurbsCurves. */
+  private static parseCurveList(buf: Float64Array): NurbsCurve[] {
+    if (buf.length < 1) return [];
+    const out: NurbsCurve[] = [];
+    const count = Number(buf[0]);
+    let offset = 1;
+    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;
+  }
+
   /**
    * Convert any supported curve type to a NurbsCurve.
    * @param c - Curve to convert