Skip to content

r.richdem.breachdepressions

Breach depressions in a DEM using RichDEM

r.richdem.breachdepressions [-e] input=name output=name [topology=string] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.richdem.breachdepressions input=name output=name

grass.tools.Tools.r_richdem_breachdepressions(input, output, topology="D8", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_richdem_breachdepressions(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.breachdepressions", input, output, topology="D8", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.richdem.breachdepressions", input="name", output="name")

Parameters

input=name [required]
    Input elevation raster
output=name [required]
    Output depression-breached elevation raster
topology=string
    Flow topology
    Allowed values: D8, D4
    Default: D8
-e
    Use Lindsay2016 epsilon-gradient shallowing (pit raised to just below lowest neighbour rather than exactly to it)
--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-breached 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
        Use Lindsay2016 epsilon-gradient shallowing (pit raised to just below lowest neighbour rather than exactly to it)
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-breached 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
        Use Lindsay2016 epsilon-gradient shallowing (pit raised to just below lowest neighbour rather than exactly to it)
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.breachdepressions removes topographic depressions from a digital elevation model (DEM) by carving a channel from each pit cell to the nearest drainage outlet, following the complete-breaching mode of the priority-flood algorithm of Lindsay (2016) as implemented in RichDEM by Richard Barnes. Unlike depression filling, which raises interior cells to the pour-point elevation, breaching lowers the cells along the breach channel, leaving the surrounding terrain unmodified.

Algorithm

The algorithm proceeds in three phases:

  1. Initialization. Each pit cell is shallowed: its elevation is raised to just below that of its lowest neighbor. This removes isolated single-cell pits cheaply and reduces the depth and length of breach channels required for larger depressions, thereby limiting the algorithm\'s impact on the DEM.
  2. Priority-flood traversal. DEM edge cells are inserted into a min-heap priority queue. The priority of each cell combines its elevation and insertion order, which correctly handles flat areas without a separate preprocessing step. Cells are removed from the queue in priority order; their unvisited neighbors are added, and a back-link is recorded for each newly encountered cell. When a pit cell is dequeued, the back-link chain is traced downslope to find the path to the nearest cell that is lower or on the DEM edge. Elevations along that path are lowered to form a monotonically descending breach channel.
  3. Output. In complete-breaching mode all depressions are resolved by breaching. (Lindsay (2016) also describes selective and constrained hybrid modes that fall back to filling for depressions whose breach channel would exceed specified depth or length thresholds; those modes are not exposed by this module.)

Complete-breaching processes DEMs in approximately 87% of the time required by an equivalent depression-filling algorithm (Lindsay, 2016).

When to breach versus fill

Breaching is preferred for high-relief landscapes dominated by fluvial processes, where most depressions are artifacts (erroneous damming along convergent topography from grid resolution or InSAR noise). It reinforces natural drainage pathways and modifies fewer cells than filling.

Filling is preferable for:

  • Very deep real depressions --- lakes, wetlands, sinkholes, open-pit mines --- where a breach channel would be unrealistically long and deeply incised.
  • Landscapes where the modelling goal is topographic depression mapping rather than surface flow routing.

For landscapes that genuinely contain both artifact and real depressions, consider the Fill--Spill--Merge workflow (r.richdem.dephier + r.richdem.fsm), which retains real depressions and routes water through them explicitly.

Flow topology

  • D8 (default) --- breach channels connect cells through any of the 8 neighbors (including diagonals).
  • D4 --- breach channels connect cells through the 4 cardinal neighbors only, producing orthogonal channel paths.

NOTES

The priority metric used during traversal combines cell elevation and insertion order using fixed-precision concatenation. This ensures correct handling of flat areas --- no separate flat-resolution step is needed after breaching, unlike after r.richdem.filldepressions (without the -e flag). If flat areas do persist, apply r.richdem.resolveflats before computing flow directions or accumulation.

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

Breach depressions using D8 topology:

r.richdem.breachdepressions input=dem output=dem_breached

Breach using D4 topology (cardinal neighbors only):

r.richdem.breachdepressions input=dem output=dem_breached_d4 topology=D4

Compare filling versus breaching on the same DEM:

r.richdem.filldepressions input=dem output=dem_filled
r.richdem.breachdepressions input=dem output=dem_breached
r.mapcalc "diff = dem_filled - dem_breached"

REFERENCES

  • Lindsay, J.B. (2016). Efficient hybrid breaching-filling sink removal methods for flow path enforcement in digital elevation models. Hydrological Processes Vol 30(6), pp 846--857. DOI: 10.1002/hyp.10648
  • Barnes, R. (2016). RichDEM: Terrain Analysis Software. URL: http://github.com/r-barnes/richdem

SEE ALSO

r.richdem.filldepressions, r.richdem.resolveflats, r.richdem.flowaccumulation, r.richdem.dephier, r.fill.dir, r.watershed

AUTHORS

John B. Lindsay (algorithm, Lindsay 2016); Richard Barnes (RichDEM implementation)

GRASS GIS bindings: Andrew D. Wickert, with assistance from Claude Sonnet 4.6

SOURCE CODE

Available at: r.richdem.breachdepressions source code (history)
Latest change: Saturday May 30 11:40:25 2026 in commit 6b92b36