geoprimsField-grade geospatial math

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

27,900m²

That point drains 27,900 m².

  • The basin reaches the window's edge, so the real basin may continue beyond the data.
Basin grid
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
The longest path
StepRowColumnElevation
12160.000 m
21248.000 m
32347.000 m
43446.000 m
54445.000 m
65444.000 m
76443.000 m
87442.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?

Your values

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

Loading…

31 cells drain to the dotBasin 27,900 m² · relief 18 mLongest path 247.28 m
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

  1. The outlet

    the pour point, snapped onto the network

    row 7, column 4 = the cell you gave, unsnapped

  2. The basin

    every cell whose flow path reaches the outlet

    49 cells in the window = 31 cells

  3. Its 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

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

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