img2num 0.0.0 → 0.2.0

package/dist/node/wasmWorker.js

@@ -0,0 +1,198 @@
+import { t as createImg2NumModule } from "./wasmWorker-CpNpexYK.js";
+//#region src/workers/wasmWorker.js
+/**
+* @file wasmWorker.js
+* @description
+* Worker for calling WASM functions (Img2Num module) with proper memory handling.
+*
+*  Notes:
+*  - WASM exposes its linear memory via typed array views such as HEAP32 (Int32) or HEAPU8 (byte).
+*  - When adding a new TypedArray type:
+*    1. Add the corresponding HEAP view to EXPORTED_RUNTIME_METHODS in the Emscripten CMakeLists.txt.
+*    2. Allocate memory with `_malloc`.
+*    3. Copy data into the appropriate HEAP view. HEAP views are important because they allow the raw data to be read correctly.
+*    4. After the call, read data back from the same HEAP view.
+*    5. Free the allocated memory. This is important! We are using C-style memory since the code interfaces with the C ABI, so there is no GC.
+*  - This ensures JavaScript arrays correctly map to WASM memory.
+*
+* Important:
+* - The `args` object passed to all convenience wrapper functions must match the order
+*   of the C++ function parameters exactly. For example:
+*     ```js
+*     args = { a: 1, b: 2 };
+*     ```
+*     corresponds to
+*     ```cpp
+*     int add(int a, int b);
+*     ```
+*
+* - Async functions:
+*   WebGPU operations inside WASM can be asynchronous. Use Emscripten Asyncify
+*   (via `ccall` with `{ async: true }`) to properly pause and resume execution.
+*
+* @example
+* self.postMessage({
+*   id: 1,
+*   funcName: "bilateral_filter_gpu",
+*   args: { input: myArray },
+*   bufferKeys: [{ key: "input", type: "Uint8Array" }],
+*   returnType: "void"
+* });
+*/
+var wasmModule;
+/**
+* Promise that resolves when WASM module is ready.
+* @type {Promise<void>}
+*/
+var readyPromise = createImg2NumModule().then((mod) => {
+	wasmModule = mod;
+});
+/**
+* Handlers for allocating, reading, and freeing different WASM types.
+* @type {Record<string, {alloc: Function, read: Function}>}
+*/
+var WASM_TYPES = {
+	void: {
+		alloc: () => null,
+		read: () => void 0
+	},
+	Int32Array: {
+		/**
+		* Allocate an Int32Array in WASM memory.
+		* @param {Int32Array} arr
+		* @returns {number} Pointer to allocated memory
+		*/
+		alloc: (arr) => {
+			const ptr = wasmModule._malloc(arr.byteLength);
+			wasmModule.HEAP32.set(arr, ptr >> 2);
+			return ptr;
+		},
+		/**
+		* Read an Int32Array from WASM memory.
+		* @param {number} ptr
+		* @param {number} len
+		* @returns {Int32Array}
+		*/
+		read: (ptr, len) => new Int32Array(wasmModule.HEAP32.buffer, ptr, len).slice()
+	},
+	Uint8Array: {
+		alloc: (arr) => {
+			const ptr = wasmModule._malloc(arr.byteLength);
+			wasmModule.HEAPU8.set(arr, ptr);
+			return ptr;
+		},
+		read: (ptr, len) => wasmModule.HEAPU8.slice(ptr, ptr + len)
+	},
+	Uint8ClampedArray: {
+		alloc: (arr) => {
+			const ptr = wasmModule._malloc(arr.byteLength);
+			wasmModule.HEAPU8.set(arr, ptr);
+			return ptr;
+		},
+		read: (ptr, len) => new Uint8ClampedArray(wasmModule.HEAPU8.slice(ptr, ptr + len))
+	},
+	string: {
+		/**
+		* Allocate a string in WASM memory.
+		* @param {string} str
+		* @returns {number} Pointer to allocated memory
+		*/
+		alloc: (str) => {
+			const len = wasmModule.lengthBytesUTF8(str) + 1;
+			const ptr = wasmModule._malloc(len);
+			wasmModule.stringToUTF8(str, ptr, len);
+			return ptr;
+		},
+		/**
+		* Read a string from WASM memory.
+		* @param {number} ptr
+		* @returns {string|null}
+		*/
+		read: (ptr) => ptr ? wasmModule.UTF8ToString(ptr) : null
+	}
+};
+/**
+* Call a WASM function via ccall, handling asyncify automatically.
+* @param {string} funcName
+* @param {Map<string, number>} argsMap - Map of argument names to WASM pointers or numbers
+* @param {string} returnType - WASM return type (e.g., 'void', 'Int32Array', 'string')
+* @returns {Promise<number>} Result pointer or numeric return value
+*/
+async function callWasm(funcName, argsMap, returnType) {
+	const argTypes = Array(argsMap.size).fill("number");
+	const retType = returnType !== "void" ? "number" : null;
+	return await wasmModule.ccall(funcName, retType, argTypes, [...argsMap.values()], { async: true });
+}
+/**
+* Handle messages from main thread.
+* Expects `data` to contain:
+*   - id: unique message ID
+*   - funcName: WASM export to call
+*   - args: object of input arguments to WASM export
+*   - bufferKeys: array of {key, type} defining memory buffers for WASM export args - JS doesn't have pointers, so we must do this
+*   - returnType: expected return type of the WASM export
+* @param {MessageEvent} event
+*/
+async function handleMessage(data) {
+	await readyPromise;
+	const { id, funcName, args, bufferKeys, returnType } = data;
+	const pointers = /* @__PURE__ */ new Map();
+	try {
+		if (!funcName) throw new Error("Missing funcName");
+		if (!args) throw new Error("Missing args");
+		if (!bufferKeys) throw new Error("Missing bufferKeys");
+		if (!returnType) throw new Error("Missing returnType");
+		const argsMap = new Map(Object.entries(args));
+		for (const { key, type } of bufferKeys) {
+			const handler = WASM_TYPES[type];
+			if (!handler) throw new Error(`Unsupported type: ${type}`);
+			const val = argsMap.get(key);
+			const ptr = handler.alloc(val);
+			pointers.set(key, {
+				ptr,
+				type,
+				length: val?.length
+			});
+			argsMap.set(key, ptr);
+		}
+		let result = await callWasm(funcName, argsMap, returnType);
+		/** @type {Record<string, any>} */
+		const output = Object.create(null);
+		for (const { key, type } of bufferKeys) {
+			const { ptr, length } = pointers.get(key);
+			output[key] = WASM_TYPES[type].read(ptr, length);
+		}
+		let returnValue = result;
+		if (returnType !== "void") returnValue = WASM_TYPES[returnType].read(result);
+		if (returnType === "string" && result) wasmModule._free(result);
+		globalThis.postMessage({
+			id,
+			output,
+			returnValue
+		});
+	} catch (error) {
+		globalThis.postMessage({
+			id,
+			error: error.message
+		});
+	} finally {
+		for (const { ptr } of pointers.values()) wasmModule._free(ptr);
+	}
+}
+{
+	const { parentPort } = await import("node:worker_threads");
+	const { initWebGPU, destroyWebGPU } = await import("./webgpu-BjVEVfI9.js");
+	try {
+		await initWebGPU();
+	} catch (err) {
+		console.error(`[Img2Num node/worker.js] Error: ${err}`);
+	}
+	globalThis.postMessage = (data) => parentPort.postMessage(data);
+	parentPort.on("message", async (data) => {
+		await handleMessage(data);
+		await destroyWebGPU();
+		parentPort.close();
+	});
+}
+//#endregion
+export {};

package/dist/node/webgpu-BjVEVfI9.js

@@ -0,0 +1,23 @@
+import { create } from "webgpu";
+//#region src/target/node/webgpu.js
+var gpuInitPromise;
+async function initWebGPU() {
+	if (globalThis.navigator?.gpu) return globalThis.navigator.gpu;
+	if (!gpuInitPromise) gpuInitPromise = Promise.resolve().then(() => {
+		const nativeGpu = create(["backend=vulkan"]);
+		globalThis.navigator ??= {};
+		globalThis.navigator.gpu = nativeGpu;
+		return nativeGpu;
+	});
+	return gpuInitPromise;
+}
+async function destroyWebGPU() {
+	if (globalThis.navigator?.gpu) {
+		delete globalThis.navigator.gpu;
+		if (Object.keys(globalThis.navigator).length === 0) delete globalThis.navigator;
+	}
+	gpuInitPromise = null;
+	await new Promise((resolve) => setTimeout(resolve, 50));
+}
+//#endregion
+export { destroyWebGPU, initWebGPU };

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "img2num",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "Img2Num is a raster vectorization library - it converts images to SVGs",
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "img2num",
     "computer-vision",
@@ -20,21 +23,28 @@
   "license": "MIT",
   "author": "Ryan-Millard",
   "type": "module",
-  "main": "./index.js",
+  "main": "./dist/browser/img2num.js",
   "engines": {
     "node": ">=14"
   },
-  "files": [
-    "build-wasm/index.js",
-    "build-wasm/index.wasm",
-    "index.js",
-    "safeWasmWrappers.js",
-    "wasmClient.js",
-    "wasmWorker.js",
-    "imageToUint8ClampedArray.js"
-  ],
-  "dependencies": {},
+  "exports": {
+    ".": {
+      "node": "./dist/node/img2num.js",
+      "browser": "./dist/browser/img2num.js",
+      "import": "./dist/browser/img2num.js",
+      "default": "./dist/browser/img2num.js"
+    }
+  },
+  "optionalDependencies": {
+    "webgpu": "^0.4.0"
+  },
+  "devDependencies": {
+    "cross-env": "^10.1.0",
+    "vite": "^8.0.14"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build:browser": "cross-env TARGET=browser vite build",
+    "build:node": "cross-env TARGET=node vite build",
+    "build": "pnpm build:browser && pnpm build:node"
   }
 }

package/{safeWasmWrappers.js → src/safeWasmWrappers.js}

@@ -16,10 +16,10 @@
  *              Each function handles memory management and exposes a JavaScript-friendly API.
  */
 
-import { initWasmWorker, callWasm } from "./wasmClient.js";
+import { callWasm, initWasmWorker } from "./wasmClient.js";
 
 // Ensure worker is ready as soon as this module is imported
-initWasmWorker();
+await initWasmWorker(); //it's an async function as of #433
 
 /**
  * @summary Apply a Gaussian blur to an image using FFT in WASM.
@@ -184,17 +184,18 @@ export const kmeans = async ({
  * @param {number} options.width - Image width.
  * @param {number} options.height - Image height.
  * @param {number} [options.min_area=100] - Minimum area of a region to be considered a contour.
- * @returns {Promise<{svg: string>} Generated SVG.
+ * @param {number} [options.min_thickness=10] - Minimum thickness of a region to be considered a contour.
+ * @returns {Promise<{svg: string}>} Generated SVG.
  * @throws {Error} If the WASM function fails or input labels are invalid.
  * @example
  * const { svg } = await findContours({ pixels, labels, width, height });
  * @variation Converts labeled (from a clustering algorithm, e.g. K-Means) image into an SVG.
  * @since 0.0.0
  */
-export const findContours = async ({ pixels, labels, width, height, min_area = 100 }) => {
+export const findContours = async ({ pixels, labels, width, height, min_area = 100, min_thickness = 10 }) => {
   const result = await callWasm({
     funcName: "labels_to_svg",
-    args: { pixels, labels, width, height, min_area },
+    args: { pixels, labels, width, height, min_area, min_thickness },
     bufferKeys: [
       { key: "pixels", type: "Uint8ClampedArray" },
       { key: "labels", type: "Int32Array" },
@@ -221,6 +222,7 @@ export const findContours = async ({ pixels, labels, width, height, min_area = 1
  * @param {number} [options.num_colors=16] - Number of color clusters.
  * @param {number} [options.max_iter=100] - Maximum number of iterations.
  * @param {number} [options.min_area=100] - Minimum area of a region to be considered a contour.
+ * @param {number} [options.min_thickness=10] - Minimum thickness of a region to be considered a contour.
  * @param {number} [options.color_space=0] - Color space mode.
  * @returns {Promise<{svg: string}>} Generated SVG.
  * @throws {Error} If the WASM function fails or input labels are invalid.
@@ -229,10 +231,10 @@ export const findContours = async ({ pixels, labels, width, height, min_area = 1
  * @variation Convert a raster image (e.g., PNG, JPG) into an SVG.
  * @since 0.0.0
  */
-export const imageToSvg = async ({ pixels, width, height, sigma_spatial = 3, sigma_range = 50, num_colors = 16, max_iter = 100, min_area = 100, color_space = 0 }) => {
+export const imageToSvg = async ({ pixels, width, height, sigma_spatial = 3, sigma_range = 50, num_colors = 16, max_iter = 100, min_area = 100, min_thickness = 10, color_space = 0 }) => {
   const result = await callWasm({
     funcName: "image_to_svg",
-    args: { pixels, width, height, sigma_spatial, sigma_range, num_colors, max_iter, min_area, color_space },
+    args: { pixels, width, height, sigma_spatial, sigma_range, num_colors, max_iter, min_area, min_thickness, color_space },
     bufferKeys: [{ key: "pixels", type: "Uint8ClampedArray" }],
     returnType: "string",
   });

package/src/target/browser/worker.js

@@ -0,0 +1,10 @@
+export async function createWorker() {
+  const worker = new Worker(new URL("@workers/wasmWorker.js", import.meta.url), { type: "module" });
+
+  return {
+    postMessage: (msg) => worker.postMessage(msg),
+    onMessage: (fn) => (worker.onmessage = (e) => fn(e.data)),
+    onError: (fn) => (worker.onerror = fn),
+    terminate: () => worker.terminate(),
+  };
+}

package/src/target/node/webgpu.js

@@ -0,0 +1,35 @@
+import { create } from "webgpu";
+
+let gpuInitPromise;
+
+export async function initWebGPU() {
+  if (globalThis.navigator?.gpu) return globalThis.navigator.gpu;
+  if (!gpuInitPromise) {
+    gpuInitPromise = Promise.resolve().then(() => {
+      const nativeGpu = create(["backend=vulkan"]);
+      globalThis.navigator ??= {};
+      globalThis.navigator.gpu = nativeGpu;
+      return nativeGpu;
+    });
+  }
+  return gpuInitPromise;
+}
+
+// Drop-in companion deallocation handler
+export async function destroyWebGPU() {
+  // 2. Sever the native reference links so Dawn can drop its ref counts
+  if (globalThis.navigator?.gpu) {
+    delete globalThis.navigator.gpu;
+    if (Object.keys(globalThis.navigator).length === 0) {
+      delete globalThis.navigator;
+    }
+  }
+
+  // 3. Reset our internal module-level promise cache
+  gpuInitPromise = null;
+
+  // 4. CRITICAL: Yield to the event loop. This gives Dawn's native engine
+  // a small time window to notice the reference count hit 0, dismantle its
+  // background threads, and flush outstanding callbacks BEFORE the process terminates.
+  await new Promise((resolve) => setTimeout(resolve, 50));
+}

package/src/target/node/worker.js

@@ -0,0 +1,20 @@
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function createWorker() {
+  // Reference the worker by path relative to this file at runtime,
+  // not via import.meta.url which Vite will try to bundle/inline.
+  const workerPath = resolve(__dirname, "./wasmWorker.js");
+
+  const worker = new Worker(workerPath);
+
+  return {
+    postMessage: (msg) => worker.postMessage(msg),
+    onMessage: (fn) => worker.on("message", fn),
+    onError: (fn) => worker.on("error", fn),
+    terminate: () => worker.terminate(),
+  };
+}

package/{wasmClient.js → src/wasmClient.js}

@@ -17,6 +17,8 @@
  *              This allows more granular control.
  */
 
+import { createWorker } from "@__TARGET__/worker.js";
+
 /**
  * Worker instance that handles communication with the WASM module.
  * @type {Worker | null}
@@ -42,6 +44,22 @@ const callbacks = new Map();
  */
 let initialized = false;
 
+/**
+ * Handle response messages from the WASM worker.
+ * @param {{ id: number, output?: any, returnValue?: any, error?: string }} data
+ */
+function handleMessage(data) {
+  const cb = callbacks.get(data.id);
+  if (!cb) return;
+  callbacks.delete(data.id);
+
+  if (data.error) {
+    cb.reject(new Error(data.error));
+  } else {
+    cb.resolve({ output: data.output, returnValue: data.returnValue });
+  }
+}
+
 /**
  * @summary Initialize the WASM worker.
  *
@@ -59,27 +77,21 @@ let initialized = false;
  *
  * @since 0.0.0
  */
-export function initWasmWorker() {
-  if (initialized) return;
-
-  worker = new Worker(new URL("./wasmWorker.js", import.meta.url), { type: "module" });
 
-  worker.onmessage = ({ data }) => {
-    const { id, error, output, returnValue } = data;
-    const cb = callbacks.get(id);
-    if (!cb) return;
+export async function initWasmWorker() {
+  if (initialized) return;
 
-    error ? cb.reject(new Error(error)) : cb.resolve({ output, returnValue });
-    callbacks.delete(id);
-  };
+  worker = await createWorker();
 
-  worker.onerror = (event) => {
-    const err = new Error(event.message || "WASM worker error");
+  worker.onMessage(handleMessage);
+  worker.onError((event) => {
+    const output = event.message || "WASM worker error";
+    const err = new Error(`[Img2Num wasmClient] Error: ${output}`);
     for (const [_id, cb] of callbacks) {
       cb.reject(err);
     }
     callbacks.clear();
-  };
+  });
 
   initialized = true;
 }
@@ -120,10 +132,13 @@ export function initWasmWorker() {
  */
 export async function callWasm({ funcName, args = {}, bufferKeys = [], returnType = "void" }) {
   if (!initialized) throw new Error("WASM worker not initialized. Call initWasmWorker() first.");
+
   const id = idCounter++;
+
   return new Promise((resolve, reject) => {
     callbacks.set(id, { resolve, reject });
-    worker.postMessage({ id, funcName, args, bufferKeys, returnType }); // <-- send it
+
+    worker.postMessage({ id, funcName, args, bufferKeys, returnType });
   });
 }