@gridspace/raster-path 1.0.5 → 1.0.7

package/src/core/raster-path.js

@@ -45,7 +45,7 @@
 /**
  * Configuration options for RasterPath
  * @typedef {Object} RasterPathConfig
- * @property {'planar'|'radial'} mode - Rasterization mode (default: 'planar')
+ * @property {'planar'|'radial'|'tracing'} mode - Rasterization mode (default: 'planar')
  * @property {boolean} autoTiling - Automatically tile large datasets (default: true)
  * @property {number} gpuMemorySafetyMargin - Safety margin as percentage (default: 0.8 = 80%)
  * @property {number} maxGPUMemoryMB - Maximum GPU memory per tile (default: 256MB)
@@ -80,8 +80,8 @@ export class RasterPath {
 
         // Validate mode
         const mode = config.mode || 'planar';
-        if (mode !== 'planar' && mode !== 'radial') {
-            throw new Error(`Invalid mode: ${mode}. Must be 'planar' or 'radial'`);
+        if (mode !== 'planar' && mode !== 'radial' && mode !== 'tracing') {
+            throw new Error(`Invalid mode: ${mode}. Must be 'planar', 'radial', or 'tracing'`);
         }
 
         // Validate rotationStep for radial mode
@@ -221,8 +221,8 @@ export class RasterPath {
             throw new Error('RasterPath not initialized. Call init() first.');
         }
 
-        if (this.mode === 'planar') {
-            // Planar: rasterize and return
+        if (this.mode === 'planar' || this.mode === 'tracing') {
+            // Planar/Tracing: rasterize and return (tracing reuses planar terrain rasterization)
             const terrainData = await this.#rasterizePlanar({ triangles, zFloor, boundsOverride, isForTool: false, onProgress });
             this.terrainData = terrainData;
             return terrainData;
@@ -269,7 +269,7 @@ export class RasterPath {
      * @param {function} params.onProgress - Optional progress callback (progress: number, info?: string) => void
      * @returns {Promise<object>} Planar: {pathData, width, height} | Radial: {strips[], numStrips, totalPoints}
      */
-    async generateToolpaths({ xStep, yStep, zFloor, onProgress }) {
+    async generateToolpaths({ xStep, yStep, zFloor, onProgress, paths, step }) {
         if (!this.isInitialized) {
             throw new Error('RasterPath not initialized. Call init() first.');
         }
@@ -278,7 +278,7 @@ export class RasterPath {
             throw new Error('Tool not loaded. Call loadTool() first.');
         }
 
-        debug.log('gen.paths', { xStep, yStep, zFloor });
+        debug.log('gen.paths', { xStep, yStep, zFloor, paths: paths?.length, step });
 
         if (this.mode === 'planar') {
             if (!this.terrainData) {
@@ -292,7 +292,7 @@ export class RasterPath {
                 zFloor,
                 onProgress
             });
-        } else {
+        } else if (this.mode === 'radial') {
             // Radial mode: use stored triangles
             if (!this.terrainTriangles) {
                 throw new Error('Terrain not loaded. Call loadTerrain() first.');
@@ -306,14 +306,83 @@ export class RasterPath {
                 zFloor: zFloor ?? this.terrainZFloor,
                 onProgress
             });
+        } else if (this.mode === 'tracing') {
+            // Tracing mode: follow input paths
+            if (!this.terrainData) {
+                throw new Error('Terrain not loaded. Call loadTerrain() first.');
+            }
+            if (!paths || paths.length === 0) {
+                throw new Error('Tracing mode requires paths parameter (array of Float32Array XY coordinates)');
+            }
+            if (!step || step <= 0) {
+                throw new Error('Tracing mode requires step parameter (sampling resolution in world units)');
+            }
+            return this.#generateToolpathsTracing({
+                paths,
+                step,
+                zFloor,
+                onProgress
+            });
+        }
+    }
+
+    /**
+     * Create reusable GPU buffers for tracing mode (optimization for iterative tracing)
+     * Call this after loadTerrain() and loadTool() to cache buffers across multiple trace calls
+     * @returns {Promise<void>}
+     */
+    async createTracingBuffers() {
+        if (this.mode !== 'tracing') {
+            throw new Error('createTracingBuffers() only available in tracing mode');
         }
+        if (!this.terrainData || !this.toolData) {
+            throw new Error('Must call loadTerrain() and loadTool() before createTracingBuffers()');
+        }
+
+        return new Promise((resolve, reject) => {
+            const handler = () => resolve();
+            this.#sendMessage(
+                'create-tracing-buffers',
+                {
+                    terrainPositions: this.terrainData.positions,
+                    toolPositions: this.toolData.positions
+                },
+                'tracing-buffers-created',
+                handler
+            );
+        });
+    }
+
+    /**
+     * Destroy reusable tracing buffers
+     * @returns {Promise<void>}
+     */
+    async destroyTracingBuffers() {
+        if (this.mode !== 'tracing') {
+            return; // No-op for non-tracing modes
+        }
+
+        return new Promise((resolve, reject) => {
+            const handler = () => resolve();
+            this.#sendMessage(
+                'destroy-tracing-buffers',
+                {},
+                'tracing-buffers-destroyed',
+                handler
+            );
+        });
     }
 
     /**
      * Terminate worker and cleanup resources
      */
-    terminate() {
+    async terminate() {
         if (this.worker) {
+            // Cleanup tracing buffers if in tracing mode
+            if (this.mode === 'tracing') {
+                await this.destroyTracingBuffers();
+            }
+
             this.worker.terminate();
             this.worker = null;
             this.isInitialized = false;
@@ -388,6 +457,46 @@ export class RasterPath {
         });
     }
 
+    async #generateToolpathsTracing({ paths, step, zFloor, onProgress }) {
+        return new Promise((resolve, reject) => {
+            // Set up progress handler if callback provided
+            if (onProgress) {
+                const progressHandler = (data) => {
+                    onProgress(data.percent, { current: data.current, total: data.total, pathIndex: data.pathIndex });
+                };
+                this.messageHandlers.set('tracing-progress', progressHandler);
+            }
+
+            const handler = (data) => {
+                // Clean up progress handler
+                if (onProgress) {
+                    this.messageHandlers.delete('tracing-progress');
+                }
+                resolve(data);
+            };
+
+            this.#sendMessage(
+                'tracing-generate-toolpaths',
+                {
+                    paths,
+                    terrainPositions: this.terrainData.positions,
+                    terrainData: {
+                        width: this.terrainData.gridWidth,
+                        height: this.terrainData.gridHeight,
+                        bounds: this.terrainData.bounds
+                    },
+                    toolPositions: this.toolData.positions,
+                    step,
+                    gridStep: this.resolution,
+                    terrainBounds: this.terrainData.bounds,
+                    zFloor: zFloor ?? 0
+                },
+                'tracing-toolpaths-complete',
+                handler
+            );
+        });
+    }
+
     async #generateToolpathsRadial({ triangles, bounds, toolData, xStep, yStep, zFloor, onProgress }) {
         const maxRadius = this.#calculateMaxRadius(triangles);
 

package/src/core/raster-worker.js

@@ -54,6 +54,7 @@ import { initWebGPU, setConfig, updateConfig, deviceCapabilities, debug, device
 import { rasterizeMesh } from './raster-planar.js';
 import { generateToolpath } from './path-planar.js';
 import { generateRadialToolpaths } from './path-radial.js';
+import { generateTracingToolpaths, createReusableTracingBuffers, destroyReusableTracingBuffers } from './path-tracing.js';
 import { calibrateGPU } from './workload-calibrate.js';
 
 // Global error handler for uncaught errors in worker
@@ -127,6 +128,46 @@ self.onmessage = async function(e) {
                 }, toolpathTransferBuffers);
                 break;
 
+            case 'tracing-generate-toolpaths':
+                const tracingResult = await generateTracingToolpaths({
+                    paths: data.paths,
+                    terrainPositions: data.terrainPositions,
+                    terrainData: data.terrainData,
+                    toolPositions: data.toolPositions,
+                    step: data.step,
+                    gridStep: data.gridStep,
+                    terrainBounds: data.terrainBounds,
+                    zFloor: data.zFloor,
+                    onProgress: (progressData) => {
+                        self.postMessage({
+                            type: 'tracing-progress',
+                            data: progressData.data
+                        });
+                    }
+                });
+                const tracingTransferBuffers = tracingResult.paths.map(p => p.buffer);
+                self.postMessage({
+                    type: 'tracing-toolpaths-complete',
+                    data: tracingResult
+                }, tracingTransferBuffers);
+                break;
+
+            case 'create-tracing-buffers':
+                createReusableTracingBuffers(data.terrainPositions, data.toolPositions);
+                self.postMessage({
+                    type: 'tracing-buffers-created',
+                    data: { success: true }
+                });
+                break;
+
+            case 'destroy-tracing-buffers':
+                destroyReusableTracingBuffers();
+                self.postMessage({
+                    type: 'tracing-buffers-destroyed',
+                    data: { success: true }
+                });
+                break;
+
             case 'calibrate':
                 const calibrationResult = await calibrateGPU(device, data?.options || {});
                 self.postMessage({

package/src/core/workload-calibrate.js

@@ -114,18 +114,72 @@ async function testWorkloadDispatch(device, pipeline, workgroupSize, triangleTes
     passEncoder.dispatchWorkgroups(dispatchX, dispatchY, 1);
     passEncoder.end();
 
-    // Readback
+    // Submit the compute work
+    device.queue.submit([commandEncoder.finish()]);
+
+    // TEST: Queue progress checkpoints while GPU works
+    const numCheckpoints = 5;
+    const checkpointInterval = 100; // ms
+    const progressSnapshots = [];
+
+    for (let i = 0; i < numCheckpoints; i++) {
+        await new Promise(resolve => setTimeout(resolve, checkpointInterval));
+
+        const checkpointStart = performance.now();
+
+        // Queue a copy to read progress
+        const checkpointEncoder = device.createCommandEncoder();
+        const checkpointStaging = device.createBuffer({
+            size: totalThreads * 4,
+            usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+        });
+
+        checkpointEncoder.copyBufferToBuffer(completionBuffer, 0, checkpointStaging, 0, totalThreads * 4);
+        device.queue.submit([checkpointEncoder.finish()]);
+
+        // Wait for this checkpoint copy to complete
+        await checkpointStaging.mapAsync(GPUMapMode.READ);
+        const checkpointElapsed = performance.now() - checkpointStart;
+
+        // Count completed threads
+        const checkpointData = new Uint32Array(checkpointStaging.getMappedRange());
+        let completedThreads = 0;
+        for (let j = 0; j < totalThreads; j++) {
+            if (checkpointData[j] === 1) completedThreads++;
+        }
+
+        progressSnapshots.push({
+            checkpoint: i + 1,
+            timeMs: Math.round(performance.now() - startTime),
+            completedThreads,
+            totalThreads,
+            percentComplete: Math.round((completedThreads / totalThreads) * 100),
+            checkpointLatencyMs: checkpointElapsed.toFixed(2)
+        });
+
+        checkpointStaging.unmap();
+        checkpointStaging.destroy();
+    }
+
+    // Final readback
     const stagingBuffer = device.createBuffer({
         size: totalThreads * 4,
         usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
     });
 
-    commandEncoder.copyBufferToBuffer(completionBuffer, 0, stagingBuffer, 0, totalThreads * 4);
-    device.queue.submit([commandEncoder.finish()]);
+    const finalEncoder = device.createCommandEncoder();
+    finalEncoder.copyBufferToBuffer(completionBuffer, 0, stagingBuffer, 0, totalThreads * 4);
+    device.queue.submit([finalEncoder.finish()]);
 
     await device.queue.onSubmittedWorkDone();
     const elapsed = performance.now() - startTime;
 
+    // Log progress snapshots
+    if (progressSnapshots.length > 0) {
+        console.log('\n📊 Progress Checkpoints:');
+        console.table(progressSnapshots);
+    }
+
     await stagingBuffer.mapAsync(GPUMapMode.READ);
     const completionData = new Uint32Array(stagingBuffer.getMappedRange());
     const completionCopy = new Uint32Array(completionData);

package/src/shaders/tracing-toolpath.wgsl

@@ -0,0 +1,95 @@
+// Tracing toolpath generation
+// Follows input polylines and calculates Z-depth at each sampled point
+// Sentinel value for empty terrain cells (must match rasterize shader)
+const EMPTY_CELL: f32 = -1e10;
+const MAX_F32: f32 = 3.402823466e+38;
+
+struct SparseToolPoint {
+    x_offset: i32,
+    y_offset: i32,
+    z_value: f32,
+    padding: f32,
+}
+
+struct Uniforms {
+    terrain_width: u32,
+    terrain_height: u32,
+    tool_count: u32,
+    point_count: u32,        // Number of sampled points to process
+    path_index: u32,         // Index of current path being processed
+    terrain_min_x: f32,      // Terrain bounding box (world coordinates)
+    terrain_min_y: f32,
+    grid_step: f32,          // Resolution of terrain rasterization
+    oob_z: f32,              // Z value for out-of-bounds points (zFloor)
+}
+
+@group(0) @binding(0) var<storage, read> terrain_map: array<f32>;
+@group(0) @binding(1) var<storage, read> sparse_tool: array<SparseToolPoint>;
+@group(0) @binding(2) var<storage, read> input_points: array<f32>;  // XY pairs
+@group(0) @binding(3) var<storage, read_write> output_depths: array<f32>;  // Z values
+@group(0) @binding(4) var<storage, read_write> max_z_buffer: array<atomic<i32>>;  // Max Z per path (as bits)
+@group(0) @binding(5) var<uniform> uniforms: Uniforms;
+
+@compute @workgroup_size(64, 1, 1)
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let point_idx = global_id.x;
+
+    if (point_idx >= uniforms.point_count) {
+        return;
+    }
+
+    // Read input X,Y world coordinates
+    let world_x = input_points[point_idx * 2u + 0u];
+    let world_y = input_points[point_idx * 2u + 1u];
+
+    // Convert world coordinates to grid coordinates
+    let grid_x_f32 = (world_x - uniforms.terrain_min_x) / uniforms.grid_step;
+    let grid_y_f32 = (world_y - uniforms.terrain_min_y) / uniforms.grid_step;
+    let tool_center_x = i32(grid_x_f32);
+    let tool_center_y = i32(grid_y_f32);
+
+    // Check if tool center is outside terrain bounds
+    let center_oob = tool_center_x < 0 || tool_center_x >= i32(uniforms.terrain_width) ||
+                     tool_center_y < 0 || tool_center_y >= i32(uniforms.terrain_height);
+
+    var max_collision_z = uniforms.oob_z;
+    var found_collision = false;
+
+    // Test each tool point for collision with terrain
+    for (var i = 0u; i < uniforms.tool_count; i++) {
+        let tool_point = sparse_tool[i];
+        let terrain_x = tool_center_x + tool_point.x_offset;
+        let terrain_y = tool_center_y + tool_point.y_offset;
+
+        // Bounds check: terrain sample must be within terrain grid
+        if (terrain_x < 0 || terrain_x >= i32(uniforms.terrain_width) ||
+            terrain_y < 0 || terrain_y >= i32(uniforms.terrain_height)) {
+            continue;
+        }
+
+        let terrain_idx = u32(terrain_y) * uniforms.terrain_width + u32(terrain_x);
+        let terrain_z = terrain_map[terrain_idx];
+
+        // Check if terrain cell has geometry (not empty sentinel value)
+        if (terrain_z > EMPTY_CELL + 1.0) {
+            // Tool z_value is positive offset from tip (tip=0, shaft=+50)
+            // Add to terrain height to find where tool center needs to be
+            let collision_z = terrain_z + tool_point.z_value;
+            max_collision_z = max(max_collision_z, collision_z);
+            found_collision = true;
+        }
+    }
+
+    // If no collision found and center was in-bounds, use oob_z
+    var output_z = uniforms.oob_z;
+    if (found_collision) {
+        output_z = max_collision_z;
+    }
+
+    output_depths[point_idx] = output_z;
+
+    // Update max Z for this path using atomic operation
+    // Convert float to int bits for atomic comparison
+    let z_bits = bitcast<i32>(output_z);
+    atomicMax(&max_z_buffer[uniforms.path_index], z_bits);
+}