okgeometry-api 0.5.0 → 0.5.2

package/dist/wasm-base64.js.map

@@ -1 +1 @@
-{"version":3,"file":"wasm-base64.js","sourceRoot":"","sources":["../src/wasm-base64.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,MAAM,CAAC,MAAM,QAAQ,GAAG,070/BAA070/B,CAAC"}
+{"version":3,"file":"wasm-base64.js","sourceRoot":"","sources":["../src/wasm-base64.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,MAAM,CAAC,MAAM,QAAQ,GAAG,ku5hCAAku5hC,CAAC"}

package/package.json

@@ -1,45 +1,46 @@
-{
-  "name": "okgeometry-api",
-  "version": "0.5.0",
-  "description": "Geometry engine API for AEC applications — NURBS, meshes, booleans, intersections. Powered by Rust/WASM.",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist/",
-    "wasm/"
-  ],
-  "scripts": {
-    "inline-wasm": "tsx scripts/inline-wasm.ts",
-    "build": "npm run inline-wasm && tsc",
-    "bench:boolean-backends": "npm run build && tsx scripts/compare-boolean-backends.ts",
-    "profile:boolean-backends": "npm run build && tsx scripts/profile-boolean-backends.ts",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "geometry",
-    "wasm",
-    "nurbs",
-    "mesh",
-    "boolean",
-    "cad",
-    "aec",
-    "3d"
-  ],
-  "author": "Mostafa El Ayoubi",
-  "license": "Proprietary License",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/moel-ai/okgeometrycore"
-  },
-  "devDependencies": {
-    "typescript": "^5.4.0",
-    "tsx": "^4.7.0"
-  }
-}
+{
+  "name": "okgeometry-api",
+  "version": "0.5.2",
+  "description": "Geometry engine API for AEC applications — NURBS, meshes, booleans, intersections. Powered by Rust/WASM.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "wasm/"
+  ],
+  "scripts": {
+    "inline-wasm": "tsx scripts/inline-wasm.ts",
+    "build": "npm run inline-wasm && tsc",
+    "bench:boolean-nextgen": "npm run build && tsx scripts/gate-boolean-nextgen.ts",
+    "gate:boolean-nextgen": "npm run build && tsx scripts/gate-boolean-nextgen.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "geometry",
+    "wasm",
+    "nurbs",
+    "mesh",
+    "boolean",
+    "cad",
+    "aec",
+    "3d"
+  ],
+  "author": "Mostafa El Ayoubi",
+  "license": "Proprietary License",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moel-ai/okgeometrycore"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "tsx": "^4.7.0"
+  }
+}

package/src/Arc.ts

@@ -0,0 +1,117 @@
+import { ensureInit } from "./engine.js";
+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 * as wasm from "../wasm/okgeometrycore_bg.js";
+
+/**
+ * Immutable circular arc defined by center, radius, and angular span.
+ * Angles are in radians, measured counter-clockwise from the positive X axis
+ * in the plane defined by the normal.
+ */
+export class Arc {
+  /**
+   * Create a new arc.
+   * @param center - Center point
+   * @param radius - Arc radius
+   * @param startAngle - Start angle in radians
+   * @param endAngle - End angle in radians
+   * @param normal - Normal vector defining the arc's plane (default Z axis)
+   */
+  constructor(
+    public readonly center: Point,
+    public readonly radius: number,
+    public readonly startAngle: number,
+    public readonly endAngle: number,
+    public readonly normal: Vec3 = Vec3.Z
+  ) {}
+
+  /**
+   * Evaluate a point on the arc at normalized parameter t.
+   * @param t - Parameter in [0, 1] (0 = start angle, 1 = end angle)
+   * @returns Point on arc at parameter t
+   */
+  pointAt(t: number): Point {
+    ensureInit();
+    const r = wasm.arc_point_at(
+      this.center.x, this.center.y, this.center.z,
+      this.normal.x, this.normal.y, this.normal.z,
+      this.radius, this.startAngle, this.endAngle, t
+    );
+    return new Point(r[0], r[1], r[2]);
+  }
+
+  /**
+   * Get the arc length.
+   * @returns Arc length = radius * angular span
+   */
+  length(): number {
+    ensureInit();
+    return wasm.arc_length(this.radius, this.startAngle, this.endAngle);
+  }
+
+  /**
+   * Translate this arc by an offset vector.
+   * @param offset - Translation vector
+   * @returns New translated arc
+   */
+  translate(offset: Vec3): Arc {
+    return new Arc(this.center.add(offset), this.radius, this.startAngle, this.endAngle, this.normal);
+  }
+
+  /**
+   * Rotate this arc around an axis.
+   * @param axis - Rotation axis (Vec3 through origin, or Line for arbitrary axis)
+   * @param angle - Rotation angle in radians
+   * @returns New rotated arc
+   */
+  rotate(axis: RotationAxis, angle: number): Arc {
+    const n = this.normal;
+    const dirAxis = 'start' in axis ? new Vec3(axis.end.x - axis.start.x, axis.end.y - axis.start.y, axis.end.z - axis.start.z) : axis;
+    const rn = new Point(n.x, n.y, n.z).rotate(dirAxis, angle);
+    return new Arc(this.center.rotate(axis, angle), this.radius, this.startAngle, this.endAngle, new Vec3(rn.x, rn.y, rn.z));
+  }
+
+  /**
+   * Offset this arc by changing its radius.
+   * @param distance - Distance to offset (positive = larger, negative = smaller)
+   * @returns New arc with adjusted radius
+   */
+  offset(distance: number): Arc {
+    return new Arc(this.center, this.radius + distance, this.startAngle, this.endAngle, this.normal);
+  }
+
+  /**
+   * Project onto plane. Returns a Polyline because a tilted arc projects to an elliptical arc.
+   * @param plane - Target plane
+   * @param direction - Optional projection direction (default: perpendicular to plane)
+   * @param samples - Number of sample points for approximation (default 64)
+   * @returns Polyline approximating the projected arc
+   */
+  projectOntoPlane(plane: Plane, direction?: Vec3, samples = 64): Polyline {
+    const pts = this.sample(samples);
+    const proj = (p: Point) => direction ? plane.projectPointAlongDirection(p, direction) : plane.projectPoint(p);
+    return new Polyline(pts.map(proj));
+  }
+
+  /**
+   * Sample the arc into evenly-spaced points.
+   * @param n - Number of points to generate
+   * @returns Array of n points along the arc
+   */
+  sample(n: number): Point[] {
+    ensureInit();
+    const buf = wasm.create_arc(
+      this.center.x, this.center.y, this.center.z,
+      this.normal.x, this.normal.y, this.normal.z,
+      this.radius, this.startAngle, this.endAngle, n
+    );
+    const pts: Point[] = [];
+    for (let i = 0; i < buf.length; i += 3) {
+      pts.push(new Point(buf[i], buf[i + 1], buf[i + 2]));
+    }
+    return pts;
+  }
+}

package/src/BufferCodec.ts

@@ -0,0 +1,181 @@
+/**
+ * Buffer encoding/decoding utilities for WASM communication.
+ *
+ * # WASM Buffer Formats
+ *
+ * ## Mesh Buffer
+ * `[vertexCount, x1,y1,z1, ..., i1,i2,i3, ...]`
+ * - Element 0: Number of vertices
+ * - Elements 1 to vertexCount*3: Vertex coordinates (xyz triplets)
+ * - Remaining elements: Triangle indices (groups of 3)
+ *
+ * ## Polyline Buffer (multi-polyline result)
+ * `[numPolylines, count1, x,y,z,..., count2, x,y,z,...]`
+ * - Element 0: Number of polylines
+ * - For each polyline: point count followed by xyz coordinates
+ *
+ * ## Intersection Points Buffer
+ * `[numPoints, x1,y1,z1, x2,y2,z2, ...]`
+ * - Element 0: Number of intersection points
+ * - Remaining: xyz triplets for each point
+ *
+ * ## Curve Encoding (for sweep/loft)
+ * See CurveTypeCode enum in types.ts for format details.
+ *
+ * ## NURBS Curve Data
+ * `[degree, numControlPoints, x1,y1,z1,..., w1,w2,..., k1,k2,...]`
+ *
+ * ## NURBS Surface Data
+ * `[degU, degV, numU, numV, cp_xyz..., weights..., knotsU..., knotsV...]`
+ *
+ * @module BufferCodec
+ */
+
+import { Point } from "./Point.js";
+import { Vec3 } from "./Vec3.js";
+
+// ── Point Array Conversion ─────────────────────────────────────────
+
+/**
+ * Convert array of Points to flat coordinate buffer.
+ * @param points - Array of Point objects
+ * @returns Float64Array with interleaved [x1,y1,z1, x2,y2,z2, ...]
+ *
+ * @example
+ * ```typescript
+ * const pts = [new Point(0,0,0), new Point(1,2,3)];
+ * const coords = pointsToCoords(pts);
+ * // coords = Float64Array [0, 0, 0, 1, 2, 3]
+ * ```
+ */
+export function pointsToCoords(points: Point[]): Float64Array {
+  const coords = new Float64Array(points.length * 3);
+  for (let i = 0; i < points.length; i++) {
+    coords[i * 3] = points[i].x;
+    coords[i * 3 + 1] = points[i].y;
+    coords[i * 3 + 2] = points[i].z;
+  }
+  return coords;
+}
+
+/**
+ * Convert flat coordinate buffer to array of Points.
+ * @param coords - Float64Array with interleaved xyz coordinates
+ * @returns Array of Point objects
+ *
+ * @example
+ * ```typescript
+ * const coords = new Float64Array([0, 0, 0, 1, 2, 3]);
+ * const pts = coordsToPoints(coords);
+ * // pts = [Point(0,0,0), Point(1,2,3)]
+ * ```
+ */
+export function coordsToPoints(coords: Float64Array | number[]): Point[] {
+  const data = coords instanceof Float64Array ? coords : new Float64Array(coords);
+  const pts: Point[] = [];
+  for (let i = 0; i < data.length; i += 3) {
+    pts.push(new Point(data[i], data[i + 1], data[i + 2]));
+  }
+  return pts;
+}
+
+/**
+ * Read a single Point from buffer at specified offset.
+ * @param buf - Source buffer
+ * @param offset - Starting index in buffer
+ * @returns Tuple of [Point, newOffset] where newOffset = offset + 3
+ */
+export function readPoint(buf: Float64Array, offset: number): [Point, number] {
+  return [new Point(buf[offset], buf[offset + 1], buf[offset + 2]), offset + 3];
+}
+
+/**
+ * Read a single Vec3 from buffer at specified offset.
+ * @param buf - Source buffer
+ * @param offset - Starting index in buffer
+ * @returns Tuple of [Vec3, newOffset] where newOffset = offset + 3
+ */
+export function readVec3(buf: Float64Array, offset: number): [Vec3, number] {
+  return [new Vec3(buf[offset], buf[offset + 1], buf[offset + 2]), offset + 3];
+}
+
+// ── WASM Result Decoding ───────────────────────────────────────────
+
+/**
+ * Decode WASM result buffer as single Point.
+ * Common pattern for pointAt(), closestPoint() results.
+ * @param r - WASM result array (must have at least 3 elements)
+ * @returns Point from first 3 elements
+ */
+export function decodePointResult(r: Float64Array): Point {
+  return new Point(r[0], r[1], r[2]);
+}
+
+/**
+ * Decode WASM result buffer as single Vec3.
+ * Common pattern for tangent(), normal() results.
+ * @param r - WASM result array (must have at least 3 elements)
+ * @returns Vec3 from first 3 elements
+ */
+export function decodeVec3Result(r: Float64Array): Vec3 {
+  return new Vec3(r[0], r[1], r[2]);
+}
+
+// ── Polyline Buffer Format ─────────────────────────────────────────
+
+/**
+ * Parse WASM multi-polyline buffer into array of point arrays.
+ * Used by mesh intersection operations that return multiple polylines.
+ *
+ * Buffer format: [numPolylines, count1, x,y,z,..., count2, x,y,z,...]
+ *
+ * @param buf - WASM result buffer
+ * @returns Array of Point arrays, one per polyline
+ *
+ * @example
+ * ```typescript
+ * // Buffer: [2, 3, 0,0,0, 1,0,0, 1,1,0, 2, 5,5,5, 6,6,6]
+ * // = 2 polylines: first has 3 points, second has 2 points
+ * const polylines = parsePolylineBuffer(buf);
+ * // polylines[0] = [Point(0,0,0), Point(1,0,0), Point(1,1,0)]
+ * // polylines[1] = [Point(5,5,5), Point(6,6,6)]
+ * ```
+ */
+export function parsePolylineBuffer(buf: Float64Array): Point[][] {
+  if (buf.length === 0) return [];
+  const numPolylines = buf[0];
+  const result: Point[][] = [];
+  let idx = 1;
+  for (let i = 0; i < numPolylines; i++) {
+    const count = buf[idx++];
+    const pts: Point[] = [];
+    for (let j = 0; j < count; j++) {
+      pts.push(new Point(buf[idx], buf[idx + 1], buf[idx + 2]));
+      idx += 3;
+    }
+    result.push(pts);
+  }
+  return result;
+}
+
+// ── Intersection Result Format ─────────────────────────────────────
+
+/**
+ * Parse WASM intersection points buffer.
+ * Used by curve-curve and curve-plane intersection operations.
+ *
+ * Buffer format: [numPoints, x1,y1,z1, x2,y2,z2, ...]
+ *
+ * @param buf - WASM result buffer
+ * @returns Array of intersection Points
+ */
+export function parseIntersectionPoints(buf: Float64Array): Point[] {
+  if (buf.length === 0) return [];
+  const numPts = buf[0];
+  const pts: Point[] = [];
+  for (let i = 0; i < numPts; i++) {
+    const off = 1 + i * 3;
+    pts.push(new Point(buf[off], buf[off + 1], buf[off + 2]));
+  }
+  return pts;
+}

package/src/Circle.ts

@@ -0,0 +1,153 @@
+import { ensureInit } from "./engine.js";
+import { Point } from "./Point.js";
+import { Vec3 } from "./Vec3.js";
+import { Mesh } from "./Mesh.js";
+import { Polygon } from "./Polygon.js";
+import { Plane } from "./Plane.js";
+import type { RotationAxis } from "./types.js";
+import * as wasm from "../wasm/okgeometrycore_bg.js";
+
+/**
+ * Immutable circle defined by center, radius, and normal.
+ * Supports evaluation, transformation, extrusion, and projection.
+ */
+export class Circle {
+  /**
+   * Create a new circle.
+   * @param center - Center point
+   * @param radius - Circle radius
+   * @param normal - Normal vector defining the circle's plane (default Z axis)
+   * @param uAxis - Optional reference direction defining where t=0 starts.
+   *                Critical for sweep operations to maintain consistent profile orientation.
+   */
+  constructor(
+    public readonly center: Point,
+    public readonly radius: number,
+    public readonly normal: Vec3 = Vec3.Z,
+    public readonly uAxis?: Vec3
+  ) {}
+
+  /**
+   * Create a Circle from a Plane, automatically using the plane's xAxis
+   * as the circle's uAxis for consistent orientation in sweep operations.
+   * @param plane - Plane defining circle's position and orientation
+   * @param radius - Circle radius
+   * @returns New Circle at plane origin with plane normal
+   */
+  static fromPlane(plane: Plane, radius: number): Circle {
+    return new Circle(plane.origin, radius, plane.normal, plane.getXAxis());
+  }
+
+  /**
+   * Evaluate a point on the circle at normalized parameter t.
+   * @param t - Parameter in [0, 1] (0 and 1 are the same point for closed circle)
+   * @returns Point on circle at parameter t
+   */
+  pointAt(t: number): Point {
+    ensureInit();
+    const r = wasm.circle_point_at(
+      this.center.x, this.center.y, this.center.z,
+      this.normal.x, this.normal.y, this.normal.z,
+      this.radius, t
+    );
+    return new Point(r[0], r[1], r[2]);
+  }
+
+  /**
+   * Get the circumference of this circle.
+   * @returns 2 * PI * radius
+   */
+  length(): number {
+    ensureInit();
+    return wasm.circle_length(this.radius);
+  }
+
+  /**
+   * Sample the circle into evenly-spaced points.
+   * @param n - Number of points to generate
+   * @returns Array of n points around the circle
+   */
+  sample(n: number): Point[] {
+    ensureInit();
+    const buf = wasm.create_circle(
+      this.center.x, this.center.y, this.center.z,
+      this.normal.x, this.normal.y, this.normal.z,
+      this.radius, n
+    );
+    const pts: Point[] = [];
+    for (let i = 0; i < buf.length; i += 3) {
+      pts.push(new Point(buf[i], buf[i + 1], buf[i + 2]));
+    }
+    return pts;
+  }
+
+  /**
+   * Translate this circle by an offset vector.
+   * @param offset - Translation vector
+   * @returns New translated circle
+   */
+  translate(offset: Vec3): Circle {
+    return new Circle(this.center.add(offset), this.radius, this.normal, this.uAxis);
+  }
+
+  /**
+   * Rotate this circle around an axis.
+   * @param axis - Rotation axis (Vec3 through origin, or Line for arbitrary axis)
+   * @param angle - Rotation angle in radians
+   * @returns New rotated circle
+   */
+  rotate(axis: RotationAxis, angle: number): Circle {
+    const n = this.normal;
+    // Normal is a direction — always rotate around origin regardless of axis type
+    const dirAxis = 'start' in axis ? new Vec3(axis.end.x - axis.start.x, axis.end.y - axis.start.y, axis.end.z - axis.start.z) : axis;
+    const rn = new Point(n.x, n.y, n.z).rotate(dirAxis, angle);
+    // Also rotate the uAxis if present
+    let rotatedUAxis: Vec3 | undefined;
+    if (this.uAxis) {
+      const ru = new Point(this.uAxis.x, this.uAxis.y, this.uAxis.z).rotate(dirAxis, angle);
+      rotatedUAxis = new Vec3(ru.x, ru.y, ru.z);
+    }
+    return new Circle(this.center.rotate(axis, angle), this.radius, new Vec3(rn.x, rn.y, rn.z), rotatedUAxis);
+  }
+
+  /**
+   * Offset this circle by changing its radius.
+   * @param distance - Distance to offset (positive = larger, negative = smaller)
+   * @returns New circle with adjusted radius
+   */
+  offset(distance: number): Circle {
+    return new Circle(this.center, this.radius + distance, this.normal, this.uAxis);
+  }
+
+  /**
+   * Project onto plane. Returns a Polygon because a tilted circle projects to an ellipse.
+   * @param plane - Target plane
+   * @param direction - Optional projection direction (default: perpendicular to plane)
+   * @param samples - Number of sample points for approximation (default 64)
+   * @returns Polygon approximating the projected circle
+   */
+  projectOntoPlane(plane: Plane, direction?: Vec3, samples = 64): Polygon {
+    const pts = this.sample(samples);
+    const proj = (p: Point) => direction ? plane.projectPointAlongDirection(p, direction) : plane.projectPoint(p);
+    return new Polygon(pts.map(proj));
+  }
+
+  /**
+   * Extrude this circle along a direction vector to create a cylindrical mesh.
+   * @param direction - Extrusion direction and magnitude
+   * @param segments - Number of circumferential segments (default 16)
+   * @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,
+      this.radius,
+      direction.x, direction.y, direction.z,
+      segments, caps
+    );
+    return Mesh.fromBuffer(buf);
+  }
+}

package/src/Geometry.ts

@@ -0,0 +1,39 @@
+import { Mesh } from "./Mesh.js";
+import { Plane } from "./Plane.js";
+import { Point } from "./Point.js";
+import { Polyline } from "./Polyline.js";
+import { NurbsCurve } from "./NurbsCurve.js";
+import { NurbsSurface } from "./NurbsSurface.js";
+
+type GeometryType = Mesh | Plane | NurbsCurve | NurbsSurface;
+type IntersectResult = Point[] | Polyline[];
+
+/**
+ * General-purpose geometry intersection dispatcher.
+ * Returns intersection curves (Polyline[]) or intersection points (Point[])
+ * depending on the input types.
+ */
+export function intersect(a: GeometryType, b: GeometryType): IntersectResult {
+  // Mesh + Plane
+  if (a instanceof Mesh && b instanceof Plane) return a.intersectPlane(b);
+  if (a instanceof Plane && b instanceof Mesh) return b.intersectPlane(a);
+
+  // Mesh + Mesh
+  if (a instanceof Mesh && b instanceof Mesh) return a.intersectMesh(b);
+
+  // NurbsCurve + Plane
+  if (a instanceof NurbsCurve && b instanceof Plane) return a.intersectPlane(b);
+  if (a instanceof Plane && b instanceof NurbsCurve) return b.intersectPlane(a);
+
+  // NurbsCurve + NurbsCurve
+  if (a instanceof NurbsCurve && b instanceof NurbsCurve) return a.intersectCurve(b);
+
+  // NurbsSurface + Plane
+  if (a instanceof NurbsSurface && b instanceof Plane) return a.intersectPlane(b);
+  if (a instanceof Plane && b instanceof NurbsSurface) return b.intersectPlane(a);
+
+  // NurbsSurface + NurbsSurface
+  if (a instanceof NurbsSurface && b instanceof NurbsSurface) return a.intersectSurface(b);
+
+  throw new Error(`Unsupported intersection: ${a.constructor.name} + ${b.constructor.name}`);
+}