maplibre-gl-raster 0.11.0 → 0.12.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,122 @@ 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.
+- **`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,