@gridspace/raster-path 1.0.2

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014-Infinity Stewart Allen <sa@grid.space>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

package/README.md

@@ -0,0 +1,292 @@
+# Raster Path - WebGPU Toolpath Generator
+
+Fast browser-based terrain + tool path generator using WebGPU compute shaders.
+
+## Features
+
+- **Dual Mode Rasterization**: Planar (traditional XY grid) and Radial (cylindrical unwrap) modes
+- **CNC Toolpath Generation**: Generate toolpaths by simulating tool movement over terrain
+- **GPU Accelerated**: 20-100× faster than CPU-based solutions
+- **Unified API**: Clean three-method interface that works uniformly across both modes
+- **ESM Module**: Importable package for browser applications
+
+## Quick Start
+
+### As a Module
+
+```javascript
+import { RasterPath } from '@gridspace/raster-path';
+
+// Initialize for planar mode
+const raster = new RasterPath({
+    mode: 'planar',
+    resolution: 0.1  // 0.1mm grid resolution
+});
+await raster.init();
+
+// 1. Load tool (from STL triangles)
+const toolTriangles = parseSTL(toolSTLBuffer);
+const toolData = await raster.loadTool({
+    triangles: toolTriangles
+});
+
+// 2. Load terrain (rasterizes immediately in planar mode)
+const terrainTriangles = parseSTL(terrainSTLBuffer);
+const terrainData = await raster.loadTerrain({
+    triangles: terrainTriangles,
+    zFloor: -100
+});
+
+// 3. Generate toolpaths
+const toolpathData = await raster.generateToolpaths({
+    xStep: 5,    // Sample every 5th point in X
+    yStep: 5,    // Sample every 5th point in Y
+    zFloor: -100
+});
+
+console.log(`Generated ${toolpathData.pathData.length} toolpath points`);
+
+// Cleanup
+raster.terminate();
+```
+
+### Radial Mode (for cylindrical parts)
+
+```javascript
+// Initialize for radial mode
+const raster = new RasterPath({
+    mode: 'radial',
+    resolution: 0.1,      // Radial resolution (mm)
+    rotationStep: 1.0     // 1 degree between rays
+});
+await raster.init();
+
+// Load tool and terrain (same API!)
+await raster.loadTool({ triangles: toolTriangles });
+await raster.loadTerrain({
+    triangles: terrainTriangles,
+    zFloor: 0
+});
+
+// Generate toolpaths with radius offset
+const toolpathData = await raster.generateToolpaths({
+    xStep: 5,
+    yStep: 5,
+    zFloor: 0,
+    radiusOffset: 20  // Tool offset above surface (radial mode only)
+});
+
+// Output is array of strips (one per rotation angle)
+console.log(`Generated ${toolpathData.numStrips} strips, ${toolpathData.totalPoints} points`);
+```
+
+### Demo UI
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:3000 and drag STL files onto the interface.
+
+## Algorithm
+
+### Planar Mode (XY Grid Rasterization)
+
+1. **Tool Rasterization**: Create XY grid at specified resolution and rasterize tool geometry (keeps min Z per grid cell)
+2. **Terrain Rasterization**: Rasterize terrain geometry on matching XY grid (keeps max Z per grid cell)
+3. **Toolpath Generation**:
+   - Scan tool over terrain in XY grid with configurable step sizes (xStep, yStep)
+   - At each position, calculate minimum Z-offset where tool doesn't collide with terrain
+   - Output scanline-based toolpath as array of Z-heights
+
+### Radial Mode (Cylindrical Rasterization)
+
+1. **Tool Rasterization**: Rasterize tool in planar mode (same as above)
+2. **Terrain Preparation**: Center terrain in YZ plane and store triangles
+3. **Toolpath Generation**:
+   - Cast rays from origin at specified rotation angles (e.g., every 1°)
+   - For each ray, rasterize terrain triangles along that angle
+   - Use X-bucketing optimization to partition triangles spatially
+   - Calculate tool-terrain collisions along each radial strip
+   - Output array of strips (one per angle), each containing Z-heights along X-axis
+
+## Performance
+
+Example (84×84×28mm model, 6,120 triangles):
+
+| Step Size | Points  | WebGPU Time | CPU Time (WASM) |
+|-----------|---------|-------------|-----------------|
+| 0.5mm     | 48K     | 0.8s        | 20-80s          |
+| 0.1mm     | 1.2M    | 2s          | 280s            |
+
+**Speedup**: 20-100× faster with WebGPU
+
+## Project Structure
+
+```
+src/
+  index.js                    # Main RasterPath API (ESM export)
+  web/
+    webgpu-worker.js         # WebGPU worker (GPU compute shaders)
+    app.js                   # Demo web application
+    index.html               # Demo UI entry point
+    style.css                # Demo styles
+    parse-stl.js             # STL file parser utility
+  test/
+    planar-test.cjs          # Planar mode regression test
+    planar-tiling-test.cjs   # Planar high-resolution test
+    radial-test.cjs          # Radial mode regression test
+  benchmark/
+    fixtures/                # Test STL files (terrain.stl, tool.stl)
+build/                        # Built files (generated by npm run build)
+```
+
+## API Reference
+
+### `RasterPath`
+
+Constructor: `new RasterPath(options)`
+
+**Options**:
+- `mode` (string): `'planar'` or `'radial'`
+- `resolution` (number): Grid resolution in mm (e.g., 0.1)
+- `rotationStep` (number, radial only): Degrees between rays (e.g., 1.0)
+
+#### `async init()`
+Initialize WebGPU worker. Must be called before other methods.
+
+**Returns**: `Promise<void>`
+
+**Example**:
+```javascript
+const raster = new RasterPath({ mode: 'planar', resolution: 0.1 });
+await raster.init();
+```
+
+---
+
+#### `async loadTool({ triangles, sparseData })`
+Load tool geometry for toolpath generation.
+
+**Parameters** (one required):
+- `triangles` (Float32Array, optional): STL triangle data (9 floats per triangle: v0.xyz, v1.xyz, v2.xyz)
+- `sparseData` (object, optional): Pre-computed raster data with `{ bounds, positions, pointCount }`
+
+**Returns**: `Promise<object>` - Tool raster data with `{ bounds, positions, pointCount }`
+
+**Example**:
+```javascript
+// From STL triangles
+const toolData = await raster.loadTool({
+    triangles: toolTriangles
+});
+
+// From pre-computed sparse data (Kiri:Moto integration)
+const toolData = await raster.loadTool({
+    sparseData: { bounds, positions, pointCount }
+});
+```
+
+---
+
+#### `async loadTerrain({ triangles, zFloor, boundsOverride, onProgress })`
+Load terrain geometry. Behavior depends on mode:
+- **Planar mode**: Rasterizes immediately and returns terrain data
+- **Radial mode**: Stores triangles for later, returns `null`
+
+**Parameters**:
+- `triangles` (Float32Array): STL triangle data
+- `zFloor` (number, optional): Z floor value for out-of-bounds areas
+- `boundsOverride` (object, optional): Override bounding box `{min: {x, y, z}, max: {x, y, z}}`
+- `onProgress` (function, optional): Progress callback `(progress: number) => void`
+
+**Returns**:
+- Planar mode: `Promise<object>` - Terrain raster data with `{ bounds, positions, pointCount }`
+- Radial mode: `Promise<null>`
+
+**Example**:
+```javascript
+// Planar mode - returns terrain data immediately
+const terrainData = await raster.loadTerrain({
+    triangles: terrainTriangles,
+    zFloor: -100
+});
+
+// Radial mode - stores for later
+await raster.loadTerrain({
+    triangles: terrainTriangles,
+    zFloor: 0
+});
+```
+
+---
+
+#### `async generateToolpaths({ xStep, yStep, zFloor, radiusOffset, onProgress })`
+Generate toolpaths from loaded tool and terrain. Must call `loadTool()` and `loadTerrain()` first.
+
+**Parameters**:
+- `xStep` (number): Sample every Nth point in X direction
+- `yStep` (number): Sample every Nth point in Y direction
+- `zFloor` (number): Z floor value for out-of-bounds areas
+- `radiusOffset` (number, radial only): Tool offset above surface (mm)
+- `onProgress` (function, optional): Progress callback `(progress: number) => void`
+
+**Returns**:
+- Planar mode: `Promise<object>` with:
+  - `pathData` (Float32Array): Z-heights in scanline order
+  - `width` (number): Points per scanline
+  - `height` (number): Number of scanlines
+
+- Radial mode: `Promise<object>` with:
+  - `strips` (Array): Array of strip objects, each containing:
+    - `angle` (number): Rotation angle in degrees
+    - `pathData` (Float32Array): Z-heights along X-axis
+  - `numStrips` (number): Total number of strips
+  - `totalPoints` (number): Sum of all points across strips
+
+**Example**:
+```javascript
+// Works for both planar and radial modes!
+const toolpathData = await raster.generateToolpaths({
+    xStep: 5,
+    yStep: 5,
+    zFloor: -100,
+    radiusOffset: 20  // radial mode only
+});
+```
+
+---
+
+#### `terminate()`
+Terminate WebGPU worker and cleanup resources.
+
+**Example**:
+```javascript
+raster.terminate();
+```
+
+## Requirements
+
+- Modern browser with WebGPU support (Chrome 113+, Edge 113+)
+- For testing: Electron (provides headless WebGPU environment)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build (copies web files to build/)
+npm run build
+
+# Run demo
+npm run serve
+
+# Test
+npm test
+```
+
+## License
+
+MIT