Repository navigation
Description
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 × directOn, 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 altitudeis 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.
ambientis 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:
ambientis saved only when it isn't the default, andbalancedonly when true, asshadowandskyare. - 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:
The peaks in the same order:
🤖 Generated with Claude Code
Activity
feat(render): balanced light and an ambient setting on Shaded Relief (#…