p.sunmask computes a terrain shadow mask from a DEM and an explicit sun position (altitude and azimuth), using parallel processing on all available CPU cores (OpenMP) and optionally on a GPU or CPU accelerator via OpenCL.
It is a drop-in replacement for r.sunmask (altitude/azimuth mode) with the same output convention: 1 = sunlit, 0 = shadow, NULL = nodata.
For each output pixel P at position (r, c) with elevation h₀:
azimuth
(from North, clockwise) at steps of 0.5 pixels.All pixels are independent, making the algorithm embarrassingly parallel.
OpenMP (always): The outer pixel loop is parallelised with
#pragma omp parallel for across all available CPU threads. Set
OMP_NUM_THREADS to control the thread count.
OpenCL (optional, probed at runtime): If the module was built with
HAVE_OPENCL and an OpenCL platform is found at runtime, the shadow kernel
runs on the first available GPU device, or on the CPU device if no GPU is
present (e.g. via PoCL). Falls back silently to OpenMP if no platform is found.
Use the -c flag to force CPU/OpenMP even when OpenCL is available.
The entire DEM is loaded into RAM as a float array. Memory requirement:
nrows × ncols × 4 bytes. For the LOLA South Polar 5 m DEM
(30336×30336) ≈ 3.5 GB; for a 10×10 km region at 5 m (2000×2000) = 16 MB.
| Parameter | Type | Range | Description |
|---|---|---|---|
elevation |
raster | required | Input DEM raster (metres) |
output |
raster | required | Output shadow mask (0=shadow, 1=sunlit) |
altitude |
float | 0–89.999 | Sun elevation angle above horizon (degrees) |
azimuth |
float | 0–360 | Sun azimuth angle from North, clockwise (degrees) |
| Flag | Description |
|---|---|
-c |
Force CPU/OpenMP path even if OpenCL is available |
Dependencies:
sudo apt install opencl-c-headerssudo apt install ocl-icd-opencl-devsudo apt install pocl-opencl-icdBuild and install:
cd p.sunmask make MODULE_TOPDIR=$(grass --config path) sudo make install MODULE_TOPDIR=$(grass --config path)
The Makefile auto-detects OpenCL at build time via pkg-config. If OpenCL
is not found the module is built with OpenMP only.
# Basic usage (identical to r.sunmask altitude/azimuth mode) p.sunmask elevation=dem output=shadow altitude=5.0 azimuth=180.0 # Force CPU/OpenMP path p.sunmask -c elevation=dem output=shadow altitude=5.0 azimuth=180.0 # Control thread count OMP_NUM_THREADS=8 p.sunmask elevation=dem output=shadow altitude=5.0 azimuth=90.0
p.sunmask uses the same flat-earth ray-march approximation as r.sunmask. This is accurate for study areas smaller than a few hundred kilometres.
The output is integer CELL type: values 0 and 1. To match r.sunmask's
convention (1=sunlit, NULL=shadow), apply: r.null map=output null=0
p.illumination.sunfraction applies this internally, so no extra step is needed in the pipeline.
r.sunmask, p.illumination.sunfraction, p.illumination.shadow
Yann Chemin
Available at: p.sunmask source code (history)
Accessed: Sunday Nov 15 11:06:17 2026
Main index | Paint index | Topics index | Keywords index | Graphical index | Full index
© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual