Repository navigation
Description
Before you start
- I searched the existing issues and the roadmap and did not find a duplicate request.
(Closest: #726's phase 4 lists "sun shadows by date and time" in full 3D scenes. This is on a raster's Shaded Relief, on any flat or tilted map and in layouts, so it doesn't wait for scenes and doesn't replace them.)
What problem does this solve?
Shaded Relief shades each cell by the way it faces one light (hillshade, crates/map/src/raster.rs:1582) and keeps a fixed share of ambient light (0.25 + 0.75 * h, raster.rs:1573). So a slope in a mountain's shadow looks as lit as one in the open, and a deep valley gets as much sky as a plain. The relief reads flatter than it is, most of all in a figure for a paper or a class.
Today this can be done in part, and I tested it: GeoLibre's sky_view_factor as a second layer with layer.blend multiply and layer.transparency gives sky visibility. It needs the optional runner, two layers tuned by hand, and has no soft cast shadow.
A Python prototype of this on the same DEM took about 7 minutes, unoptimised. I'll add a picture of it next to today's Shaded Relief in a comment, once I've confirmed the DEM's licence allows it.
Proposed solution
Two more settings on Shaded Relief, in raster.symbology and the Style pane:
shadow, 0 to 1: how dark cast shadows are, with a soft edge from a sun of finite size.sky, 0 to 1: how much a cell's visible sky scales its ambient light.
Both default to 0, which draws today's picture exactly, so existing projects don't change.
How it works:
- Per cell, once per raster and sun, off the frame on the desktop, then kept: a grid of light left by the shadows and a grid of visible sky, from the horizon seen by each cell.
- The draw path (
crates/render/src/raster.rs:689) reads them next tohillshade, and the colour becomesambient * sky + direct * shadow. Layouts, exports and the tilted drape get it from the same path.
Choices in this proposal, which can change if you prefer otherwise:
- Written here, from the geometry, with no new dependency. rayshader is GPL-3.
surtgis-relief(MIT/Apache) is a candidate, but it adds 11 crates, needs Rust 1.91, and itsray_shadeover-shadows on diagonal suns (ray_shade marks lit slopes as shadowed on diagonal azimuths (cell read at the wrong distance) franciscoparrao/surtgis#153, still open, and still there in 1.8.1). - Heights read between cells while tracing the sun (bilinear), for the reason in that report: reading the nearest cell over-shadows diagonal suns.
- The trace stops once the ray is above the raster's highest cell, since nothing past that point can shade it. On a DEM of 2.36 million cells it changed no cell and halved the time on one thread.
- Two PRs, or three: cast shadows; sky visibility; a fill light on its own, if wanted.
- Off the frame on the desktop with no new cap, and a cap of 0.5 million cells in the browser, which has no threads. Natively on one thread that is about 1.4–1.7 s of shadow and 2.3 s of sky; the browser is likely slower, which I haven't measured. A larger raster draws without these in the browser, with a notice saying so (AGENTS.md, Never silent).
Tests:
- Against geometry with a known answer, at every azimuth: a wall's shadow has the length its height gives, and a pit has the sky its depth gives. Not against another tool.
- 0 gives the same pixels as today.
- A raster over the cap gives the notice, and one under it gives none.
Limits I know of:
- A shadow cast from outside the raster isn't seen, so a small clip can miss one from a mountain beyond its edge.
- A COG read only in part has no cells for this. It would take the same notice as an oversized raster.
- I timed the algorithm in Rust outside RustGIS:
surtgis-relief's code with the bilinear read and the early stop, on 1378 × 1715 cells (2.36 million), on a 16-thread PC that was also compiling. Soft shadow from 11 sun altitudes: 0.8–2.0 s on 16 threads, 6.4–8.1 s on one. Sky visibility, 16 directions and 3 km, without the early stop: 1.3–1.5 s on 16 threads, 10.7–11.4 s on one. GeoLibre'ssky_view_factortook 7.5–8 s for the same sky, reading and writing files included. Not measured in WebAssembly. - The trace has been checked against known geometry at 10 azimuths: a plane is right at all of them, and a 5 × 5 tower is exact at the eight main ones but loses 17 of 109 shadow cells at 20°. Narrow occluders between those directions would need a different stepping.
I can do this if it looks right.
Estimated scope
Medium: a broader feature that is feasible in a reasonable timeframe
Alternatives considered
- GeoLibre tools plus blend modes: works today for the sky part (tested above), but needs the optional runner and has no soft shadow.
- A raster function that writes the shadow as a new layer: useful, but it leaves the same hand tuning, so I'd rather have the setting. The grids could also be offered that way later.
- The GPU: exports and tilted rasters draw on the CPU today (
docs/user-guide/maps.md), so it wouldn't reach them.
🤖 Generated with Claude Code
Activity
docs(raster): cast shadows' time as measured (opengeos#1782)
fix(raster): cast shadows don't hold the Layout view, and a new sun s…
test(raster): wait for the cast shadows' landing instead of reading a…
fix(raster): a Layout page says why it drew no cast shadows; Cancel a…
fix(raster): a cancelled export stops the cast shadows it waited for (o…
fix(raster): cast shadows are owned by the map and layer drawing them (…
fix(raster): each owner's latest cast shadows are kept, so many maps …
fix(raster): map exports say a layer drawn without its cast shadows, …
fix(raster): a map of a relief alone gets its cast shadows without be…
fix(render): whatever draws the map says its layers drawn without cas…
feat(raster): Shaded Relief casts soft shadows (#1782, part 1) (#1796)
fix(render): a tilted export waits for the cast shadows its bands draw (
fix(render): #1782 follow-ups: exports wait only for the cast shadows…
test(render): the tilted wait test waits for the export's own signal (o…
test(render): the tilted wait test fails, not hangs, after 30 s (open…
fix(render): #1782 follow-ups 2: an export says only its last pass's …
feat(raster): Shaded Relief dims its ambient light by the sky each ce…
elpidioassinaturas commentedon Nov 14, 2026
Done: cast shadows in #1796 (follow-ups #1823, #1830), sky visibility in #1871, and the fill light in #2005. Closing.