Design Proposal: handle nodata in `raster-dem`

[Kanahiro]

Design Proposal: handle nodata in raster-dem

Motivation

In Japan, an encoding called "Numerical PNG Tile" is used by the government to distribute dem tiles. Many developers utilize it to use DEM data in WebGIS.

https://maps.gsi.go.jp/development/demtile.html

specification: https://maps.gsi.go.jp/development/demtile.html

This encoding is not available as is in MapLibre GL JS because it has two problem so I have to workaround by using addProtocol to modify tile contents to fit to encodings TerrainRGB or Terrarium but as it is not the best way in terms of performance.

My workaround: https://github.com/mug-jp/maplibre-gl-gsi-terrain

Problem1: nodata

This encoding has "no-data" - rgb (128, 0, 0) is treated as nodata and any height value is not defined.
It is good to set height=0 to pixels which has the nodata in ordinary cases. So, I think it is nice to set nodataRgb and nodataValue in raster-dem source.

It may be useful in other encodings when original data has pixels with no-data and they have specific rgb value.

Problem2: not "monotonically increasing"

The encoding is NOT "monotonically increasing" - it means that when red value is bigger than 2^23, we have to subtract 2^24 from value.

I don't have a good solution I can think so, then I don't propose it in this issue.
However I have tried to handle this by adding heightRange to clamp values into the range. I mean if a value is larger than maximum value, substract value toward minimum (like overflow in programming).

https://github.com/Kanahiro/maplibre-gl-js/blob/1beaf562e3d617f35e51d6c2e9bfa2212840a6e0/test/examples/rasterdem-custom-encoding.html#L51

Proposed Change

• add nodataRgb and nodataHeight parameters to raster-dem source.

API Modifications

 {
    type: "raster-dem",
    tiles: ["https://cyberjapandata.gsi.go.jp/xyz/dem_png/{z}/{x}/{y}.png"],
    tileSize: 256,
    maxzoom: 14,
    encoding: "custom",
    redFactor: 655.36,
    greenFactor: 2.56,
    blueFactor: 0.01,
    nodataRgb: [128, 0, 0], // added
    nodataHeight: 0, // added
}

// means pixles with rgb=128,0,0 are treated as height = 0

https://github.com/Kanahiro/maplibre-gl-js/blob/1beaf562e3d617f35e51d6c2e9bfa2212840a6e0/test/examples/rasterdem-custom-encoding.html#L52

Migration Plan and Compatibility

none

Rejected Alternatives

none

[HarelM]

From my experience, dem data is not something that changes often, why not simply convert it to terrain RGB once and use that?

[Kanahiro]

Thank you for comment.

There are few people to generate new tiles with the encoding in my experience. In such case we often pick TerrainRGB.

The reason why we use it is that tiles with good quality of 10m resolution for entire Japan distributed by government are available freely and easily and an encoding of the tile is that I explained.

[Kanahiro]

I mean, following tiles are distributed and can be used freely under a generous license.
https://cyberjapandata.gsi.go.jp/xyz/dem_png/{z}/{x}/{y}.png

[Kanahiro]

I have deployed a webpage to demonstrate this proposal.
https://kanahiro.github.io/gljs-gsi-terrain/#13.29/34.09535/133.79584/-166.1/73

https://github.com/Kanahiro/gljs-gsi-terrain/blob/main/index.html
maplibre/maplibre-gl-js#5934

[Kanahiro]

https://mug-jp.github.io/maplibre-gl-gsi-terrain/
This is my workaround to use that encoding with addProtocol. You can see latency to load terrain compared to above example.
It is needed in this workaround that make another GL context and pass img data some times.