r.richdem.filldepressions
Fill depressions in a DEM using RichDEM
r.richdem.filldepressions [-e] input=name output=name [topology=string] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.richdem.filldepressions input=name output=name
grass.tools.Tools.r_richdem_filldepressions(input, output, topology="D8", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_richdem_filldepressions(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.filldepressions", input, output, topology="D8", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("r.richdem.filldepressions", input="name", output="name")
Parameters
input=name [required]
Input elevation raster
output=name [required]
Output depression-filled elevation raster
topology=string
Flow topology
Allowed values: D8, D4
Default: D8
-e
Apply epsilon gradient to flat areas after filling
--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 depression-filled elevation raster
Used as: output, raster, name
topology : str, optional
Flow topology
Allowed values: D8, D4
Default: D8
flags : str, optional
Allowed values: e
e
Apply epsilon gradient to flat areas after filling
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 depression-filled elevation raster
Used as: output, raster, name
topology : str, optional
Flow topology
Allowed values: D8, D4
Default: D8
flags : str, optional
Allowed values: e
e
Apply epsilon gradient to flat areas after filling
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.filldepressions fills all topographic depressions (pits, sinks) in a digital elevation model (DEM) so that every cell drains to the map boundary. Depression filling is a common pre-processing step before computing flow directions or flow accumulation.
Depressions are raised to the elevation of their lowest outlet (the pour point), producing a hydrologically conditioned DEM in which no interior drainage exists. The algorithm is based on the Priority-Flood approach of Barnes et al. (2014), which runs in optimal O(N log N) time.
When the -e flag is set, an epsilon (ε) gradient is imposed on the filled flat areas. This ensures that a unique steepest-descent flow direction exists for every cell, including those within large flat regions created by the fill. Without this flag, filled areas may contain cells with no unique downhill neighbor.
Two flow topologies are supported:
- D8 (default) --- each cell drains to one of its 8 neighbors.
- D4 --- each cell drains to one of its 4 cardinal neighbors only.
NOTES
Depression filling removes all interior basins by raising their elevations. This is appropriate when depressions are considered artifacts (e.g., errors in lidar or SRTM data). When depressions represent real landscape features (lakes, prairie potholes, endorheic basins), consider using r.richdem.breachdepressions or the r.richdem.dephier / r.richdem.fsm workflow instead.
After filling, flat regions may be created where the fill raised cells to the same elevation as the pour point. Use the -e flag or r.richdem.resolveflats to impose drainage gradients on such areas.
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
Fill depressions using D8 topology:
r.richdem.filldepressions input=dem output=dem_filled
Fill depressions and impose an epsilon gradient on flat areas:
r.richdem.filldepressions -e input=dem output=dem_filled_eps
Fill using D4 topology:
r.richdem.filldepressions input=dem output=dem_filled_d4 topology=D4
REFERENCES
- Barnes, R., Lehman, C., Mulla, D. (2014). Priority-flood: An optimal depression-filling and watershed-labeling algorithm for digital elevation models. Computers & Geosciences Vol 62, pp 117--127. DOI: 10.1016/j.cageo.2013.04.024
- Barnes, R. (2016). RichDEM: Terrain Analysis Software. URL: http://github.com/r-barnes/richdem
SEE ALSO
r.richdem.breachdepressions, r.richdem.resolveflats, r.richdem.flowaccumulation, r.richdem.dephier, r.fill.dir, r.watershed
AUTHORS
Richard Barnes (RichDEM library)
GRASS GIS bindings: Andrew D. Wickert, with assistance from Claude Sonnet 4.6
SOURCE CODE
Available at: r.richdem.filldepressions source code
(history)
Latest change: Saturday May 30 11:40:25 2026 in commit 6b92b36