# RavingDesk Watershed & Stream Network (D8 from a DEM)

> Fill sinks, route flow (D8) and delineate the watershed and streams above a pour point. 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.

Part of usefulweb.app (https://usefulweb.app/). Part of [RavingDesk](https://ravingdesk.usefulweb.app/) (ownerApp: ravingdesk). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://ravingdeskwatershed.usefulweb.app/ (interactive tool at https://ravingdeskwatershed.usefulweb.app/tool)
- JSON API: POST https://ravingdeskwatershed.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://ravingdeskwatershed.usefulweb.app/api/v1/tool)
- OpenAPI: https://ravingdeskwatershed.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://ravingdeskwatershed.usefulweb.app/mcp - tool `ravingdesk_watershed`

## Inputs
- file (file): Elevation model (DEM) - ESRI ASCII grid (.asc), XYZ grid text, GeoTIFF (Int16, UInt16 or Float32, one band, uncompressed or Deflate, WGS84 or UTM) or a PNG heightmap. Up to 25 MB and 1,048,576 cells.
- text (textarea): Or paste an ESRI ASCII grid or XYZ points
- crs (select): Coordinate system of an ASCII or XYZ grid - GeoTIFFs carry their own coordinate system; PNG heightmaps are always local.
- utmZone (text): UTM zone - Only for “WGS84 UTM zone”: zone number and N or S.
- pngEncoding (select): PNG heightmap encoding
- cellSize (number): Cell size of a PNG heightmap - PNG heightmaps and TIFFs without georeferencing have no cell size of their own.
- greyMin (number): Elevation of black (grey PNG)
- greyMax (number): Elevation of white (grey PNG)
- pourPoint (text, required): Pour point (outlet) - A cell (“row 72, col 91”, counted from the top-left), grid coordinates “x, y” on local grids, or a coordinate in any notation on georeferenced grids.
- snapRadius (integer): Snap the pour point within - Moves the pour point to the cell with the largest flow accumulation within this radius, so it lands on the stream.
- streamThreshold (integer): Stream threshold - Cells with at least this many upstream cells are streams. Empty: 1 % of the grid, at least 10.

## Method
- 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).