whitebox-wasm 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,151 @@
+# whitebox-wasm
+
+**Pure-Rust GeoTIFF decoding compiled to WebAssembly.** No GDAL, no PROJ, no
+native libraries, no server. Decode GeoTIFF / BigTIFF / COG entirely in the
+browser, Node, Deno, or any Wasm host.
+
+This wraps `wbgeotiff`, the shared GeoTIFF engine from the original
+[**whitebox_next_gen**](https://github.com/jblindsay/whitebox_next_gen) project
+by John Lindsay (Whitebox Geospatial Inc.) - the next-generation, pure-Rust
+rewrite of WhiteboxTools - and exposes a tiny WebAssembly API. The entire codec
+stack (Deflate, LZW, PackBits, JPEG, WebP, JPEG-XL, PNG predictors, BigTIFF,
+tiling) is pure Rust with zero C dependencies, so the published module imports
+nothing from the host beyond its own linear memory.
+
+## Install
+
+```bash
+npm install whitebox-wasm
+```
+
+## Usage (browser / Deno / Node >= 20, ESM)
+
+```js
+import init, { geotiff_info, GeoTiffReader, CogBuilder } from "whitebox-wasm";
+
+await init();                       // in Node, pass the .wasm bytes to init()
+const bytes = new Uint8Array(await (await fetch("dem.tif")).arrayBuffer());
+
+// Metadata only - O(header) memory, works on multi-GB rasters:
+console.log(JSON.parse(geotiff_info(bytes)));
+// { ok:true, width, height, bands, epsg, nodata, bits_per_sample,
+//   sample_format, compression, tiled, bigtiff }
+
+// Parse once, read many times:
+const tif = new GeoTiffReader(bytes);
+console.log(tif.width, tif.height, tif.bands, tif.epsg, tif.nodata);
+console.log(Array.from(tif.geo_transform()));   // [ox, px, 0, oy, 0, -py]
+console.log(Array.from(tif.bounding_box()));    // [minx, miny, maxx, maxy]
+const band0 = tif.read_band_f64(0);             // Float64Array
+console.log(JSON.parse(tif.stats_json()));
+
+// Encode a Cloud Optimized GeoTIFF (also a valid plain GeoTIFF):
+const cb = new CogBuilder(width, height, 1);
+cb.set_epsg(32610);
+cb.set_origin(500000, 4000000, 30);             // x_min, y_max, pixel size
+cb.set_compression("deflate");
+cb.set_nodata(-9999);
+const cogBytes = cb.write_f64(new Float64Array(pixels));   // Uint8Array
+```
+
+In Node the `web` target needs the wasm bytes handed to `init()`:
+
+```js
+import { readFileSync } from "node:fs";
+import init, { geotiff_info } from "whitebox-wasm";
+await init({ module_or_path: readFileSync("node_modules/whitebox-wasm/whitebox_wasm_bg.wasm") });
+```
+
+## API
+
+### Convenience functions
+
+| Function | Returns |
+|---|---|
+| `geotiff_info(bytes)` | JSON metadata, header-only (incl. `bbox`, `center`, `center_lonlat`) |
+| `geotiff_stats(bytes)` | JSON band-0 stats `{valid, min, max, mean, ...}` |
+| `geotiff_read_band_f64(bytes, band)` | `Float64Array` of band pixels |
+| `version()` | crate version string |
+
+### `GeoTiffReader` (parse once, read many)
+
+`new GeoTiffReader(bytes)`, then:
+
+- Properties: `width`, `height`, `bands`, `bits_per_sample`, `sample_format`, `compression`, `is_bigtiff`, `epsg`, `nodata`
+- `geo_transform()` -> `[x_origin, pixel_width, row_rot, y_origin, col_rot, pixel_height]` (empty if none)
+- `bounding_box()` -> `[min_x, min_y, max_x, max_y]` in the dataset CRS (empty if not georeferenced)
+- `center()` -> `[x, y]` center in the dataset CRS
+- `center_lonlat()` -> `[lon, lat]` WGS84 degrees; `bounds_lonlat()` -> `[min_lon, min_lat, max_lon, max_lat]` WGS84 (any EPSG via the bundled pure-Rust projection engine; also handles user-defined projections like NLCD's Albers; empty if not georeferenced)
+- `value_transform()` -> `[scale, offset]` (GDAL scale/offset; empty if none)
+- `info_json()`, `stats_json()` -> JSON strings
+- `read_band_f64(band)` / `read_all_f64()` -> `Float64Array` (any on-disk type converted)
+- `read_band_bytes(band)` -> raw `Uint8Array`
+- Native typed reads (require matching on-disk type): `read_band_u8` / `i8` / `u16` / `i16` / `u32` / `i32` / `f32`
+
+### `CogBuilder` (write Cloud Optimized GeoTIFFs)
+
+`new CogBuilder(width, height, bands)`, configure, then `write_u8` / `write_f32` / `write_f64(data)` -> `Uint8Array`:
+
+- `set_epsg(code)`, `set_nodata(v)`, `set_compression("none|lzw|deflate|packbits|webp|jpeg|jpegxl")`
+- `set_geo_transform([6 values])` or `set_origin(x_min, y_max, pixel_size)`
+- `set_tile_size(px)`, `set_bigtiff(bool)`, `set_overview_levels([2,4,8])`
+
+Output is a tiled COG with overviews and GDAL ghost metadata - readable by GDAL, rasterio, QGIS, and `GeoTiffReader`.
+
+### `CogStream` (read remote COGs via HTTP range requests)
+
+Read a window or overview out of a large COG **without downloading the whole
+file**. The wasm parses the header and reports byte ranges; your JS does the
+range requests:
+
+```js
+import init, { CogStream } from "whitebox-wasm";
+await init();
+
+const url = "https://example.com/big-cog.tif";
+const range = (a, b) => fetch(url, { headers: { Range: `bytes=${a}-${b}` } })
+  .then(r => r.arrayBuffer()).then(b => new Uint8Array(b));
+
+const stream = new CogStream(await range(0, 65535));   // header prefix
+const lv = JSON.parse(stream.levels_json())[0];        // level 0 = full res
+const tiles = JSON.parse(stream.tiles_for_window(0, 1200, 800, 256, 256));
+
+for (const t of tiles) {
+  const bytes = await range(t.offset, t.offset + t.length - 1);  // one tile
+  const px = stream.decode_tile_f64(0, bytes);                   // Float64Array
+  // place px (tile_width x tile_height) into your output window...
+}
+```
+
+- `new CogStream(headerBytes)` - parse the IFD chain + tile index (throws if the
+  prefix is too short; fetch more and retry).
+- `num_levels`, `epsg`, `nodata`, `geo_transform()`, `levels_json()`
+- `bounding_box()`, `center()`, `center_lonlat()`, `bounds_lonlat()` (same semantics as `GeoTiffReader`)
+- `tiles_for_window(level, x, y, w, h)` -> JSON `[{col,row,offset,length}]`
+- `tile_range(level, col, row)` -> `[offset, length]`
+- `decode_tile_f64(level, tileBytes)` -> `Float64Array` (one decoded tile)
+
+Use a higher `level` (overview) for zoomed-out views. See
+[`examples/cog-stream.mjs`](../../examples/cog-stream.mjs) for a full window read
+that fetches only the tiles it needs (about 13% of a 5.7 MiB file for a 256x256
+window). Requires a tiled COG on a server that supports HTTP range requests.
+
+JSON-returning functions report failures as `{"ok":false,"error":"..."}`; class methods throw on error.
+
+## Limits
+
+WebAssembly is 32-bit, so linear memory is capped at ~4 GiB. `geotiff_info` is
+header-only and unaffected, but reads/writes that materialize a full raster are
+bounded by that ceiling (a national 1-billion-pixel raster cannot be fully
+decoded in-browser). For such data, read metadata only or process server-side.
+
+## Links
+
+- Source, live demo, and issues: https://github.com/opengeos/whitebox-wasm
+- Live browser demo: https://opengeos.org/whitebox-wasm/
+
+## License
+
+Dual-licensed under MIT or Apache-2.0, at your option. Includes the vendored
+`wbgeotiff` and `wbprojection` crates (Copyright John Lindsay, Whitebox
+Geospatial Inc.), used under the same dual license.

package/package.json

@@ -2,7 +2,7 @@
   "name": "whitebox-wasm",
   "type": "module",
   "description": "WebAssembly bindings for the pure-Rust Whitebox GeoTIFF engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
@@ -26,4 +26,4 @@
     "raster",
     "webassembly"
   ]
-}
+}

package/whitebox_wasm.d.ts

@@ -2,20 +2,271 @@
 /* eslint-disable */
 
 /**
- * Decode a GeoTIFF and return only its georeferencing/shape metadata as JSON:
- * `{"ok":true,"width":W,"height":H,"bands":B,"epsg":E|null,"nodata":V|null}`.
+ * Builder for encoding a Cloud Optimized GeoTIFF (tiled, with overviews and
+ * GDAL ghost metadata) to bytes. A COG is also a valid plain GeoTIFF.
+ *
+ * Configure with the `set_*` methods, then call one of `write_*` with the
+ * pixel data to get a `Uint8Array` of the encoded file.
  */
-export function geotiff_info(data: Uint8Array): string;
+export class CogBuilder {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * New builder for a `width` x `height` raster with `bands` bands.
+     */
+    constructor(width: number, height: number, bands: number);
+    /**
+     * Force BigTIFF (64-bit offsets) for very large outputs.
+     */
+    set_bigtiff(on: boolean): void;
+    /**
+     * Compression: `none`, `lzw`, `deflate`, `packbits`, `webp`, `jpeg`, `jpegxl`.
+     */
+    set_compression(name: string): void;
+    /**
+     * Set the EPSG code (1..=65535).
+     */
+    set_epsg(epsg: number): void;
+    /**
+     * Set the full affine geo-transform:
+     * `[x_origin, pixel_width, row_rotation, y_origin, col_rotation, pixel_height]`.
+     */
+    set_geo_transform(gt: Float64Array): void;
+    /**
+     * Set the no-data sentinel value.
+     */
+    set_nodata(v: number): void;
+    /**
+     * Convenience: north-up geo-transform from upper-left origin and pixel size.
+     */
+    set_origin(x_min: number, y_max: number, pixel_size: number): void;
+    /**
+     * Explicit overview decimation factors (e.g. `[2,4,8]`); empty disables overviews.
+     */
+    set_overview_levels(levels: Uint32Array): void;
+    /**
+     * Internal tile size in pixels (default 512).
+     */
+    set_tile_size(px: number): void;
+    /**
+     * Encode `f32` pixel data to a COG. `Uint8Array`.
+     */
+    write_f32(data: Float32Array): Uint8Array;
+    /**
+     * Encode `f64` pixel data to a COG. `Uint8Array`.
+     */
+    write_f64(data: Float64Array): Uint8Array;
+    /**
+     * Encode `u8` pixel data to a COG. `Uint8Array`.
+     */
+    write_u8(data: Uint8Array): Uint8Array;
+}
 
 /**
- * Decode a GeoTIFF from raw bytes and return summary statistics as a JSON string.
+ * Range-request reader for a (tiled) Cloud Optimized GeoTIFF.
  *
- * The returned JSON has the shape:
- * `{"ok":true,"width":W,"height":H,"bands":B,"epsg":E|null,"valid":N,
- *   "min":..,"max":..,"mean":..}` on success, or
- * `{"ok":false,"error":"..."}` on failure.
+ * The wasm module does no network I/O itself; this class parses the header and
+ * tells the JS host exactly which byte ranges to fetch, then decodes the tiles
+ * the host fetches. Typical flow:
+ *
+ * 1. Range-fetch the first chunk of the file (e.g. 0..1 MiB) and
+ *    `new CogStream(headerBytes)`. If it throws "need more header bytes", fetch
+ *    a larger prefix and retry.
+ * 2. Pick a level (0 = full res, higher = overviews) and a pixel window.
+ * 3. `tiles_for_window(level, x, y, w, h)` returns the tiles and their byte
+ *    ranges; range-fetch each, then `decode_tile_f64(level, bytes)`.
+ */
+export class CogStream {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Bounding box `[min_x, min_y, max_x, max_y]` in the dataset CRS, or empty.
+     */
+    bounding_box(): Float64Array;
+    /**
+     * Bounds `[min_lon, min_lat, max_lon, max_lat]` in WGS84 degrees, or empty.
+     */
+    bounds_lonlat(): Float64Array;
+    /**
+     * Image center `[x, y]` in the dataset CRS, or empty.
+     */
+    center(): Float64Array;
+    /**
+     * Image center `[lon, lat]` in WGS84 degrees, or empty if not convertible.
+     */
+    center_lonlat(): Float64Array;
+    /**
+     * Decode one tile's fetched (compressed) bytes into an `f64` `Float64Array`,
+     * pixel-interleaved, length `tile_width * tile_height * bands`. Edge tiles
+     * come back full-size; clip to the image/window on the JS side.
+     */
+    decode_tile_f64(level: number, tile_bytes: Uint8Array): Float64Array;
+    /**
+     * Level-0 geo-transform `[x_origin, pixel_width, row_rot, y_origin, col_rot,
+     * pixel_height]`, or empty if not georeferenced.
+     */
+    geo_transform(): Float64Array;
+    /**
+     * JSON array describing every level: `[{level,width,height,tile_width,
+     * tile_height,tiles_x,tiles_y,bands,bits_per_sample,sample_format,compression}]`.
+     */
+    levels_json(): string;
+    /**
+     * Parse a COG's tile layout from front-of-file header bytes.
+     */
+    constructor(header_bytes: Uint8Array);
+    /**
+     * `[offset, length]` byte range of the tile at `(col, row)` on `level`.
+     */
+    tile_range(level: number, col: number, row: number): Float64Array;
+    /**
+     * Tiles covering a pixel window on `level`, as a JSON array of
+     * `{col,row,offset,length}`. Fetch each byte range, then `decode_tile_f64`.
+     */
+    tiles_for_window(level: number, x: number, y: number, w: number, h: number): string;
+    /**
+     * EPSG code of the full-resolution level, if any.
+     */
+    readonly epsg: number | undefined;
+    /**
+     * No-data sentinel, if declared.
+     */
+    readonly nodata: number | undefined;
+    /**
+     * Number of resolution levels (1 + overview count).
+     */
+    readonly num_levels: number;
+}
+
+/**
+ * A parsed GeoTIFF held in memory. Construct once, then call the accessor and
+ * `read_*` methods many times without re-parsing the file.
+ */
+export class GeoTiffReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Bounding box as `[min_x, min_y, max_x, max_y]`, or empty if not georeferenced.
+     */
+    bounding_box(): Float64Array;
+    /**
+     * Bounds `[min_lon, min_lat, max_lon, max_lat]` in WGS84 degrees, or empty
+     * if not convertible.
+     */
+    bounds_lonlat(): Float64Array;
+    /**
+     * Image center `[x, y]` in the dataset CRS, or empty if not georeferenced.
+     */
+    center(): Float64Array;
+    /**
+     * Image center `[lon, lat]` in WGS84 degrees, or empty if not georeferenced
+     * or the CRS is not convertible.
+     */
+    center_lonlat(): Float64Array;
+    /**
+     * Affine geo-transform as `[x_origin, pixel_width, row_rotation,
+     * y_origin, col_rotation, pixel_height]`, or an empty array if absent.
+     */
+    geo_transform(): Float64Array;
+    /**
+     * Full metadata as a JSON string (same shape as [`geotiff_info`]).
+     */
+    info_json(): string;
+    /**
+     * Parse a GeoTIFF / BigTIFF / COG from raw bytes.
+     */
+    constructor(data: Uint8Array);
+    /**
+     * Read every band as `f64`, interleaved per pixel (`band0,band1,...`).
+     */
+    read_all_f64(): Float64Array;
+    /**
+     * Read a band's raw, undecoded-to-native bytes. `Uint8Array`.
+     */
+    read_band_bytes(band: number): Uint8Array;
+    /**
+     * Native `f32` band. `Float32Array`.
+     */
+    read_band_f32(band: number): Float32Array;
+    /**
+     * Read a band as `f64`, converting from any on-disk type. `Float64Array`.
+     */
+    read_band_f64(band: number): Float64Array;
+    /**
+     * Native `i16` band. `Int16Array`.
+     */
+    read_band_i16(band: number): Int16Array;
+    /**
+     * Native `i32` band. `Int32Array`.
+     */
+    read_band_i32(band: number): Int32Array;
+    /**
+     * Native `i8` band. `Int8Array`.
+     */
+    read_band_i8(band: number): Int8Array;
+    /**
+     * Native `u16` band. `Uint16Array`.
+     */
+    read_band_u16(band: number): Uint16Array;
+    /**
+     * Native `u32` band. `Uint32Array`.
+     */
+    read_band_u32(band: number): Uint32Array;
+    /**
+     * Native `u8` band. `Uint8Array`.
+     */
+    read_band_u8(band: number): Uint8Array;
+    /**
+     * Band-0 statistics as a JSON string (same shape as [`geotiff_stats`]).
+     */
+    stats_json(): string;
+    /**
+     * GDAL value transform as `[scale, offset]` (physical = raw*scale+offset),
+     * or empty if none. Apply to `read_*` outputs to get physical values.
+     */
+    value_transform(): Float64Array;
+    readonly bands: number;
+    readonly bits_per_sample: number;
+    readonly compression: string;
+    /**
+     * EPSG code, or `undefined` if the file is not georeferenced by EPSG.
+     */
+    readonly epsg: number | undefined;
+    readonly height: number;
+    readonly is_bigtiff: boolean;
+    /**
+     * No-data sentinel, or `undefined` if none is declared.
+     */
+    readonly nodata: number | undefined;
+    readonly sample_format: string;
+    readonly width: number;
+}
+
+/**
+ * Install a panic hook so Rust panics surface as readable `console.error`
+ * messages instead of an opaque `RuntimeError: unreachable`.
+ */
+export function __start(): void;
+
+/**
+ * Decode only a GeoTIFF's header and return its metadata as JSON. O(header)
+ * memory, so it works on multi-gigabyte rasters that whole-image reads cannot
+ * fit in WASM's 4 GiB address space.
  *
- * Statistics are computed over band 0, skipping NaN and the nodata value.
+ * `{"ok":true,"width","height","bands","epsg"|null,"nodata"|null,
+ *   "bits_per_sample","sample_format","compression","tiled","bigtiff"}`
+ */
+export function geotiff_info(data: Uint8Array): string;
+
+/**
+ * Read a single band of pixel values as an `f64` `Float64Array` (any on-disk
+ * sample format is converted), row-major, length `width * height`.
+ */
+export function geotiff_read_band_f64(data: Uint8Array, band: number): Float64Array;
+
+/**
+ * Decode a GeoTIFF and return band-0 summary statistics as JSON:
+ * `{"ok":true,"width","height","bands","epsg","valid","min","max","mean"}`.
  */
 export function geotiff_stats(data: Uint8Array): string;
 
@@ -28,12 +279,72 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly __wbg_cogbuilder_free: (a: number, b: number) => void;
+    readonly __wbg_cogstream_free: (a: number, b: number) => void;
+    readonly __wbg_geotiffreader_free: (a: number, b: number) => void;
+    readonly cogbuilder_new: (a: number, b: number, c: number) => number;
+    readonly cogbuilder_set_bigtiff: (a: number, b: number) => void;
+    readonly cogbuilder_set_compression: (a: number, b: number, c: number, d: number) => void;
+    readonly cogbuilder_set_epsg: (a: number, b: number) => void;
+    readonly cogbuilder_set_geo_transform: (a: number, b: number, c: number, d: number) => void;
+    readonly cogbuilder_set_nodata: (a: number, b: number) => void;
+    readonly cogbuilder_set_origin: (a: number, b: number, c: number, d: number) => void;
+    readonly cogbuilder_set_overview_levels: (a: number, b: number, c: number) => void;
+    readonly cogbuilder_set_tile_size: (a: number, b: number) => void;
+    readonly cogbuilder_write_f32: (a: number, b: number, c: number, d: number) => void;
+    readonly cogbuilder_write_f64: (a: number, b: number, c: number, d: number) => void;
+    readonly cogbuilder_write_u8: (a: number, b: number, c: number, d: number) => void;
+    readonly cogstream_bounding_box: (a: number, b: number) => void;
+    readonly cogstream_bounds_lonlat: (a: number, b: number) => void;
+    readonly cogstream_center: (a: number, b: number) => void;
+    readonly cogstream_center_lonlat: (a: number, b: number) => void;
+    readonly cogstream_decode_tile_f64: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly cogstream_epsg: (a: number) => number;
+    readonly cogstream_geo_transform: (a: number, b: number) => void;
+    readonly cogstream_levels_json: (a: number, b: number) => void;
+    readonly cogstream_new: (a: number, b: number, c: number) => void;
+    readonly cogstream_nodata: (a: number, b: number) => void;
+    readonly cogstream_num_levels: (a: number) => number;
+    readonly cogstream_tile_range: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly cogstream_tiles_for_window: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly geotiff_info: (a: number, b: number, c: number) => void;
+    readonly geotiff_read_band_f64: (a: number, b: number, c: number, d: number) => void;
     readonly geotiff_stats: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_bands: (a: number) => number;
+    readonly geotiffreader_bits_per_sample: (a: number) => number;
+    readonly geotiffreader_bounding_box: (a: number, b: number) => void;
+    readonly geotiffreader_bounds_lonlat: (a: number, b: number) => void;
+    readonly geotiffreader_center: (a: number, b: number) => void;
+    readonly geotiffreader_center_lonlat: (a: number, b: number) => void;
+    readonly geotiffreader_compression: (a: number, b: number) => void;
+    readonly geotiffreader_epsg: (a: number) => number;
+    readonly geotiffreader_geo_transform: (a: number, b: number) => void;
+    readonly geotiffreader_height: (a: number) => number;
+    readonly geotiffreader_info_json: (a: number, b: number) => void;
+    readonly geotiffreader_is_bigtiff: (a: number) => number;
+    readonly geotiffreader_new: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_nodata: (a: number, b: number) => void;
+    readonly geotiffreader_read_all_f64: (a: number, b: number) => void;
+    readonly geotiffreader_read_band_bytes: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_read_band_f32: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_read_band_f64: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_read_band_i16: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_read_band_i32: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_read_band_i8: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_read_band_u16: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_read_band_u32: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_read_band_u8: (a: number, b: number, c: number) => void;
+    readonly geotiffreader_sample_format: (a: number, b: number) => void;
+    readonly geotiffreader_stats_json: (a: number, b: number) => void;
+    readonly geotiffreader_value_transform: (a: number, b: number) => void;
+    readonly geotiffreader_width: (a: number) => number;
     readonly version: (a: number) => void;
+    readonly __start: () => void;
+    readonly __wbindgen_export: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export2: (a: number, b: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
-    readonly __wbindgen_export: (a: number, b: number) => number;
-    readonly __wbindgen_export2: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
 }
 
 export type SyncInitInput = BufferSource | WebAssembly.Module;