Watershed above a pour point
Every cell of an elevation grid whose water reaches the point you pick, with the basin's area, relief, mean slope, outline, and its longest flow path.
Experimental: not yet fully verified. How results are checked
That point drains 27,900 m².
- The basin reaches the window's edge, so the real basin may continue beyond the data.
| Elevations |
|---|
| 1, 1, 1, 1, 1, 1, 1 |
| 1, 1, 1, 1, 1, 1, 1 |
| 0, 1, 1, 1, 1, 1, 0 |
| 0, 0, 1, 1, 1, 0, 0 |
| 0, 0, 1, 1, 1, 0, 0 |
| 0, 0, 1, 1, 1, 0, 0 |
| 0, 0, 1, 1, 1, 0, 0 |
| Step | Row | Column | Elevation |
|---|---|---|---|
| 1 | 2 | 1 | 60.000 m |
| 2 | 1 | 2 | 48.000 m |
| 3 | 2 | 3 | 47.000 m |
| 4 | 3 | 4 | 46.000 m |
| 5 | 4 | 4 | 45.000 m |
| 6 | 5 | 4 | 44.000 m |
| 7 | 6 | 4 | 43.000 m |
| 8 | 7 | 4 | 42.000 m |
- Basin cells
- Outlet row
- Outlet column
- How the outlet was placed
- Relief
- Mean slope
Provenance
- Computed by
- raster.hydrology.watershed 1.0.0, core 0.1.0
- Model
- The basin is every cell whose D8 path reaches the outlet (Jenson and Domingue 1988), found by walking the pointers upstream from it. The outlet is first snapped, by the nearest channel cell at the threshold or by the most water within the search distance. Area = cells × cell size²; relief = the basin's highest cell above the outlet; mean slope averages each cell's steepest descent; the longest flow path is the longest chain of pointers ending at the outlet, summing the cell size along sides and √2 times it along diagonals
- Accuracy
- Exact in the arithmetic of the rules over the window given: the basin is every cell the pointers lead from, and the path length is the walked chain of cell centres
- Notes
- 2 shown with the answer
- Cites
- Jenson, S. K., and Domingue, J. O., Photogrammetric Engineering and Remote Sensing, Extracting topographic structure from digital elevation data for geographic information system analysis; O'Callaghan, J. F., and Mark, D. M., Computer Vision, Graphics, and Image Processing, The extraction of drainage networks from digital elevation data
Something look off?
How we got thisFormula, worked example, sources, and proof
Model: The basin is every cell whose D8 path reaches the outlet (Jenson and Domingue 1988), found by walking the pointers upstream from it. The outlet is first snapped, by the nearest channel cell at the threshold or by the most water within the search distance. Area = cells × cell size²; relief = the basin's highest cell above the outlet; mean slope averages each cell's steepest descent; the longest flow path is the longest chain of pointers ending at the outlet, summing the cell size along sides and √2 times it along diagonals
Show your work
The outlet
the pour point, snapped onto the networkrow 7, column 4= the cell you gave, unsnappedThe basin
every cell whose flow path reaches the outlet49 cells in the window= 31 cellsIts area
cells × cell size²31 × 30 m × 30 m= 27,900 m²
The same steps an agent gets from the MCP server with explain: true.
Accuracy: Exact in the arithmetic of the rules over the window given: the basin is every cell the pointers lead from, and the path length is the walked chain of cell centres
When to use this: Use this to find what drains to a point: a culvert, a gauge, a reservoir, a sample site. Give the conditioned grid, the cell size, and the point's row and column, and let the tool snap it onto the channel first, since a point one cell off the channel delineates a hillside instead of a basin. It returns the basin's cells and area, its relief and mean slope, the longest flow path for a time-of-concentration estimate, and the basin as a grid you can draw.
Limitations: The window bounds the answer: when the basin reaches the edge, the real basin may continue beyond the data, which the result says and warns. An unconditioned pit cuts a basin short, so fill or breach first. The grid is plane, so the area is the cell count times the cell size squared rather than a geodesic area; a geographic grid needs its cell size in meters at the latitude. Mean slope is the average of the cells' steepest descents, not a fitted surface. The window holds at most 25,000 cells.
Worked example: The basin above the bottom of a valley. Source: add-raster-hydrology raster/hydrology: the cells whose water reaches the valley's outlet, with the longest path down it.
You enter
- Cell size
- 30 m
- Elevation grid
- 60, 48, 60, 60, 60, 48, 60 60, 60, 47, 60, 47, 60, 60 60, 60, 60, 46, 60, 60, 60 60, 60, 60, 45, 60, 60, 60 60, 60, 60, 44, 60, 60, 60 60, 60, 60, 43, 60, 60, 60 60, 60, 60, 42, 60, 60, 60
- Pour point column
- 4
- Pour point row
- 7
- Snap rule
- none
You get
- Basin area
- 27,900 m²
- Basin cells
- 31
- Outlet row
- 7
- Outlet column
- 4
- How the outlet was placed
- the cell you gave, unsnapped
- Relief
- 18 m
- Mean slope
- 0.3349
- Longest flow path
- 247.28 m
- Drop along that path
- 18 m
- Reaches the window's edge
- yes
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-07, changed: The stream and watershed tools now draw what they found, over the grid you entered and to scale. The stream page draws every link through the cells it runs, thicker as its Strahler order rises, so the main stem reads at a glance and the headwaters read as headwaters, with a dot where the network leaves the window. The watershed page shades the cells that drain to your point and draws the longest flow path down them, from its top to the outlet. Both drawings are your own numbers, not an illustration of the idea. Changelog
- 2026-11-07, added: A fifth hydrology tool answers what drains to a point. Give an elevation grid and a cell, and it returns every cell whose water reaches it: the basin as a grid you can draw, its area, how much higher its highest ground is than the outlet, its mean slope, and the longest path water takes to get there, with the drop along it. It moves your point onto the channel first, either to the nearest channel cell or to the cell with the most water nearby, and says whether it moved and how far, because a point one cell off the channel maps a hillside instead of a basin. When the basin runs into the edge of your data the result says so, since the real basin may continue past it. Changelog
Checked against: 18 golden test vectors (download the test vectors, each with its source and tolerance). See how results are checked and every source.
Sources
- Extracting topographic structure from digital elevation data for geographic information system analysis, Jenson, S. K., and Domingue, J. O., Photogrammetric Engineering and Remote Sensing, Volume 54, issue 11, pages 1593-1600. Delineating a watershed as every cell whose flow path reaches the outlet, and snapping an outlet onto the drainage network before delineating.
- The extraction of drainage networks from digital elevation data, O'Callaghan, J. F., and Mark, D. M., Computer Vision, Graphics, and Image Processing, Volume 28, issue 3, pages 323-344 (DOI 10.1016/S0734-189X(84)80011-0). The steepest-descent rule that sends each cell's water to one of its eight neighbours, the D8 method.
Experimental means this tool has not yet met the stable bar: at least 20 golden vectors, differential tests, and an independent worked example.