r.richdem.resolveflats
Resolve flat areas in a DEM by imposing a local gradient using RichDEM
r.richdem.resolveflats input=name output=name [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.richdem.resolveflats input=name output=name
grass.tools.Tools.r_richdem_resolveflats(input, output, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_richdem_resolveflats(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.resolveflats", input, output, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("r.richdem.resolveflats", input="name", output="name")
Parameters
input=name [required]
Input (filled or breached) elevation raster
output=name [required]
Output elevation raster with resolved flats
--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 (filled or breached) elevation raster
Used as: input, raster, name
output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
Output elevation raster with resolved flats
Used as: output, raster, name
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 (filled or breached) elevation raster
Used as: input, raster, name
output : str, required
Output elevation raster with resolved flats
Used as: output, raster, name
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.resolveflats imposes a small epsilon gradient on flat areas of a DEM so that every cell has a unique downhill neighbor and a well-defined flow direction. Flat areas---regions in which all cells share the same elevation---commonly arise after depression filling or in gently sloping terrain and prevent the computation of meaningful flow directions.
The algorithm of Barnes et al. (2014) constructs two auxiliary gradient fields and combines them to produce a gradient that drains away from higher terrain and toward lower terrain, ensuring that flow traverses flats in a physically plausible way without crossing drainage divides. The elevation adjustments are on the order of the floating-point epsilon, so they do not meaningfully alter the DEM's topographic properties.
NOTES
r.richdem.resolveflats is typically applied after r.richdem.filldepressions or r.richdem.breachdepressions to handle any flat areas created by the conditioning step.
An alternative approach is to use the -e flag in r.richdem.filldepressions directly, which combines filling and epsilon-gradient imposition in one step.
This module is not needed before running r.richdem.dephier, which handles flat areas internally.
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
Resolve flat areas after depression filling:
r.richdem.filldepressions input=dem output=dem_filled
r.richdem.resolveflats input=dem_filled output=dem_conditioned
Resolve flats on a raw DEM before computing flow accumulation:
r.richdem.resolveflats input=dem output=dem_noflats
r.richdem.flowaccumulation input=dem_noflats output=flow_accum
REFERENCES
- Barnes, R., Lehman, C., Mulla, D. (2014). An efficient assignment of drainage direction over flat surfaces in raster digital elevation models. Computers & Geosciences Vol 62, pp 128--135. DOI: 10.1016/j.cageo.2013.01.009
- Barnes, R. (2016). RichDEM: Terrain Analysis Software. URL: http://github.com/r-barnes/richdem
SEE ALSO
r.richdem.filldepressions, r.richdem.breachdepressions, r.richdem.flowaccumulation, 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.resolveflats source code
(history)
Latest change: Sunday May 31 20:21:19 2026 in commit 2163cf6