whitebox-wasm 0.3.0 → 0.4.0

package/README.md

@@ -9,6 +9,7 @@ in the browser, Node, Deno, or any Wasm host:
 - **Vector** - read GeoJSON, TopoJSON, GML, GPX, KML, FlatGeobuf, GeoPackage, KMZ -> GeoJSON, with reprojection
 - **LiDAR** - read LAS / LAZ / PLY point clouds (xyz, classification, intensity)
 - **Analysis** - convex hull, Moran's I spatial autocorrelation
+- **Tools** - the full WhiteboxTools suite (733 tools) via `whitebox-wasm/tools`
 
 This wraps `wbgeotiff`, the shared GeoTIFF engine from the original
 [**whitebox_next_gen**](https://github.com/jblindsay/whitebox_next_gen) project
@@ -172,6 +173,40 @@ const xyz = lidar_read_xyz(las, "laz");          // Float64Array [x0,y0,z0, x1,y
 - `convex_hull(points_xy)` -> hull ring `Float64Array` (input `[x0,y0,x1,y1,...]`)
 - `morans_i(points_xy, values, distance_threshold)` -> JSON global spatial autocorrelation `{morans_i, expected, variance, z_score, p_value, n}`
 
+## Tools (the full WhiteboxTools suite)
+
+The `whitebox-wasm/tools` subpath runs the complete **WhiteboxTools** algorithm
+suite (**733 tools** - slope, filters, hydrology, geomorphometry, vector ops,
+...). The tools are path-based, so they run through an in-memory WASI filesystem
+(bundled `whitebox-cli.wasm`); raster outputs are Cloud Optimized GeoTIFFs.
+
+```js
+import { runTool, listTools } from "whitebox-wasm/tools";
+
+console.log((await listTools()).length);  // 733
+
+// raster: slope -> a COG
+const { files } = await runTool("slope", {
+  args: ["--input=/work/dem.tif", "--output=/work/slope.tif", "--units=degrees"],
+  input: { "dem.tif": demBytes },         // Uint8Array, placed under /work
+});
+const slopeCog = files["slope.tif"];      // Uint8Array (tiled, Deflate, overviews)
+
+// vector: convex hull -> GeoJSON
+const hull = await runTool("minimum_convex_hull", {
+  args: ["--input=/work/in.geojson", "--output=/work/hull.geojson"],
+  input: { "in.geojson": geojsonBytes },
+});
+```
+
+- `listTools()` -> `string[]` of tool ids
+- `runTool(id, { args, input })` -> `{ exitCode, stdout, files }` (`files` = outputs the tool wrote)
+- `initTools(source?)` -> compile the runner; in Node pass the wasm bytes (browsers/bundlers omit it)
+
+Needs the `@bjorn3/browser_wasi_shim` peer (declared as a dependency). The
+`whitebox-cli.wasm` (~5 MB gzipped) is only fetched the first time you call a
+tool, so the rest of the library stays lightweight.
+
 ## Limits
 
 WebAssembly is 32-bit, so linear memory is capped at ~4 GiB. `geotiff_info` is

package/package.json

@@ -2,7 +2,7 @@
   "name": "whitebox-wasm",
   "type": "module",
   "description": "Pure-Rust geospatial toolkit (raster, vector, LiDAR, projections) compiled to WebAssembly",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
@@ -11,7 +11,10 @@
   "files": [
     "whitebox_wasm_bg.wasm",
     "whitebox_wasm.js",
-    "whitebox_wasm.d.ts"
+    "whitebox_wasm.d.ts",
+    "whitebox-cli.wasm",
+    "tools.mjs",
+    "tools.d.ts"
   ],
   "main": "whitebox_wasm.js",
   "homepage": "https://github.com/opengeos/whitebox-wasm",
@@ -25,5 +28,18 @@
     "gis",
     "geotiff",
     "lidar"
-  ]
+  ],
+  "dependencies": {
+    "@bjorn3/browser_wasi_shim": "^0.4.2"
+  },
+  "exports": {
+    ".": {
+      "types": "./whitebox_wasm.d.ts",
+      "default": "./whitebox_wasm.js"
+    },
+    "./tools": {
+      "types": "./tools.d.ts",
+      "default": "./tools.mjs"
+    }
+  }
 }

package/tools.d.ts

@@ -0,0 +1,26 @@
+/** Result of running a tool. */
+export interface ToolResult {
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /** Captured stdout/stderr lines. */
+  stdout: string[];
+  /** New files the tool wrote, keyed by filename (e.g. the --output path's basename). */
+  files: Record<string, Uint8Array>;
+}
+
+export interface RunToolOptions {
+  /** CLI args, e.g. ["--input=/work/dem.tif", "--output=/work/out.tif", "--units=degrees"]. */
+  args?: string[];
+  /** Input files placed under /work, keyed by filename. */
+  input?: Record<string, Uint8Array>;
+}
+
+/** Compile the WASI tool runner once. Omit `source` in browsers/bundlers; pass
+ *  the wasm bytes or a URL/Response in Node. */
+export function initTools(source?: URL | Response | BufferSource | string): Promise<WebAssembly.Module>;
+
+/** List every available tool id. */
+export function listTools(): Promise<string[]>;
+
+/** Run one tool over an in-memory filesystem. */
+export function runTool(tool: string, opts?: RunToolOptions): Promise<ToolResult>;

package/tools.mjs

@@ -0,0 +1,83 @@
+// whitebox-wasm/tools - run the WhiteboxTools (wbtools_oss) algorithm suite from
+// JavaScript. The tools are the WASI binary `whitebox-cli.wasm` (733 path-based
+// tools); this module executes them through a WASI shim with an in-memory
+// filesystem, so they run in browsers, Node, Deno, and bundlers without a real
+// disk. Raster outputs are Cloud Optimized GeoTIFFs.
+//
+//   import { runTool, listTools } from "whitebox-wasm/tools";
+//   const { files } = await runTool("slope", {
+//     args: ["--input=/work/dem.tif", "--output=/work/slope.tif", "--units=degrees"],
+//     input: { "dem.tif": demBytes },   // Uint8Array, placed under /work
+//   });
+//   const slopeCog = files["slope.tif"];  // Uint8Array
+import { WASI, File, OpenFile, ConsoleStdout, PreopenDirectory } from "@bjorn3/browser_wasi_shim";
+
+let _module = null;
+
+/**
+ * Compile the WASI tool runner once. In browsers/bundlers it loads the bundled
+ * `whitebox-cli.wasm` relative to this module. In Node (no fetch of file URLs),
+ * pass the wasm bytes or a URL/Response explicitly.
+ * @param {URL|Response|BufferSource|string} [source]
+ * @returns {Promise<WebAssembly.Module>}
+ */
+export async function initTools(source) {
+  if (_module) return _module;
+  if (!source) source = new URL("./whitebox-cli.wasm", import.meta.url);
+  if (source instanceof Uint8Array || source instanceof ArrayBuffer) {
+    _module = await WebAssembly.compile(source);
+  } else if (source instanceof Response) {
+    _module = await WebAssembly.compileStreaming(source);
+  } else {
+    _module = await WebAssembly.compileStreaming(fetch(source));
+  }
+  return _module;
+}
+
+async function exec(argv, inputFiles) {
+  const mod = await initTools();
+  const inNames = new Set(Object.keys(inputFiles));
+  const contents = new Map(
+    Object.entries(inputFiles).map(([k, v]) => [k, new File(new Uint8Array(v))]));
+  const work = new PreopenDirectory("/work", contents);
+  const stdout = [];
+  const fds = [
+    new OpenFile(new File(new Uint8Array())),
+    ConsoleStdout.lineBuffered((s) => stdout.push(s)),
+    ConsoleStdout.lineBuffered((s) => stdout.push(s)),
+    work,
+  ];
+  const wasi = new WASI(["whitebox", ...argv], [], fds, { debug: false });
+  const inst = await WebAssembly.instantiate(mod, { wasi_snapshot_preview1: wasi.wasiImport });
+  let exitCode = 0;
+  try { exitCode = wasi.start(inst); }
+  catch (e) { if (e && e.constructor && e.constructor.name === "WASIProcExit") exitCode = e.code; else throw e; }
+  const files = {};
+  for (const [name, entry] of work.dir.contents) {
+    if (entry.data && !inNames.has(name)) files[name] = entry.data;
+  }
+  return { exitCode, stdout, files };
+}
+
+/**
+ * List every available tool id (733 of them).
+ * @returns {Promise<string[]>}
+ */
+export async function listTools() {
+  const { stdout } = await exec(["list"], {});
+  return stdout.map((s) => s.trim()).filter((s) => s && !/tools:$/.test(s));
+}
+
+/**
+ * Run one tool over an in-memory filesystem.
+ * @param {string} tool  tool id, e.g. "slope" (see {@link listTools})
+ * @param {object} [opts]
+ * @param {string[]} [opts.args]  CLI args, e.g. ["--input=/work/dem.tif","--output=/work/out.tif","--units=degrees"]
+ * @param {Object<string, Uint8Array>} [opts.input]  files placed under /work (key = filename)
+ * @returns {Promise<{exitCode:number, stdout:string[], files:Object<string,Uint8Array>}>}
+ *   `files` contains any new files the tool wrote (e.g. the --output path).
+ */
+export async function runTool(tool, opts = {}) {
+  const { args = [], input = {} } = opts;
+  return exec([tool, ...args], input);
+}

package/whitebox_wasm.d.ts

@@ -282,10 +282,10 @@ export function geotiff_stats(data: Uint8Array): string;
 export function lidar_formats(): string;
 
 /**
- * Read a LiDAR file's metadata as JSON without loading all points where
- * possible (LAS/LAZ report count and bounds from the header):
+ * Read a LiDAR file's metadata as JSON. For LAS/LAZ this is header-only (count,
+ * bounds, CRS, point format, COPC flag) and never decodes points:
  * `{"ok":true,"format","points","epsg"|null,"point_format"|null,
- *   "bounds":[min_x,min_y,min_z,max_x,max_y,max_z]|null}`.
+ *   "bounds":[min_x,min_y,min_z,max_x,max_y,max_z]|null,"copc":bool}`.
  */
 export function lidar_info(data: Uint8Array, format: string): string;
 

package/whitebox_wasm.js

@@ -1120,10 +1120,10 @@ export function lidar_formats() {
 }
 
 /**
- * Read a LiDAR file's metadata as JSON without loading all points where
- * possible (LAS/LAZ report count and bounds from the header):
+ * Read a LiDAR file's metadata as JSON. For LAS/LAZ this is header-only (count,
+ * bounds, CRS, point format, COPC flag) and never decodes points:
  * `{"ok":true,"format","points","epsg"|null,"point_format"|null,
- *   "bounds":[min_x,min_y,min_z,max_x,max_y,max_z]|null}`.
+ *   "bounds":[min_x,min_y,min_z,max_x,max_y,max_z]|null,"copc":bool}`.
  * @param {Uint8Array} data
  * @param {string} format
  * @returns {string}