Hypsometric Tint from terrain-RGB tiles

[JBLINZ]

User Story

As a map maker/owner, I would like to render a hypsometric tint using my terrain-RGB tiles in MapLibre to deliver high-quality cartographic products.

Rationale

Currently, I cannot render anything other than a hillshade using my terrain-RGB tiles, although there are many common outputs from this type of elevation data that could be useful.

By introducing hypsometric tint rendering from terrain RGB tiles, similar to GDAL’s “color-relief”, MapLibre can extend its usefulness for advanced cartography, visualisation and basic analysis.

Ideally, users could display terrain tiles with a hypsometric tint or any other customised relief shading in MapLibre GL JS using the map style. The new terrain display algorithm could be similar to color-relief in GDAL.

This command outputs a 3-band (RGB) or 4-band (RGBA) raster with values are computed from the elevation and a text-based color configuration file, containing the association between various elevation values and the corresponding wished color. By default, the colors between the given elevation values are blended smoothly and the result is a nice colorized DEM

Here is a basic example combined with a dynamic hill-shade:

[HarelM]

As far as I understand this requirement, this doesn't rotate when rotating the map, right? This is somewhat similar to contours...?
I propose to start with a plugin that uses addProtocol to convert DEM data into raster tiles and see if it is good enough.
If the plugin is widely used or the use case is requested frequently, we can consider adding this to the code base.
What do you think?
Cc: @NathanMOlson

[acalcutt]

If you need some ideas, this is an example I have of doing color-relief with addProtocol and rainbowvis https://stackblitz.com/edit/web-platform-muooeab7?file=index.html . I updated it recently so it worked with maplibre-gl 4+ with promises.

[NathanMOlson]

As far as I understand this requirement, this doesn't rotate when rotating the map, right? This is somewhat similar to contours...?

Correct, the color is a function of elevation only, and independent of the rotation of the map. It's similar to contours, but even more similar to hillshade. Like hillshade, the input is elevation and the output is a color. There is no intermediate vector output like contours.

I propose to start with a plugin that uses addProtocol to convert DEM data into raster tiles and see if it is good enough.

That approach definitely looks possible. Thanks @acalcutt for the beautiful example.

[acalcutt]

One thing that stinks about doing it the way my example does is you have to decode the image height values yourself, which requires specific source conditions. it would still be really nice to see this included so the code maplibre already uses to decode height values could be used and it would just support what maplibre supports.

maplibre-contour does this nice thing where the source terrain can be read by the plugin and cached. that cached source can be used by maplibre as well. Just mentioning it because it seemed like that helped with having download the images multiple times. I think there is some propasal to bring over some of the maplibre-contour ideas in the style spec... it would be nice if something like that single source cache for terrain made it to maplibre. right now the source gets read multiple times, since you have to specify different sources for terrain/hillshade/contours/color relief which could make it slower.

[NathanMOlson]

I think this is the contour-related proposal mentioned by @acalcutt: maplibre/maplibre-style-spec#583

[larsmaxfield]

A couple months ago I experimentally implemented hypsometric tint color relief (colormapping?) directly with shaders by duplicating the hillshade mechanisms into a different layer.

Here's an example with painting data from a project I work on: https://pants.dev/swings/cas-winter-landscape/

It's fast because it uses polynomials fitted to colormaps like these: https://www.shadertoy.com/view/WlfXRN

This is in a v4 fork which is not in state to merge, but I'd be willing to help with a pull request or simply to help explain my implementation further.

[NathanMOlson]

Thanks @larsmaxfield, that looks great! I believe @JBLINZ has a requirement for colormaps with sharp transitions (for example, at sea level) which will make polynomials unsuitable.

I'd love to hear more about your experience, and your thoughts having this functionality provided as a plugin vs builtin.

[larsmaxfield]

@NathanMOlson indeed for sharp/discontinuous breakpoints we would need conditionals.

Actually I'm realizing now that polynomials may be a dealbreaker (despite their speed) because we can't easily specify or customize colormaps. @acalcutt's solution is far superior -- it lets you set each breakpoint and its respective color.

@acalcutt also best summarized how builtin would be best with the caveat that we really should move to a single source cache for terrain, hillshade, hypsometric, contour lines, and other DEM layers.

Lastly, to unsell my implementation even further, the colormap layer I created suffers from the same issue as the hillshade layer:

• setPaintProperty does not work correctly when terrain is used. #3001

...which means I have to force a reload of the cache when a user changes the upper and lower breakpoints like this:

setTimeout(() => {
  map.terrain.sourceCache.sourceCache.reload();
}, 200);

Especially for a colormap that users can adjust, we would need to solve that.

[NathanMOlson]

I've reviewed the feedback and explored the implementation, and concluded that having this functionality built-in is more appropriate that having it as part of a plugin. The main reasons are:

1. Community interest. I've already seen 3 independent implementation of people doing this outside MapLibre (2 using addProtocol(), 1 using a new layer type).
2. Performance/de-duplication. The reasons given here Design Proposal: Contour Line Source from Raster DEM Tiles maplibre-style-spec#583 by @msbarry apply even more-so to hypsometric tint (if 90% of maplibre-contour is duplicate of MapLibre GL JS, a hypsometric tint plugin will be an even higher percentage duplicate functionality, because what it needs to do is so much simpler).
3. Precedent. Hypsometric tint is very similar to hillshade (it's a method of rendering DEM tiles directly to raster without an intermediate vector step), which is built-in.

[NathanMOlson]

Here's a rough draft of what this could look like in MapLibre GL JS: #5742.

Suggestions/comments/concerns are welcome.