@gridspace/raster-path 1.0.6 → 1.0.8

package/build/app.js

@@ -12,6 +12,7 @@ let zFloor = -100;
 let xStep = 5;
 let yStep = 5;
 let angleStep = 1.0; // degrees
+let traceStep = 0.5; // mm - sampling resolution for tracing mode
 let toolSize = 2.5; // mm - target tool diameter
 
 let modelSTL = null;  // ArrayBuffer (current, possibly rotated)
@@ -61,6 +62,7 @@ function saveParameters() {
     localStorage.setItem('raster-xStep', xStep);
     localStorage.setItem('raster-yStep', yStep);
     localStorage.setItem('raster-angleStep', angleStep);
+    localStorage.setItem('raster-traceStep', traceStep);
     localStorage.setItem('raster-toolSize', toolSize);
     console.log(`[App] Saved tool size: ${toolSize}mm`);
 
@@ -69,6 +71,12 @@ function saveParameters() {
     if (showWrappedCheckbox) {
         localStorage.setItem('raster-showWrapped', showWrappedCheckbox.checked);
     }
+
+    // Save radial V3 checkbox
+    const radialV3Checkbox = document.getElementById('radial-v3');
+    if (radialV3Checkbox) {
+        localStorage.setItem('raster-radialV3', radialV3Checkbox.checked);
+    }
 }
 
 function loadParameters() {
@@ -127,6 +135,12 @@ function loadParameters() {
         document.getElementById('angle-step').value = angleStep;
     }
 
+    const savedTraceStep = localStorage.getItem('raster-traceStep');
+    if (savedTraceStep !== null) {
+        traceStep = parseFloat(savedTraceStep);
+        document.getElementById('trace-step').value = traceStep;
+    }
+
     const savedToolSize = localStorage.getItem('raster-toolSize');
     if (savedToolSize !== null) {
         toolSize = parseFloat(savedToolSize);
@@ -145,6 +159,15 @@ function loadParameters() {
             showWrappedCheckbox.checked = savedShowWrapped === 'true';
         }
     }
+
+    // Restore radial V3 checkbox
+    const savedRadialV3 = localStorage.getItem('raster-radialV3');
+    if (savedRadialV3 !== null) {
+        const radialV3Checkbox = document.getElementById('radial-v3');
+        if (radialV3Checkbox) {
+            radialV3Checkbox.checked = savedRadialV3 === 'true';
+        }
+    }
 }
 
 // ============================================================================
@@ -513,10 +536,14 @@ async function initRasterPath() {
         rasterPath.terminate();
     }
 
+    const radialV3Checkbox = document.getElementById('radial-v3');
+    const useRadialV3 = mode === 'radial' && radialV3Checkbox && radialV3Checkbox.checked;
+
     rasterPath = new RasterPath({
         mode: mode,
         resolution: resolution,
         rotationStep: mode === 'radial' ? angleStep : undefined,
+        radialV3: useRadialV3,
         batchDivisor: 5,
         debug: true
     });
@@ -545,8 +572,8 @@ async function rasterizeAll() {
             updateInfo(`Tool loaded in ${(t1 - t0).toFixed(0)}ms`);
         }
 
-        if (mode === 'planar') {
-            // Planar mode: rasterize terrain immediately
+        if (mode === 'planar' || mode === 'tracing') {
+            // Planar/Tracing mode: rasterize terrain immediately
             if (modelTriangles) {
                 updateInfo('Rasterizing terrain...');
                 const t0 = performance.now();
@@ -557,7 +584,7 @@ async function rasterizeAll() {
                 const t1 = performance.now();
                 updateInfo(`Terrain rasterized in ${(t1 - t0).toFixed(0)}ms`);
             }
-        } else {
+        } else if (mode === 'radial') {
             // Radial mode: MUST load tool FIRST
             if (!toolTriangles) {
                 updateInfo('Error: Radial mode requires tool to be loaded first');
@@ -608,30 +635,81 @@ async function generateToolpath() {
             updateInfo('Model must be rasterized first');
             return;
         }
-    } else {
+    } else if (mode === 'radial') {
         // Radial mode: terrain must be loaded (stored internally)
         if (!modelTriangles) {
             updateInfo('Model STL must be loaded');
             return;
         }
+    } else if (mode === 'tracing') {
+        // Tracing mode: terrain must be rasterized
+        if (!modelRasterData) {
+            updateInfo('Model must be rasterized first');
+            return;
+        }
     }
 
     try {
         const t0 = performance.now();
         updateInfo('Generating toolpath...');
 
-        // Unified API - works for both modes!
-        toolpathData = await rasterPath.generateToolpaths({
-            xStep: xStep,
-            yStep: yStep,
+        // Generate trace paths for tracing mode
+        let tracePaths = null;
+        if (mode === 'tracing') {
+            // Get model bounds from raster data
+            const bounds = modelRasterData.bounds;
+            const minX = bounds.min.x;
+            const maxX = bounds.max.x;
+            const minY = bounds.min.y;
+            const maxY = bounds.max.y;
+
+            // Create two cross paths: horizontal through center, vertical through center
+            const centerY = (minY + maxY) / 2;
+            const centerX = (minX + maxX) / 2;
+
+            tracePaths = [
+                new Float32Array([minX, centerY, maxX, centerY]),  // Horizontal line
+                new Float32Array([centerX, minY, centerX, maxY])   // Vertical line
+            ];
+
+            debug.log(`Generated trace paths: H(${minX.toFixed(2)}, ${centerY.toFixed(2)}) to (${maxX.toFixed(2)}, ${centerY.toFixed(2)})`);
+            debug.log(`                        V(${centerX.toFixed(2)}, ${minY.toFixed(2)}) to (${centerX.toFixed(2)}, ${maxY.toFixed(2)})`);
+        }
+
+        // Unified API - works for all modes!
+        const generateParams = {
             zFloor: zFloor
-        });
+        };
+
+        if (mode === 'tracing') {
+            generateParams.paths = tracePaths;
+            generateParams.step = traceStep;
+        } else {
+            generateParams.xStep = xStep;
+            generateParams.yStep = yStep;
+        }
+
+        toolpathData = await rasterPath.generateToolpaths(generateParams);
 
         const t1 = performance.now();
 
         if (mode === 'planar') {
             const numPoints = toolpathData.pathData.length;
             updateInfo(`Toolpath generated: ${numPoints.toLocaleString()} points in ${(t1 - t0).toFixed(0)}ms`);
+        } else if (mode === 'tracing') {
+            const totalPoints = toolpathData.paths.reduce((sum, path) => sum + path.length / 3, 0);
+            debug.log(`[Tracing] Generated ${toolpathData.paths.length} paths with ${totalPoints} total points`);
+
+            // Log sample Z values from each path
+            toolpathData.paths.forEach((path, idx) => {
+                const zValues = [];
+                for (let i = 2; i < Math.min(path.length, 15); i += 3) {
+                    zValues.push(path[i].toFixed(2));
+                }
+                debug.log(`[Tracing] Path ${idx} Z samples:`, zValues.join(', '));
+            });
+
+            updateInfo(`Toolpath generated: ${toolpathData.paths.length} paths, ${totalPoints.toLocaleString()} points in ${(t1 - t0).toFixed(0)}ms`);
         } else {
             // debug.log('[Radial] Toolpaths generated:', toolpathData);
             debug.log(`[Radial] Received ${toolpathData.strips.length} strips from worker, numStrips=${toolpathData.numStrips}`);
@@ -901,8 +979,8 @@ function displayModelRaster(wrapped) {
     const positions = [];
     const colors = [];
 
-    if (mode === 'planar') {
-        // Planar: terrain is dense (Z-only array)
+    if (mode === 'planar' || mode === 'tracing') {
+        // Planar/Tracing: terrain is dense (Z-only array)
         const { positions: rasterPos, bounds, gridWidth, gridHeight } = modelRasterData;
         const stepSize = resolution;
 
@@ -1057,6 +1135,59 @@ function displayToolpaths(wrapped) {
         return;
     }
 
+    if (mode === 'tracing') {
+        // Tracing toolpaths - array of XYZ paths
+        const { paths } = toolpathData;
+
+        // Calculate total points
+        let totalPoints = 0;
+        for (const path of paths) {
+            totalPoints += path.length / 3;
+        }
+
+        debug.log('[Toolpath Display] Tracing mode:', paths.length, 'paths,', totalPoints, 'total points');
+
+        // Preallocate typed arrays
+        const positions = new Float32Array(totalPoints * 3);
+        const colors = new Float32Array(totalPoints * 3);
+
+        let arrayIdx = 0;
+        for (let pathIdx = 0; pathIdx < paths.length; pathIdx++) {
+            const path = paths[pathIdx];
+            const numPoints = path.length / 3;
+
+            // Use different colors for each path
+            const color = pathIdx === 0 ? [1, 0.4, 0] : [0, 0.8, 1]; // Orange for horizontal, cyan for vertical
+
+            for (let i = 0; i < numPoints; i++) {
+                positions[arrayIdx] = path[i * 3];       // X
+                positions[arrayIdx + 1] = path[i * 3 + 1]; // Y
+                positions[arrayIdx + 2] = path[i * 3 + 2]; // Z
+
+                colors[arrayIdx] = color[0];
+                colors[arrayIdx + 1] = color[1];
+                colors[arrayIdx + 2] = color[2];
+
+                arrayIdx += 3;
+            }
+        }
+
+        // Create geometry
+        const geometry = new THREE.BufferGeometry();
+        geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+        geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+
+        const material = new THREE.PointsMaterial({
+            size: resolution * 1.5,
+            vertexColors: true
+        });
+
+        toolpathPoints = new THREE.Points(geometry, material);
+        rotatedGroup.add(toolpathPoints);
+
+        return; // Exit early for tracing mode
+    }
+
     if (mode === 'planar') {
         // Planar toolpaths
         const { pathData, numScanlines, pointsPerLine } = toolpathData;
@@ -1324,15 +1455,35 @@ function updateButtonStates() {
 // ============================================================================
 
 function updateModeUI() {
-    // Show/hide wrapped toggle and angle step for radial mode
+    // Show/hide mode-specific controls
     const wrappedContainer = document.getElementById('wrapped-container').classList;
     const angleStepContainer = document.getElementById('angle-step-container').classList;
+    const traceStepContainer = document.getElementById('trace-step-container').classList;
+    const xStepContainer = document.getElementById('x-step-container').classList;
+    const yStepContainer = document.getElementById('y-step-container').classList;
+    const radialV3Container = document.getElementById('radial-v3-container').classList;
+
     if (mode === 'radial') {
         wrappedContainer.remove('hide');
         angleStepContainer.remove('hide');
+        traceStepContainer.add('hide');
+        xStepContainer.remove('hide');
+        yStepContainer.remove('hide');
+        radialV3Container.remove('hide');
+    } else if (mode === 'tracing') {
+        wrappedContainer.add('hide');
+        angleStepContainer.add('hide');
+        traceStepContainer.remove('hide');
+        xStepContainer.add('hide');
+        yStepContainer.add('hide');
     } else {
+        // planar
         wrappedContainer.add('hide');
         angleStepContainer.add('hide');
+        traceStepContainer.add('hide');
+        radialV3Container.add('hide');
+        xStepContainer.remove('hide');
+        yStepContainer.remove('hide');
     }
 }
 
@@ -1446,12 +1597,36 @@ document.addEventListener('DOMContentLoaded', async () => {
             modelRasterData = null;  // Need to re-rasterize with new angle step
             toolRasterData = null;
             toolpathData = null;
+            initRasterPath();  // Reinit with new angle step
         }
         saveParameters();
         updateInfo(`Angle Step changed to ${angleStep}°`);
         updateButtonStates();
     });
 
+    document.getElementById('trace-step').addEventListener('change', (e) => {
+        traceStep = parseFloat(e.target.value);
+        if (mode === 'tracing') {
+            toolpathData = null;  // Need to regenerate toolpath
+        }
+        saveParameters();
+        updateInfo(`Trace Step changed to ${traceStep}mm`);
+        updateButtonStates();
+    });
+
+    document.getElementById('radial-v3').addEventListener('change', (e) => {
+        if (mode === 'radial') {
+            modelRasterData = null;  // Need to re-rasterize with different algorithm
+            toolRasterData = null;
+            toolpathData = null;
+            initRasterPath();  // Reinit with V3 setting
+        }
+        saveParameters();
+        const v3Status = e.target.checked ? 'V3 (experimental)' : 'V2 (default)';
+        updateInfo(`Radial algorithm: ${v3Status}`);
+        updateButtonStates();
+    });
+
     // Tool size change
     document.getElementById('tool-size').addEventListener('change', async (e) => {
         toolSize = parseFloat(e.target.value);

package/build/index.html

@@ -53,6 +53,7 @@
                 <div class="mode-toggle">
                     <label><input type="radio" name="mode" value="planar" checked> Planar</label>
                     <label><input type="radio" name="mode" value="radial"> Radial</label>
+                    <label><input type="radio" name="mode" value="tracing"> Tracing</label>
                 </div>
             </div>
 
@@ -79,15 +80,21 @@
                 <label>
                     Z Floor: <input type="number" id="z-floor" value="-100" step="10" style="width: 70px;">
                 </label>
-                <label>
+                <label id="x-step-container">
                     X Step: <input type="number" id="x-step" value="5" min="1" max="50" style="width: 60px;">
                 </label>
-                <label>
+                <label id="y-step-container">
                     Y Step: <input type="number" id="y-step" value="5" min="1" max="50" style="width: 60px;">
                 </label>
                 <label id="angle-step-container" class="hide">
                     Angle Step (deg): <input type="number" id="angle-step" value="1" min="0.1" max="10" step="0.1" style="width: 60px;">
                 </label>
+                <label id="trace-step-container" class="hide">
+                    Trace Step (mm): <input type="number" id="trace-step" value="0.5" min="0.1" max="5" step="0.1" style="width: 60px;">
+                </label>
+                <label id="radial-v3-container" class="hide">
+                    <input type="checkbox" id="radial-v3"> Use V3 (experimental)
+                </label>
             </div>
 
             <div class="section">

package/build/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
@@ -111,6 +111,7 @@ export class RasterPath {
             gpuMemorySafetyMargin: config.gpuMemorySafetyMargin ?? 0.8,
             autoTiling: config.autoTiling ?? true,
             batchDivisor: config.batchDivisor ?? 1, // For testing batching overhead
+            radialV3: config.radialV3 ?? false, // Use radial V3 pipeline (rotate-filter-toolpath)
             debug: config.debug,
             quiet: config.quiet
         };
@@ -221,8 +222,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 +270,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 +279,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 +293,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 +307,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 +458,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);
 
@@ -422,9 +532,13 @@ export class RasterPath {
                 resolve(data);
             };
 
-            // Send entire pipeline to worker
+            // Send entire pipeline to worker (use V3 if configured)
+            const messageType = this.config.radialV3
+                ? 'radial-generate-toolpaths-v3'
+                : 'radial-generate-toolpaths';
+
             this.#sendMessage(
-                'radial-generate-toolpaths',
+                messageType,
                 {
                     triangles: triangles,
                     bucketData,