geoprimsField-grade geospatial math

Fill or breach the pits in a DEM

Removes the depressions that trap water in an elevation grid, by Priority-Flood with a small slope or by cutting a channel out of each pit, and reports every cell it changed and how much earth that is.

Experimental: not yet fully verified. How results are checked

25

Conditioning moved 25 cells.

Conditioned grid
Elevations
100, 100, 100, 100, 100, 100, 100
100, 100.00001, 100.00001, 100.00001, 100.00001, 100.00001, 100
100, 100.00001, 100.00002, 100.00002, 100.00002, 100.00001, 100
100, 100.00001, 100.00002, 100.00003000000001, 100.00002, 100.00001, 100
100, 100.00001, 100.00002, 100.00002, 100.00002, 100.00001, 100
100, 100.00001, 100.00001, 100.00001, 100.00001, 100.00001, 100
100, 100, 100, 100, 100, 100, 100
Fill volume
Cut volume
Deepest pit filled
Deepest cut made
Pits before
Pits left
Provenance
Computed by
raster.hydrology.fill 1.0.0, core 0.1.0
Model
Priority-Flood + ε (Barnes, Lehman, and Mulla 2014, Algorithm 3): every edge cell and every cell touching no data seeds a priority queue ordered by elevation; a cell reached from a lower one is raised to that cell's elevation plus ε, so every filled cell keeps a descending path out. Breaching (Lindsay 2016) first cuts each pit a least-cost channel to a lower cell, the cost being the earth dug at the pit's level less ε a step, within the depth and length allowed, then fills what is left. No-data cells are never changed and never crossed
Accuracy
The conditioned grid is exact in the arithmetic of the method: the fill volume is the sum of each cell's rise times the cell area, and after conditioning no cell is left without a path out of the window
Notes
1 shown with the answer
Cites
Barnes, R., Lehman, C., and Mulla, D., Computers & Geosciences, Priority-flood: An optimal depression-filling and watershed-labeling algorithm for digital elevation models; Lindsay, J. B., Hydrological Processes, Efficient hybrid breaching-filling sink removal methods for flow path enforcement in digital elevation models

Something look off?

Your values

Showing an example. Change anything.
More options 4
Run many at once from a CSV

Loading…

How we got thisFormula, worked example, sources, and proof

Model: Priority-Flood + ε (Barnes, Lehman, and Mulla 2014, Algorithm 3): every edge cell and every cell touching no data seeds a priority queue ordered by elevation; a cell reached from a lower one is raised to that cell's elevation plus ε, so every filled cell keeps a descending path out. Breaching (Lindsay 2016) first cuts each pit a least-cost channel to a lower cell, the cost being the earth dug at the pit's level less ε a step, within the depth and length allowed, then fills what is left. No-data cells are never changed and never crossed

Show your work

  1. Pits found

    A cell with no neighbor at or below it

    49 cells = 1 pits

  2. Conditioning

    Priority-Flood from the window's edge and its no-data boundary

    Priority-Flood with 0.00001 m a cell = 0 pits left

  3. What moved

    Cells whose elevation changed

    3700.04 m³ added, 0.00 m³ taken out = 25

The same steps an agent gets from the MCP server with explain: true.

Accuracy: The conditioned grid is exact in the arithmetic of the method: the fill volume is the sum of each cell's rise times the cell area, and after conditioning no cell is left without a path out of the window

When to use this: Use this before any flow work on a DEM clip: flow directions, accumulation, streams, and watersheds all assume water can leave every cell, and a raw DEM has pits from noise, bridges, and culverts that trap it. Enter the grid and its cell size, pick filling or breaching, and it returns the conditioned grid with every cell it moved and the earth that represents, so you can judge whether the conditioning changed the terrain more than you want.

Limitations: It conditions the window you give and treats its edge as an outlet, so a depression that continues past the edge is treated as drained there; clip wider than the basin you care about. Breaching cuts a one-cell channel along a least-cost path and does not widen it, and pits it cannot reach an outlet for within the depth and length allowed are filled instead, which the result says. The grid is plane: cell area is the cell size squared, so a geographic grid in degrees needs its cell size in meters at the latitude. The window holds at most 25,000 cells.

Worked example: A 7 by 7 grid with one pit 3 m deep. Source: add-raster-hydrology raster/hydrology, the Single bowl scenario: the pit is raised to the elevation it spills at, and only the bowl's cells move. It is golden test vector v001, and every build checks the tool still gives its answer within its tolerance.

You enter

Cell size
10 m
Elevation grid
100, 100, 100, 100, 100, 100, 100 100, 99, 99, 99, 99, 99, 100 100, 99, 98, 98, 98, 99, 100 100, 99, 98, 95, 98, 99, 100 100, 99, 98, 98, 98, 99, 100 100, 99, 99, 99, 99, 99, 100 100, 100, 100, 100, 100, 100, 100
Method
fill

You get

Cells changed
25
Fill volume
3,700.04 m³
Cut volume
0 m³
Deepest pit filled
5 m
Deepest cut made
0 m
Pits before
1
Pits left
0
Method
Priority-Flood with 0.00001 m a cell

Review: Not yet independently reviewed by a GIS professional.

Last verified: 2026-11-06, when a maintainer last confirmed this tool's sources at the issuer. See the sources ledger.

Status: version 1.0.0, core 0.1.0. See this tool in the verification report.

Changes

Checked against: 22 golden test vectors (download the test vectors, each with its source and tolerance). See how results are checked and every source.

Sources

Terms

DEM: digital elevation model
A grid of elevations. A surface model includes buildings and canopy; a terrain model is the ground beneath them. Source: Copernicus DEM GLO-30

Experimental means this tool has not yet met the stable bar: at least 20 golden vectors, differential tests, and an independent worked example.