maplibre-gl-raster 0.11.1 → 0.13.0

package/README.md

@@ -11,6 +11,8 @@ A MapLibre GL JS plugin for visualizing local and remote raster datasets (GeoTIF
 
 - **Local and remote rasters** - Load Cloud Optimized GeoTIFFs from any CORS-enabled URL, or drag-and-drop local GeoTIFF files
 - **Mosaic VRTs** - Load a `.vrt` that mosaics COGs; its sources are rendered as one layer with a single shared stretch ([details and limits](#mosaic-vrt-support))
+- **Three rendering backends** - Switch at runtime between the deck.gl GPU pipeline (default), a serverless WASM tiler, and a remote [TiTiler](https://developmentseed.org/titiler/) server ([details](#rendering-engines))
+- **Mosaics** - Render a [MosaicJSON](https://github.com/developmentseed/mosaicjson-spec) or STAC `FeatureCollection` of COGs as one layer: client-side on the GPU (deck.gl) by default, or server-side via TiTiler ([details](#rendering-engines))
 - **Multiple layers** - Layer list with visibility toggles, reordering, zoom-to, and per-layer settings
 - **GPU rendering pipeline** - Band compositing, per-band rescale, 90+ colormaps, nodata filtering, linear/sqrt/log stretch, and gamma correction as deck.gl shader modules; parameter changes re-render without re-fetching tiles
 - **Auto statistics** - Per-band min/max and histograms sampled from COG overviews (or GDAL metadata), with draggable histogram handles for the rescale range
@@ -119,10 +121,11 @@ The main control class implementing MapLibre's `IControl` interface.
 | `sampleDataLabel` | `string` | `'Load sample data...'` | Placeholder shown in the sample-data dropdown |
 | `closeOnOutsideClick` | `boolean` | `true` | Collapse the panel when clicking outside it; set `false` to close only via the header button |
 | `engine`      | `RenderEngine` | `'maplibre-gl-raster'` | Initial rendering backend; switchable at runtime from the panel    |
+| `titilerEndpoint` | `string` | `'https://titiler.d2s.org'` | TiTiler instance used by the `'titiler'` engine (COG + MosaicJSON) |
 
 #### Raster Methods
 
-- `addRaster(source, options?)` - Add a raster from a COG or [mosaic `.vrt`](#mosaic-vrt-support) URL (`string`), or a local GeoTIFF / `.vrt` `File` (a local `.vrt` must name its sources as absolute URLs); resolves with the layer id
+- `addRaster(source, options?)` - Add a raster from a COG, [mosaic `.vrt`](#mosaic-vrt-support), or [mosaic `.json`](#rendering-engines) (MosaicJSON or STAC `FeatureCollection`) URL (`string`), or a local GeoTIFF / `.vrt` `File` (a local `.vrt` must name its sources as absolute URLs); resolves with the layer id. A mosaic `.json` renders on the deck.gl engine by default, and also on [`cog-tiler-wasm`](#rendering-engines) (a MosaicJSON additionally on [`titiler`](#rendering-engines))
 - `removeRaster(id)` - Remove a raster layer
 - `getRaster(id)` / `getRasters()` - Get layer snapshots (`RasterLayerInfo`); for a mosaic VRT, `memberUrls` lists the COGs it expanded to
 - `setRasterState(id, patch)` - Update visualization state (mode, bands, rescale, colormap, reversed, nodata, opacity, gamma, stretch, visible)
@@ -155,12 +158,125 @@ layer:
 
 - **`maplibre-gl-raster`** (default) - the GPU pipeline described above: a
   deck.gl `COGLayer` on a shared `MapboxOverlay`. Parameter changes re-render
-  without re-fetching tiles.
+  without re-fetching tiles. It also renders a **mosaic** client-side (see
+  [Mosaics](#mosaics) below).
 - **`cog-tiler-wasm`** - a serverless CPU/WASM XYZ tiler
   ([cog-tiler-wasm](https://github.com/opengeos/cog-tiler-wasm)) wired to a
   MapLibre custom protocol. Tiles are rendered on the CPU and served as native
   MapLibre raster layers. The panel's settings (bands, rescale, colormap,
-  curve, gamma, nodata, opacity) map directly onto its render parameters.
+  curve, gamma, nodata, opacity) map directly onto its render parameters. This
+  tiler ships a shorter colormap list than the deck.gl sprite, so while it is
+  active the panel's colormap picker narrows to the ramps it can actually draw
+  (a name it does not know renders black rather than falling back).
+- **`titiler`** - a server-side dynamic tiler
+  ([TiTiler](https://developmentseed.org/titiler/)). Tiles are rendered by a
+  remote TiTiler instance and drawn as native MapLibre raster layers, so
+  nothing is decoded in the browser. It renders a
+  [MosaicJSON](https://developmentseed.org/titiler/examples/notebooks/Working_with_MosaicJSON)
+  server-side through TiTiler's `/mosaicjson` router, so it reaches assets a
+  browser cannot (e.g. non-CORS or `s3://` buckets). Bands, rescale, colormap,
+  and a numeric nodata map onto TiTiler's tile parameters (index mode uses a
+  server-side band-math `expression`, so the real normalized-difference index
+  is rendered). The `stretch` and `gamma` controls have no standard TiTiler
+  parameter and are ignored. Only remote sources work (TiTiler reads over
+  HTTP), so local files and `.vrt` mosaics render on the other engines.
+
+  The default instance is `https://titiler.d2s.org`; point it at your own
+  deployment with the `titilerEndpoint` option, the `setTitilerEndpoint()` API,
+  or the **TiTiler server** input the panel shows while the `titiler` engine is
+  selected (clearing it restores the default):
+
+  ```typescript
+  const control = new RasterControl({
+    engine: "titiler",
+    titilerEndpoint: "https://titiler.example.com",
+  });
+  await control.addRaster("https://example.com/cog.tif");
+  // Switch the server at runtime (the panel input stays in sync):
+  control.setTitilerEndpoint("https://titiler.xyz");
+  ```
+
+  > Because TiTiler is a *dynamic* tiler, the plugin does not cap the MapLibre
+  > source at a MosaicJSON's advertised `minzoom` (that would leave a small,
+  > high-resolution source blank until you zoomed in) - instead the initial fit
+  > is floored to that zoom so the view lands where tiles exist.
+
+### Mosaics
+
+A **mosaic** is a `.json` manifest of many COGs rendered as one layer. Two
+shapes are accepted:
+
+- **[MosaicJSON](https://github.com/developmentseed/mosaicjson-spec)** - `tiles`
+  maps web-mercator quadkeys to the covering COGs; each asset's extent is
+  derived from those quadkeys.
+- **STAC `FeatureCollection`** - each feature carries its own `bbox` and an
+  `assets` map (the shape the
+  [deck.gl-raster NAIP example](https://developmentseed.org/deck.gl-raster/examples/naip-mosaic/)
+  renders); the COG URL is read from the `visual`/`image` asset.
+
+```typescript
+// Renders on the deck.gl engine by default:
+await control.addRaster("https://example.com/mosaic.json");
+await control.addRaster(
+  "https://data.source.coop/giswqs/opengeos/naip_nd_2023_stac.json",
+);
+```
+
+To build a STAC `FeatureCollection` from your own COGs (local or remote), use
+the `make_stac.py` helper in this repo:
+
+```bash
+# A directory of local COGs, hosted under a public base URL:
+python python/make_stac.py ./tiles -o mosaic.json --href-base https://data.example.com/tiles
+# ...or explicit remote COG URLs (add --full for complete STAC Items):
+python python/make_stac.py https://data.example.com/a.tif https://data.example.com/b.tif -o mosaic.json
+```
+
+To build the same `FeatureCollection` from imagery you *don't* host — by
+searching a STAC API such as the
+[Planetary Computer](https://planetarycomputer.microsoft.com/) — use
+`search_stac.py` (standard library only):
+
+```bash
+# NAIP over a bbox, one year:
+python python/search_stac.py -c naip -b -99.3759,46.8959,-98.8825,47.1299 -d 2023 -o naip.json
+# Least-cloudy Sentinel-2 scenes, with SAS-signed hrefs for browser access:
+python python/search_stac.py -c sentinel-2-l2a -b 5.6,45.8,6.2,46.1 -d 2024-06-01/2024-09-01 \
+    --query '{"eo:cloud_cover":{"lt":10}}' --sortby eo:cloud_cover \
+    --max-items 20 --asset visual --sign -o s2.json
+```
+
+Both scripts pretty-print with a 2-space indent by default; pass `--compact` to
+write the document on a single line instead (about a third smaller, and the
+shape the deck.gl-raster example ships).
+
+Point `--api` at any other STAC API (e.g. Earth Search) to search it instead.
+Planetary Computer collections whose blobs are not anonymously readable need
+`--sign`; those tokens expire, so re-run the search rather than reusing an old
+file.
+
+On the default **`maplibre-gl-raster`** engine the mosaic is a deck.gl
+`MosaicLayer`: a spatial index culls to the viewport and renders one on-GPU
+`COGLayer` per visible asset (each read directly over HTTP and reprojected by
+its own header), all sharing one visualization state. Both mosaic kinds also
+render on the **`cog-tiler-wasm`** engine, which composites them per tile: for
+each tile it picks the assets whose bbox covers it, decodes each on the CPU, and
+paints them into one tile (stopping as soon as the tile is opaque, so a tile
+inside a single asset costs one decode). A **MosaicJSON** can additionally render
+on the **`titiler`** engine (server-side); a **STAC** mosaic has no TiTiler
+equivalent. Adding a mosaic keeps the active engine when it can draw it, and
+otherwise falls back to the deck.gl engine.
+
+A large mosaic (more than ~48 assets) opens on a capped, centred view and hides
+below a `minZoom` derived from the asset size, so a low/world view never spins
+up a `COGLayer` for every asset at once — zoom in to explore, and pan to stream
+in neighbours. A small mosaic always draws its full extent.
+
+> Client-side rendering reads each COG directly, so the assets must be
+> **CORS-enabled** and `https` (an `s3://` asset is rewritten to its
+> virtual-hosted `https` form, but the bucket must still allow browser access).
+> For assets a browser cannot reach, use the `titiler` engine instead. The band
+> count, colormap and rescale window are taken from the first asset's header.
 
 `cog-tiler-wasm` is an **optional peer dependency**, loaded lazily the first
 time the engine is selected, so it never enters the default bundle. To use it,