Supporting `TerrainRGB` and `Terrarium` via the XYZTilesPlugin

[jo-chemla]

Description

Dedicated issue tracker for TerrainRGB/Terrarium support following #943 (comment)

Motivation for additional terrain sources

In case it's useful, I just gathered several 2.5D TerrainRGB and Terrarium resources, existing terrain tile providers, and references in a similar feature request made on the CesiumJS repo here CesiumGS/cesium#13035 (comment) - see the interesting bits quoted below.

Allowing such elevation/terrain sources to be rendered via 3DTilesRendererJS would offer a wider range of material customization, like:

• raster source reprojection of sources already handled by the lib (TMS, WMTS, WMS etc) or upcoming tiled formats
• proper lighting via standard threejs materials via point (or other) light sources
• postprocessing via eg takram-design-engineering/three-geospatial/r3f/pmndrs/postprocessing
• custom shader for slope, aspect, or any normal-derived attributes, via eg postprocessing passes - for more context, additional feature requested to maplibre here Design Proposal: Color terrain by normal-derived attributes: slope, aspect, curvature, matcap, etc maplibre/maplibre-style-spec#1374.

TerrainRGB/Terrarium server endpoints

[...] to support additional terrain representations - similar to how libs like maplibre, mapbox do it - especially the following elevation RGB encodings:

• TerrainRGB by Mapbox/MapTiler: height = -10000 + ((R * 256 * 256 + G * 256 + B) * 0.1)
• Terrarium by Mapzen: height = (R * 256 + G + B / 256) - 32768
• a bit more convoluted: DEM COG (or DSM/DTM, Digital Elevation Model) support added via geomatico/maplibre-cog-protocol see example

The above 2 specifications are similar to heightmap-1.0 in that the endpoints serve TMS templated URLs like https://tiles.mapterhorn.com/{z}/{x}/{y}.webp in EPSG:3857 WebMercator tiles, usually 256² raster tiles where RGB triplets encode elevation via the above formulas/equations. Some providers also provide a TileJSON endpoint, like Mapterhorn https://tiles.mapterhorn.com/tilejson.json

Example providers serving terrain-rgb or terrarium encoded terrain

• Mapterhorn open-data https://tiles.mapterhorn.com/{z}/{x}/{y}.webp
• AWS Terrain Tiles open-data https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png
• MapTiler terrain via API-key https://api.maptiler.com/tiles/terrain-rgb-v2/{z}/{x}/{y}.webp?key={KEY}
• Mapbox Terrain-DEM v1 via API-key https://api.mapbox.com/v4/mapbox.terrain-rgb/{z}/{x}/{y}.png?access_token={KEY}

Note 1: The libs mentioned (maplibre, mapbox etc) usually handle these elevation datasets both as

• terrain, a 2.5D displacement of the globe or tilted plane surface,
• as well as for other visualization modes (example layer types for maplibre: hillshade, color-relief, contours etc)

Solution

Quote from Garrett:

The XYZTilesPlugin should be pretty straightforward to extend too support something like TerrainRGB or Terrarium files. It's really just a matter of reading the texture data to the CPU and modifying the geometry to account for the heights. I'm open to PRs for these formats if anyone wants to give it a go. I can give any direction in a dedicated issue or PR if it's needed.

Alternatives

Maplibre & Mapbox do support Terrarium/TerrainRGB TMS sources, cesiumjs does not (but supports quantized-mesh, google earth, arcgis etc, see CesiumGS/cesium#13035 (comment))

Additional context

I've used these for a POC maplibre app to compare terrain tiles providers (both 2.5D terrain, as well as viz-modes hillshade, color-relief & contours), that should be released soon, see screencast demo.