@gridspace/raster-path 1.0.3 → 1.0.5

package/src/core/raster-config.js

@@ -0,0 +1,185 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * Raster Config - Shared WebGPU State and Configuration
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Central module providing shared state, configuration, and utilities for all
+ * worker modules. All WebGPU resources and pipelines are initialized here.
+ *
+ * EXPORTS:
+ * ────────
+ * State Variables:
+ *   - config              - Worker configuration (memory limits, tiling, etc.)
+ *   - device              - WebGPU device handle
+ *   - deviceCapabilities  - Device limits and capabilities
+ *   - isInitialized       - Initialization status flag
+ *
+ * Cached Pipelines:
+ *   - cachedRasterizePipeline      - Planar rasterization compute pipeline
+ *   - cachedToolpathPipeline       - Planar toolpath generation pipeline
+ *   - cachedRadialBatchPipeline    - Radial rasterization pipeline
+ *   - cachedRasterizeShaderModule  - Compiled planar rasterize shader
+ *   - cachedToolpathShaderModule   - Compiled planar toolpath shader
+ *   - cachedRadialBatchShaderModule - Compiled radial shader
+ *
+ * Constants:
+ *   - EMPTY_CELL    - Sentinel value for empty raster cells (-1e10)
+ *   - log_pre       - Log prefix string "[Worker]"
+ *   - diagnostic    - Debug mode flag
+ *
+ * Utilities:
+ *   - debug         - Logging object (error, warn, log, ok)
+ *   - round(v, d)   - Round number to d decimal places
+ *
+ * Functions:
+ *   - initWebGPU()         - Initialize WebGPU device and compile pipelines
+ *   - setConfig(obj)       - Replace entire config object
+ *   - updateConfig(obj)    - Merge updates into existing config
+ *
+ * ARCHITECTURE:
+ * ─────────────
+ * This module acts as a singleton state container. All worker modules import
+ * from here to access GPU resources. The initWebGPU() function is called once
+ * during worker initialization and pre-compiles all compute pipelines to avoid
+ * runtime compilation overhead.
+ *
+ * Shader code placeholders ('SHADER:xxx') are replaced during build by the
+ * build-shaders.js script, which bundles modules with esbuild then injects
+ * WGSL shader source code.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+// WebGPU state
+export let config = {};
+export let device = null;
+export let deviceCapabilities = null;
+export let isInitialized = false;
+
+// Cached pipelines (created during initialization)
+export let cachedRasterizePipeline = null;
+export let cachedRasterizeShaderModule = null;
+export let cachedToolpathPipeline = null;
+export let cachedToolpathShaderModule = null;
+export let cachedRadialBatchPipeline = null;
+export let cachedRadialBatchShaderModule = null;
+
+// Constants
+export const EMPTY_CELL = -1e10;
+export const log_pre = '[Worker]';
+export const diagnostic = false;
+
+// Logging utilities
+let lastlog;
+export const debug = {
+    error: function() { console.error(log_pre, ...arguments) },
+    warn: function() { console.warn(log_pre, ...arguments) },
+    log: function() {
+        if (!config.quiet) {
+            let now = performance.now();
+            let since = ((now - (lastlog ?? now)) | 0).toString().padStart(4,' ');
+            console.log(log_pre, `[${since}]`, ...arguments);
+            lastlog = now;
+        }
+    },
+    ok: function() { console.log(log_pre, '✅', ...arguments) },
+};
+
+// Utility functions
+export function round(v, d = 1) {
+    return parseFloat(v.toFixed(d));
+}
+
+// Shader code placeholders (replaced by build script)
+const rasterizeShaderCode = 'SHADER:planar-rasterize';
+const toolpathShaderCode = 'SHADER:planar-toolpath';
+const radialRasterizeShaderCode = 'SHADER:radial-raster';
+
+// Initialize WebGPU device in worker context
+export async function initWebGPU() {
+    if (isInitialized) return true;
+
+    if (!navigator.gpu) {
+        debug.warn('WebGPU not supported');
+        return false;
+    }
+
+    try {
+        const adapter = await navigator.gpu.requestAdapter();
+        if (!adapter) {
+            debug.warn('WebGPU adapter not available');
+            return false;
+        }
+
+        // Request device with higher limits for large meshes
+        const adapterLimits = adapter.limits;
+        debug.log('Adapter limits:', {
+            maxStorageBufferBindingSize: adapterLimits.maxStorageBufferBindingSize,
+            maxBufferSize: adapterLimits.maxBufferSize
+        });
+
+        device = await adapter.requestDevice({
+            requiredLimits: {
+                maxStorageBufferBindingSize: Math.min(
+                    adapterLimits.maxStorageBufferBindingSize,
+                    1024 * 1024 * 1024 // Request up to 1GB
+                ),
+                maxBufferSize: Math.min(
+                    adapterLimits.maxBufferSize,
+                    1024 * 1024 * 1024 // Request up to 1GB
+                )
+            }
+        });
+
+        // Pre-compile rasterize shader module (expensive operation)
+        cachedRasterizeShaderModule = device.createShaderModule({ code: rasterizeShaderCode });
+
+        // Pre-create rasterize pipeline (very expensive operation)
+        cachedRasterizePipeline = device.createComputePipeline({
+            layout: 'auto',
+            compute: { module: cachedRasterizeShaderModule, entryPoint: 'main' },
+        });
+
+        // Pre-compile toolpath shader module
+        cachedToolpathShaderModule = device.createShaderModule({ code: toolpathShaderCode });
+
+        // Pre-create toolpath pipeline
+        cachedToolpathPipeline = device.createComputePipeline({
+            layout: 'auto',
+            compute: { module: cachedToolpathShaderModule, entryPoint: 'main' },
+        });
+
+        // Pre-compile radial batch shader module
+        cachedRadialBatchShaderModule = device.createShaderModule({ code: radialRasterizeShaderCode });
+
+        // Pre-create radial batch pipeline
+        cachedRadialBatchPipeline = device.createComputePipeline({
+            layout: 'auto',
+            compute: { module: cachedRadialBatchShaderModule, entryPoint: 'main' },
+        });
+
+        // Store device capabilities
+        deviceCapabilities = {
+            maxStorageBufferBindingSize: device.limits.maxStorageBufferBindingSize,
+            maxBufferSize: device.limits.maxBufferSize,
+            maxComputeWorkgroupSizeX: device.limits.maxComputeWorkgroupSizeX,
+            maxComputeWorkgroupSizeY: device.limits.maxComputeWorkgroupSizeY,
+        };
+
+        isInitialized = true;
+        debug.log('Initialized (pipelines cached)');
+        return true;
+    } catch (error) {
+        debug.error('Failed to initialize:', error);
+        return false;
+    }
+}
+
+// Mutators for config (called from worker main)
+export function setConfig(newConfig) {
+    config = newConfig;
+}
+
+export function updateConfig(updates) {
+    Object.assign(config, updates);
+}

package/src/{index.js → core/raster-path.js}

@@ -48,13 +48,10 @@
  * @property {'planar'|'radial'} 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} maxConcurrentTiles - Max concurrent tiles for radial rasterization (default: 50)
  * @property {number} maxGPUMemoryMB - Maximum GPU memory per tile (default: 256MB)
- * @property {number} minTileSize - Minimum tile dimension (default: 50mm)
- * @property {number} radialRotationOffset - Radial mode: rotation offset in degrees (default: 0, use 90 to start at Z-axis)
  * @property {number} resolution - Grid step size in mm (required)
  * @property {number} rotationStep - Radial mode only: degrees between rays (e.g., 1.0 = 360 rays)
- * @property {number} trianglesPerTile - Target triangles per tile for radial rasterization (default: calculated)
+ * @property {number} batchDivisor - Testing parameter to artificially divide batch size (default: 1)
  * @property {boolean} debug - Enable debug logging (default: false)
  * @property {boolean} quiet - Suppress log output (default: false)
  */
@@ -103,26 +100,22 @@ export class RasterPath {
         this.deviceCapabilities = null;
 
         // Configure debug output
-        let urlOpt = [];
         if (config.quiet) {
             debug.log = function() {};
-            urlOpt.push('quiet');
-        }
-        if (config.debug) {
-            urlOpt.push('debug');
         }
 
         // Configuration with defaults
         this.config = {
-            workerName: (config.workerName ?? "webgpu-worker.js") + (urlOpt.length ? "?"+urlOpt.join('&') : ""),
+            workerName: config.workerName ?? "raster-worker.js",
             maxGPUMemoryMB: config.maxGPUMemoryMB ?? 256,
             gpuMemorySafetyMargin: config.gpuMemorySafetyMargin ?? 0.8,
             autoTiling: config.autoTiling ?? true,
-            minTileSize: config.minTileSize ?? 50,
-            maxConcurrentTiles: config.maxConcurrentTiles ?? 10,
-            trianglesPerTile: config.trianglesPerTile, // undefined = auto-calculate
-            radialRotationOffset: config.radialRotationOffset ?? 0, // degrees
+            batchDivisor: config.batchDivisor ?? 1, // For testing batching overhead
+            debug: config.debug,
+            quiet: config.quiet
         };
+
+        debug.log('config', this.config);
     }
 
     /**
@@ -137,14 +130,14 @@ export class RasterPath {
 
         return new Promise((resolve, reject) => {
             try {
-                // Create worker from the webgpu-worker.js file
+                // Create worker from the raster-worker.js file
                 const workerName = this.config.workerName;
                 const isBuildVersion = import.meta.url.includes('/build/') || import.meta.url.includes('raster-path.js');
                 const workerPath = workerName
                     ? new URL(workerName, import.meta.url)
                 : isBuildVersion
-                    ? new URL(`./webgpu-worker.js`, import.meta.url)
-                    : new URL(`./web/webgpu-worker.js`, import.meta.url);
+                    ? new URL(`./raster-worker.js`, import.meta.url)
+                    : new URL(`../core/raster-worker.js`, import.meta.url);
                 this.worker = new Worker(workerPath, { type: 'module' });
 
                 // Set up message handler
@@ -238,8 +231,8 @@ export class RasterPath {
             const originalBounds = boundsOverride || this.#calculateBounds(triangles);
 
             // Center model in YZ plane (required for radial rasterization)
-            // Radial mode casts rays from origin, so terrain must be centered at (0,0) in YZ
-            // to ensure rays intersect the geometry symmetrically around the rotation axis
+            // Radial mode casts rays from max_radius distance inward toward the X-axis,
+            // and centering ensures the geometry is symmetric around the rotation axis
             const centerY = (originalBounds.min.y + originalBounds.max.y) / 2;
             const centerZ = (originalBounds.min.z + originalBounds.max.z) / 2;
 
@@ -273,12 +266,10 @@ export class RasterPath {
      * @param {number} params.xStep - Sample every Nth point in X direction
      * @param {number} params.yStep - Sample every Nth point in Y direction
      * @param {number} params.zFloor - Z floor value for out-of-bounds areas
-     * @param {number} params.radiusOffset - (Radial mode only) Distance from terrain surface to tool tip in mm.
-     *                                        Used to calculate radial collision offset. Default: 20mm
      * @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, radiusOffset = 20, onProgress }) {
+    async generateToolpaths({ xStep, yStep, zFloor, onProgress }) {
         if (!this.isInitialized) {
             throw new Error('RasterPath not initialized. Call init() first.');
         }
@@ -287,6 +278,8 @@ export class RasterPath {
             throw new Error('Tool not loaded. Call loadTool() first.');
         }
 
+        debug.log('gen.paths', { xStep, yStep, zFloor });
+
         if (this.mode === 'planar') {
             if (!this.terrainData) {
                 throw new Error('Terrain not loaded. Call loadTerrain() first.');
@@ -444,8 +437,7 @@ export class RasterPath {
                     zFloor: zFloor,
                     bounds,
                     xStep,
-                    yStep,
-                    gridStep: this.resolution
+                    yStep
                 },
                 'radial-toolpaths-complete',
                 completionHandler