cog-tiler-wasm 0.1.0

package/cog-tiler.d.ts

@@ -0,0 +1,73 @@
+/**
+ * cog-tiler-wasm - reusable client-side COG tiling for MapLibre/Leaflet.
+ * High-level wrapper over the wasm `CogTiler` + whitebox-wasm `CogStream`.
+ */
+
+export interface RenderOptions {
+  /** Low end of the rescale range (continuous bands). Default 0. */
+  min?: number;
+  /** High end of the rescale range (continuous bands). Default 1. */
+  max?: number;
+  /** Colormap name: "viridis" | "magma" | "terrain" | "gray". Default "viridis". */
+  colormap?: string;
+}
+
+/** A level descriptor from `CogStream.levels_json()`. */
+export interface LevelInfo {
+  level: number;
+  width: number;
+  height: number;
+  tile_width: number;
+  tile_height: number;
+  tiles_x: number;
+  tiles_y: number;
+  bands: number;
+  bits_per_sample: number;
+  sample_format: string;
+  compression: string;
+}
+
+/** An opened COG; renders XYZ tiles in either the 3857 or warp path. */
+export declare class CogSource {
+  /** "3857" (fast affine path) or "warp" (reprojected on the fly). */
+  readonly mode: "3857" | "warp";
+  /** Human-readable CRS label, e.g. "EPSG:3857" or "warped from +proj=aea". */
+  readonly crsLabel: string;
+  /** Overview levels, finest first. */
+  readonly levels: LevelInfo[];
+  /** WGS84 bounds [minLon, minLat, maxLon, maxLat] for fitBounds. */
+  readonly boundsLonLat: number[];
+  /** True when the band is paletted (categorical) and rendered via its table. */
+  readonly hasPalette: boolean;
+  /** Render an XYZ tile to a 256x256 RGBA buffer, or null if empty. */
+  renderTileRGBA(z: number, x: number, y: number, opts?: RenderOptions): Promise<Uint8ClampedArray | null>;
+  /** Render an XYZ tile to PNG bytes (empty Uint8Array for a blank tile). */
+  renderTilePNG(z: number, x: number, y: number, opts?: RenderOptions): Promise<Uint8Array>;
+}
+
+/** Initialize the wasm modules (idempotent). Resolve before `openCog`. */
+export declare function init(): Promise<unknown>;
+
+/** Open a COG and return a {@link CogSource} ready to render XYZ tiles. */
+export declare function openCog(url: string): Promise<CogSource>;
+
+/** Encode a 256x256 RGBA buffer to PNG bytes (browser; uses OffscreenCanvas). */
+export declare function rgbaToPng(rgba: Uint8Array | Uint8ClampedArray): Promise<Uint8Array>;
+
+/** Minimal shape of the maplibre-gl module needed to register a protocol. */
+export interface MapLibreLike {
+  addProtocol(
+    name: string,
+    handler: (params: { url: string }) => Promise<{ data: Uint8Array }>,
+  ): void;
+}
+
+/**
+ * Register a MapLibre custom protocol (e.g. `cog://{z}/{x}/{y}`). `resolve()` is
+ * called per tile and returns the active source + render settings.
+ */
+export declare function registerCogProtocol(
+  maplibregl: MapLibreLike,
+  name: string,
+  resolve: () => { source: CogSource | null; render?: RenderOptions } | null,
+): void;

package/cog-tiler.js

@@ -0,0 +1,358 @@
+/**
+ * cog-tiler-wasm - reusable, client-side COG tiling for MapLibre/Leaflet.
+ *
+ * Wraps whitebox-wasm (`CogStream`: pure-Rust COG decode + HTTP range reads) and
+ * this repo's `CogTiler` (Web Mercator math + rescale/colormap render) into a
+ * tiler that:
+ *   - serves EPSG:3857 COGs directly (fast affine path), and
+ *   - warps any other projected / EPSG:4326 COG to Web Mercator on the fly,
+ *     rendering paletted (categorical) bands through their color table.
+ *
+ * Dependencies are bare module specifiers - provide them through your bundler
+ * (as peer dependencies) or an import map:
+ *   whitebox-wasm, proj4, geotiff, geotiff-geokeys-to-proj4
+ * The wasm package (`cog_tiler_wasm.js` + `_bg.wasm`) must sit next to this file.
+ *
+ * Usage:
+ *   import { init, openCog, registerCogProtocol } from "./cog-tiler.js";
+ *   await init();
+ *   const src = await openCog(url);
+ *   registerCogProtocol(maplibregl, "cog", () => ({ source: src, render: { min, max, colormap } }));
+ *   map.addSource("cog", { type: "raster", tiles: ["cog://{z}/{x}/{y}"], tileSize: 256 });
+ */
+import initWhitebox, { CogStream } from "whitebox-wasm";
+import initTiler, { CogTiler } from "./cog_tiler_wasm.js";
+import proj4 from "proj4";
+import * as GeoTIFF from "geotiff";
+import geokeysToProj4 from "geotiff-geokeys-to-proj4";
+
+const OS = 20037508.342789244; // Web Mercator half-extent (m)
+const TILE = 256; // output tile size (px)
+const NG = 16; // warp grid cells per axis
+const MAX_CACHED_TILES = 256; // ~0.5 MB each at 256x256 f64
+
+proj4.defs(
+  "EPSG:3857",
+  "+proj=merc +a=6378137 +b=6378137 +lat_ts=0 +lon_0=0 +x_0=0 +y_0=0 +k=1 +units=m +nadgrids=@null +wktext +no_defs",
+);
+
+let _ready = null;
+/** Initialize the wasm modules (idempotent). Resolve this before `openCog`. */
+export function init() {
+  if (!_ready) _ready = Promise.all([initWhitebox(), initTiler()]);
+  return _ready;
+}
+
+/** EPSG:3857 bounds [minx,miny,maxx,maxy] of an XYZ tile. */
+function tileBounds3857(z, x, y) {
+  const span = (2 * OS) / 2 ** z;
+  return [-OS + x * span, OS - (y + 1) * span, -OS + (x + 1) * span, OS - y * span];
+}
+
+const rangeFetcher = (url) => (a, b) =>
+  fetch(url, { headers: { Range: `bytes=${a}-${b}` } })
+    .then((r) => r.arrayBuffer())
+    .then((b) => new Uint8Array(b));
+
+/** Build a 256-entry RGBA palette from a TIFF ColorMap (16-bit R,G,B blocks). */
+function buildPalette(colorMap) {
+  if (!colorMap) return null;
+  const n = colorMap.length / 3;
+  const pal = new Uint8ClampedArray(256 * 4);
+  for (let i = 0; i < 256 && i < n; i++) {
+    pal[i * 4] = colorMap[i] >> 8;
+    pal[i * 4 + 1] = colorMap[n + i] >> 8;
+    pal[i * 4 + 2] = colorMap[2 * n + i] >> 8;
+    pal[i * 4 + 3] = 255;
+  }
+  return pal;
+}
+
+function bilin(v00, v10, v01, v11, tx, ty) {
+  if (!isFinite(v00) || !isFinite(v10) || !isFinite(v01) || !isFinite(v11)) {
+    return isFinite(v00) ? v00 : NaN; // near projection edges
+  }
+  const top = v00 + (v10 - v00) * tx, bot = v01 + (v11 - v01) * tx;
+  return top + (bot - top) * ty;
+}
+
+/**
+ * Open a COG and return a {@link CogSource} ready to render XYZ tiles.
+ * Detects EPSG:3857 (fast path) vs. any other CRS (warp path), and reads the
+ * source projection + color table from the GeoTIFF header (whitebox-wasm 0.4.0
+ * does not expose them).
+ */
+export async function openCog(url) {
+  await init();
+  const range = rangeFetcher(url);
+  // Parse the COG header; grow the prefix and retry for large COGs whose IFDs
+  // exceed 64 KB (many overviews / huge tile-offset arrays).
+  let stream;
+  for (let len = 65536; ; len *= 8) {
+    try {
+      stream = new CogStream(await range(0, len - 1));
+      break;
+    } catch (e) {
+      if (len >= 1 << 25) throw e; // give up past ~32 MB
+    }
+  }
+  const gt = stream.geo_transform(); // [x0, px_w, rot, y0, rot, px_h]
+  const levels = JSON.parse(stream.levels_json());
+  if (!Array.isArray(levels) || levels.length === 0) {
+    throw new Error("levels_json() returned no levels");
+  }
+  // CogTiler renders an assembled f64 window -> RGBA (rescale + colormap +
+  // nodata). render() ignores the CRS, so we build one in both modes.
+  const tiler = new CogTiler(
+    Float64Array.from(gt),
+    levels[0].width,
+    levels[0].height,
+    3857,
+    stream.nodata,
+    JSON.stringify(levels),
+  );
+  const base = { url, range, stream, tiler, levels, gt, nodata: stream.nodata };
+
+  if (stream.epsg === 3857) {
+    return new CogSource({
+      ...base,
+      mode: "3857",
+      crsLabel: "EPSG:3857",
+      palette: null,
+      boundsLonLat: Array.from(stream.bounds_lonlat()),
+    });
+  }
+
+  // Warp path: read the real source CRS + optional palette from the header.
+  const tiff = await GeoTIFF.fromUrl(url);
+  const img = await tiff.getImage();
+  const srcDef = geokeysToProj4.toProj4(img.getGeoKeys()).proj4;
+  if (!srcDef) throw new Error("could not derive source CRS from GeoTIFF geokeys");
+  const toSource = proj4("EPSG:3857", srcDef); // forward: mercator -> source
+  const toLonLat = proj4(srcDef, "EPSG:4326"); // forward: source -> lon/lat
+  const palette = buildPalette(img.fileDirectory.ColorMap);
+
+  // fitBounds bounds: transform the source corners to lon/lat.
+  const fw = levels[0].width, fh = levels[0].height;
+  const corners = [
+    [gt[0], gt[3]],
+    [gt[0] + fw * gt[1], gt[3]],
+    [gt[0], gt[3] + fh * gt[5]],
+    [gt[0] + fw * gt[1], gt[3] + fh * gt[5]],
+  ].map((c) => toLonLat.forward(c));
+  const lons = corners.map((c) => c[0]), lats = corners.map((c) => c[1]);
+
+  return new CogSource({
+    ...base,
+    mode: "warp",
+    toSource,
+    palette,
+    boundsLonLat: [Math.min(...lons), Math.min(...lats), Math.max(...lons), Math.max(...lats)],
+    crsLabel: "warped from " + (srcDef.match(/\+proj=\w+/) || ["custom CRS"])[0],
+  });
+}
+
+/** A single opened COG. Renders XYZ tiles via {@link CogSource#renderTileRGBA}. */
+export class CogSource {
+  constructor(fields) {
+    Object.assign(this, fields);
+    // Decoded source tiles keyed by "level/col/row"; caching the decode lets
+    // panning/zooming reuse overlapping tiles instead of re-fetching/decoding.
+    this.tileCache = new Map();
+  }
+
+  /** True when the band is paletted (categorical) and rendered via its table. */
+  get hasPalette() {
+    return !!this.palette;
+  }
+
+  /** Render an XYZ tile to a 256x256 RGBA `Uint8ClampedArray`, or null if empty. */
+  async renderTileRGBA(z, x, y, opts = {}) {
+    return this.mode === "warp"
+      ? this._warp(z, x, y, opts)
+      : this._render3857(z, x, y, opts);
+  }
+
+  /** Render an XYZ tile to PNG bytes (empty `Uint8Array` for a blank tile). */
+  async renderTilePNG(z, x, y, opts = {}) {
+    const rgba = await this.renderTileRGBA(z, x, y, opts);
+    return rgba ? rgbaToPng(rgba) : new Uint8Array();
+  }
+
+  // --- internals ------------------------------------------------------------
+
+  _getTile(level, t) {
+    const key = level + "/" + t.col + "/" + t.row;
+    let p = this.tileCache.get(key);
+    if (!p) {
+      p = this.range(t.offset, t.offset + t.length - 1)
+        .then((bytes) => this.stream.decode_tile_f64(level, bytes))
+        .catch((err) => {
+          this.tileCache.delete(key); // don't cache failures; allow retry
+          throw err;
+        });
+      this.tileCache.set(key, p);
+      if (this.tileCache.size > MAX_CACHED_TILES) {
+        this.tileCache.delete(this.tileCache.keys().next().value); // evict oldest
+      }
+    }
+    return p;
+  }
+
+  // Fetch (parallel, cached) + decode the source tiles covering a level pixel
+  // window and assemble them into a row-major f64 buffer (NaN = no data).
+  async _assembleWindow(level, x, y, w, h) {
+    const lv = this.levels[level];
+    const tiles = JSON.parse(this.stream.tiles_for_window(level, x, y, w, h));
+    const decoded = await Promise.all(tiles.map((t) => this._getTile(level, t)));
+    const buf = new Float64Array(w * h).fill(NaN);
+    const tw = lv.tile_width, th = lv.tile_height, bands = lv.bands;
+    tiles.forEach((t, i) => {
+      const px = decoded[i];
+      const tx0 = t.col * tw, ty0 = t.row * th;
+      for (let ry = 0; ry < th; ry++) {
+        const oy = ty0 + ry - y;
+        if (oy < 0 || oy >= h) continue;
+        for (let rx = 0; rx < tw; rx++) {
+          const ox = tx0 + rx - x;
+          if (ox < 0 || ox >= w) continue;
+          buf[oy * w + ox] = px[(ry * tw + rx) * bands]; // band 0
+        }
+      }
+    });
+    return buf;
+  }
+
+  // Choose the overview whose source resolution is the coarsest still finer than
+  // `srcRes` (m/px), avoiding upsampling; finest level otherwise.
+  _chooseLevel(srcRes) {
+    const baseRes = Math.abs(this.gt[1]), fw = this.levels[0].width;
+    let best = -1, bestRes = 0, finest = 0, finestRes = Infinity;
+    this.levels.forEach((lv, i) => {
+      const res = baseRes * (fw / lv.width);
+      if (res < finestRes) { finestRes = res; finest = i; }
+      if (res <= srcRes && res > bestRes) { best = i; bestRes = res; }
+    });
+    return best >= 0 ? best : finest;
+  }
+
+  _levelPixelSize(level) {
+    const lv = this.levels[level], L0 = this.levels[0];
+    return [
+      Math.abs(this.gt[1]) * (L0.width / lv.width),
+      Math.abs(this.gt[5]) * (L0.height / lv.height),
+    ];
+  }
+
+  // Fast path: source already EPSG:3857, so a tile maps affinely to a window.
+  async _render3857(z, x, y, { min = 0, max = 1, colormap = "viridis" } = {}) {
+    const win = this.tiler.pixel_window_for_tile(z, x, y);
+    if (win.empty) return null;
+    const buf = await this._assembleWindow(win.level, win.x, win.y, win.w, win.h);
+    return this.tiler.render(buf, win.w, win.h, min, max, colormap, true);
+  }
+
+  // Warp path: reproject a Web Mercator tile from the source CRS on the fly.
+  // A coarse grid of mercator->source samples (proj4) is bilinearly interpolated
+  // per output pixel, then nearest-sampled from the source window (correct for
+  // categorical data). Paletted sources use the color table; others reuse the
+  // Rust colormap (render resamples 256->256, ~identity).
+  async _warp(z, x, y, { min = 0, max = 1, colormap = "viridis" } = {}) {
+    const tb = tileBounds3857(z, x, y);
+    const nx = new Float64Array((NG + 1) * (NG + 1));
+    const ny = new Float64Array((NG + 1) * (NG + 1));
+    let sminx = Infinity, sminy = Infinity, smaxx = -Infinity, smaxy = -Infinity, any = false;
+    for (let gy = 0; gy <= NG; gy++) {
+      const my = tb[3] - (gy / NG) * (tb[3] - tb[1]);
+      for (let gx = 0; gx <= NG; gx++) {
+        const mx = tb[0] + (gx / NG) * (tb[2] - tb[0]);
+        let s;
+        try { s = this.toSource.forward([mx, my]); } catch { s = [NaN, NaN]; }
+        const i = gy * (NG + 1) + gx;
+        nx[i] = s[0]; ny[i] = s[1];
+        if (isFinite(s[0]) && isFinite(s[1])) {
+          any = true;
+          if (s[0] < sminx) sminx = s[0];
+          if (s[0] > smaxx) smaxx = s[0];
+          if (s[1] < sminy) sminy = s[1];
+          if (s[1] > smaxy) smaxy = s[1];
+        }
+      }
+    }
+    if (!any) return null;
+
+    const level = this._chooseLevel((smaxx - sminx) / TILE);
+    const lv = this.levels[level];
+    const [lpw, lph] = this._levelPixelSize(level);
+    const ox = this.gt[0], oy = this.gt[3];
+    let c0 = Math.floor((sminx - ox) / lpw), c1 = Math.ceil((smaxx - ox) / lpw);
+    let r0 = Math.floor((oy - smaxy) / lph), r1 = Math.ceil((oy - sminy) / lph);
+    c0 = Math.max(0, Math.min(c0, lv.width)); c1 = Math.max(0, Math.min(c1, lv.width));
+    r0 = Math.max(0, Math.min(r0, lv.height)); r1 = Math.max(0, Math.min(r1, lv.height));
+    const ww = c1 - c0, hh = r1 - r0;
+    if (ww <= 0 || hh <= 0) return null;
+    const buf = await this._assembleWindow(level, c0, r0, ww, hh);
+
+    const pal = this.palette;
+    const out = new Uint8ClampedArray(TILE * TILE * 4);
+    const grid = pal ? null : new Float64Array(TILE * TILE).fill(NaN);
+    for (let py = 0; py < TILE; py++) {
+      const fy = (py / TILE) * NG, gy0 = Math.min(NG - 1, Math.floor(fy)), ty = fy - gy0;
+      for (let px = 0; px < TILE; px++) {
+        const fx = (px / TILE) * NG, gx0 = Math.min(NG - 1, Math.floor(fx)), tx = fx - gx0;
+        const i00 = gy0 * (NG + 1) + gx0;
+        const sx = bilin(nx[i00], nx[i00 + 1], nx[i00 + NG + 1], nx[i00 + NG + 2], tx, ty);
+        const sy = bilin(ny[i00], ny[i00 + 1], ny[i00 + NG + 1], ny[i00 + NG + 2], tx, ty);
+        if (!isFinite(sx) || !isFinite(sy)) continue;
+        const col = Math.floor((sx - ox) / lpw) - c0;
+        const row = Math.floor((oy - sy) / lph) - r0;
+        if (col < 0 || col >= ww || row < 0 || row >= hh) continue;
+        const v = buf[row * ww + col];
+        if (!isFinite(v)) continue;
+        if (pal) {
+          const ci = v & 255;
+          if (ci === 0 || (this.nodata != null && v === this.nodata)) continue;
+          const o = (py * TILE + px) * 4;
+          out[o] = pal[ci * 4]; out[o + 1] = pal[ci * 4 + 1];
+          out[o + 2] = pal[ci * 4 + 2]; out[o + 3] = 255;
+        } else {
+          grid[py * TILE + px] = v;
+        }
+      }
+    }
+    if (pal) return out;
+    return this.tiler.render(grid, TILE, TILE, min, max, colormap, true);
+  }
+}
+
+/** Encode a 256x256 RGBA buffer to PNG bytes (browser; uses OffscreenCanvas). */
+export async function rgbaToPng(rgba) {
+  const img = new ImageData(new Uint8ClampedArray(rgba), TILE, TILE);
+  const cv = new OffscreenCanvas(TILE, TILE);
+  cv.getContext("2d").putImageData(img, 0, 0);
+  const blob = await cv.convertToBlob({ type: "image/png" });
+  return new Uint8Array(await blob.arrayBuffer());
+}
+
+/**
+ * Register a MapLibre custom protocol (e.g. `cog://{z}/{x}/{y}`).
+ * `resolve()` is called per tile and returns `{ source, render }`, where
+ * `source` is a {@link CogSource} and `render` is `{ min, max, colormap }`.
+ */
+export function registerCogProtocol(maplibregl, name, resolve) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // literal protocol name
+  const re = new RegExp(`${escaped}://(\\d+)/(\\d+)/(\\d+)`);
+  maplibregl.addProtocol(name, async (params) => {
+    const ctx = resolve();
+    if (!ctx || !ctx.source) return { data: new Uint8Array() };
+    const m = params.url.match(re);
+    if (!m) return { data: new Uint8Array() };
+    const [z, x, y] = m.slice(1).map(Number);
+    try {
+      return { data: await ctx.source.renderTilePNG(z, x, y, ctx.render || {}) };
+    } catch (e) {
+      console.error(name, "tile", z, x, y, e);
+      return { data: new Uint8Array() };
+    }
+  });
+}

package/cog_tiler_wasm.d.ts

@@ -0,0 +1,101 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Tiling engine for a single COG.
+ */
+export class CogTiler {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Build a tiler from COG metadata (all of which `CogStream` exposes).
+     *
+     * * `geo_transform` - 6-element GDAL affine transform of the full-res raster.
+     * * `width` / `height` - full-resolution pixel dimensions.
+     * * `epsg` - source CRS code; must be `3857` in v1.
+     * * `nodata` - optional nodata value (pass `NaN`/`undefined` for none).
+     * * `levels_json` - JSON array of `{ "width", "height" }`, finest first,
+     *   e.g. `[{"width":8192,"height":8192},{"width":4096,"height":4096}]`.
+     */
+    constructor(geo_transform: Float64Array, width: number, height: number, epsg: number, nodata: number | null | undefined, levels_json: string);
+    /**
+     * Map an XYZ tile to the overview level and pixel window that cover it.
+     *
+     * Returns a [`PixelWindow`] (as a JS object). When the tile lies outside
+     * the raster, `empty` is `true` and `w == h == 0`. Errors if the source is
+     * not EPSG:3857 (v1 limitation).
+     */
+    pixel_window_for_tile(z: number, x: number, y: number): any;
+    /**
+     * Render a decoded source window into a 256x256 RGBA tile.
+     *
+     * * `pixels` - row-major `f64` window of size `win_w * win_h`, as returned
+     *   by assembling `CogStream.decode_tile_f64` outputs over the window from
+     *   [`Self::pixel_window_for_tile`].
+     * * `min` / `max` - rescale range mapped to the colormap's `[0, 1]`.
+     * * `colormap` - `"viridis"`, `"magma"`, `"terrain"`, or `"gray"`.
+     * * `nodata_alpha` - when `true`, nodata pixels become fully transparent.
+     *
+     * Returns `256 * 256 * 4` bytes (RGBA). An empty window (`win_w == 0`)
+     * yields a fully transparent tile.
+     */
+    render(pixels: Float64Array, win_w: number, win_h: number, min: number, max: number, colormap: string, nodata_alpha: boolean): Uint8Array;
+    /**
+     * Source CRS EPSG code.
+     */
+    readonly epsg: number;
+    /**
+     * Number of overview levels (including full resolution).
+     */
+    readonly num_levels: number;
+}
+
+/**
+ * EPSG:3857 bounds `[min_x, min_y, max_x, max_y]` of an XYZ tile.
+ */
+export function tile_bounds_3857(z: number, x: number, y: number): Float64Array;
+
+/**
+ * Crate version (from `Cargo.toml`).
+ */
+export function version(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_cogtiler_free: (a: number, b: number) => void;
+    readonly cogtiler_epsg: (a: number) => number;
+    readonly cogtiler_new: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
+    readonly cogtiler_num_levels: (a: number) => number;
+    readonly cogtiler_pixel_window_for_tile: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly cogtiler_render: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
+    readonly tile_bounds_3857: (a: number, b: number, c: number, d: number) => void;
+    readonly version: (a: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;

package/cog_tiler_wasm.js

@@ -0,0 +1,470 @@
+/* @ts-self-types="./cog_tiler_wasm.d.ts" */
+
+/**
+ * Tiling engine for a single COG.
+ */
+export class CogTiler {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        CogTilerFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_cogtiler_free(ptr, 0);
+    }
+    /**
+     * Source CRS EPSG code.
+     * @returns {number}
+     */
+    get epsg() {
+        const ret = wasm.cogtiler_epsg(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Build a tiler from COG metadata (all of which `CogStream` exposes).
+     *
+     * * `geo_transform` - 6-element GDAL affine transform of the full-res raster.
+     * * `width` / `height` - full-resolution pixel dimensions.
+     * * `epsg` - source CRS code; must be `3857` in v1.
+     * * `nodata` - optional nodata value (pass `NaN`/`undefined` for none).
+     * * `levels_json` - JSON array of `{ "width", "height" }`, finest first,
+     *   e.g. `[{"width":8192,"height":8192},{"width":4096,"height":4096}]`.
+     * @param {Float64Array} geo_transform
+     * @param {number} width
+     * @param {number} height
+     * @param {number} epsg
+     * @param {number | null | undefined} nodata
+     * @param {string} levels_json
+     */
+    constructor(geo_transform, width, height, epsg, nodata, levels_json) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passArrayF64ToWasm0(geo_transform, wasm.__wbindgen_export);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(levels_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.cogtiler_new(retptr, ptr0, len0, width, height, epsg, !isLikeNone(nodata), isLikeNone(nodata) ? 0 : nodata, 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);
+            }
+            this.__wbg_ptr = r0;
+            CogTilerFinalization.register(this, this.__wbg_ptr, this);
+            return this;
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Number of overview levels (including full resolution).
+     * @returns {number}
+     */
+    get num_levels() {
+        const ret = wasm.cogtiler_num_levels(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Map an XYZ tile to the overview level and pixel window that cover it.
+     *
+     * Returns a [`PixelWindow`] (as a JS object). When the tile lies outside
+     * the raster, `empty` is `true` and `w == h == 0`. Errors if the source is
+     * not EPSG:3857 (v1 limitation).
+     * @param {number} z
+     * @param {number} x
+     * @param {number} y
+     * @returns {any}
+     */
+    pixel_window_for_tile(z, x, y) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.cogtiler_pixel_window_for_tile(retptr, this.__wbg_ptr, z, x, y);
+            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 takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Render a decoded source window into a 256x256 RGBA tile.
+     *
+     * * `pixels` - row-major `f64` window of size `win_w * win_h`, as returned
+     *   by assembling `CogStream.decode_tile_f64` outputs over the window from
+     *   [`Self::pixel_window_for_tile`].
+     * * `min` / `max` - rescale range mapped to the colormap's `[0, 1]`.
+     * * `colormap` - `"viridis"`, `"magma"`, `"terrain"`, or `"gray"`.
+     * * `nodata_alpha` - when `true`, nodata pixels become fully transparent.
+     *
+     * Returns `256 * 256 * 4` bytes (RGBA). An empty window (`win_w == 0`)
+     * yields a fully transparent tile.
+     * @param {Float64Array} pixels
+     * @param {number} win_w
+     * @param {number} win_h
+     * @param {number} min
+     * @param {number} max
+     * @param {string} colormap
+     * @param {boolean} nodata_alpha
+     * @returns {Uint8Array}
+     */
+    render(pixels, win_w, win_h, min, max, colormap, nodata_alpha) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passArrayF64ToWasm0(pixels, wasm.__wbindgen_export);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(colormap, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.cogtiler_render(retptr, this.__wbg_ptr, ptr0, len0, win_w, win_h, min, max, ptr1, len1, nodata_alpha);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var v3 = getArrayU8FromWasm0(r0, r1).slice();
+            wasm.__wbindgen_export3(r0, r1 * 1, 1);
+            return v3;
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+}
+if (Symbol.dispose) CogTiler.prototype[Symbol.dispose] = CogTiler.prototype.free;
+
+/**
+ * EPSG:3857 bounds `[min_x, min_y, max_x, max_y]` of an XYZ tile.
+ * @param {number} z
+ * @param {number} x
+ * @param {number} y
+ * @returns {Float64Array}
+ */
+export function tile_bounds_3857(z, x, y) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.tile_bounds_3857(retptr, z, x, y);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var v1 = getArrayF64FromWasm0(r0, r1).slice();
+        wasm.__wbindgen_export3(r0, r1 * 8, 8);
+        return v1;
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
+/**
+ * Crate version (from `Cargo.toml`).
+ * @returns {string}
+ */
+export function version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.version(retptr);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred1_0 = r0;
+        deferred1_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred1_0, deferred1_1, 1);
+    }
+}
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg_Error_fdd633d4bb5dd76a: function(arg0, arg1) {
+            const ret = Error(getStringFromWasm0(arg0, arg1));
+            return addHeapObject(ret);
+        },
+        __wbg_String_8564e559799eccda: function(arg0, arg1) {
+            const ret = String(getObject(arg1));
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_throw_ea4887a5f8f9a9db: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_new_2e117a478906f062: function() {
+            const ret = new Object();
+            return addHeapObject(ret);
+        },
+        __wbg_set_6be42768c690e380: function(arg0, arg1, arg2) {
+            getObject(arg0)[takeObject(arg1)] = takeObject(arg2);
+        },
+        __wbindgen_cast_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return addHeapObject(ret);
+        },
+        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(String) -> Externref`.
+            const ret = getStringFromWasm0(arg0, arg1);
+            return addHeapObject(ret);
+        },
+        __wbindgen_cast_0000000000000003: function(arg0) {
+            // Cast intrinsic for `U64 -> Externref`.
+            const ret = BigInt.asUintN(64, arg0);
+            return addHeapObject(ret);
+        },
+        __wbindgen_object_clone_ref: function(arg0) {
+            const ret = getObject(arg0);
+            return addHeapObject(ret);
+        },
+        __wbindgen_object_drop_ref: function(arg0) {
+            takeObject(arg0);
+        },
+    };
+    return {
+        __proto__: null,
+        "./cog_tiler_wasm_bg.js": import0,
+    };
+}
+
+const CogTilerFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_cogtiler_free(ptr, 1));
+
+function addHeapObject(obj) {
+    if (heap_next === heap.length) heap.push(heap.length + 1);
+    const idx = heap_next;
+    heap_next = heap[idx];
+
+    heap[idx] = obj;
+    return idx;
+}
+
+function dropObject(idx) {
+    if (idx < 1028) return;
+    heap[idx] = heap_next;
+    heap_next = idx;
+}
+
+function getArrayF64FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getFloat64ArrayMemory0().subarray(ptr / 8, ptr / 8 + len);
+}
+
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+let cachedFloat64ArrayMemory0 = null;
+function getFloat64ArrayMemory0() {
+    if (cachedFloat64ArrayMemory0 === null || cachedFloat64ArrayMemory0.byteLength === 0) {
+        cachedFloat64ArrayMemory0 = new Float64Array(wasm.memory.buffer);
+    }
+    return cachedFloat64ArrayMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function getObject(idx) { return heap[idx]; }
+
+let heap = new Array(1024).fill(undefined);
+heap.push(undefined, null, true, false);
+
+let heap_next = heap.length;
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passArrayF64ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 8, 8) >>> 0;
+    getFloat64ArrayMemory0().set(arg, ptr / 8);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeObject(idx) {
+    const ret = getObject(idx);
+    dropObject(idx);
+    return ret;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+let wasmModule, wasmInstance, wasm;
+function __wbg_finalize_init(instance, module) {
+    wasmInstance = instance;
+    wasm = instance.exports;
+    wasmModule = module;
+    cachedDataViewMemory0 = null;
+    cachedFloat64ArrayMemory0 = null;
+    cachedUint8ArrayMemory0 = null;
+    return wasm;
+}
+
+async function __wbg_load(module, imports) {
+    if (typeof Response === 'function' && module instanceof Response) {
+        if (typeof WebAssembly.instantiateStreaming === 'function') {
+            try {
+                return await WebAssembly.instantiateStreaming(module, imports);
+            } catch (e) {
+                const validResponse = module.ok && expectedResponseType(module.type);
+
+                if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
+                    console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+
+                } else { throw e; }
+            }
+        }
+
+        const bytes = await module.arrayBuffer();
+        return await WebAssembly.instantiate(bytes, imports);
+    } else {
+        const instance = await WebAssembly.instantiate(module, imports);
+
+        if (instance instanceof WebAssembly.Instance) {
+            return { instance, module };
+        } else {
+            return instance;
+        }
+    }
+
+    function expectedResponseType(type) {
+        switch (type) {
+            case 'basic': case 'cors': case 'default': return true;
+        }
+        return false;
+    }
+}
+
+function initSync(module) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module !== undefined) {
+        if (Object.getPrototypeOf(module) === Object.prototype) {
+            ({module} = module)
+        } else {
+            console.warn('using deprecated parameters for `initSync()`; pass a single object instead')
+        }
+    }
+
+    const imports = __wbg_get_imports();
+    if (!(module instanceof WebAssembly.Module)) {
+        module = new WebAssembly.Module(module);
+    }
+    const instance = new WebAssembly.Instance(module, imports);
+    return __wbg_finalize_init(instance, module);
+}
+
+async function __wbg_init(module_or_path) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module_or_path !== undefined) {
+        if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+            ({module_or_path} = module_or_path)
+        } else {
+            console.warn('using deprecated parameters for the initialization function; pass a single object instead')
+        }
+    }
+
+    if (module_or_path === undefined) {
+        module_or_path = new URL('cog_tiler_wasm_bg.wasm', import.meta.url);
+    }
+    const imports = __wbg_get_imports();
+
+    if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) {
+        module_or_path = fetch(module_or_path);
+    }
+
+    const { instance, module } = await __wbg_load(await module_or_path, imports);
+
+    return __wbg_finalize_init(instance, module);
+}
+
+export { initSync, __wbg_init as default };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "cog-tiler-wasm",
+  "type": "module",
+  "collaborators": [
+    "Qiusheng Wu <giswqs@gmail.com>"
+  ],
+  "description": "Serverless Cloud Optimized GeoTIFF (COG) dynamic tiling in WebAssembly. TiTiler-style XYZ tiles, no backend.",
+  "version": "0.1.0",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/opengeos/cog-tiler-wasm"
+  },
+  "files": [
+    "cog_tiler_wasm_bg.wasm",
+    "cog_tiler_wasm.js",
+    "cog_tiler_wasm.d.ts",
+    "cog-tiler.js",
+    "cog-tiler.d.ts"
+  ],
+  "main": "cog-tiler.js",
+  "types": "cog-tiler.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ],
+  "module": "cog-tiler.js",
+  "exports": {
+    ".": {
+      "types": "./cog-tiler.d.ts",
+      "default": "./cog-tiler.js"
+    },
+    "./wasm": {
+      "types": "./cog_tiler_wasm.d.ts",
+      "default": "./cog_tiler_wasm.js"
+    }
+  },
+  "peerDependencies": {
+    "whitebox-wasm": "^0.4.0",
+    "proj4": "^2.15.0",
+    "geotiff": "^2.1.0",
+    "geotiff-geokeys-to-proj4": "^2024.4.13"
+  },
+  "keywords": [
+    "cog",
+    "geotiff",
+    "tiler",
+    "webassembly",
+    "wasm",
+    "maplibre",
+    "xyz",
+    "web-mercator",
+    "titiler",
+    "raster"
+  ],
+  "homepage": "https://opengeos.github.io/cog-tiler-wasm/"
+}