Repository navigation
Description
Problem
A Shaded Relief has one light, the sun. A slope turned away from it is drawn at the ambient floor, base × 0.25 (Colorizer::color, crates/map/src/raster.rs, the ShadedRelief arm), and with cast shadows (#1796) a whole valley can sit there. Detail on those slopes is lost: a gully on the shaded side of a ridge reads as a flat dark patch.
Relief artists and tools like rayshader add a weak fill light from the other side for this. RustGIS's MapLibre hillshade layer already takes several lights (hillshade-method multidirectional, crates/tiles/src/dem.rs:187), but the raster Shaded Relief has none.
Proposal
One new setting, Fill light (raster.symbology "fill", 0 to 1, default 0): a light from the side opposite the sun (sun azimuth + 180°), 55° up. It adds to each cell's brightness
fill × max(0, L_fill − sin 55°)
where L_fill is the Lambert term toward that light (the same Horn slopes as the hillshade). Flat ground gets exactly sin 55° and so gains nothing. Only slopes turned toward the fill gain, and the more they turn, the more.
Choices in this proposal
- Only the slopes turned to the fill gain. I tried both forms in a local build (below). The plain additive fill, which the rayshader-like Python prototype for [Feature]: Shaded Relief with soft cast shadows and sky visibility #1782 used, brightens the flat ground as much as the slopes: it washes the map out before it opens the shadows. Removing the flat ground's share keeps the map's tone and spends the light where it's missing.
- One strength, a fixed direction. Opposite the sun is where the light is missing; 55° keeps the fill from casting its own long gradients.
fillAzimuthandfillAltitudecould follow if someone needs them. - Not shadowed. A fill stands for light scattered from the sky and the facing slopes, which has no sharp source. Cast shadows (feat(raster): Shaded Relief casts soft shadows (#1782, part 1) #1796) darken only the sun's light, as now.
- 0 by default. Existing projects draw today's pixels, and the setting is saved only when it isn't 0, as
shadowis.
Measured (local prototype)
Copernicus DEM GLO-30, Ouro Preto (Minas Gerais), UTM 23S at 30 m. Shaded Relief with a hypsometric ramp, sun 315° / 30°, Z factor 1.5, shadow 0.8, Bilinear. Grey level of the exported pixels (0–255):
| Mean | Std. deviation (contrast) | Darkest fifth's mean | |
|---|---|---|---|
| Flat 1:40,000, today | 132.8 | 43.1 | 68.4 |
| Additive fill 0.15 | 156.8 | 38.0 | 99.1 |
| Additive fill 0.3 | 180.4 | 32.8 | |
| Slopes only, fill 0.3 | 135.0 | 40.5 | 75.8 |
| Slopes only, fill 0.6 | 137.1 | 38.1 | 83.2 |
| Tilted 60°, 1:60,000, today | 138.0 | 61.5 | |
| Tilted, additive 0.15 | 159.5 | 51.1 | |
| Tilted, slopes only 0.6 | 143.5 | 56.6 |
The cost is one more Lambert term per cell from the 3 × 3 window already read. I didn't time it separately.
DEM: Copernicus DEM GLO-30, © DLR e.V. and Airbus, provided under COPERNICUS by the European Union and ESA.
How it fits with the rest of #1782
The light becomes ambient (sky visibility, #1782 part 2, PR #1871) + direct × cast shadow + fill. It belongs after part 2, which reshapes the same composition, and after the Bilinear light fix (#1880), so the fill is blended between cells like the rest.
Alternatives considered
- The additive fill. Measured above: it lifts the whole map, not the shadows.
- A multidirectional hillshade (MapLibre's method). It averages several suns, so the relief loses the single light direction that makes it read, and it can't share the one sun with cast shadows.
- A higher ambient floor. That lifts the shadowed slopes and the lit ones alike, the same washing as the additive fill.
🤖 Generated with Claude Code
Activity
feat(render): a fill light on Shaded Relief that opens the slopes in …