Premium apps Part of RavingDesk
RavingDesk Watershed & Stream Network (D8 from a DEM)
Fill sinks, route flow (D8) and delineate the watershed and streams above a pour point.
Try an example: Synthetic hills (ESRI ASCII grid): the main valley above row 72, column 91 · The same terrain as a WGS84 GeoTIFF with the pour point as latitude/longitude and a denser stream network · A V-shaped valley from XYZ points: everything drains to the thalweg outlet
How it works
Takes your elevation model and a pour point, fills closed depressions with Priority-Flood, routes water with the D8 method, accumulates the upstream area, extracts the stream network with Strahler orders, snaps the pour point to the strongest flow nearby and outlines the watershed that drains through it. Returns the watershed polygon, the streams and the pour point as GeoJSON, a PNG map and basin statistics (area, relief, mean slope, longest flow path, drainage density). It is the hydrology engine of RavingDesk’s Data & charts “Terrain” step.
- DEM reading: ESRI ASCII grids (xll/yll corner or centre, cellsize or dx/dy, NODATA_value); XYZ points on a regular grid (cell centres; missing positions become no data); GeoTIFF subset (one band of Int16, UInt16 or Float32, uncompressed or Deflate, strips or tiles, predictors 1–3, ModelTiepoint + ModelPixelScale or a north-up ModelTransformation, WGS84 EPSG:4326 or WGS84 UTM EPSG:326xx/327xx; other coordinate systems, LZW, BigTIFF and rotated grids are refused with a reason); PNG heightmaps (Terrarium, Mapbox Terrain-RGB or grey; transparent pixels are no data). Only files you supply are read — nothing is downloaded.
- Depressions are filled with Priority-Flood (Barnes, Lehman & Mulla 2014). For routing, the ε variant (their Algorithm 3, ε = 10⁻⁶ m) gives filled flats a tiny gradient towards their spill point, so every cell has a downslope neighbour; the reported fill depths come from the plain fill.
- D8 (O’Callaghan & Mark 1984): every cell drains to the neighbour with the steepest drop per metre (diagonals at their true distance); cells on the edge without a lower neighbour are outlets. Flow accumulation counts the upstream cells (and areas) in topological order; streams are cells at or above the threshold, with Strahler orders (two streams of the same order make the next order).
- The pour point snaps to the largest accumulation within the radius (ties: the nearest cell). The watershed is every cell whose D8 path passes through it; its outline follows the cell edges (exterior counter-clockwise as RFC 7946 asks). The longest flow path is measured along D8 steps; drainage density = stream length in the watershed / its area.
- Cell sizes on geographic grids come from the WGS84 radii of curvature at each row (meridional M and prime vertical N·cos φ) and cell areas from the exact ellipsoidal quadrangle; UTM and local grids use map metres (the UTM scale factor of 0.9996–1.0004 is ignored).
Sources
- Hill shading and the reflectance map (Proc. IEEE 69(1), 14–47) (B. K. P. Horn, 1981)
- Priority-Flood: an optimal depression-filling and watershed-labeling algorithm for digital elevation models (Computers & Geosciences 62, 117–127) (R. Barnes, C. Lehman, D. Mulla, 2014)
- The extraction of drainage networks from digital elevation data (CVGIP 28, 323–344) (J. F. O’Callaghan and D. M. Mark, 1984)
- Quantitative analysis of land surface topography (Earth Surface Processes and Landforms 12, 47–56) (L. W. Zevenbergen and C. R. Thorne, 1987)
- GeoTIFF format specification 1.0 / OGC GeoTIFF 1.1 (Open Geospatial Consortium)
- Esri ASCII raster format (Esri)
Part of RavingDesk
-
RavingDesk Paper trading & data workspace
Practise trading on paper and chart your data: orders, risk, datasets, analyses, reports.
Related tools
- RavingDesk Terrain Analyzer (DEM slope, aspect, hillshade, contours) – Slope, aspect, hillshade, curvature, sinks and contour lines from your elevation model.
- RavingDesk Elevation Profile from a DEM – Elevation profile along a line over your DEM: CSV, chart, climb, descent and grades.
- RavingDesk GeoJSON Validator & Inspector – Validate and repair GeoJSON (RFC 7946) and measure areas and lengths on WGS84.
How to use the RavingDesk Watershed & Stream Network tool
Fill sinks, route water with D8 and outline the watershed and streams above a pour point in your own elevation model, with area, relief and drainage density.
What it is for
Where does the rain that falls on a hillside end up, and which area drains through a given point on a stream? Planners ask this before placing a culvert, hydrologists before modelling runoff, and students when they learn how catchments work. The answer is the watershed (catchment) of that point.
This tool takes an elevation model you supply (ESRI ASCII grid, XYZ grid, GeoTIFF in WGS84 or UTM, or a PNG heightmap) and a pour point. It fills closed depressions, lets every cell drain to its steepest neighbour (D8), counts how many cells drain through each cell, draws the stream network and outlines the area upstream of your point. You get the watershed polygon, the streams and the snapped pour point as GeoJSON, a PNG map and basin statistics.
Worked example
The second example uses a synthetic test terrain (a WGS84 GeoTIFF placed at 0° N, 0° E so it is clearly not a real place). The pour point is entered as latitude and longitude, 0.002361, 0.025139, and the stream threshold is 40 cells.
| Result | Value |
|---|---|
| Pour point after snapping | 0.001806, 0.025694 (row 74, col 93), moved 2.83 cells |
| Watershed area | 2.9699 km² (3,127 cells, 40.7 % of the grid) |
| Relief | 302.7 – 479.2 m (176.5 m) |
| Mean slope | 6.14° |
| Longest flow path | 3.756 km |
| Streams in the watershed | 7.224 km in 23 segments |
| Drainage density | 2.43 km/km² |
| Highest Strahler order in the grid | 4 |
The typed point lay a few cells beside the main channel, so snapping moved it to the cell with the largest flow within three cells. The outline drawn along cell edges gives 2.969943 km², the same as the sum of the cell areas.
How to read the result
- Snapping moves the pour point to the strongest flow nearby. Without it, a point one cell off the stream may drain only a tiny strip of hillside.
- The stream threshold decides how many upstream cells make a stream. A lower threshold gives more and shorter streams. Empty means 1 % of the grid.
- Strahler order grows when two streams of the same order meet.
- Longest flow path follows the D8 steps from the farthest cell to the outlet.
- A warning that the watershed reaches the grid edge means it may continue outside your data. The area is then a lower bound.
Tips and common mistakes
- Cells are counted from the top-left:
row 1, col 1is the north-west corner. On georeferenced grids you can also type a coordinate in any notation, for example DMS, UTM or MGRS. - Use a DEM that extends well beyond the catchment, or the edge cuts it off.
- Real DEMs contain small pits and bridges across rivers. The fill removes pits, but a road embankment can still divert flow. Burning in culverts is not supported.
- D8 sends each cell's water to one neighbour only, so streams on wide flat plains look straight and parallel.
FAQ
Why are depressions filled before routing?
Without a fill, water would stop in every small pit. Priority-Flood raises each pit to its spill level, and a tiny gradient lets the filled flats drain towards their outlet.
Is the GeoJSON valid for GIS software?
Yes. On georeferenced grids it is RFC 7946 GeoJSON in WGS84 with counter-clockwise outer rings. Local grids keep their grid metres and say so in the file.
Can I see the watershed while I move the point?
In RavingDesk, a Terrain step under Data & charts redraws the watershed when you click the map or press Enter on the keyboard cursor.
Does it model rainfall or discharge?
No. It describes drainage paths and areas only, not volumes of water over time.
Guide last updated:
For scripts and AI agents
- JSON API:
POST https://ravingdeskwatershed.usefulweb.site/api/v1/calculate(same calculation as this page) - Interface description: OpenAPI 3.1 · AI guide: llms.txt
- MCP server (Streamable HTTP):
https://ravingdeskwatershed.usefulweb.site/mcp· tool nameravingdesk_watershed
Example request
curl -s -X POST https://ravingdeskwatershed.usefulweb.site/api/v1/calculate \
-H 'content-type: application/json' \
-d '{…see OpenAPI examples…}'