GRASS logo

NAME

p.shadow.planet - Compute a shadow mask for a planetary DEM.
Generates a binary shadow mask (1=sunlit, 0=shadow) for a planetary elevation raster given the solar azimuth and elevation angles. Uses ray-marching along the solar direction. Input DEM should be height above reference [m or km]; consistent units with planet radius.

KEYWORDS

Planetary, Terrain Analysis, shadow, terrain, solar

SYNOPSIS

p.shadow.planet
p.shadow.planet --help
p.shadow.planet elevation=name output=name solar_azimuth=float solar_elevation=float [radius=float] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

elevation=name [required]
Input height-above-reference DEM
output=name [required]
Name for output raster map
solar_azimuth=float [required]
Solar azimuth [degrees, N=0, E=90]
solar_elevation=float [required]
Solar elevation angle above horizon [degrees, 0–90]
radius=float
Mean planetary radius [same units as DEM heights]
Default: 3390000.0

Table of contents

DESCRIPTION

p.shadow.planet computes a shadow mask for a planetary DEM given the solar illumination direction. For each surface pixel the algorithm ray-marches toward the sun along the terrain and tests whether any intervening topography blocks the solar ray, using the DEM elevation values.

The sun direction is specified either as solar azimuth and elevation angles (typically from p.phocube or p.caminfo) or as a sun vector in body-fixed Cartesian coordinates.

Output is a binary raster (1 = illuminated, NULL = self-shadowed or cast-shadowed). An optional shadow_depth output raster contains the length of shadow behind each shadowed pixel.

NOTES

Ray-marching step size defaults to one DEM pixel. Sub-pixel accuracy can be increased at the cost of computation time. The maximum shadow trace distance is bounded by the image diagonal.

OpenMP parallelism is used across rows.

EXAMPLES

Compute shadow mask using sun angles from p.caminfo:

p.shadow.planet input=mola_dem \
    sun_azimuth=247.3 sun_elevation=32.1 \
    output=shadow_mask

ISIS3-equivalent workflow

ISIS3 ships a shadow application that ray-marches each pixel back toward the sun and flags those occluded by the DEM. To replicate

shade   from=mola.cub  to=mola_shaded.cub \
        azimuth=247.3 zenith=57.9    # zenith = 90 - elevation
shadow  from=mola.cub  to=mola_shadow.cub \
        sunazimuth=247.3 sunzenith=57.9

in GRASS, the equivalent chain is:

# 1. ISIS3 .cub -> GRASS DEM raster
p.in.isis input=mola.cub output=mola_dem
# 2. Shadow mask (replaces ISIS3 shadow)
p.shadow.planet input=mola_dem \
    sun_azimuth=247.3 sun_elevation=32.1 \
    output=mola_shadow
# 3. (optional) export back to ISIS3 .cub
p.out.isis input=mola_shadow output=mola_shadow.cub

mola_shadow is a binary raster with 1 = shadowed, NULL = sunlit, matching ISIS3's shadow.cub semantics. For a continuous shadow-depth output (relief shading rather than binary occlusion), add the -d flag.

REFERENCES

SEE ALSO

p.dem.prep, p.slope.planet, p.phocube, r.sunmask

AUTHOR

Yann Chemin

SOURCE CODE

Available at: p.shadow.planet source code (history)

Accessed: Sunday Nov 15 11:06:06 2026


Main index | Paint index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual