cog-tiler-wasm 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenGeos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# cog-tiler-wasm
+
+[![CI](https://github.com/opengeos/cog-tiler-wasm/actions/workflows/ci.yml/badge.svg)](https://github.com/opengeos/cog-tiler-wasm/actions/workflows/ci.yml)
+[![Live demo](https://img.shields.io/badge/demo-GitHub%20Pages-blue)](https://opengeos.github.io/cog-tiler-wasm/)
+
+**Serverless, TiTiler-style XYZ tiling of Cloud Optimized GeoTIFFs, in
+WebAssembly.** No backend, no GDAL, no PROJ - the map fetches COG byte ranges
+directly and synthesizes `z/x/y` tiles client-side.
+
+**[Live demo](https://opengeos.github.io/cog-tiler-wasm/)** - loads a sample
+EPSG:3857 COG over HTTP range requests and renders it on a MapLibre map, all in
+the browser. Paste any CORS- and range-enabled 3857 COG URL to try your own.
+
+This crate is the **tiling brain**. It does the slippy-map math (tile -> source
+pixel window), picks the right COG overview level, and renders a decoded window
+into an RGBA tile (rescale + colormap + nodata alpha). It deliberately does
+**not** parse COGs or do network I/O - that is delegated to
+[`whitebox-wasm`](https://github.com/opengeos/whitebox-wasm)'s `CogStream`,
+which already implements a pure-Rust codec stack (Deflate/LZW/JPEG/WebP/…) and
+HTTP range streaming. The two compose into a complete tiler:
+
+```
+  CogStream (whitebox-wasm)               CogTiler (this crate)
+  ─────────────────────────               ─────────────────────
+  geo_transform(), levels_json()   ──▶     new(gt, w, h, epsg, nodata, levels)
+                                           pixel_window_for_tile(z,x,y) ─▶ {level,x,y,w,h}
+  tiles_for_window(level,x,y,w,h)  ◀──     (JS fetches byte ranges, decodes tiles)
+  decode_tile_f64(...)             ──▶     render(window, w, h, min, max, cmap) ─▶ RGBA
+```
+
+The result is a TiTiler-class viewer with **zero hosting cost**: wire it to a
+MapLibre custom protocol and the browser does everything.
+
+## Why this is feasible without a server
+
+A dynamic tile server (TiTiler = FastAPI + rio-tiler + GDAL) does five things:
+read a COG by HTTP **range request**, decode the relevant internal tiles,
+resample to the requested XYZ tile, apply rescale/colormap/nodata, and encode.
+Every one of those has a pure-Rust, WASM-clean implementation today - the two
+historically hard parts (a C-free codec stack and CRS handling) are already
+solved in `whitebox-wasm`. This crate adds the thin layer on top: mercator
+addressing, overview selection, resampling, and rendering.
+
+## Status
+
+**v1 (this scaffold):** EPSG:3857 sources, single-band rendering, built-in
+colormaps, MapLibre demo. The crate builds to `wasm32-unknown-unknown` and ships
+a `wasm-pack` web package.
+
+See [Roadmap](#roadmap) for warping, multi-band, and edge/WASI serving.
+
+## Build
+
+```bash
+rustup target add wasm32-unknown-unknown
+cargo install wasm-pack
+wasm-pack build crates/cog-tiler-wasm --release --target web --out-dir pkg
+```
+
+### Run the demo locally
+
+```bash
+npm run dev   # builds the wasm, assembles demo/, serves http://localhost:8000/
+```
+
+`npm run dev` builds the wasm into `demo/`, copies in `cog-tiler.js` + the sample,
+and starts a zero-dependency static server with **HTTP range support** (which the
+tile streaming needs - the stdlib `python -m http.server` does not do ranges).
+Set `PORT` to change the port. No `npm install` is required (the dev scripts use
+only Node built-ins; the demo loads its peer deps from a CDN via an import map).
+
+The published [GitHub Pages demo](https://opengeos.github.io/cog-tiler-wasm/) is
+built the same way by `.github/workflows/pages.yml`.
+
+## Usage (reusable module)
+
+[`cog-tiler.js`](cog-tiler.js) is the package's main entry. It wraps the wasm
+tiler + `whitebox-wasm` and handles EPSG:3857 sources, on-the-fly **warping** of
+any projected/4326 COG to Web Mercator, and **paletted (categorical)** rendering -
+so apps import it instead of copying the demo.
+
+It ships **inside the npm package** (`main`/`module` -> `cog-tiler.js`); the raw
+wasm tiler is also available at the `cog-tiler-wasm/wasm` subpath. Install it
+alongside its peer dependencies:
+
+```bash
+npm install cog-tiler-wasm whitebox-wasm proj4 geotiff geotiff-geokeys-to-proj4 maplibre-gl
+```
+
+```js
+import maplibregl from "maplibre-gl";
+import { init, openCog, registerCogProtocol } from "cog-tiler-wasm";
+
+await init(); // load the wasm modules once
+
+let source = null;
+// The protocol resolves the active source + render settings per tile.
+registerCogProtocol(maplibregl, "cog", () => ({
+  source,
+  render: { min: 0, max: 3000, colormap: "viridis" }, // ignored for paletted COGs
+}));
+
+source = await openCog(url); // EPSG:3857 fast path, or warped if projected/4326
+// openCog also accepts a local raster: a File (e.g. from <input type=file>),
+// Blob, ArrayBuffer, or Uint8Array - read in memory, no server needed.
+map.addSource("cog", { type: "raster", tiles: ["cog://{z}/{x}/{y}"], tileSize: 256 });
+map.addLayer({ id: "cog", type: "raster", source: "cog" });
+
+// source.crsLabel, source.levels, source.hasPalette, source.boundsLonLat
+// and source.renderTileRGBA(z, x, y, render) / renderTilePNG(...) are also exposed.
+```
+
+### TiTiler-style COG API
+
+`CogSource` mirrors the read endpoints of
+[TiTiler's COG API](https://developmentseed.org/titiler/endpoints/cog/),
+client-side (works on projected/paletted sources too, via the warp path):
+
+```js
+// Metadata / read
+src.info();           // /cog/info         -> bounds, count, dtype, nodata, overviews, min/maxzoom, ...
+src.infoGeoJSON();    // /cog/info.geojson -> GeoJSON Feature (bbox polygon + info)
+src.tilejson();       // /cog/tilejson.json -> Mapbox TileJSON document
+await src.point(lon, lat);          // /cog/point -> band value(s) at a WGS84 coordinate
+await src.statistics({ maxSize });  // /cog/statistics -> per-band min/max/mean/std/count/
+                                    //   valid_percent/median/percentiles/histogram (from an overview)
+
+// Image generation (all accept render params below)
+await src.previewPNG({ maxSize: 1024 });               // /cog/preview -> PNG bytes
+await src.bboxPNG([minLon, minLat, maxLon, maxLat]);   // /cog/bbox    -> PNG bytes
+await src.preview(opts);   // -> { width, height, rgba }  (bbox() likewise)
+
+// Render params (on tiles, preview, bbox):
+//   bidx:     1-based bands; one -> colormap/palette, three -> RGB composite
+//   rescale:  [[min,max], ...] per band, or [min,max]; or min/max shorthand
+//   colormap: one of colormaps()  (viridis, magma, plasma, inferno, cividis,
+//             turbo, terrain, blues, greens, reds, rdylgn, spectral, gray)
+//   reversed: sample the colormap back-to-front (single-band)
+//   stretch:  transfer curve "linear" | "sqrt" | "log"  (applied after rescale)
+//   gamma:    power-law gamma (1 = off; applied after the stretch)
+//   nodata:   override the transparency value
+//   opacity:  output alpha multiplier 0..1
+await src.renderTilePNG(z, x, y, { bidx: [4, 3, 2], rescale: [0, 3000] }); // false-color RGB
+import { colormaps } from "cog-tiler-wasm";
+```
+
+The render pipeline (nodata -> rescale -> stretch -> gamma -> colormap, plus
+reverse/opacity) matches the controls of GPU raster viewers such as
+[maplibre-gl-raster](https://github.com/opengeos/maplibre-gl-raster), so
+`cog-tiler-wasm` can serve as a CPU/WASM rendering backend for the same UI - the
+panel (band, rescale, colormap, curve, gamma, opacity) maps directly onto these
+params and re-renders by re-requesting tiles.
+
+Server-only endpoints (`/map.html`, `WMTSCapabilities.xml`, `/validate`,
+`/stac`) are out of scope for a client-side library; band-math `expression` is
+on the [roadmap](#roadmap).
+
+For a no-build page, map the peer deps with an import map (see
+[`demo/index.html`](demo/index.html)):
+
+```html
+<script type="importmap">
+  { "imports": {
+    "whitebox-wasm": "https://esm.sh/whitebox-wasm@0.4.0",
+    "proj4": "https://esm.sh/proj4@2.20.9",
+    "geotiff": "https://esm.sh/geotiff@2.1.3",
+    "geotiff-geokeys-to-proj4": "https://esm.sh/geotiff-geokeys-to-proj4@2024.4.13"
+  } }
+</script>
+```
+
+### Low-level Rust API
+
+The wasm crate (`CogTiler`) is the 3857 tiling brain underneath `cog-tiler.js`:
+`pixel_window_for_tile(z, x, y)` maps a tile to a source-pixel window/overview,
+and `render(window, w, h, min, max, colormap, nodata_alpha)` rasterizes an
+assembled f64 window to RGBA. See [`cog-tiler.js`](cog-tiler.js) for the
+window-assembly and warp loops built on top.
+
+A runnable MapLibre example (custom `cog://` protocol) is in
+[`demo/index.html`](demo/index.html).
+
+## API
+
+`version()`, `tile_bounds_3857(z, x, y) -> [minx,miny,maxx,maxy]`.
+
+**`new CogTiler(geo_transform, width, height, epsg, nodata, levels_json)`**
+- `geo_transform` - 6-element GDAL affine of the full-res raster (`Float64Array`)
+- `width`/`height` - full-resolution pixel dimensions
+- `epsg` - source CRS; must be `3857` in v1
+- `nodata` - optional nodata value (`undefined`/`NaN` = none)
+- `levels_json` - JSON array of level descriptors, finest level first; only
+  `width`/`height` are read (extra `whitebox-wasm` fields are ignored)
+
+Properties: `epsg`, `num_levels`.
+
+**`pixel_window_for_tile(z, x, y)`** -> `{ level, x, y, w, h, level_width, level_height, empty }`
+The overview level and pixel window covering the tile. `empty` is true when the
+tile lies outside the raster.
+
+**`render(pixels, win_w, win_h, min, max, colormap, nodata_alpha)`** -> `Uint8Array`
+A `256*256*4` RGBA tile. `pixels` is the decoded row-major `f64` window;
+`colormap` is `"viridis" | "magma" | "terrain" | "gray"`. Empty windows render
+fully transparent.
+
+## Roadmap
+
+- **TiTiler COG API parity** - done: `info`, `info.geojson`, `tilejson`,
+  `point`, `statistics`, `preview`, `bbox`, `bidx`/RGB band selection, and 13
+  colormaps (see [above](#titiler-style-cog-api)). Next: band-math
+  **`expression`** and `color_formula`.
+- **Warping** of projected/4326 sources and **paletted/categorical** rendering
+  are done in [`cog-tiler.js`](cog-tiler.js) (proj4js + geotiff.js). **Planar**
+  (`INTERLEAVE=BAND`) multi-band COGs are read per-band via geotiff.js too, since
+  whitebox-wasm's streaming decoder is chunky-only. Next: planar support
+  **upstream in `whitebox-wasm`** (and exposing its proj string + color table) to
+  drop the geotiff.js dependency, then move the warp into the Rust crate
+  (`proj4rs`).
+- **Edge / WASI serving** - run the same module as a serverless XYZ endpoint
+  near the data, not only in the browser.
+- **STAC / mosaics** - multi-asset orchestration.
+
+## Releasing
+
+The npm package bundles the wasm tiler **and** the `cog-tiler.js` module
+(assembled by [`scripts/prepare-pkg.mjs`](scripts/prepare-pkg.mjs)). To cut a
+release, push a `vX.Y.Z` tag; [`release.yml`](.github/workflows/release.yml)
+builds, assembles, and publishes to npm via Trusted Publishing (OIDC, no token):
+
+```bash
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+One-time setup: configure the package's Trusted Publisher on npmjs.com (package
+-> Settings -> Trusted Publisher) to this repo + `release.yml`.
+
+## License
+
+[MIT](LICENSE) © OpenGeos.

package/cog-tiler.d.ts

@@ -8,8 +8,31 @@ export interface RenderOptions {
   min?: number;
   /** High end of the rescale range (continuous bands). Default 1. */
   max?: number;
-  /** Colormap name: "viridis" | "magma" | "terrain" | "gray". Default "viridis". */
+  /** Per-band rescale `[[min,max], ...]`, or a single `[min,max]`. Overrides min/max. */
+  rescale?: [number, number][] | [number, number];
+  /** Colormap name (single-band). See {@link colormaps}. Default "viridis". */
   colormap?: string;
+  /** 1-based band indices. One band -> palette/colormap; three -> RGB composite.
+   *  Default: all-bands RGB if the source has >= 3 bands, else band 1. */
+  bidx?: number[];
+  /** Override the source nodata value for transparency. */
+  nodata?: number;
+  /** Transfer curve applied to the rescaled value before the colormap.
+   *  Default "linear". */
+  stretch?: "linear" | "sqrt" | "log";
+  /** Power-law gamma (1 = off). Applied after the stretch. */
+  gamma?: number;
+  /** Sample the colormap back-to-front (single-band). */
+  reversed?: boolean;
+  /** Output alpha multiplier in [0,1]. Default 1. */
+  opacity?: number;
+}
+
+/** A rendered image: row-major RGBA, `width * height * 4` bytes. */
+export interface RenderedImage {
+  width: number;
+  height: number;
+  rgba: Uint8ClampedArray;
 }
 
 /** A level descriptor from `CogStream.levels_json()`. */
@@ -39,20 +62,80 @@ export declare class CogSource {
   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 a 256x256 RGBA buffer, or null if empty. (Paletted
+   * tiles are a `Uint8ClampedArray`; continuous tiles are the wasm `render()`
+   * `Uint8Array`.) */
+  renderTileRGBA(
+    z: number,
+    x: number,
+    y: number,
+    opts?: RenderOptions,
+  ): Promise<Uint8Array | 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>;
+
+  // TiTiler-style read API.
+
+  /** Dataset info (bounds, bands, dtype, nodata, overviews, min/maxzoom, ...). */
+  info(): Record<string, unknown>;
+  /** Dataset info as a GeoJSON Feature (bbox polygon + info properties). */
+  infoGeoJSON(): Record<string, unknown>;
+  /** Mapbox TileJSON document. */
+  tilejson(opts?: {
+    tilesUrl?: string;
+    minzoom?: number;
+    maxzoom?: number;
+    scheme?: string;
+  }): Record<string, unknown>;
+  /** Band value(s) at a WGS84 lon/lat. `bidx` is 1-based; default all bands. */
+  point(
+    lon: number,
+    lat: number,
+    opts?: { bidx?: number[] },
+  ): Promise<{ coordinates: [number, number]; values: number[]; band_names: string[]; outside?: boolean }>;
+  /** Per-band statistics from a decimated overview (≤ `maxSize` px wide). */
+  statistics(opts?: { maxSize?: number }): Promise<Record<string, Record<string, unknown>>>;
+
+  /** Render a preview of the whole dataset (≈ `/cog/preview`). */
+  preview(
+    opts?: RenderOptions & { maxSize?: number; width?: number; height?: number },
+  ): Promise<RenderedImage>;
+  /** Render a WGS84 bbox `[minLon, minLat, maxLon, maxLat]` region (≈ `/cog/bbox`). */
+  bbox(
+    bbox: [number, number, number, number],
+    opts?: RenderOptions & { maxSize?: number; width?: number; height?: number },
+  ): Promise<RenderedImage>;
+  /** {@link preview} encoded as PNG bytes. */
+  previewPNG(
+    opts?: RenderOptions & { maxSize?: number; width?: number; height?: number },
+  ): Promise<Uint8Array>;
+  /** {@link bbox} encoded as PNG bytes. */
+  bboxPNG(
+    bbox: [number, number, number, number],
+    opts?: RenderOptions & { maxSize?: number; width?: number; height?: number },
+  ): Promise<Uint8Array>;
 }
 
+/** Names of the built-in single-band colormaps. */
+export declare function colormaps(): string[];
+
 /** 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>;
+/**
+ * Open a COG and return a {@link CogSource} ready to render XYZ tiles. Pass a URL
+ * string (read via HTTP range) or in-memory bytes / a Blob / a File for a local
+ * raster.
+ */
+export declare function openCog(source: string | ArrayBuffer | Uint8Array | Blob): Promise<CogSource>;
 
-/** Encode a 256x256 RGBA buffer to PNG bytes (browser; uses OffscreenCanvas). */
-export declare function rgbaToPng(rgba: Uint8Array | Uint8ClampedArray): Promise<Uint8Array>;
+/** Encode an RGBA buffer to PNG bytes (browser; uses OffscreenCanvas).
+ *  Defaults to 256x256 when `width`/`height` are omitted. */
+export declare function rgbaToPng(
+  rgba: Uint8Array | Uint8ClampedArray,
+  width?: number,
+  height?: number,
+): Promise<Uint8Array>;
 
 /** Minimal shape of the maplibre-gl module needed to register a protocol. */
 export interface MapLibreLike {

package/cog-tiler.js

@@ -21,7 +21,7 @@
  *   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 initTiler, { colorize, colormap_names } from "./cog_tiler_wasm.js";
 import proj4 from "proj4";
 import * as GeoTIFF from "geotiff";
 import geokeysToProj4 from "geotiff-geokeys-to-proj4";
@@ -54,6 +54,99 @@ const rangeFetcher = (url) => (a, b) =>
     .then((r) => r.arrayBuffer())
     .then((b) => new Uint8Array(b));
 
+/** Map a level descriptor's sample format + bit depth to a numpy-style dtype. */
+function dtypeOf(lv) {
+  const b = lv.bits_per_sample;
+  const f = (lv.sample_format || "").toLowerCase();
+  if (f.includes("float") || f.includes("ieee")) return "float" + b;
+  if (f === "uint" || f.includes("unsigned")) return "uint" + b;
+  if (f === "int" || f.includes("signed")) return "int" + b;
+  return (f || "uint") + b;
+}
+
+/** Min/max/mean/std/count/valid_percent/percentiles/histogram for a band buffer. */
+function computeStats(buf, nodata) {
+  let min = Infinity, max = -Infinity, sum = 0, sumsq = 0;
+  const valid = [];
+  for (let i = 0; i < buf.length; i++) {
+    const v = buf[i];
+    if (Number.isNaN(v)) continue;
+    if (nodata != null && v === nodata) continue;
+    if (v < min) min = v;
+    if (v > max) max = v;
+    sum += v;
+    sumsq += v * v;
+    valid.push(v);
+  }
+  const count = valid.length;
+  if (count === 0) return { count: 0, valid_percent: 0 };
+  const mean = sum / count;
+  const std = Math.sqrt(Math.max(0, sumsq / count - mean * mean));
+  valid.sort((a, b) => a - b);
+  const pct = (p) => valid[Math.min(count - 1, Math.floor((p / 100) * count))];
+  const bins = 10, span = max - min || 1, hist = new Array(bins).fill(0);
+  for (const v of valid) {
+    let k = Math.floor(((v - min) / span) * bins);
+    if (k >= bins) k = bins - 1;
+    if (k < 0) k = 0;
+    hist[k]++;
+  }
+  const edges = Array.from({ length: bins + 1 }, (_, i) => min + (span * i) / bins);
+  return {
+    min, max, mean, std, count,
+    valid_percent: (count / buf.length) * 100,
+    median: pct(50),
+    percentile_2: pct(2),
+    percentile_98: pct(98),
+    histogram: [hist, edges],
+  };
+}
+
+/** Transfer curve for a rescaled value in 0..1: stretch then gamma (mirrors the
+ *  Rust `transfer`; reversal is colormap-only so it's not applied to RGB). */
+function transferCurve(t, stretch, gamma) {
+  if (stretch === "sqrt") t = Math.sqrt(t);
+  else if (stretch === "log") t = Math.log(1 + 99 * t) / Math.log(100);
+  if (Math.abs(gamma - 1) > 1e-9) t = Math.pow(t, 1 / Math.max(gamma, 1e-4));
+  return t;
+}
+
+/** Normalize render rescale options to a list of [min,max] pairs (per band). */
+function rescaleList(opts) {
+  if (Array.isArray(opts.rescale) && opts.rescale.length) {
+    return Array.isArray(opts.rescale[0]) ? opts.rescale : [opts.rescale];
+  }
+  return [[opts.min ?? 0, opts.max ?? 1]];
+}
+
+/** WGS84 [w,s,e,n] -> EPSG:3857 [minx,miny,maxx,maxy]. */
+function mercExtentFromLonLat([w, s, e, n]) {
+  const t = proj4("EPSG:4326", "EPSG:3857");
+  const [minx, miny] = t.forward([w, s]);
+  const [maxx, maxy] = t.forward([e, n]);
+  return [minx, miny, maxx, maxy];
+}
+
+/** Output [w,h] honoring explicit width/height, else fitting `maxSize` to aspect.
+ *  width/height/maxSize are user inputs, so validate them as positive integers
+ *  before they reach typed-array / canvas constructors. */
+function fitSize(extW, extH, maxSize, width, height) {
+  const posInt = (v, name) => {
+    if (v == null) return undefined;
+    const n = Math.floor(v);
+    if (!Number.isFinite(n) || n < 1) throw new Error(`${name} must be a positive integer`);
+    return n;
+  };
+  const w = posInt(width, "width"), h = posInt(height, "height"), max = posInt(maxSize, "maxSize") ?? 1024;
+  const ar = extW / extH || 1;
+  if (w && h) return [w, h];
+  if (w) return [w, Math.max(1, Math.round(w / ar))];
+  if (h) return [Math.max(1, Math.round(h * ar)), h];
+  return ar >= 1
+    ? [max, Math.max(1, Math.round(max / ar))]
+    : [Math.max(1, Math.round(max * ar)), max];
+}
+
 /** Build a 256-entry RGBA palette from a TIFF ColorMap (16-bit R,G,B blocks). */
 function buildPalette(colorMap) {
   if (!colorMap) return null;
@@ -76,15 +169,60 @@ function bilin(v00, v10, v01, v11, tx, ty) {
   return top + (bot - top) * ty;
 }
 
+// Bilinear sample of a row-major window at fractional (fc,fr). Returns NaN when
+// the cell center is outside the window so out-of-raster pixels stay transparent
+// (no edge smear); falls back to nearest at the window edge / next to nodata.
+function sampleWindowBilinear(buf, w, h, fc, fr) {
+  const c0 = Math.floor(fc), r0 = Math.floor(fr);
+  if (c0 < 0 || c0 >= w || r0 < 0 || r0 >= h) return NaN;
+  const c1 = Math.min(c0 + 1, w - 1), r1 = Math.min(r0 + 1, h - 1);
+  const v00 = buf[r0 * w + c0];
+  if (Number.isNaN(v00)) return NaN;
+  const v10 = buf[r0 * w + c1], v01 = buf[r1 * w + c0], v11 = buf[r1 * w + c1];
+  if (Number.isNaN(v10) || Number.isNaN(v01) || Number.isNaN(v11)) return v00; // edge/nodata
+  const tx = fc - c0, ty = fr - r0;
+  const top = v00 + (v10 - v00) * tx, bot = v01 + (v11 - v01) * tx;
+  return top + (bot - top) * ty;
+}
+
+// Build a byte reader from a URL string or an in-memory source (ArrayBuffer,
+// Uint8Array, or Blob/File). `range(a,b)` yields bytes [a..b]; `openTiff()`
+// returns a geotiff.js GeoTIFF for reading the CRS / color table from the header.
+async function makeReader(source) {
+  if (typeof source === "string") {
+    return { label: source, range: rangeFetcher(source), openTiff: () => GeoTIFF.fromUrl(source) };
+  }
+  let bytes;
+  if (source instanceof Uint8Array) bytes = source;
+  else if (source instanceof ArrayBuffer) bytes = new Uint8Array(source);
+  else if (source && typeof source.arrayBuffer === "function") {
+    bytes = new Uint8Array(await source.arrayBuffer()); // Blob / File
+  } else {
+    throw new Error("openCog: expected a URL string, ArrayBuffer, Uint8Array, or Blob");
+  }
+  // Reuse the underlying buffer when the view spans it exactly; only copy for a
+  // partial view (avoids duplicating a large raster in memory).
+  const ab =
+    bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+      ? bytes.buffer
+      : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  return {
+    label: source.name || "(local file)",
+    range: (a, b) => Promise.resolve(bytes.subarray(a, Math.min(b + 1, bytes.length))),
+    openTiff: () => GeoTIFF.fromArrayBuffer(ab),
+  };
+}
+
 /**
- * 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).
+ * Open a COG and return a {@link CogSource} ready to render XYZ tiles. `source`
+ * is a URL string (read via HTTP range) or in-memory bytes / a Blob / a File for
+ * a local raster. Detects EPSG:3857 (fast path) vs. any other CRS (warp path),
+ * reading the source projection + color table from the GeoTIFF header (which
+ * whitebox-wasm 0.4.0 does not expose).
  */
-export async function openCog(url) {
+export async function openCog(source) {
   await init();
-  const range = rangeFetcher(url);
+  const { range, openTiff, label } = await makeReader(source);
   // 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;
@@ -101,17 +239,18 @@ export async function openCog(url) {
   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 };
+  // Open the GeoTIFF with geotiff.js when we need the CRS (non-3857) or to check
+  // the planar config (multi-band). whitebox-wasm's streaming decoder is
+  // chunky-only, so planar (INTERLEAVE=BAND) multi-band COGs are read per-band
+  // through geotiff.js instead (see _assembleWindow / point).
+  const multiBand = levels[0].bands > 1;
+  let tiff = null, img = null, planar = false;
+  if (stream.epsg !== 3857 || multiBand) {
+    tiff = await openTiff();
+    img = await tiff.getImage();
+    planar = multiBand && img.fileDirectory.PlanarConfiguration === 2;
+  }
+  const base = { url: label, range, stream, levels, gt, nodata: stream.nodata, tiff, planar };
 
   if (stream.epsg === 3857) {
     return new CogSource({
@@ -119,13 +258,12 @@ export async function openCog(url) {
       mode: "3857",
       crsLabel: "EPSG:3857",
       palette: null,
+      toSource: { forward: (c) => c }, // identity: mercator meters == source meters
       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
@@ -166,11 +304,9 @@ export class CogSource {
     return !!this.palette;
   }
 
-  /** Render an XYZ tile to a 256x256 RGBA `Uint8ClampedArray`, or null if empty. */
+  /** Render an XYZ tile to a 256x256 RGBA buffer, 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);
+    return this._renderExtent(tileBounds3857(z, x, y), TILE, TILE, opts);
   }
 
   /** Render an XYZ tile to PNG bytes (empty `Uint8Array` for a blank tile). */
@@ -199,9 +335,27 @@ export class CogSource {
     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) {
+  /** geotiff.js image for an overview level (cached). Used for planar reads. */
+  _tiffImage(level) {
+    if (!this._imgs) this._imgs = new Map();
+    let p = this._imgs.get(level);
+    if (!p) {
+      p = this.tiff.getImage(level);
+      this._imgs.set(level, p);
+    }
+    return p;
+  }
+
+  // Fetch + decode band `band` (0-based) over a level pixel window into a
+  // row-major buffer. Chunky COGs go through whitebox (cached, NaN for gaps);
+  // planar (INTERLEAVE=BAND) COGs are read per-band via geotiff.js, which
+  // whitebox's chunky-only streaming decoder can't address.
+  async _assembleWindow(level, x, y, w, h, band = 0) {
+    if (this.planar) {
+      const img = await this._tiffImage(level);
+      const rasters = await img.readRasters({ window: [x, y, x + w, y + h], samples: [band] });
+      return rasters[0]; // typed array, length w*h, row-major
+    }
     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)));
@@ -216,7 +370,7 @@ export class CogSource {
         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
+          buf[oy * w + ox] = px[(ry * tw + rx) * bands + band];
         }
       }
     });
@@ -244,28 +398,40 @@ export class CogSource {
     ];
   }
 
-  // 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);
-  }
+  // Render a Web Mercator extent (3857 [minx,miny,maxx,maxy]) to an outW x outH
+  // RGBA buffer. A coarse grid of mercator->source samples (the proj4 transform,
+  // or identity for EPSG:3857) is bilinearly interpolated per output pixel to a
+  // source location, then sampled from the source window. Bands: 1 (paletted via
+  // the color table, else single-band colormap) or >=3 (RGB composite, per-band
+  // rescale). Out-of-raster pixels stay transparent. Powers tiles, preview, bbox.
+  async _renderExtent(merc, outW, outH, opts = {}) {
+    const [minx, miny, maxx, maxy] = merc;
+    const l0 = this.levels[0];
+    const wanted = opts.bidx && opts.bidx.length ? opts.bidx : this.palette ? [1] : l0.bands >= 3 ? [1, 2, 3] : [1];
+    const bands0 = wanted.map((b) => b - 1).filter((b) => b >= 0 && b < l0.bands);
+    if (!bands0.length) bands0.push(0);
+    const rgb = bands0.length >= 3;
+    const rescales = rescaleList(opts);
+    const colormap = opts.colormap || "viridis";
+    const nodata = opts.nodata != null ? opts.nodata : this.nodata;
+    const ndSet = nodata != null && !Number.isNaN(nodata);
+    // Transfer-curve params (parity with maplibre-gl-raster's shader pipeline).
+    // Normalize gamma/opacity here so the JS (RGB) and Rust (single-band) paths
+    // apply identical curves for the same options (e.g. gamma 0 -> clamped, not skipped).
+    const stretch = opts.stretch || "linear";
+    const gamma = Number.isFinite(+opts.gamma) ? Math.max(+opts.gamma, 1e-4) : 1;
+    const reversed = !!opts.reversed;
+    const opacity = Number.isFinite(+opts.opacity) ? Math.max(0, Math.min(1, +opts.opacity)) : 1;
+    const alpha = Math.round(opacity * 255);
 
-  // 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);
+    // Gridded mercator -> source samples, and the source-coord bbox they span.
     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]);
+      const my = maxy - (gy / NG) * (maxy - miny);
       for (let gx = 0; gx <= NG; gx++) {
-        const mx = tb[0] + (gx / NG) * (tb[2] - tb[0]);
+        const mx = minx + (gx / NG) * (maxx - minx);
         let s;
         try { s = this.toSource.forward([mx, my]); } catch { s = [NaN, NaN]; }
         const i = gy * (NG + 1) + gx;
@@ -281,7 +447,7 @@ export class CogSource {
     }
     if (!any) return null;
 
-    const level = this._chooseLevel((smaxx - sminx) / TILE);
+    const level = this._chooseLevel((smaxx - sminx) / outW);
     const lv = this.levels[level];
     const [lpw, lph] = this._levelPixelSize(level);
     const ox = this.gt[0], oy = this.gt[3];
@@ -291,49 +457,230 @@ export class CogSource {
     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);
 
+    // Assemble the needed band window(s): 1 (palette/colormap) or 3 (RGB).
+    const used = rgb ? bands0.slice(0, 3) : [bands0[0]];
+    const bufs = await Promise.all(used.map((b) => this._assembleWindow(level, c0, r0, ww, hh, b)));
     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 out = new Uint8ClampedArray(outW * outH * 4);
+    const grid = !pal && !rgb ? new Float64Array(outW * outH).fill(NaN) : null;
+    for (let py = 0; py < outH; py++) {
+      const fy = (py / outH) * NG, gy0 = Math.min(NG - 1, Math.floor(fy)), ty = fy - gy0;
+      for (let px = 0; px < outW; px++) {
+        const fx = (px / outW) * 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;
+        const fcol = (sx - ox) / lpw - c0;
+        const frow = (oy - sy) / lph - r0;
+        const o = (py * outW + px) * 4;
         if (pal) {
+          // Categorical: nearest-neighbor + color table.
+          const col = Math.floor(fcol), row = Math.floor(frow);
+          if (col < 0 || col >= ww || row < 0 || row >= hh) continue;
+          const v = bufs[0][row * ww + col];
+          if (!isFinite(v)) continue;
           const ci = v & 255;
-          if (ci === 0 || (this.nodata != null && v === this.nodata)) continue;
-          const o = (py * TILE + px) * 4;
+          // Transparency: the declared nodata when present, else the GDAL
+          // paletted convention that index 0 is the background/no-data class.
+          if (ndSet ? v === nodata : ci === 0) continue;
           out[o] = pal[ci * 4]; out[o + 1] = pal[ci * 4 + 1];
-          out[o + 2] = pal[ci * 4 + 2]; out[o + 3] = 255;
+          out[o + 2] = pal[ci * 4 + 2]; out[o + 3] = alpha;
+        } else if (rgb) {
+          // RGB composite: bilinear-sample each band, rescale -> curve -> gamma.
+          let ok = true;
+          for (let k = 0; k < 3; k++) {
+            const v = sampleWindowBilinear(bufs[k], ww, hh, fcol, frow);
+            if (!isFinite(v) || (ndSet && v === nodata)) { ok = false; break; }
+            const [mn, mx] = rescales[k] || rescales[0];
+            const t = transferCurve(Math.max(0, Math.min(1, (v - mn) / ((mx - mn) || 1))), stretch, gamma);
+            out[o + k] = Math.round(t * 255);
+          }
+          if (ok) out[o + 3] = alpha;
+          else { out[o] = out[o + 1] = out[o + 2] = 0; }
         } else {
-          grid[py * TILE + px] = v;
+          // Continuous single band: bilinear; colormap applied below.
+          const v = sampleWindowBilinear(bufs[0], ww, hh, fcol, frow);
+          if (!isFinite(v) || (ndSet && v === nodata)) continue;
+          grid[py * outW + px] = v;
         }
       }
     }
-    if (pal) return out;
-    return this.tiler.render(grid, TILE, TILE, min, max, colormap, true);
+    if (pal || rgb) return out;
+    const [mn, mx] = rescales[0];
+    // colorize returns a Uint8Array; expose a Uint8ClampedArray (zero-copy view,
+    // matching the palette/RGB branches and the RenderedImage type) so callers
+    // can pass it straight to ImageData.
+    const c = colorize(
+      grid, outW, outH, mn, mx, colormap, ndSet ? nodata : undefined, true,
+      stretch, gamma, reversed, opacity,
+    );
+    return new Uint8ClampedArray(c.buffer, c.byteOffset, c.length);
+  }
+
+  // --- TiTiler-style read API ----------------------------------------------
+
+  /** XYZ zoom whose tile resolution matches the full-res pixel size. */
+  _maxzoom() {
+    const res = Math.abs(this.gt[1]);
+    return Math.max(0, Math.min(24, Math.round(Math.log2((2 * OS) / (TILE * res)))));
+  }
+
+  /** XYZ zoom whose tile resolution matches the coarsest overview. */
+  _minzoom() {
+    const c = this.levels[this.levels.length - 1];
+    const res = Math.abs(this.gt[1]) * (this.levels[0].width / c.width);
+    return Math.max(0, Math.min(24, Math.round(Math.log2((2 * OS) / (TILE * res)))));
+  }
+
+  /** Dataset info (≈ TiTiler `/cog/info`). */
+  info() {
+    const l0 = this.levels[0];
+    const b = this.boundsLonLat;
+    return {
+      bounds: b, // WGS84 [minlon, minlat, maxlon, maxlat]
+      crs: this.crsLabel,
+      width: l0.width,
+      height: l0.height,
+      count: l0.bands,
+      dtype: dtypeOf(l0),
+      nodata: this.nodata == null || Number.isNaN(this.nodata) ? null : this.nodata,
+      colorinterp: this.palette ? ["palette"] : null,
+      overviews: this.levels.length - 1,
+      tile_size: [l0.tile_width, l0.tile_height],
+      minzoom: this._minzoom(),
+      maxzoom: this._maxzoom(),
+      band_descriptions: Array.from({ length: l0.bands }, (_, i) => `b${i + 1}`),
+      compression: l0.compression,
+    };
+  }
+
+  /** Dataset info as a GeoJSON Feature (≈ TiTiler `/cog/info.geojson`). */
+  infoGeoJSON() {
+    const [w, s, e, n] = this.boundsLonLat;
+    return {
+      type: "Feature",
+      geometry: {
+        type: "Polygon",
+        coordinates: [[[w, s], [e, s], [e, n], [w, n], [w, s]]],
+      },
+      properties: this.info(),
+    };
+  }
+
+  /** Mapbox TileJSON document (≈ TiTiler `/cog/tilejson.json`). */
+  tilejson({ tilesUrl = "cog://{z}/{x}/{y}", minzoom, maxzoom, scheme = "xyz" } = {}) {
+    const b = this.boundsLonLat;
+    const mn = minzoom ?? this._minzoom();
+    return {
+      tilejson: "2.2.0",
+      version: "1.0.0",
+      scheme,
+      tiles: [tilesUrl],
+      minzoom: mn,
+      maxzoom: maxzoom ?? this._maxzoom(),
+      bounds: b,
+      center: [(b[0] + b[2]) / 2, (b[1] + b[3]) / 2, mn],
+    };
+  }
+
+  /** Band value(s) at a WGS84 lon/lat (≈ TiTiler `/cog/point/{lon},{lat}`). */
+  async point(lon, lat, { bidx } = {}) {
+    const [mx, my] = proj4("EPSG:4326", "EPSG:3857").forward([lon, lat]);
+    const [sx, sy] = this.toSource.forward([mx, my]); // source CRS coords
+    const l0 = this.levels[0];
+    const col = Math.floor((sx - this.gt[0]) / Math.abs(this.gt[1]));
+    const row = Math.floor((this.gt[3] - sy) / Math.abs(this.gt[5]));
+    if (col < 0 || col >= l0.width || row < 0 || row >= l0.height) {
+      return { coordinates: [lon, lat], values: [], band_names: [], outside: true };
+    }
+    const bands = bidx ? bidx.map((b) => b - 1) : Array.from({ length: l0.bands }, (_, i) => i);
+    let values;
+    if (this.planar) {
+      // Planar: whitebox can't address bands 1..n; read the pixel via geotiff.js.
+      const img = await this._tiffImage(0);
+      const r = await img.readRasters({ window: [col, row, col + 1, row + 1], samples: bands });
+      values = r.map((b) => b[0]);
+    } else {
+      const tcol = Math.floor(col / l0.tile_width), trow = Math.floor(row / l0.tile_height);
+      const [off, len] = Array.from(this.stream.tile_range(0, tcol, trow));
+      const px = await this._getTile(0, { col: tcol, row: trow, offset: off, length: len });
+      const base = ((row % l0.tile_height) * l0.tile_width + (col % l0.tile_width)) * l0.bands;
+      values = bands.map((b) => px[base + b]);
+    }
+    return {
+      coordinates: [lon, lat],
+      values,
+      band_names: bands.map((b) => `b${b + 1}`),
+    };
+  }
+
+  /** Per-band statistics (≈ TiTiler `/cog/statistics`), from a decimated
+   *  overview (the largest one whose width is ≤ `maxSize`). */
+  async statistics({ maxSize = 1024 } = {}) {
+    let level = this.levels.length - 1;
+    for (let i = 0; i < this.levels.length; i++) {
+      if (this.levels[i].width <= maxSize) { level = i; break; }
+    }
+    const lv = this.levels[level];
+    const nodata = this.nodata == null || Number.isNaN(this.nodata) ? null : this.nodata;
+    const out = {};
+    for (let b = 0; b < lv.bands; b++) {
+      const buf = await this._assembleWindow(level, 0, 0, lv.width, lv.height, b);
+      out[`b${b + 1}`] = computeStats(buf, nodata);
+    }
+    return out;
+  }
+
+  /** Render a preview of the whole dataset (≈ TiTiler `/cog/preview`).
+   *  Returns `{ width, height, rgba }`. `opts` accepts the render params
+   *  (`bidx`, `min`/`max`/`rescale`, `colormap`, `nodata`) plus `maxSize` /
+   *  `width` / `height`. */
+  async preview({ maxSize = 1024, width, height, ...render } = {}) {
+    const merc = mercExtentFromLonLat(this.boundsLonLat);
+    const [w, h] = fitSize(merc[2] - merc[0], merc[3] - merc[1], maxSize, width, height);
+    const rgba = (await this._renderExtent(merc, w, h, render)) || new Uint8ClampedArray(w * h * 4);
+    return { width: w, height: h, rgba };
+  }
+
+  /** Render a WGS84 bbox region (≈ TiTiler `/cog/bbox`). `bbox` is
+   *  [minLon, minLat, maxLon, maxLat]. Returns `{ width, height, rgba }`. */
+  async bbox(bbox, { maxSize = 1024, width, height, ...render } = {}) {
+    const merc = mercExtentFromLonLat(bbox);
+    const [w, h] = fitSize(merc[2] - merc[0], merc[3] - merc[1], maxSize, width, height);
+    const rgba = (await this._renderExtent(merc, w, h, render)) || new Uint8ClampedArray(w * h * 4);
+    return { width: w, height: h, rgba };
+  }
+
+  /** Like {@link preview}, encoded as PNG bytes. */
+  async previewPNG(opts = {}) {
+    const { width, height, rgba } = await this.preview(opts);
+    return rgbaToPng(rgba, width, height);
+  }
+
+  /** Like {@link bbox}, encoded as PNG bytes. */
+  async bboxPNG(bbox, opts = {}) {
+    const r = await this.bbox(bbox, opts);
+    return rgbaToPng(r.rgba, r.width, r.height);
   }
 }
 
-/** 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);
+/** Encode a `w`x`h` RGBA buffer to PNG bytes (browser; uses OffscreenCanvas). */
+export async function rgbaToPng(rgba, w = TILE, h = TILE) {
+  const img = new ImageData(new Uint8ClampedArray(rgba), w, h);
+  const cv = new OffscreenCanvas(w, h);
   cv.getContext("2d").putImageData(img, 0, 0);
   const blob = await cv.convertToBlob({ type: "image/png" });
   return new Uint8Array(await blob.arrayBuffer());
 }
 
+/** Names of the built-in colormaps (for single-band rendering). */
+export function colormaps() {
+  return JSON.parse(colormap_names());
+}
+
 /**
  * Register a MapLibre custom protocol (e.g. `cog://{z}/{x}/{y}`).
  * `resolve()` is called per tile and returns `{ source, render }`, where

package/cog_tiler_wasm.d.ts

@@ -50,6 +50,20 @@ export class CogTiler {
     readonly num_levels: number;
 }
 
+/**
+ * Colormap a single-band `w*h` grid to RGBA at 1:1 (no resampling), for any
+ * output size, with rescale -> stretch -> gamma -> colormap (+ reverse) and a
+ * constant alpha from `opacity`. `NaN` (and the nodata value when
+ * `nodata_alpha`) become transparent. Pairs with the JS warp loop, which
+ * samples a grid at the output resolution.
+ */
+export function colorize(pixels: Float64Array, width: number, height: number, min: number, max: number, colormap: string, nodata: number | null | undefined, nodata_alpha: boolean, stretch: string, gamma: number, reversed: boolean, opacity: number): Uint8Array;
+
+/**
+ * Names of the built-in colormaps (JSON array string).
+ */
+export function colormap_names(): string;
+
 /**
  * EPSG:3857 bounds `[min_x, min_y, max_x, max_y]` of an XYZ tile.
  */
@@ -70,6 +84,8 @@ export interface InitOutput {
     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 colorize: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number, q: number) => void;
+    readonly colormap_names: (a: 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;

package/cog_tiler_wasm.js

@@ -134,6 +134,67 @@ export class CogTiler {
 }
 if (Symbol.dispose) CogTiler.prototype[Symbol.dispose] = CogTiler.prototype.free;
 
+/**
+ * Colormap a single-band `w*h` grid to RGBA at 1:1 (no resampling), for any
+ * output size, with rescale -> stretch -> gamma -> colormap (+ reverse) and a
+ * constant alpha from `opacity`. `NaN` (and the nodata value when
+ * `nodata_alpha`) become transparent. Pairs with the JS warp loop, which
+ * samples a grid at the output resolution.
+ * @param {Float64Array} pixels
+ * @param {number} width
+ * @param {number} height
+ * @param {number} min
+ * @param {number} max
+ * @param {string} colormap
+ * @param {number | null | undefined} nodata
+ * @param {boolean} nodata_alpha
+ * @param {string} stretch
+ * @param {number} gamma
+ * @param {boolean} reversed
+ * @param {number} opacity
+ * @returns {Uint8Array}
+ */
+export function colorize(pixels, width, height, min, max, colormap, nodata, nodata_alpha, stretch, gamma, reversed, opacity) {
+    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;
+        const ptr2 = passStringToWasm0(stretch, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len2 = WASM_VECTOR_LEN;
+        wasm.colorize(retptr, ptr0, len0, width, height, min, max, ptr1, len1, !isLikeNone(nodata), isLikeNone(nodata) ? 0 : nodata, nodata_alpha, ptr2, len2, gamma, reversed, opacity);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var v4 = getArrayU8FromWasm0(r0, r1).slice();
+        wasm.__wbindgen_export3(r0, r1 * 1, 1);
+        return v4;
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
+/**
+ * Names of the built-in colormaps (JSON array string).
+ * @returns {string}
+ */
+export function colormap_names() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.colormap_names(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);
+    }
+}
+
 /**
  * EPSG:3857 bounds `[min_x, min_y, max_x, max_y]` of an XYZ tile.
  * @param {number} z

package/package.json

@@ -5,8 +5,8 @@
     "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",
+  "version": "0.2.1",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/opengeos/cog-tiler-wasm"
@@ -16,7 +16,9 @@
     "cog_tiler_wasm.js",
     "cog_tiler_wasm.d.ts",
     "cog-tiler.js",
-    "cog-tiler.d.ts"
+    "cog-tiler.d.ts",
+    "README.md",
+    "LICENSE"
   ],
   "main": "cog-tiler.js",
   "types": "cog-tiler.d.ts",