okgeometry-api 1.14.0 → 1.16.0

package/src/Polyline.ts

@@ -1,13 +1,13 @@
 import { ensureInit } from "./engine.js";
 import { Point } from "./Point.js";
 import { Vec3 } from "./Vec3.js";
-import { Mesh } from "./Mesh.js";
-import { Line } from "./Line.js";
-import { PolyCurve } from "./PolyCurve.js";
-import type { Plane } from "./Plane.js";
-import type { CurveOffsetOptions, RotationAxis } from "./types.js";
-import { pointsToCoords } from "./BufferCodec.js";
-import * as wasm from "./wasm-bindings.js";
+import { Mesh } from "./Mesh.js";
+import { Line } from "./Line.js";
+import { PolyCurve } from "./PolyCurve.js";
+import type { Plane } from "./Plane.js";
+import type { CurveOffsetOptions, RotationAxis } from "./types.js";
+import { pointsToCoords } from "./BufferCodec.js";
+import * as wasm from "./wasm-bindings.js";
 
 /**
  * Open or closed polyline defined by a sequence of points.
@@ -50,6 +50,56 @@ export class Polyline {
     return this.points[0].equals(this.points[this.points.length - 1], eps);
   }
 
+  /**
+   * Compute all transversal crossing points of this polyline with a triangle
+   * mesh. Works on OPEN meshes (sheets) — the mesh is not required to be a
+   * closed volume. Hits are deduplicated and sorted along the polyline;
+   * coplanar sliding overlaps yield no hits.
+   *
+   * @param mesh - Mesh to intersect with (open or closed)
+   * @returns Crossings with the 3D point, segment index/parameter in [0, 1],
+   *   and triangle index
+   */
+  intersectMesh(
+    mesh: Mesh,
+  ): { point: Point; segmentIndex: number; segmentT: number; triangleIndex: number }[] {
+    return mesh.intersectPolyline(this);
+  }
+
+  /**
+   * Split this polyline into pieces at every crossing with a mesh (open
+   * sheets allowed). Crossing 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 —
+   * see `clipBySheet` / `Mesh.clipPolyline` for classification.
+   *
+   * @param mesh - Mesh to split against (open or closed)
+   * @returns Polyline pieces in order along this polyline
+   */
+  splitByMesh(mesh: Mesh): Polyline[] {
+    return mesh.splitPolyline(this);
+  }
+
+  /**
+   * Clip this polyline by an OPEN oriented sheet: split it at every sheet
+   * crossing and classify each piece by the SIGNED SIDE of the sheet —
+   * `inside` = in FRONT of the sheet normal, `outside` = behind it (the
+   * sheet's stored winding defines the normals).
+   *
+   * This is side classification, NOT containment — unlike
+   * `Mesh.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. Adjacent same-side pieces (a touch, not a
+   * crossing) merge back into one run; closed loops merge the run spanning
+   * the seam.
+   *
+   * @param sheet - Oriented sheet mesh (open or closed)
+   */
+  clipBySheet(sheet: Mesh): { inside: Polyline[]; outside: Polyline[] } {
+    return sheet.clipPolylineBySheet(this);
+  }
+
   /**
    * Extrude this polyline along a direction vector.
    * @param direction - Extrusion direction and magnitude
@@ -57,28 +107,28 @@ export class Polyline {
    * @param caps - Whether to cap the ends (default false)
    * @returns Mesh representing the extruded surface
    */
-  extrude(direction: Vec3, segments = 1, caps = false): Mesh {
-    ensureInit();
-    const buf = wasm.extrude_polyline(
-      this.toCoords(),
-      direction.x, direction.y, direction.z,
+  extrude(direction: Vec3, segments = 1, caps = false): Mesh {
+    ensureInit();
+    const buf = wasm.extrude_polyline(
+      this.toCoords(),
+      direction.x, direction.y, direction.z,
       segments, caps
-    );
-    return Mesh.fromBuffer(buf);
-  }
-
-  /**
-   * Extrude this closed polyline into a trusted solid suitable for booleans.
-   * @param direction - Extrusion direction and magnitude
-   * @returns Closed mesh solid ready for boolean operations
-   */
-  extrudeAsSolid(direction: Vec3): Mesh {
-    return Mesh.extrudeCurveAsSolid(this, direction);
-  }
-
-  /**
-   * Translate this polyline by an offset vector.
-   * @param offset - Translation vector
+    );
+    return Mesh.fromBuffer(buf);
+  }
+
+  /**
+   * Extrude this closed polyline into a trusted solid suitable for booleans.
+   * @param direction - Extrusion direction and magnitude
+   * @returns Closed mesh solid ready for boolean operations
+   */
+  extrudeAsSolid(direction: Vec3): Mesh {
+    return Mesh.extrudeCurveAsSolid(this, direction);
+  }
+
+  /**
+   * Translate this polyline by an offset vector.
+   * @param offset - Translation vector
    * @returns New translated polyline
    */
   translate(offset: Vec3): Polyline {
@@ -95,73 +145,73 @@ export class Polyline {
     return new Polyline(this.points.map(p => p.rotate(axis, angle)));
   }
 
-  /**
-   * Offset this polyline perpendicular to its segments.
-   * @param distance - Offset distance
-   * @param normal - Reference normal for determining offset direction
-   * @param arcSamples - Number of samples per arc join in the returned polyline(s)
-   * @param options - Offset options such as join style
-   * @returns New offset polyline
-   */
-  offset(
-    distance: number,
-    normal?: Vec3,
-    arcSamples = 32,
-    options: CurveOffsetOptions = {},
-  ): Polyline {
-    const results = this.offsetAll(distance, normal, arcSamples, options);
-    if (results.length === 1) return results[0];
-    if (results.length === 0) {
-      throw new Error("Polyline.offset() collapsed and produced no valid result polylines");
-    }
-    throw new Error(
-      `Polyline.offset() produced ${results.length} result polylines. Use Polyline.offsetAll() instead.`,
-    );
-  }
-
-  /**
-   * Offset this polyline and return every sampled result polyline.
-   * @param distance - Offset distance
-   * @param normal - Reference normal for determining offset direction
-   * @param arcSamples - Number of samples per exact arc segment in the returned polylines
-   * @param options - Offset options such as join style
-   * @returns Every valid offset polyline
-   */
-  offsetAll(
-    distance: number,
-    normal?: Vec3,
-    arcSamples = 32,
-    options: CurveOffsetOptions = {},
-  ): Polyline[] {
-    const exact = this.toPolyCurve().offsetAll(distance, normal, options);
-    const samples = Number.isFinite(arcSamples) ? Math.max(3, Math.floor(arcSamples)) : 32;
-    return exact.map(curve => new Polyline(curve.sample(samples)));
-  }
-
-  /**
-   * Thicken this open polyline into a closed PolyCurve suitable for extrusion.
-   * When `bothSides` is false, the source polyline forms one side of the result.
-   * When true, the thickness is added on each side of the source polyline.
-   */
-  thicken(
-    distance: number,
-    bothSides = false,
-    normal?: Vec3,
-    options: CurveOffsetOptions = {},
-  ): PolyCurve {
-    if (this.points.length < 2) {
-      throw new Error("Polyline.thicken() requires at least 2 points");
-    }
-    if (this.isClosed()) {
-      throw new Error("Polyline.thicken() requires an open polyline");
-    }
-    return this.toPolyCurve().thicken(distance, bothSides, normal, options);
-  }
-
-  /**
-   * Project this polyline onto a plane.
-   * @param plane - Target plane
-   * @param direction - Optional projection direction (default: perpendicular to plane)
+  /**
+   * Offset this polyline perpendicular to its segments.
+   * @param distance - Offset distance
+   * @param normal - Reference normal for determining offset direction
+   * @param arcSamples - Number of samples per arc join in the returned polyline(s)
+   * @param options - Offset options such as join style
+   * @returns New offset polyline
+   */
+  offset(
+    distance: number,
+    normal?: Vec3,
+    arcSamples = 32,
+    options: CurveOffsetOptions = {},
+  ): Polyline {
+    const results = this.offsetAll(distance, normal, arcSamples, options);
+    if (results.length === 1) return results[0];
+    if (results.length === 0) {
+      throw new Error("Polyline.offset() collapsed and produced no valid result polylines");
+    }
+    throw new Error(
+      `Polyline.offset() produced ${results.length} result polylines. Use Polyline.offsetAll() instead.`,
+    );
+  }
+
+  /**
+   * Offset this polyline and return every sampled result polyline.
+   * @param distance - Offset distance
+   * @param normal - Reference normal for determining offset direction
+   * @param arcSamples - Number of samples per exact arc segment in the returned polylines
+   * @param options - Offset options such as join style
+   * @returns Every valid offset polyline
+   */
+  offsetAll(
+    distance: number,
+    normal?: Vec3,
+    arcSamples = 32,
+    options: CurveOffsetOptions = {},
+  ): Polyline[] {
+    const exact = this.toPolyCurve().offsetAll(distance, normal, options);
+    const samples = Number.isFinite(arcSamples) ? Math.max(3, Math.floor(arcSamples)) : 32;
+    return exact.map(curve => new Polyline(curve.sample(samples)));
+  }
+
+  /**
+   * Thicken this open polyline into a closed PolyCurve suitable for extrusion.
+   * When `bothSides` is false, the source polyline forms one side of the result.
+   * When true, the thickness is added on each side of the source polyline.
+   */
+  thicken(
+    distance: number,
+    bothSides = false,
+    normal?: Vec3,
+    options: CurveOffsetOptions = {},
+  ): PolyCurve {
+    if (this.points.length < 2) {
+      throw new Error("Polyline.thicken() requires at least 2 points");
+    }
+    if (this.isClosed()) {
+      throw new Error("Polyline.thicken() requires an open polyline");
+    }
+    return this.toPolyCurve().thicken(distance, bothSides, normal, options);
+  }
+
+  /**
+   * Project this polyline onto a plane.
+   * @param plane - Target plane
+   * @param direction - Optional projection direction (default: perpendicular to plane)
    * @returns New projected polyline
    */
   projectOntoPlane(plane: Plane, direction?: Vec3): Polyline {