whitebox-wasm 0.5.1 → 0.6.0

package/README.md

@@ -126,12 +126,42 @@ for (const t of tiles) {
 
 - `new CogStream(headerBytes)` - parse the IFD chain + tile index (throws if the
   prefix is too short; fetch more and retry).
+- `first_ifd_offset(headerBytes)` - where the directory actually is (see below).
+- `CogStream.from_windows(prefix, tailOffset, tail)` - parse from a front prefix
+  plus a window elsewhere in the file.
 - `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)
 
+#### Plain GeoTIFFs, whose directory sits at the end
+
+A COG keeps every IFD at the front of the file, so a 64 KB prefix reaches it. A
+**plain** GeoTIFF - what GDAL and libtiff write unless you ask for a COG - puts
+the directory *after* the pixel data, so growing a front-of-file prefix can only
+reach it by downloading the entire file. Read the offset first and fetch that
+region instead:
+
+```js
+import init, { CogStream, first_ifd_offset } from "whitebox-wasm";
+
+// An open-ended `Range: bytes=N-` asks for everything from N to the end, so the
+// file's length never has to be looked up.
+const range = (a, b) => fetch(url, { headers: { Range: `bytes=${a}-${b ?? ""}` } })
+  .then(r => r.arrayBuffer()).then(b => new Uint8Array(b));
+
+const prefix = await range(0, 16383);
+const ifd = first_ifd_offset(prefix);          // 74026916 on a 74 MB file
+const stream = ifd < prefix.length
+  ? new CogStream(prefix)                      // COG: it is already in hand
+  : CogStream.from_windows(prefix, ifd, await range(ifd));
+```
+
+That reads under 1 MB of a 74 MB raster. If a tag array happens to sit *before*
+the directory, `from_windows` throws `need more header bytes at offset N`; start
+the tail earlier and retry.
+
 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

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.5.1",
+  "version": "0.6.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",

package/whitebox_wasm.d.ts

@@ -75,6 +75,11 @@ export class CogBuilder {
  * 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)`.
+ *
+ * A *plain* (non-COG) GeoTIFF, as GDAL and libtiff write one by default, keeps
+ * its directory at the **end** of the file, so no front-of-file prefix short of
+ * the whole file can reach it. Use `first_ifd_offset` to locate the directory
+ * and `CogStream.from_windows` to parse it from a small tail window.
  */
 export class CogStream {
     free(): void;
@@ -101,6 +106,19 @@ export class CogStream {
      * come back full-size; clip to the image/window on the JS side.
      */
     decode_tile_f64(level: number, tile_bytes: Uint8Array): Float64Array;
+    /**
+     * Parse the tile layout from two disjoint windows of the file: a
+     * front-of-file `prefix` and a `tail` starting at absolute byte offset
+     * `tail_offset`.
+     *
+     * This is the path for a plain GeoTIFF whose directory sits at the end of
+     * the file. Fetch the first few kilobytes plus the region from
+     * `first_ifd_offset` to the end and pass both; the bytes in between are
+     * pixel data that header parsing never reads. If a tag array happens to sit
+     * *before* the directory, this throws "need more header bytes at offset N" —
+     * widen the tail to cover N and retry.
+     */
+    static from_windows(prefix: Uint8Array, tail_offset: number, tail: Uint8Array): CogStream;
     /**
      * Level-0 geo-transform `[x_origin, pixel_width, row_rot, y_origin, col_rot,
      * pixel_height]`, or empty if not georeferenced.
@@ -254,6 +272,17 @@ export function __start(): void;
  */
 export function convex_hull(points_xy: Float64Array): Float64Array;
 
+/**
+ * Offset of a GeoTIFF's first IFD, read from the file's first 8 (classic TIFF)
+ * or 16 (BigTIFF) bytes. An offset past the prefix you already hold means the
+ * directory lives further into the file: fetch that region and hand it to
+ * `CogStream.from_windows`.
+ *
+ * Throws on an offset a JS number cannot hold exactly, which only a corrupt
+ * header produces: passing it back would address the wrong bytes.
+ */
+export function first_ifd_offset(header_bytes: Uint8Array): number;
+
 /**
  * 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
@@ -376,6 +405,7 @@ export interface InitOutput {
     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_from_windows: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     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;
@@ -384,6 +414,7 @@ export interface InitOutput {
     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 convex_hull: (a: number, b: number, c: number) => void;
+    readonly first_ifd_offset: (a: number, b: number, c: 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;

package/whitebox_wasm.js

@@ -206,8 +206,19 @@ if (Symbol.dispose) CogBuilder.prototype[Symbol.dispose] = CogBuilder.prototype.
  * 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)`.
+ *
+ * A *plain* (non-COG) GeoTIFF, as GDAL and libtiff write one by default, keeps
+ * its directory at the **end** of the file, so no front-of-file prefix short of
+ * the whole file can reach it. Use `first_ifd_offset` to locate the directory
+ * and `CogStream.from_windows` to parse it from a small tail window.
  */
 export class CogStream {
+    static __wrap(ptr) {
+        const obj = Object.create(CogStream.prototype);
+        obj.__wbg_ptr = ptr;
+        CogStreamFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
     __destroy_into_raw() {
         const ptr = this.__wbg_ptr;
         this.__wbg_ptr = 0;
@@ -322,6 +333,41 @@ export class CogStream {
         const ret = wasm.cogstream_epsg(this.__wbg_ptr);
         return ret === Number.MAX_SAFE_INTEGER ? undefined : ret;
     }
+    /**
+     * Parse the tile layout from two disjoint windows of the file: a
+     * front-of-file `prefix` and a `tail` starting at absolute byte offset
+     * `tail_offset`.
+     *
+     * This is the path for a plain GeoTIFF whose directory sits at the end of
+     * the file. Fetch the first few kilobytes plus the region from
+     * `first_ifd_offset` to the end and pass both; the bytes in between are
+     * pixel data that header parsing never reads. If a tag array happens to sit
+     * *before* the directory, this throws "need more header bytes at offset N" —
+     * widen the tail to cover N and retry.
+     * @param {Uint8Array} prefix
+     * @param {number} tail_offset
+     * @param {Uint8Array} tail
+     * @returns {CogStream}
+     */
+    static from_windows(prefix, tail_offset, tail) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passArray8ToWasm0(prefix, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passArray8ToWasm0(tail, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.cogstream_from_windows(retptr, ptr0, len0, tail_offset, ptr1, len1);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return CogStream.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Level-0 geo-transform `[x_origin, pixel_width, row_rot, y_origin, col_rot,
      * pixel_height]`, or empty if not georeferenced.
@@ -1016,6 +1062,35 @@ export function convex_hull(points_xy) {
     }
 }
 
+/**
+ * Offset of a GeoTIFF's first IFD, read from the file's first 8 (classic TIFF)
+ * or 16 (BigTIFF) bytes. An offset past the prefix you already hold means the
+ * directory lives further into the file: fetch that region and hand it to
+ * `CogStream.from_windows`.
+ *
+ * Throws on an offset a JS number cannot hold exactly, which only a corrupt
+ * header produces: passing it back would address the wrong bytes.
+ * @param {Uint8Array} header_bytes
+ * @returns {number}
+ */
+export function first_ifd_offset(header_bytes) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passArray8ToWasm0(header_bytes, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.first_ifd_offset(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getFloat64(retptr + 8 * 0, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        if (r3) {
+            throw takeObject(r2);
+        }
+        return r0;
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
 /**
  * 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