Design Proposal: Color terrain by normal-derived attributes: slope, aspect, curvature, matcap, etc

[jo-chemla]

Design Proposal: Color terrain by normal-derived attributes: slope, aspect, curvature, matcap, etc

Motivation

Originally suggested on the maplibre-gl-js repo maplibre/maplibre-gl-js#6711

Recent maplibre features introduced additional hillshade options (discussion maplibre/maplibre-gl-js#5665 and pr maplibre/maplibre-gl-js#5768 inspired by gdal: combined, multi-dir, igor), hypsometric tint (discussion #1067 and pr maplibre/maplibre-gl-js#5666) or contours #583. In various mapping contexts it is useful to add other visualization modes - based off of the surface normal - for the micro-scale (similar to hillshade) to highlight micro-relief, topographical indicators of on-the-ground features, or for the macro-scale (similar to hypso) to grasp the environment at a glance (aspect, slope etc).

Proposed Change

Some of these attributes can be live-computed, shader-side, directly from the surface normal vector. They could then be colormapped via paint color-relief-color interpolate:

• slope is the z component of the normal vector,
• aspect is the angle between up/north vector and the normal
• slightly more convoluted, matcap is using a sphere texture that describes the color of the light ray coming from eye to surface reflected by surface normal (easy equation, but requires eye position being passed to the shader as uniform). Similarly, a simpler illumination model like phong could be applied, by passing point-light positions, colors and intensities.
• others like curvature would be a 2nd order derivative of the surface, so 1st degree derivative of the normal vector field.

The advanced morphological descriptors are probably not needed, but some simple like slope, aspect, and evnentually normals/matcap would be useful. Happy to hear everyone's thoughts about adding (some of) these rendering modes!

// Proposal 1: single layer-type with additional attribute to specify method
{
  "type":"normal-derived",
  "source":"terrain-source",
  "paint": {
      "normal-method": "slope", // could be slope, aspect, curvature etc
      "color": ["interpolate",
         ["linear"],
         ["slope"],
        ...
        ]
  } 

}
// Proposal 2: one layer-type per new visualization mode
{
"layers": [
    {
        "id": "terrain-Visualization",
        "source": "terrain-source",
        "type": "normal-slope", // could be one of normal-slope, normal-aspect, normal-curvature etc
        "paint": {
            "color": ["interpolate",
                ["linear"],
                ["slope"],
                0,"black",
                8000,"#FFFFFF"
            ]
        }
    }
]
}

API Modifications

No change to the API.

Migration Plan and Compatibility

No change to existing functionality. To use the new functionality, create a normal-attribute layer.

Rejected Alternatives

Note the aspect can almost be replicated - although with transparent opacity dependent on the hillshade, which should not happen - via the new "hillshade-method": "multidirectional", see folded

Details

{
  "type":"hillshade",
  "source":"terrain-source",
  "paint": {
      "hillshade-method": "multidirectional",
      "hillshade-highlight-color": [
          "#FF4000",
          "#FFFF00",
          "#40ff00",
          "#00FF80"
      ],
      "hillshade-shadow-color": [
          "#00bfff",
          "#0000ff",
          "#bf00ff",
          "#FF0080"
      ],
      "hillshade-illumination-direction": [
          270,
          315,
          0,
          45
      ],
      "hillshade-illumination-altitude": [
          30,
          30,
          30,
          30
      ]
  },
  "paint2": {
      "hillshade-method": "multidirectional",
      "hillshade-highlight-color": [
          "#CC0000",
          "#0000CC"
      ],
      "hillshade-shadow-color": [
          "#00CCCC",
          "#CCCC00"
      ],
      "hillshade-illumination-direction": [
          0,
          270
      ],
      "hillshade-illumination-altitude": [
          30,
          30
      ]
  }
}

More advanced visualization modes can be viewed on the EU area on EcoDataCube from @Open-Earth-Monitor (open the Layers side-panel, open the Soil & Terrain section, and search for DTM to get the list). They are actually sourced from OpenLandMap GEDTM30 (STAC), which applied WhiteBox Geospatial tools on the terrain dataset to extract:

• slope
• pos/neg openness
• min/max/profile/tangential/ring curvature
• difference from mean
• shape index
• spherical deviation of normals

Example extracted from Morphosedimentary characterization of the Capbreton submarine canyon system, Bay of Biscay (Cantabrian Sea) by Gómez Ballesteros) et al

Other example

[Application and Comparison of Decision Tree-Based Machine Learning Methods in Landside Susceptibility Assessment at Pauri Garhwal Area, Uttarakhand, India](https://www.researchgate.net/publication/317380218_Application_and_Comparison_of_Decision_Tree-Based_Machine_Learning_Methods_in_Landside_Susceptibility_Assessment_at_Pauri_Garhwal_Area_Uttarakhand_India?_tp=eyJjb250ZXh0Ijp7ImZpcnN0UGFnZSI6Il9kaXJlY3QiLCJwYWdlIjoiX2RpcmVjdCJ9fQ) by Pham et al

[HarelM]

Can you explain why this shouldn't be a hillshade method and requires a new type of layer?

[jo-chemla]

These visualization modes could definitely be new sub-types, or hillshade-method, of the type: hillshade layer-type rather than requiring a new layer type!
Just had a quick glance at the hillshade.fragment.glsl shader, which also already includes eg aspect computation so it does indeed make sense. Just need to understand how deriv is computed and stored in texture passed to fragment to retrieve back from 2d to 3d.

I just initially thought it could make sense to separate the visualization modes proposed by this discussion - which are (besides matcap/phong) solely based on the geometry, as mathematical quantities derived only from the surface geometry, local normal, topographical features - from hillshade, which results of an illumination model applied to the geometry - no the geometry only. But this distinction probably do not make sense from the user/dev perspective!

[larsmaxfield]

Instead of expanding the list of built-in shaders, what about generalized way to add a custom shader?

That is, providing a string of HLSL code at the layer level?

Just an idea. I don't think it would be easy. But I personally would find it useful to make a custom hillshade shader that filters out certain elevations (NaNs) in our data.

[HarelM]

Can't you do in with a CustomLayer?

[larsmaxfield]

Ah I meant to say a custom shader with access to the raster DEM source — the u_image. It would be a bit like a hook to the hillsahde.fragment.glsl?

I know its possible with workers *like with maplibre-contour, but that's not as fast.