okgeometry-api 1.2.0 → 1.4.0

package/src/MeshSurface.ts

@@ -0,0 +1,72 @@
+import { ensureInit } from "./engine.js";
+import { decodePointResult } from "./BufferCodec.js";
+import type { Mesh, MeshPlanarFace } from "./Mesh.js";
+import { Point } from "./Point.js";
+import type { Surface } from "./Surface.js";
+import { Vec3 } from "./Vec3.js";
+import * as wasm from "./wasm-bindings.js";
+
+/**
+ * Logical planar surface extracted from a coplanar connected face group on a mesh.
+ * Mirrors the `NurbsSurface` query API for evaluation and normals.
+ */
+export class MeshSurface implements Surface {
+  constructor(
+    public readonly mesh: Mesh,
+    public readonly face: MeshPlanarFace,
+  ) {}
+
+  get index(): number {
+    return this.face.index;
+  }
+
+  get seedTriangleIndex(): number {
+    return this.face.seedTriangleIndex;
+  }
+
+  get triangleIndices(): number[] {
+    return this.face.triangleIndices;
+  }
+
+  get triangleCount(): number {
+    return this.face.triangleCount;
+  }
+
+  get centroid(): Point {
+    return this.face.centroid;
+  }
+
+  get faceNormal(): Vec3 {
+    return this.face.normal;
+  }
+
+  get area(): number {
+    return this.face.area;
+  }
+
+  /**
+   * Evaluate a point on this planar mesh surface.
+   * Parameters map across the face group's local 2D bounds.
+   * Returns `Point(NaN, NaN, NaN)` when the query falls outside the actual face region.
+   */
+  evaluate(u: number, v: number): Point {
+    ensureInit();
+    return decodePointResult(
+      wasm.mesh_planar_face_evaluate(
+        this.mesh.vertexCount,
+        this.mesh.rawBuffer,
+        this.seedTriangleIndex,
+        u,
+        v,
+      ),
+    );
+  }
+
+  /**
+   * Unit normal of this planar mesh surface.
+   * The result is constant across the entire face group.
+   */
+  normal(_u: number, _v: number): Vec3 {
+    return this.faceNormal;
+  }
+}

package/src/NurbsCurve.ts

@@ -4,9 +4,10 @@ import { Vec3 } from "./Vec3.js";
 import { Plane } from "./Plane.js";
 import { Mesh } from "./Mesh.js";
 import { Polyline } from "./Polyline.js";
+import { PolyCurve } from "./PolyCurve.js";
 import type { Line } from "./Line.js";
 import type { Arc } from "./Arc.js";
-import type { RotationAxis } from "./types.js";
+import type { CurveOffsetOptions, RotationAxis } from "./types.js";
 import * as wasm from "./wasm-bindings.js";
 
 /**
@@ -160,12 +161,81 @@ export class NurbsCurve {
    * @param distance - Offset distance
    * @param normal - Reference normal for determining offset direction
    * @param samples - Number of sample points (default 64)
+   * @param arcSamples - Number of samples per exact arc segment in the returned polyline(s)
+   * @param options - Offset options such as join style
    * @returns Offset polyline approximation
    */
-  offset(distance: number, normal?: Vec3, samples = 64): Polyline {
+  offset(
+    distance: number,
+    normal?: Vec3,
+    samples = 64,
+    arcSamples = 32,
+    options: CurveOffsetOptions = {},
+  ): Polyline {
+    const results = this.offsetAll(distance, normal, samples, arcSamples, options);
+    if (results.length === 1) return results[0];
+    if (results.length === 0) {
+      throw new Error("NurbsCurve.offset() collapsed and produced no valid result polylines");
+    }
+    throw new Error(
+      `NurbsCurve.offset() produced ${results.length} result polylines. Use NurbsCurve.offsetAll() instead.`,
+    );
+  }
+
+  /**
+   * Offset this curve by a distance and return every sampled result polyline.
+   * Note: NURBS offset is approximated by sampling and offsetting as polyline.
+   * @param distance - Offset distance
+   * @param normal - Reference normal for determining offset direction
+   * @param samples - Number of sample points used to approximate the source curve
+   * @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 approximation
+   */
+  offsetAll(
+    distance: number,
+    normal?: Vec3,
+    samples = 64,
+    arcSamples = 32,
+    options: CurveOffsetOptions = {},
+  ): Polyline[] {
     const pts = this.sample(samples);
     const pl = new Polyline(pts);
-    return pl.offset(distance, normal);
+    return pl.offsetAll(distance, normal, arcSamples, options);
+  }
+
+  /**
+   * Thicken this curve into a closed PolyCurve.
+   * Note: this is approximated by sampling the NURBS curve into a polyline first.
+   *
+   * When `bothSides` is false, the sampled source curve forms one side of the
+   * result. When true, the distance is applied on each side of the sampled curve.
+   */
+  thicken(
+    distance: number,
+    bothSides = false,
+    normal?: Vec3,
+    samples = 64,
+    options: CurveOffsetOptions = {},
+  ): PolyCurve {
+    const pts = this.sample(samples);
+    return new Polyline(pts).thicken(distance, bothSides, normal, options);
+  }
+
+  /**
+   * Extrude this curve along a direction vector.
+   * Note: this is approximated by sampling the NURBS curve into a polyline
+   * first. Open curves produce an open sheet; closed curves an uncapped tube
+   * unless `caps` is true (see extrudeAsSolid for a boolean-ready solid).
+   * @param direction - Extrusion direction and magnitude
+   * @param segments - Number of segments along the extrusion (default 1)
+   * @param caps - Whether to cap the ends of a closed profile (default false)
+   * @param samples - Number of curve samples used for tessellation (default 64)
+   * @returns Mesh representing the extruded surface
+   */
+  extrude(direction: Vec3, segments = 1, caps = false, samples = 64): Mesh {
+    const pts = this.sample(samples);
+    return new Polyline(pts).extrude(direction, segments, caps);
   }
 
   /**
@@ -178,6 +248,36 @@ export class NurbsCurve {
     return Mesh.extrudeCurveAsSolid(this, direction, segments);
   }
 
+  /**
+   * Build a NURBS curve from raw control points with kernel-managed knots and
+   * uniform weights.
+   *
+   * Open curves use a clamped uniform knot vector (curve interpolates the first
+   * and last control points). Closed curves are periodic (C^{degree-1}
+   * continuous loops); the first control point must NOT be repeated at the end.
+   *
+   * @param degree - Requested degree (clamped by the kernel to the valid range)
+   * @param controlPoints - Control points (min 2 open / 3 closed)
+   * @param closed - Build a periodic closed loop (default false)
+   * @returns New NurbsCurve instance
+   */
+  static fromPoints(degree: number, controlPoints: Point[], closed = false): NurbsCurve {
+    ensureInit();
+    const coords = new Float64Array(controlPoints.length * 3);
+    for (let i = 0; i < controlPoints.length; i++) {
+      coords[i * 3] = controlPoints[i].x;
+      coords[i * 3 + 1] = controlPoints[i].y;
+      coords[i * 3 + 2] = controlPoints[i].z;
+    }
+    const buf = wasm.build_nurbs_curve(degree, coords, closed);
+    if (buf.length < 2) {
+      throw new Error(
+        `NurbsCurve.fromPoints failed (degree ${degree}, ${controlPoints.length} points, closed=${closed})`,
+      );
+    }
+    return NurbsCurve.fromData(buf);
+  }
+
   /**
    * Decode a NurbsCurve from WASM flat buffer.
    * @param data - Buffer in format [degree, num_cp, xyz..., w..., k...]

package/src/NurbsSurface.ts

@@ -5,13 +5,18 @@ import { Plane } from "./Plane.js";
 import { Mesh } from "./Mesh.js";
 import { Polyline } from "./Polyline.js";
 import { Polygon } from "./Polygon.js";
-import { Line } from "./Line.js";
-import { Arc } from "./Arc.js";
-import { PolyCurve } from "./PolyCurve.js";
-import { NurbsCurve } from "./NurbsCurve.js";
-import type { LoftableCurve, RotationAxis } from "./types.js";
-import { parsePolylineBuffer as parsePolylineBuf } from "./BufferCodec.js";
-import * as wasm from "./wasm-bindings.js";
+import { Line } from "./Line.js";
+import { Arc } from "./Arc.js";
+import { PolyCurve } from "./PolyCurve.js";
+import { NurbsCurve } from "./NurbsCurve.js";
+import type { Surface } from "./Surface.js";
+import type { LoftableCurve, RotationAxis } from "./types.js";
+import {
+  decodePointResult,
+  decodeVec3Result,
+  parsePolylineBuffer as parsePolylineBuf,
+} from "./BufferCodec.js";
+import * as wasm from "./wasm-bindings.js";
 
 /**
  * Non-Uniform Rational B-Spline (NURBS) surface backed by WASM.
@@ -19,7 +24,7 @@ import * as wasm from "./wasm-bindings.js";
  *
  * WASM data format: [degree_u, degree_v, num_u, num_v, ...cp(flat)..., ...weights..., ...knots_u..., ...knots_v...]
  */
-export class NurbsSurface {
+export class NurbsSurface implements Surface {
   private _data: Float64Array;
 
   /**
@@ -82,11 +87,21 @@ export class NurbsSurface {
    * @param v - Parameter in V direction [0, 1]
    * @returns Point on surface at (u, v)
    */
-  evaluate(u: number, v: number): Point {
-    ensureInit();
-    const r = wasm.nurbs_surface_evaluate(this._data, u, v);
-    return new Point(r[0], r[1], r[2]);
-  }
+  evaluate(u: number, v: number): Point {
+    ensureInit();
+    return decodePointResult(wasm.nurbs_surface_evaluate(this._data, u, v));
+  }
+
+  /**
+   * Evaluate the unit normal on the surface at parameters (u, v).
+   * @param u - Parameter in U direction [0, 1]
+   * @param v - Parameter in V direction [0, 1]
+   * @returns Unit surface normal at (u, v)
+   */
+  normal(u: number, v: number): Vec3 {
+    ensureInit();
+    return decodeVec3Result(wasm.nurbs_surface_normal(this._data, u, v));
+  }
 
   /**
    * Tessellate this surface into a triangle mesh.

package/src/PolyCurve.ts

@@ -6,15 +6,31 @@ import { Vec3 } from "./Vec3.js";
 import { Mesh } from "./Mesh.js";
 import { NurbsCurve } from "./NurbsCurve.js";
 import type { Plane } from "./Plane.js";
-import type { CurveSegment, RotationAxis } from "./types.js";
+import type {
+  CurveOffsetJoinStyle,
+  CurveOffsetOptions,
+  CurveSegment,
+  RotationAxis,
+} from "./types.js";
 import { SegmentTypeCode } from "./types.js";
 import { pointsToCoords } from "./BufferCodec.js";
 import * as wasm from "./wasm-bindings.js";
-
-/**
- * Composite curve made of sequential Line and Arc segments.
- */
-export class PolyCurve {
+
+function offsetJoinStyleCode(style: CurveOffsetJoinStyle | undefined): number {
+  switch (style ?? "miter") {
+    case "round":
+      return 1;
+    case "bevel":
+      return 2;
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Composite curve made of sequential Line and Arc segments.
+ */
+export class PolyCurve {
   public readonly segments: CurveSegment[];
 
   constructor(segments: CurveSegment[]) {
@@ -199,10 +215,10 @@ export class PolyCurve {
   }
 
   /** Decode a PolyCurve from WASM segment buffer [count, type, ...data, ...] */
-  static fromSegmentData(buf: Float64Array | number[]): PolyCurve {
-    const count = buf[0];
-    const segs: CurveSegment[] = [];
-    let idx = 1;
+  static fromSegmentData(buf: Float64Array | number[]): PolyCurve {
+    const count = buf[0];
+    const segs: CurveSegment[] = [];
+    let idx = 1;
     for (let i = 0; i < count; i++) {
       const type = buf[idx++];
       if (type === SegmentTypeCode.Line) {
@@ -221,9 +237,32 @@ export class PolyCurve {
         segs.push(new Arc(center, radius, startAngle, endAngle, normal));
         idx += 9;
       }
-    }
-    return new PolyCurve(segs);
-  }
+    }
+    return new PolyCurve(segs);
+  }
+
+  /** Decode multiple PolyCurves from WASM buffer [curveCount, curveLen, curveData..., ...] */
+  static fromSegmentDataSet(buf: Float64Array | number[]): PolyCurve[] {
+    const data = buf instanceof Float64Array ? buf : new Float64Array(buf);
+    const curveCount = Math.max(0, Math.floor(data[0] ?? 0));
+    const curves: PolyCurve[] = [];
+    let idx = 1;
+
+    for (let i = 0; i < curveCount; i++) {
+      const curveLen = Math.max(0, Math.floor(data[idx++] ?? -1));
+      if (curveLen <= 0 || idx + curveLen > data.length) {
+        throw new Error("PolyCurve.fromSegmentDataSet() received invalid curve set buffer");
+      }
+      curves.push(PolyCurve.fromSegmentData(data.slice(idx, idx + curveLen)));
+      idx += curveLen;
+    }
+
+    if (idx !== data.length) {
+      throw new Error("PolyCurve.fromSegmentDataSet() received trailing buffer data");
+    }
+
+    return curves;
+  }
 
   /**
    * Chamfer corners of this PolyCurve by cutting each corner with a straight segment.
@@ -263,76 +302,109 @@ export class PolyCurve {
     return PolyCurve.fromSegmentData(buf);
   }
 
-  /**
-   * Offset this PolyCurve by a distance in the given plane.
-   * Extracts vertex points, offsets as a polyline, returns a new PolyCurve of line segments.
-   */
-  offset(distance: number, normal?: Vec3): PolyCurve {
-    ensureInit();
-    if (this.segments.length < 1) {
-      throw new Error("PolyCurve.offset() requires at least 1 segment");
-    }
-
-    const pts: Point[] = [];
-    for (const seg of this.segments) {
-      if (seg instanceof Line) {
-        if (pts.length === 0) pts.push(seg.start);
-        pts.push(seg.end);
-      } else {
-        if (pts.length === 0) pts.push(seg.pointAt(0));
-        pts.push(seg.pointAt(1));
-      }
-    }
-    if (pts.length < 2) {
-      throw new Error("PolyCurve.offset() requires at least 2 vertices");
-    }
-
-    const coords = new Float64Array(pts.length * 3);
-    for (let i = 0; i < pts.length; i++) {
-      coords[i * 3] = pts[i].x;
-      coords[i * 3 + 1] = pts[i].y;
-      coords[i * 3 + 2] = pts[i].z;
-    }
-
-    const nx = normal?.x ?? 0, ny = normal?.y ?? 0, nz = normal?.z ?? 0;
-    const result = wasm.offset_polyline_curve(coords, distance, nx, ny, nz);
-    if (result.length < 6) {
-      throw new Error("PolyCurve.offset() failed - WASM returned insufficient data");
-    }
-
-    // Convert flat coords back to line segments
-    const segs: CurveSegment[] = [];
-    for (let i = 0; i < result.length - 3; i += 3) {
-      const s = new Point(result[i], result[i + 1], result[i + 2]);
-      const e = new Point(result[i + 3], result[i + 4], result[i + 5]);
-      segs.push(new Line(s, e));
-    }
-    return new PolyCurve(segs);
-  }
-
-  /**
-   * Convert to an exact NURBS curve representation via WASM.
-   * Lines become degree-1 NURBS, Arcs become degree-2 rational NURBS.
-   * All segments are degree-elevated to a common degree and joined.
+  /**
+   * Offset this PolyCurve by a distance in the given plane.
+   * Preserves exact line/arc segments where possible and applies the requested outside-corner join style.
+   * Defaults to `miter`.
+   */
+  offset(distance: number, normal?: Vec3, options: CurveOffsetOptions = {}): PolyCurve {
+    const results = this.offsetAll(distance, normal, options);
+    if (results.length === 1) return results[0];
+    if (results.length === 0) {
+      throw new Error("PolyCurve.offset() collapsed and produced no valid result curves");
+    }
+    throw new Error(
+      `PolyCurve.offset() produced ${results.length} result curves. Use PolyCurve.offsetAll() instead.`,
+    );
+  }
+
+  /**
+   * Offset this PolyCurve by a distance in the given plane and return every exact result curve.
+   * Defaults to `miter`.
+   */
+  offsetAll(distance: number, normal?: Vec3, options: CurveOffsetOptions = {}): PolyCurve[] {
+    ensureInit();
+    if (this.segments.length < 1) {
+      throw new Error("PolyCurve.offsetAll() requires at least 1 segment");
+    }
+
+    const nx = normal?.x ?? 0, ny = normal?.y ?? 0, nz = normal?.z ?? 0;
+    const joinStyleCode = offsetJoinStyleCode(options.joinStyle);
+    const result = wasm.offset_polycurve_all(this.toSegmentData(), distance, nx, ny, nz, joinStyleCode);
+    if (result.length < 1) {
+      throw new Error("PolyCurve.offsetAll() failed - WASM returned empty result");
+    }
+    return PolyCurve.fromSegmentDataSet(result);
+  }
+
+  /**
+   * Thicken this open PolyCurve into a single closed loop.
+   * When `bothSides` is false, the source curve forms one side and the offset
+   * curve forms the other. When true, the distance is applied on each side of
+   * the source curve, doubling the overall width.
+   *
+   * For line-like inputs where the plane is ambiguous, provide `normal`.
+   */
+  thicken(
+    distance: number,
+    bothSides = false,
+    normal?: Vec3,
+    options: CurveOffsetOptions = {},
+  ): PolyCurve {
+    ensureInit();
+    if (this.segments.length < 1) {
+      throw new Error("PolyCurve.thicken() requires at least 1 segment");
+    }
+    if (!Number.isFinite(distance) || distance <= 0) {
+      throw new Error("PolyCurve.thicken() requires a positive distance");
+    }
+    if (this.isClosed()) {
+      throw new Error("PolyCurve.thicken() requires an open curve");
+    }
+
+    const nx = normal?.x ?? 0, ny = normal?.y ?? 0, nz = normal?.z ?? 0;
+    const joinStyleCode = offsetJoinStyleCode(options.joinStyle);
+    const result = wasm.thicken_polycurve(
+      this.toSegmentData(),
+      distance,
+      bothSides,
+      nx,
+      ny,
+      nz,
+      joinStyleCode,
+    );
+    if (result.length < 1) {
+      throw new Error("PolyCurve.thicken() failed - WASM returned empty result");
+    }
+    return PolyCurve.fromSegmentData(result);
+  }
+
+  /**
+   * Convert to an exact NURBS curve representation via WASM.
+   * Lines become degree-1 NURBS, Arcs become degree-2 rational NURBS.
+   * All segments are degree-elevated to a common degree and joined.
    */
-  toNurbs(): NurbsCurve {
-    ensureInit();
-    const segData: number[] = [this.segments.length];
-    for (const seg of this.segments) {
-      if (seg instanceof Line) {
-        segData.push(SegmentTypeCode.Line);
-        segData.push(seg.start.x, seg.start.y, seg.start.z);
-        segData.push(seg.end.x, seg.end.y, seg.end.z);
-      } else {
-        // Arc
-        segData.push(SegmentTypeCode.Arc);
-        segData.push(seg.center.x, seg.center.y, seg.center.z);
-        segData.push(seg.normal.x, seg.normal.y, seg.normal.z);
-        segData.push(seg.radius, seg.startAngle, seg.endAngle);
-      }
-    }
-    const buf = wasm.polycurve_to_nurbs(new Float64Array(segData));
-    if (buf.length < 2) throw new Error("Failed to convert PolyCurve to NURBS");
-    return NurbsCurve.fromData(buf);
-  }
-}
+  toNurbs(): NurbsCurve {
+    ensureInit();
+    const buf = wasm.polycurve_to_nurbs(this.toSegmentData());
+    if (buf.length < 2) throw new Error("Failed to convert PolyCurve to NURBS");
+    return NurbsCurve.fromData(buf);
+  }
+
+  private toSegmentData(): Float64Array {
+    const segData: number[] = [this.segments.length];
+    for (const seg of this.segments) {
+      if (seg instanceof Line) {
+        segData.push(SegmentTypeCode.Line);
+        segData.push(seg.start.x, seg.start.y, seg.start.z);
+        segData.push(seg.end.x, seg.end.y, seg.end.z);
+      } else {
+        segData.push(SegmentTypeCode.Arc);
+        segData.push(seg.center.x, seg.center.y, seg.center.z);
+        segData.push(seg.normal.x, seg.normal.y, seg.normal.z);
+        segData.push(seg.radius, seg.startAngle, seg.endAngle);
+      }
+    }
+    return new Float64Array(segData);
+  }
+}

package/src/Polygon.ts

@@ -2,7 +2,7 @@ import { Point } from "./Point.js";
 import { Vec3 } from "./Vec3.js";
 import { Polyline } from "./Polyline.js";
 import type { Plane } from "./Plane.js";
-import type { RotationAxis } from "./types.js";
+import type { CurveOffsetOptions, RotationAxis } from "./types.js";
 
 /**
  * A closed polygon defined by vertices.
@@ -55,11 +55,41 @@ export class Polygon extends Polyline {
    * Offset this polygon perpendicular to its edges.
    * @param distance - Offset distance
    * @param normal - Reference normal for determining offset direction
+   * @param arcSamples - Number of samples per arc join in the returned polygon(s)
+   * @param options - Offset options such as join style
    * @returns New offset polygon
    */
-  override offset(distance: number, normal?: Vec3): Polygon {
-    const pl = super.offset(distance, normal);
-    return new Polygon(pl.points);
+  override offset(
+    distance: number,
+    normal?: Vec3,
+    arcSamples = 32,
+    options: CurveOffsetOptions = {},
+  ): Polygon {
+    const results = this.offsetAll(distance, normal, arcSamples, options);
+    if (results.length === 1) return results[0];
+    if (results.length === 0) {
+      throw new Error("Polygon.offset() collapsed and produced no valid result polygons");
+    }
+    throw new Error(
+      `Polygon.offset() produced ${results.length} result polygons. Use Polygon.offsetAll() instead.`,
+    );
+  }
+
+  /**
+   * Offset this polygon and return every sampled result polygon.
+   * @param distance - Offset distance
+   * @param normal - Reference normal for determining offset direction
+   * @param arcSamples - Number of samples per exact arc segment in the returned polygons
+   * @param options - Offset options such as join style
+   * @returns Every valid offset polygon
+   */
+  offsetAll(
+    distance: number,
+    normal?: Vec3,
+    arcSamples = 32,
+    options: CurveOffsetOptions = {},
+  ): Polygon[] {
+    return super.offsetAll(distance, normal, arcSamples, options).map(polyline => new Polygon(polyline.points));
   }
 
   /**