okgeometry-api 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okgeometry-api",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Geometry engine API for AEC applications — NURBS, meshes, booleans, intersections. Powered by Rust/WASM.",
   "type": "module",
   "main": "dist/index.js",

package/wasm/README.md

@@ -0,0 +1,102 @@
+# OkGeometryCore
+
+A production-grade geometry engine written in Rust, compiled to WebAssembly. Built for [OkNodes](https://orkestra.online), a visual programming tool for the AEC (Architecture, Engineering, Construction) industry.
+
+## Features
+
+### Mesh Primitives
+- Box, Cylinder, Sphere, Prism, Cone, Torus
+
+### Mesh Operations
+- **Transforms** - translate, rotate, scale, mirror, arbitrary matrix
+- **Extrude** - linear extrusion with optional end caps
+- **Loft** - surface generation between multiple curves
+- **Sweep** - curve along path
+- **Boolean** - union, intersection, subtraction (~95% reliable on manifold meshes)
+- **Subdivision** - Catmull-Clark (quad meshes) and Loop (triangle meshes)
+- **Offset / Shell** - inward/outward mesh offset
+- **Bevel / Chamfer** - flat bevel on all edges or selected edges
+- **Triangulation** - ear clipping and fan triangulation
+
+### Curve Primitives
+- Line, Arc, Circle, Polyline, Polycurve (mixed segments)
+
+### Curve Operations
+- Evaluate, tangent, length, closest point, bounds
+- Chamfer corners, fillet corners (arc), offset polyline
+
+### Intersection
+- Line-Line, Line-Plane, Line-Circle, Circle-Circle
+- Ray-Mesh (BVH-accelerated), closest point on mesh
+
+### Spatial Indexing
+- BVH (Bounding Volume Hierarchy) for O(log n) ray casting and proximity queries
+
+### I/O
+- OBJ import/export
+
+## Architecture
+
+```
+OkNodes (TypeScript)
+  |  ArrayBuffer / TypedArray
+  v
+OkGeometryCore (Rust -> WASM)
+  |- math/          Vector3, Matrix4, Quaternion, Plane, Ray, AABB
+  |- curves/        Line, Arc, Circle, Polyline, Polycurve
+  |- intersection/  Curve-curve intersections
+  |- mesh/          Half-edge data structure, primitives
+  |- ops/           Boolean, extrude, loft, sweep, subdivide, bevel...
+  |- spatial/       BVH, ray casting, closest point
+  |- io/            OBJ format
+```
+
+The engine uses an **index-based half-edge mesh** data structure for cache-friendly traversal and easy WASM serialization. All data crosses the WASM boundary as flat typed arrays to minimize overhead.
+
+## Building
+
+### Prerequisites
+- [Rust](https://rustup.rs/)
+- [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/)
+
+### Build WASM
+```bash
+wasm-pack build --target web
+```
+
+### Run tests
+```bash
+cargo test
+```
+
+### Viewer
+The `okgeometry-viewer/` directory contains interactive Three.js viewers for visual verification:
+
+```bash
+# Serve the viewer directory with any static file server, e.g.:
+npx serve okgeometry-viewer
+```
+
+Available viewers:
+- **Curves** - Line, Circle, Arc, Polyline visualization
+- **Intersections** - All curve-curve intersection scenarios
+- **Meshes** - Primitives, wireframe, OBJ import/export
+- **Booleans** - Union, intersection, subtraction with position controls
+- **Subdivision** - Catmull-Clark and Loop with iteration slider
+- **Ray Casting** - Interactive ray cast and closest point queries
+- **Bevel / Chamfer** - Flat bevel on box, cylinder, prism
+
+## Dependencies
+
+| Crate | Purpose |
+|-------|---------|
+| `wasm-bindgen` | Rust-WASM interop |
+| `js-sys` / `web-sys` | Browser API access |
+| `robust` | Exact geometric predicates (orient2d, orient3d, incircle) |
+| `spade` | Constrained Delaunay triangulation |
+| `serde` | Serialization |
+| `nalgebra` | Linear algebra (optional feature) |
+
+## License
+
+Copyright Mostafa El Ayoubi / Orkestra Online. All rights reserved.

package/wasm/okgeometrycore.d.ts

@@ -0,0 +1,286 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Get the length of an arc.
+ */
+export function arc_length(radius: number, start_angle: number, end_angle: number): number;
+
+/**
+ * Evaluate a point on an arc at parameter t ∈ [0,1].
+ * Returns [x, y, z].
+ */
+export function arc_point_at(cx: number, cy: number, cz: number, nx: number, ny: number, nz: number, radius: number, start_angle: number, end_angle: number, t: number): Float64Array;
+
+/**
+ * Get the circumference of a circle.
+ */
+export function circle_length(radius: number): number;
+
+/**
+ * Evaluate a point on a circle at parameter t ∈ [0,1].
+ * Returns [x, y, z].
+ */
+export function circle_point_at(cx: number, cy: number, cz: number, nx: number, ny: number, nz: number, radius: number, t: number): Float64Array;
+
+/**
+ * Create an arc and return sampled points
+ */
+export function create_arc(cx: number, cy: number, cz: number, nx: number, ny: number, nz: number, radius: number, start_angle: number, end_angle: number, samples: number): Float64Array;
+
+/**
+ * Create a circle and return sampled points
+ */
+export function create_circle(cx: number, cy: number, cz: number, nx: number, ny: number, nz: number, radius: number, samples: number): Float64Array;
+
+/**
+ * Create a line segment and return sampled points
+ */
+export function create_line(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number, samples: number): Float64Array;
+
+/**
+ * Create a polyline and return the points
+ */
+export function create_polyline(coords: Float64Array, samples_per_segment: number): Float64Array;
+
+/**
+ * Serialize a curve to a list of points for Three.js rendering
+ * Returns a flat array of coordinates: [x1, y1, z1, x2, y2, z2, ...]
+ */
+export function curve_to_points(curve_type: string, params: Float64Array, samples: number): Float64Array;
+
+/**
+ * Extrude a circle and return mesh buffers
+ */
+export function extrude_circle(cx: number, cy: number, cz: number, nx: number, ny: number, nz: number, radius: number, dx: number, dy: number, dz: number, segments: number, with_caps: boolean): Float64Array;
+
+/**
+ * Extrude a line segment and return mesh buffers
+ */
+export function extrude_line(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number, dx: number, dy: number, dz: number, segments: number): Float64Array;
+
+/**
+ * Extrude a polyline and return mesh buffers
+ */
+export function extrude_polyline(coords: Float64Array, dx: number, dy: number, dz: number, segments: number, with_caps: boolean): Float64Array;
+
+/**
+ * Get the length of a line segment.
+ */
+export function line_length(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number): number;
+
+/**
+ * Evaluate a point on a line segment at parameter t ∈ [0,1].
+ * Returns [x, y, z].
+ */
+export function line_point_at(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number, t: number): Float64Array;
+
+/**
+ * Get the tangent direction of a line segment. Returns [x, y, z].
+ */
+export function line_tangent(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number): Float64Array;
+
+/**
+ * Loft between multiple circles
+ *
+ * # Parameters
+ * * `circle_data` - Flat array of circle definitions [cx, cy, cz, nx, ny, nz, radius, ...]
+ * * `segments` - Number of segments to sample along each curve
+ * * `with_caps` - Whether to create end caps
+ *
+ * # Returns
+ * Mesh buffers for the lofted surface
+ */
+export function loft_circles(circle_data: Float64Array, segments: number, with_caps: boolean): Float64Array;
+
+/**
+ * Loft between multiple polylines
+ *
+ * # Parameters
+ * * `polyline_data` - Flat array where each polyline is prefixed by its point count:
+ *   [count1, x1, y1, z1, x2, y2, z2, ..., count2, x1, y1, z1, ...]
+ * * `segments` - Number of segments to sample along each curve
+ * * `with_caps` - Whether to create end caps
+ *
+ * # Returns
+ * Mesh buffers for the lofted surface
+ */
+export function loft_polylines(polyline_data: Float64Array, segments: number, with_caps: boolean): Float64Array;
+
+/**
+ * Perform boolean intersection on two meshes
+ */
+export function mesh_boolean_intersection(vertex_count_a: number, buffer_a: Float64Array, vertex_count_b: number, buffer_b: Float64Array): Float64Array;
+
+/**
+ * Perform boolean operation on two meshes
+ *
+ * # Parameters
+ * * `vertex_count_a` - Number of vertices in mesh A
+ * * `buffer_a` - Buffer for mesh A [vertices..., indices...]
+ * * `vertex_count_b` - Number of vertices in mesh B
+ * * `buffer_b` - Buffer for mesh B [vertices..., indices...]
+ * * `operation` - Operation type: "union", "intersection", or "subtraction"
+ *
+ * # Returns
+ * Result mesh buffer [vertices..., indices...]
+ */
+export function mesh_boolean_operation(vertex_count_a: number, buffer_a: Float64Array, vertex_count_b: number, buffer_b: Float64Array, operation: string): Float64Array;
+
+/**
+ * Perform boolean subtraction on two meshes (A - B)
+ */
+export function mesh_boolean_subtraction(vertex_count_a: number, buffer_a: Float64Array, vertex_count_b: number, buffer_b: Float64Array): Float64Array;
+
+/**
+ * Perform boolean union on two meshes
+ */
+export function mesh_boolean_union(vertex_count_a: number, buffer_a: Float64Array, vertex_count_b: number, buffer_b: Float64Array): Float64Array;
+
+/**
+ * Chamfer all edges of a primitive mesh (flat bevel)
+ *
+ * # Arguments
+ * * `mesh_type` - "box", "cylinder", or "prism"
+ * * `params` - Parameters: [width,height,depth] for box, [radius,height,segments] for cylinder/prism
+ * * `offset` - Chamfer offset distance
+ *
+ * # Returns
+ * Result mesh buffer [vertexCount, vertices..., indices...]
+ */
+export function mesh_chamfer_all_edges(mesh_type: string, params: Float64Array, offset: number): Float64Array;
+
+/**
+ * Create a box mesh and return buffers
+ * Returns [vertices..., indices...]
+ */
+export function mesh_create_box(width: number, height: number, depth: number): Float64Array;
+
+/**
+ * Create a cone mesh and return buffers
+ */
+export function mesh_create_cone(radius: number, height: number, segments: number): Float64Array;
+
+/**
+ * Create a cylinder mesh and return buffers
+ */
+export function mesh_create_cylinder(radius: number, height: number, segments: number): Float64Array;
+
+/**
+ * Create a prism mesh and return buffers
+ */
+export function mesh_create_prism(radius: number, height: number, sides: number): Float64Array;
+
+/**
+ * Create a sphere mesh and return buffers
+ */
+export function mesh_create_sphere(radius: number, segments: number, rings: number): Float64Array;
+
+/**
+ * Export a mesh to OBJ format
+ * Takes mesh buffers as input (same format as mesh_to_buffers output)
+ * Returns OBJ string
+ */
+export function mesh_export_obj(vertex_count: number, buffer: Float64Array): string;
+
+/**
+ * Get mesh statistics
+ * Returns [vertex_count, face_count, edge_count]
+ */
+export function mesh_get_stats(vertex_count: number, buffer: Float64Array): Float64Array;
+
+/**
+ * Import OBJ data and return mesh buffers
+ */
+export function mesh_import_obj(obj_data: string): Float64Array;
+
+/**
+ * Intersect two meshes, returning intersection polyline points.
+ * Returns: [num_polylines, n1, x,y,z,..., n2, x,y,z,...]
+ */
+export function mesh_mesh_intersect(va_count: number, buffer_a: Float64Array, vb_count: number, buffer_b: Float64Array): Float64Array;
+
+/**
+ * Intersect a mesh with a plane, returning polyline points.
+ * Input: vertex_count, mesh_buffer..., nx, ny, nz, d
+ * Returns: [num_polylines, n1, x,y,z,..., n2, x,y,z,...]
+ */
+export function mesh_plane_intersect(vertex_count: number, buffer: Float64Array, nx: number, ny: number, nz: number, d: number): Float64Array;
+
+/**
+ * Rotate a mesh around an arbitrary axis and return new buffers
+ * Axis is defined by (ax, ay, az), angle in radians
+ */
+export function mesh_rotate(vertex_count: number, buffer: Float64Array, ax: number, ay: number, az: number, angle: number): Float64Array;
+
+/**
+ * Scale a mesh non-uniformly and return new buffers
+ */
+export function mesh_scale(vertex_count: number, buffer: Float64Array, sx: number, sy: number, sz: number): Float64Array;
+
+/**
+ * Translate a mesh by an offset vector and return new buffers
+ */
+export function mesh_translate(vertex_count: number, buffer: Float64Array, dx: number, dy: number, dz: number): Float64Array;
+
+/**
+ * Intersect two NURBS curves.
+ * Returns: [num_points, x,y,z, ...]
+ */
+export function nurbs_curve_curve_intersect(data_a: Float64Array, data_b: Float64Array): Float64Array;
+
+/**
+ * Intersect a NURBS curve with a plane.
+ * Input: same curve format as sample_nurbs_curve + plane normal (nx,ny,nz) and d.
+ * Returns: [num_points, x,y,z, x,y,z, ...]
+ */
+export function nurbs_curve_plane_intersect(data: Float64Array, nx: number, ny: number, nz: number, d: number): Float64Array;
+
+/**
+ * Intersect a NURBS surface with a plane.
+ * Input: same surface format as tessellate_nurbs_surface, then plane (nx,ny,nz,d) appended.
+ * Returns polyline buffer: [num_polylines, n1, x,y,z,..., n2, x,y,z,...]
+ */
+export function nurbs_surface_plane_intersect(surface_data: Float64Array, nx: number, ny: number, nz: number, d: number, tess: number): Float64Array;
+
+/**
+ * Intersect two NURBS surfaces.
+ * Returns polyline buffer.
+ */
+export function nurbs_surface_surface_intersect(data_a: Float64Array, data_b: Float64Array, tess: number): Float64Array;
+
+/**
+ * Get the total length of a polyline.
+ * Input: flat coords [x1,y1,z1, x2,y2,z2, ...]
+ */
+export function polyline_length(coords: Float64Array): number;
+
+/**
+ * Evaluate a point on a polyline at parameter t ∈ [0,1].
+ * Input: flat coords [x1,y1,z1, x2,y2,z2, ...]
+ * Returns [x, y, z].
+ */
+export function polyline_point_at(coords: Float64Array, t: number): Float64Array;
+
+/**
+ * Sample a NURBS curve.
+ * Input: degree, then flat control points [x,y,z,...], then flat weights, then flat knots
+ * Format: [degree, num_pts, x0,y0,z0, ..., w0,w1,..., k0,k1,...]
+ */
+export function sample_nurbs_curve(data: Float64Array, samples: number): Float64Array;
+
+/**
+ * Tessellate a NURBS surface to a mesh buffer.
+ * Input format: [degree_u, degree_v, num_u, num_v, ...control_points(flat)..., ...weights(flat)..., ...knots_u..., ...knots_v..., u_segs, v_segs]
+ */
+export function tessellate_nurbs_surface(data: Float64Array): Float64Array;
+
+/**
+ * Simple test function to verify WASM is working
+ */
+export function test_wasm(): string;
+
+/**
+ * Get version info
+ */
+export function version(): string;

package/wasm/okgeometrycore.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./okgeometrycore.d.ts" */
+
+import * as wasm from "./okgeometrycore_bg.wasm";
+import { __wbg_set_wasm } from "./okgeometrycore_bg.js";
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    arc_length, arc_point_at, circle_length, circle_point_at, create_arc, create_circle, create_line, create_polyline, curve_to_points, extrude_circle, extrude_line, extrude_polyline, line_length, line_point_at, line_tangent, loft_circles, loft_polylines, mesh_boolean_intersection, mesh_boolean_operation, mesh_boolean_subtraction, mesh_boolean_union, mesh_chamfer_all_edges, mesh_create_box, mesh_create_cone, mesh_create_cylinder, mesh_create_prism, mesh_create_sphere, mesh_export_obj, mesh_get_stats, mesh_import_obj, mesh_mesh_intersect, mesh_plane_intersect, mesh_rotate, mesh_scale, mesh_translate, nurbs_curve_curve_intersect, nurbs_curve_plane_intersect, nurbs_surface_plane_intersect, nurbs_surface_surface_intersect, polyline_length, polyline_point_at, sample_nurbs_curve, tessellate_nurbs_surface, test_wasm, version
+} from "./okgeometrycore_bg.js";

package/wasm/okgeometrycore_bg.d.ts

@@ -0,0 +1,3 @@
+/* Auto-generated type declarations for okgeometrycore_bg.js */
+export * from "./okgeometrycore.js";
+export function __wbg_set_wasm(val: any): void;