This tool will perform a watershedding operation based on a group of input vector pour points (`pour_pts`), i.e. outlets or points-of-interest. Watershedding is a procedure that identifies all of the cells upslope of a cell of interest (pour point) that are connected to the pour point by a flow-path. The user must input a D8-derived flow pointer (flow direction) raster (`d8_pntr`) and a vector pour point file (`pour_pts`). The pour points must be of a Point ShapeType (i.e. Point, PointZ, PointM, MultiPoint, MultiPointZ, MultiPointM). Watersheds will be assigned the input pour point FID value. The flow pointer raster must be generated using the D8 algorithm, d8_pointer.

Pour point vectors can be attained by on-screen digitizing to designate these points-of-interest locations. Because pour points are usually, although not always, situated on a stream network, it is recommended that you use Jenson's method (jenson_snap_pour_points) to snap pour points on the stream network. This will ensure that the digitized outlets are coincident with the digital stream contained within the DEM flowpaths. If this is not done prior to inputting a pour-point set to the watershed tool, anomalously small watersheds may be output, as pour points that fall off of the main flow path (even by one cell) in the D8 pointer will yield very different catchment areas.

If a raster pour point is specified instead of vector points, the watershed labels will derive their IDs from the grid cell values of all non-zero, non-NoData valued grid cells in the pour points file. Notice that this file can contain any integer data. For example, if a lakes raster, with each lake possessing a unique ID, is used as the pour points raster, the tool will map the watersheds draining to each of the input lake features. Similarly, a pour points raster may actually be a streams file, such as what is generated by the stream_link_identifier tool.

By default, the pointer raster is assumed to use the clockwise indexing method used by Whitebox Workflows. If the pointer file contains ESRI flow direction values instead, the `esri_pntr` must be True.

There are several tools that perform similar watershedding operations in Whitebox Workflows. watershed is appropriate to use when you have a set of specific locations for which you need to derive the watershed areas. Use the basins tool instead when you simply want to find the watersheds draining to each outlet situated along the edge of a DEM. The isobasins tool can be used to divide a landscape into roughly equally sized watersheds. The subbasins and strahler_order_basins are useful when you need to find the areas draining to each link within a stream network. Finally, hillslopes can be used to identify the areas draining the each of the left and right banks of a stream network.

## Reference

Jenson, S. K. (1991), Applications of hydrological information automatically extracted from digital elevation models, Hydrological Processes, 5, 31–44, doi:10.1002/hyp.3360050104.

Lindsay JB, Rothwell JJ, and Davies H. 2008. Mapping outlet points used for watershed delineation onto DEM-derived stream networks, Water Resources Research, 44, W08442, doi:10.1029/2007WR006507.

## See Also

d8_pointer, basins, subbasins, isobasins, strahler_order_basins, hillslopes, jenson_snap_pour_points, breach_depressions_least_cost, fill_depressions

## Function Signature

`def watershed(self, d8_pointer: Raster, pour_points: Vector, esri_pntr: bool = False) -> Raster: ...`

## Project Links

WbW Homepage User Manual Support WbW