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
Conditioning moved 25 cells.
| 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?
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
Pits found
A cell with no neighbor at or below it49 cells= 1 pitsConditioning
Priority-Flood from the window's edge and its no-data boundaryPriority-Flood with 0.00001 m a cell= 0 pits leftWhat moved
Cells whose elevation changed3700.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
- 2026-11-07, changed: The six hydrology tools now hand their work along. Every flow tool tells you to condition the grid first, and the fill tool's answer is exactly what they want, so its page now offers to carry the conditioned grid straight into the flow tools, with the cell size and the no-data value. The tools also point at each other in the order you would use them: fill, flow direction, accumulation, streams, watershed, longest path. A test routes water over a conditioned grid and over the grid as entered, and shows the difference: no cell left stranded in the first, a pit swallowing the bowl in the second. Changelog
- 2026-11-06, added: A new tool conditions a DEM so water can leave every cell, which every flow calculation assumes and no measured elevation grid gives you: noise, bridges, culverts, and road embankments leave hollows that trap water. Enter the grid and its cell size and it either fills each hollow to the height it would spill at, by the Priority-Flood method, or cuts a channel out of it, which moves far less earth where a road or a dam is what dammed the water. It reports every cell it moved, before and after, and the earth that represents, so you can judge whether the conditioning changed the ground more than you want. Cells marked no data are never raised, never cut, and never crossed, and the window's edge is treated as an outlet, so clip wider than the basin you care about. Changelog
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
- Priority-flood: An optimal depression-filling and watershed-labeling algorithm for digital elevation models, Barnes, R., Lehman, C., and Mulla, D., Computers & Geosciences, Volume 62, pages 117-127 (DOI 10.1016/j.cageo.2013.04.024); preprint arXiv:1511.04463. Algorithm 2 (Improved Priority-Flood) and Algorithm 3 (Priority-Flood+ε), which raises each cell to just above the one it was reached from so that every filled cell keeps a descending path to the outlet.
- Efficient hybrid breaching-filling sink removal methods for flow path enforcement in digital elevation models, Lindsay, J. B., Hydrological Processes, Volume 30, issue 6, pages 846-857 (DOI 10.1002/hyp.10648). The hybrid method: breach a pit along the least-cost path, the cost being the elevation that must be dug out, within a maximum depth and length, and fill what cannot be breached within those limits.
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.