Skip to content

[Feature]: Shaded Relief: a fill light that opens the slopes in shadow without flattening the map #1912

Closed

Description

@elpidioassinaturas

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. fillAzimuth and fillAltitude could 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 shadow is.

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.

flat map at 1:40,000: today, additive 0.15, slopes only 0.3 and 0.6 tilted 60°: the same four

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

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