r.richdem.terrainattribute
Calculate terrain attributes using RichDEM
r.richdem.terrainattribute input=name output=name [attribute=string] [zscale=float] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.richdem.terrainattribute input=name output=name
grass.tools.Tools.r_richdem_terrainattribute(input, output, attribute=None, zscale=1.0, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_richdem_terrainattribute(input="name", output="name")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
grass.script.run_command("r.richdem.terrainattribute", input, output, attribute=None, zscale=1.0, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("r.richdem.terrainattribute", input="name", output="name")
Parameters
input=name [required]
Input elevation raster
output=name [required]
Output terrain attribute raster
attribute=string
Terrain attribute to calculate
Allowed values: slope_riserun, slope_percentage, slope_degrees, slope_radians, aspect, curvature, planform_curvature, profile_curvature
zscale=float
Z-axis scale factor applied before calculation
Default: 1.0
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
input : str | np.ndarray, required
Input elevation raster
Used as: input, raster, name
output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
Output terrain attribute raster
Used as: output, raster, name
attribute : str, optional
Terrain attribute to calculate
Allowed values: slope_riserun, slope_percentage, slope_degrees, slope_radians, aspect, curvature, planform_curvature, profile_curvature
zscale : float, optional
Z-axis scale factor applied before calculation
Default: 1.0
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.
Raises:
grass.tools.ToolError: When the tool ended with an error.
input : str, required
Input elevation raster
Used as: input, raster, name
output : str, required
Output terrain attribute raster
Used as: output, raster, name
attribute : str, optional
Terrain attribute to calculate
Allowed values: slope_riserun, slope_percentage, slope_degrees, slope_radians, aspect, curvature, planform_curvature, profile_curvature
zscale : float, optional
Z-axis scale factor applied before calculation
Default: 1.0
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
DESCRIPTION
r.richdem.terrainattribute calculates first- and second-order terrain attributes from a digital elevation model. Available attributes are slope (in four unit systems), aspect, and three curvature measures.
Slope
Slope is the magnitude of the terrain gradient---the rate of elevation change in the steepest downhill direction. It is computed using the Horn (1981) method, which uses a weighted average of finite differences over a 3×3 neighborhood to estimate the east--west and north--south gradient components. Slope is available in four unit systems:
- slope_riserun --- dimensionless rise/run ratio (tan of slope angle)
- slope_percentage --- rise/run expressed as a percentage
- slope_degrees --- angle in degrees from horizontal
- slope_radians --- angle in radians from horizontal
Aspect
aspect is the compass direction of the steepest downhill gradient, measured in degrees clockwise from north (0--360°), using the Horn (1981) method.
Curvature
Curvature describes the rate of change of slope and is useful for identifying ridges, valleys, and areas of flow convergence or divergence. Three curvature attributes are available, following Zevenbergen and Thorne (1987):
- curvature --- total (mean) curvature; positive values indicate convex surfaces, negative indicate concave surfaces.
- planform_curvature --- curvature of the contour line perpendicular to the slope direction; positive values indicate flow divergence, negative indicate convergence.
- profile_curvature --- curvature in the slope direction; positive values indicate slope acceleration (convex profile), negative indicate slope deceleration (concave profile).
Z-axis scaling
The optional zscale parameter multiplies elevation values before computation. This is useful when vertical and horizontal units differ (e.g., elevation in feet, horizontal in meters: use zscale=0.3048). When horizontal units are geographic degrees and elevation is in meters, projecting to a metric coordinate system is preferable to using zscale.
NOTES
Computations use a 3×3 moving window and assume a planar local coordinate system. For data in geographic (latitude/longitude) coordinates, the horizontal scale varies with latitude and slope results will be approximate. In such cases, project to an equal-area or conformal coordinate system before computing terrain attributes, or apply an appropriate zscale.
To compute slope and aspect simultaneously in GRASS, consider r.slope.aspect. For more morphometric parameters computed over variable window sizes, see r.param.scale.
REQUIREMENTS
This module requires the RichDEM Python package, which is not a standard GRASS GIS dependency and must be installed separately:
pip install richdem
If pip install richdem fails (the package requires a C++ compiler), build
from source:
git clone https://github.com/r-barnes/richdem.git
cd richdem/wrappers/pyrichdem
pip install -e .
Ensure that RichDEM is installed into the same Python environment used by GRASS GIS.
EXAMPLES
Calculate slope in degrees:
r.richdem.terrainattribute input=dem output=slope attribute=slope_degrees
Calculate aspect:
r.richdem.terrainattribute input=dem output=aspect attribute=aspect
Calculate planform curvature:
r.richdem.terrainattribute input=dem output=planform_curv attribute=planform_curvature
Scale elevation in feet to match horizontal units in meters:
r.richdem.terrainattribute input=dem_ft output=slope attribute=slope_degrees zscale=0.3048
REFERENCES
- Horn, B.K.P. (1981). Hill shading and the reflectance map. Proceedings of the IEEE Vol 69(1), pp 14--47. DOI: 10.1109/PROC.1981.11918
- Zevenbergen, L.W., Thorne, C.R. (1987). Quantitative analysis of land surface topography. Earth Surface Processes and Landforms Vol 12(1), pp 47--56. DOI: 10.1002/esp.3290120107
- Barnes, R. (2016). RichDEM: Terrain Analysis Software. URL: http://github.com/r-barnes/richdem
SEE ALSO
r.slope.aspect, r.param.scale, r.richdem.flowaccumulation
AUTHORS
Richard Barnes (RichDEM library)
GRASS GIS bindings: Andrew D. Wickert, with assistance from Claude Sonnet 4.6
SOURCE CODE
Available at: r.richdem.terrainattribute source code
(history)
Latest change: Saturday May 30 11:40:25 2026 in commit 6b92b36