Skip to content

[Feature]: Shaded Relief: balanced light, so flat ground keeps the ramp's colour and lit slopes brighten #1977

Closed

Description

@elpidioassinaturas

Problem

A Shaded Relief with a colour ramp multiplies the ramp's colour by 0.25 + 0.75 h (Colorizer::paint, the ShadedRelief arm in crates/map/src/raster.rs). Here h is the Lambert term toward the sun, from 0 to 1. Three things follow:

  • The whole map is darker than its legend. Flat ground lit from 45° gets h = sin 45° ≈ 0.71, so it is drawn at about 78% of the ramp's colour. The legend and the colorbar show the ramp itself, so a reader matches the map's colours against lighter swatches. On the test below, the drawn map's mean brightness is 65% of the ramp's.
  • No slope is brighter than the ramp. The factor never passes 1, so the relief shows only by darkening the slopes turned from the sun. Slopes facing the sun never catch a highlight, and the map reads as dim rather than lit.
  • How dark the shadows are is fixed. The 0.25 a slope in full shadow keeps is a constant in the code, so a map can't have softer or deeper shadows without a second layer.

Web relief viewers often use a balanced form instead. One example is the GEM-15 terrain viewer (bertt/gem15, MapLibre), whose hillshade looks strongly three-dimensional on a flat map.

Proposal

Two settings in Shaded Relief, both passed to the function that lights each cell (Colorizer::paint and the light it is given):

  • "ambient": 0 to 1, the share of the ramp's colour a slope turned fully from the sun keeps. This is today's constant 0.25, made a parameter. It applies to both lights below.

  • "balanced": true or false. Off, a cell is drawn as today:

    f = ambient × sky + (1 − ambient) × h × direct

    On, the sun's term is divided by its value on flat ground:

    f = ambient × sky + (1 − ambient) × (h / sin altitude) × direct, at most 1.3.

In both, sky is the share of the sky a cell sees (sky, #1782 part 2) and direct is what cast shadows leave of the sun (shadow, #1796), as now.

With "balanced": true:

  • h / sin altitude is 1 on flat ground, whatever the sun's height. So flat ground is drawn in the ramp's exact colour, the colour the legend shows.
  • Slopes turned toward the sun brighten, up to 1.3. Slopes turned away fall to ambient.
  • Each channel is clamped to 255, as now.

The Z factor, azimuth, altitude, Bilinear blending (#1880) and the other Shaded Relief settings work as they do today. The panel would show Ambient as a slider and Balanced as a check box, beside Shadow and Sky.

Choices in this proposal

  • Flat ground is the reference. A hypsometric map is read through its legend, so the commonest ground should carry the legend's colour, and the light should add and take away around it.
  • ambient is one parameter for both lights. It is the one value a mapmaker tunes most: how deep the shadows go. Making today's 0.25 a parameter also lets the current light have softer shadows.
  • Default ambient: 0.25, or 0.5 when balanced. 0.25 keeps today's pixels. With the balanced light, 0.5 keeps about today's contrast (standard deviation 36.9 against 37.4 in the test below) while the map reaches 88% of the ramp's brightness. At 0.65 the shadows were too pale (contrast 28.9); at 0.35 the map was more dramatic than today (45.8) but clipped 2.5% of its pixels.
  • Multiply, then clamp. I also tried moving highlights toward white (c + (255 − c)(f − 1)) so that light colours never clip. It made the map hazier: the contrast fell from 36.9 to 33.5. Plain multiplication clipped 1.2% of the pixels.
  • At most 1.3. Enough for a visible highlight on slopes facing the sun, while keeping the clipped share low.
  • Saved only when set. Existing projects keep drawing today's pixels: ambient is saved only when it isn't the default, and balanced only when true, as shadow and sky are.
  • Separate from the fill light ([Feature]: Shaded Relief: a fill light that opens the slopes in shadow without flattening the map #1912). [Feature]: Shaded Relief: a fill light that opens the slopes in shadow without flattening the map #1912 adds a second light that opens shaded slopes without touching flat ground. This issue rescales the sun's light so that flat ground is the ramp, and makes the shadows' depth a setting. The two can be used together.

Measured (prototype in Python, not RustGIS output)

Copernicus GLO-30 DEM of the Caparaó range (Minas Gerais / Espírito Santo), resampled ×2 bilinearly, a green–yellow–orange–brown–white ramp, sun 315° / 45°, Z factor 2, no cast shadows. Grey levels of the drawn pixels (0–255); the ramp alone has a mean of 159.6.

Mean Share of the ramp's brightness Std. deviation (contrast) Darkest fifth's mean Clipped pixels
Today (ambient 0.25) 104.2 65% 37.4 50.4 0%
Balanced, ambient 0.65 146.2 92% 28.9 108.4 0.27%
Balanced, ambient 0.5 (this proposal's default) 140.4 88% 36.9 89.2 1.21%
Balanced, ambient 0.35 134.6 84% 45.8 68.8 2.51%
Balanced 0.5, highlights toward white 138.1 87% 33.5 89.2 0%

With Z factor 1 the balanced map (ambient 0.5) reaches 95% of the ramp's brightness, but low hills flatten (contrast 28.8). A Z factor of 1.5 to 2 suits it better on 30 m data.

Today, balanced with ambient 0.5, and balanced with 0.65, over the whole range, with the ramp alone under them:

Caparaó range drawn with today's light, the balanced light with ambient 0.5, and with ambient 0.65, all with Z factor 2. Drawn in Python, not RustGIS output.

The peaks in the same order:

Detail of the Caparaó peaks in the same three versions.

🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions