okgeometry-api 1.26.1 → 1.27.0

package/src/Polyline.ts

@@ -1,316 +1,316 @@
-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";
-
-/**
- * Open or closed polyline defined by a sequence of points.
- * Supports length, evaluation, transformation, and extrusion operations.
- */
-export class Polyline {
-  public readonly points: Point[];
-
-  constructor(points: Point[]) {
-    this.points = points;
-  }
-
-  /**
-   * Get the total length of this polyline.
-   * @returns Sum of segment lengths
-   */
-  length(): number {
-    ensureInit();
-    return wasm.polyline_length(this.toCoords());
-  }
-
-  /**
-   * Evaluate a point on the polyline at normalized parameter t.
-   * @param t - Parameter in [0, 1] (0 = first point, 1 = last point)
-   * @returns Point on polyline at parameter t
-   */
-  pointAt(t: number): Point {
-    ensureInit();
-    const r = wasm.polyline_point_at(this.toCoords(), t);
-    return new Point(r[0], r[1], r[2]);
-  }
-
-  /**
-   * Check if this polyline is closed.
-   * @param eps - Tolerance for comparing first and last points
-   * @returns True if first and last points coincide
-   */
-  isClosed(eps = 1e-10): boolean {
-    if (this.points.length < 2) return false;
-    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
-   * @param segments - Number of segments along extrusion (default 1)
-   * @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,
-      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
-   * @returns New translated polyline
-   */
-  translate(offset: Vec3): Polyline {
-    return new Polyline(this.points.map(p => p.add(offset)));
-  }
-
-  /**
-   * Apply a row-major 4x4 matrix to every vertex.
-   * @param matrix - Row-major 4x4 matrix (16 entries)
-   * @returns New transformed polyline
-   */
-  applyMatrix(matrix: number[] | Float64Array): Polyline {
-    return new Polyline(this.points.map(p => p.applyMatrix(matrix)));
-  }
-
-  /**
-   * Rotate this polyline around an axis.
-   * @param axis - Rotation axis (Vec3 through origin, or Line for arbitrary axis)
-   * @param angle - Rotation angle in radians
-   * @returns New rotated polyline
-   */
-  rotate(axis: RotationAxis, angle: number): 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)
-   * @returns New projected polyline
-   */
-  projectOntoPlane(plane: Plane, direction?: Vec3): Polyline {
-    const proj = (p: Point) => direction ? plane.projectPointAlongDirection(p, direction) : plane.projectPoint(p);
-    return new Polyline(this.points.map(proj));
-  }
-
-  /**
-   * Fillet corners of this polyline with arcs of the given radius.
-   * @param radius - Fillet radius
-   * @param normal - Reference normal for arc orientation (auto-detected if not provided)
-   * @returns PolyCurve with Line and Arc segments
-   */
-  fillet(radius: number, normal?: Vec3): PolyCurve {
-    ensureInit();
-    if (this.points.length < 3) {
-      throw new Error("Polyline.fillet() requires at least 3 points");
-    }
-
-    const nx = normal?.x ?? 0, ny = normal?.y ?? 0, nz = normal?.z ?? 0;
-    const buf = wasm.fillet_polycurve(this.toCoords(), radius, nx, ny, nz);
-    if (buf.length < 1) {
-      throw new Error("Polyline.fillet() failed - WASM returned empty result");
-    }
-
-    return PolyCurve.fromSegmentData(buf);
-  }
-
-  /**
-   * Chamfer corners of this polyline with straight cuts of the given
-   * setback distance (clamped per corner to half the shorter adjacent
-   * segment). Closed polylines (duplicated end point) chamfer every corner
-   * including the seam and stay closed; open polylines never touch their
-   * endpoints. `options.corners` selects vertex indices to chamfer
-   * (indices into the unique point list, seam duplicate excluded).
-   */
-  chamfer(distance: number, options: { corners?: number[] } = {}): Polyline {
-    ensureInit();
-    const pts = this.points;
-    if (pts.length < 3) {
-      throw new Error("Polyline.chamfer() requires at least 3 points");
-    }
-    const first = pts[0];
-    const last = pts[pts.length - 1];
-    const closed =
-      pts.length >= 4 &&
-      Math.abs(first.x - last.x) < 1e-10 &&
-      Math.abs(first.y - last.y) < 1e-10 &&
-      Math.abs(first.z - last.z) < 1e-10;
-    const unique = closed ? pts.slice(0, -1) : pts;
-    const coords = new Float64Array(unique.length * 3);
-    unique.forEach((p, i) => {
-      coords[i * 3] = p.x;
-      coords[i * 3 + 1] = p.y;
-      coords[i * 3 + 2] = p.z;
-    });
-    const cornerBuf = new Float64Array(options.corners ?? []);
-    const buf = wasm.chamfer_polyline_corners(coords, closed, distance, cornerBuf);
-    if (buf.length < 6) {
-      throw new Error(
-        `Polyline.chamfer() failed: ${wasm.geometry_last_error() || "unknown error"}`,
-      );
-    }
-    const out: Point[] = [];
-    for (let i = 0; i + 2 < buf.length; i += 3) {
-      out.push(new Point(buf[i], buf[i + 1], buf[i + 2]));
-    }
-    if (closed && out.length > 0) {
-      out.push(out[0]);
-    }
-    return new Polyline(out);
-  }
-
-  /**
-   * Convert this polyline to a PolyCurve (line segments only).
-   * @returns PolyCurve with Line segments connecting consecutive points
-   */
-  toPolyCurve(): PolyCurve {
-    const segs: Line[] = [];
-    for (let i = 0; i < this.points.length - 1; i++) {
-      segs.push(new Line(this.points[i], this.points[i + 1]));
-    }
-    return new PolyCurve(segs);
-  }
-
-  /**
-   * Convert points to flat coordinate array for WASM.
-   * @returns Float64Array [x1,y1,z1, x2,y2,z2, ...]
-   */
-  private toCoords(): Float64Array {
-    return pointsToCoords(this.points);
-  }
-}
+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 { wasm } from "./wasm-active.js";
+
+/**
+ * Open or closed polyline defined by a sequence of points.
+ * Supports length, evaluation, transformation, and extrusion operations.
+ */
+export class Polyline {
+  public readonly points: Point[];
+
+  constructor(points: Point[]) {
+    this.points = points;
+  }
+
+  /**
+   * Get the total length of this polyline.
+   * @returns Sum of segment lengths
+   */
+  length(): number {
+    ensureInit();
+    return wasm.polyline_length(this.toCoords());
+  }
+
+  /**
+   * Evaluate a point on the polyline at normalized parameter t.
+   * @param t - Parameter in [0, 1] (0 = first point, 1 = last point)
+   * @returns Point on polyline at parameter t
+   */
+  pointAt(t: number): Point {
+    ensureInit();
+    const r = wasm.polyline_point_at(this.toCoords(), t);
+    return new Point(r[0], r[1], r[2]);
+  }
+
+  /**
+   * Check if this polyline is closed.
+   * @param eps - Tolerance for comparing first and last points
+   * @returns True if first and last points coincide
+   */
+  isClosed(eps = 1e-10): boolean {
+    if (this.points.length < 2) return false;
+    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
+   * @param segments - Number of segments along extrusion (default 1)
+   * @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,
+      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
+   * @returns New translated polyline
+   */
+  translate(offset: Vec3): Polyline {
+    return new Polyline(this.points.map(p => p.add(offset)));
+  }
+
+  /**
+   * Apply a row-major 4x4 matrix to every vertex.
+   * @param matrix - Row-major 4x4 matrix (16 entries)
+   * @returns New transformed polyline
+   */
+  applyMatrix(matrix: number[] | Float64Array): Polyline {
+    return new Polyline(this.points.map(p => p.applyMatrix(matrix)));
+  }
+
+  /**
+   * Rotate this polyline around an axis.
+   * @param axis - Rotation axis (Vec3 through origin, or Line for arbitrary axis)
+   * @param angle - Rotation angle in radians
+   * @returns New rotated polyline
+   */
+  rotate(axis: RotationAxis, angle: number): 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)
+   * @returns New projected polyline
+   */
+  projectOntoPlane(plane: Plane, direction?: Vec3): Polyline {
+    const proj = (p: Point) => direction ? plane.projectPointAlongDirection(p, direction) : plane.projectPoint(p);
+    return new Polyline(this.points.map(proj));
+  }
+
+  /**
+   * Fillet corners of this polyline with arcs of the given radius.
+   * @param radius - Fillet radius
+   * @param normal - Reference normal for arc orientation (auto-detected if not provided)
+   * @returns PolyCurve with Line and Arc segments
+   */
+  fillet(radius: number, normal?: Vec3): PolyCurve {
+    ensureInit();
+    if (this.points.length < 3) {
+      throw new Error("Polyline.fillet() requires at least 3 points");
+    }
+
+    const nx = normal?.x ?? 0, ny = normal?.y ?? 0, nz = normal?.z ?? 0;
+    const buf = wasm.fillet_polycurve(this.toCoords(), radius, nx, ny, nz);
+    if (buf.length < 1) {
+      throw new Error("Polyline.fillet() failed - WASM returned empty result");
+    }
+
+    return PolyCurve.fromSegmentData(buf);
+  }
+
+  /**
+   * Chamfer corners of this polyline with straight cuts of the given
+   * setback distance (clamped per corner to half the shorter adjacent
+   * segment). Closed polylines (duplicated end point) chamfer every corner
+   * including the seam and stay closed; open polylines never touch their
+   * endpoints. `options.corners` selects vertex indices to chamfer
+   * (indices into the unique point list, seam duplicate excluded).
+   */
+  chamfer(distance: number, options: { corners?: number[] } = {}): Polyline {
+    ensureInit();
+    const pts = this.points;
+    if (pts.length < 3) {
+      throw new Error("Polyline.chamfer() requires at least 3 points");
+    }
+    const first = pts[0];
+    const last = pts[pts.length - 1];
+    const closed =
+      pts.length >= 4 &&
+      Math.abs(first.x - last.x) < 1e-10 &&
+      Math.abs(first.y - last.y) < 1e-10 &&
+      Math.abs(first.z - last.z) < 1e-10;
+    const unique = closed ? pts.slice(0, -1) : pts;
+    const coords = new Float64Array(unique.length * 3);
+    unique.forEach((p, i) => {
+      coords[i * 3] = p.x;
+      coords[i * 3 + 1] = p.y;
+      coords[i * 3 + 2] = p.z;
+    });
+    const cornerBuf = new Float64Array(options.corners ?? []);
+    const buf = wasm.chamfer_polyline_corners(coords, closed, distance, cornerBuf);
+    if (buf.length < 6) {
+      throw new Error(
+        `Polyline.chamfer() failed: ${wasm.geometry_last_error() || "unknown error"}`,
+      );
+    }
+    const out: Point[] = [];
+    for (let i = 0; i + 2 < buf.length; i += 3) {
+      out.push(new Point(buf[i], buf[i + 1], buf[i + 2]));
+    }
+    if (closed && out.length > 0) {
+      out.push(out[0]);
+    }
+    return new Polyline(out);
+  }
+
+  /**
+   * Convert this polyline to a PolyCurve (line segments only).
+   * @returns PolyCurve with Line segments connecting consecutive points
+   */
+  toPolyCurve(): PolyCurve {
+    const segs: Line[] = [];
+    for (let i = 0; i < this.points.length - 1; i++) {
+      segs.push(new Line(this.points[i], this.points[i + 1]));
+    }
+    return new PolyCurve(segs);
+  }
+
+  /**
+   * Convert points to flat coordinate array for WASM.
+   * @returns Float64Array [x1,y1,z1, x2,y2,z2, ...]
+   */
+  private toCoords(): Float64Array {
+    return pointsToCoords(this.points);
+  }
+}