Skip to content

[Feature]: Shaded Relief with soft cast shadows and sky visibility #1782

Closed

Description

@elpidioassinaturas

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 to hillshade, and the colour becomes ambient * 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 its ray_shade over-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's sky_view_factor took 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

  1. added a commit that references this issue on Nov 12, 2026
  2. added a commit that references this issue on Nov 12, 2026
  3. elpidioassinaturas commented on Nov 14, 2026

    @elpidioassinaturas
    ContributorAuthor

    Done: cast shadows in #1796 (follow-ups #1823, #1830), sky visibility in #1871, and the fill light in #2005. Closing.

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