GRASS logo

NAME - Delineates basins according stream network.
Input can be stream network, vector point map with outlets or outlet coordinates.


raster, hydrology, stream network, basin creation

SYNOPSIS --help [-zclm] direction=name [coordinates=east,north[,east,north,...]] [stream_rast=name] [cats=range] [points=name] [memory=integer] basins=name [--overwrite] [--help] [--verbose] [--quiet] [--ui]


Create zero-value background instead of NULL
Use unique category sequence instead of input streams
Create basins only for last stream links
Use memory swap (operation is slow)
Allow output files to overwrite existing files
Print usage summary
Verbose module output
Quiet module output
Force launching GUI dialog


direction=name [required]
Name of input flow direction raster map
Basin's outlet's coordinates
Name of input stream mask raster map
Category values
Create basins only for these categories
Name of input vector map
Name of input vector points map
Maximum memory used in memory swap mode (MB)
Default: 300
basins=name [required]
Name for output basin raster map

Table of contents


The module is prepared to delineate basins and subbasins with different input data. The module is prepared to delineate an unrestricted number of basins in one step. It can delineate basins with three methods: Only one method can be used at once: the methods cannot be mixed.

The recommended method requires two maps: flow direction and streams. Using cats option it is possible to create basins having the same category of the stream they refer to. The module is prepared to work with output data of r.watershed,, also with modification done by r.reclass and r.mapcalc. can delineate basins according outlets marked by raster streams, polygons, vector points or coordinates. If the outlets are given by points or coordinates, the module delineates the basins individuating the cells that drain into that point. If the outlets are marked by the streams, it includes the cells that contribute to the last (downstream) cell of each stream. If the outlets are marked by polygons, it includes the cells contributing to the most downstream cell of the polygon. If the polygon covers more outlets than of one basins, it will create a collective basin for all the outlets with common category.


Creates zero-value background instead of NULL. For some reason (like map algebra calculation) zero-valued background may be required.
By default uses streams category as basin category. In some cases - for example if streams map is a product of map algebra and separate streams may not have unique values - this option will create a new category sequence for each basin (it does not work in vector point mode).
By default creates basins for all unique streams. This option delineates basins only for the last streams, ignoring upstream (it does not work in vector point mode).
Flow direction: name of input flow direction map produced by r.watershed or The resolution of the computational region must match with the resolution of the raster map. Also the stream network map (if used) and the direction map must have the same resolution. It is checked by default. If resolutions differ, the module informs about it and stops. Region boundary and maps boundaries may differ but it may lead to unexpected results.
East and north coordinates for the basin outlet. Using this option, it is possible to delineate only one basin at a time, similarly to r.water.outlet.
Stream network: name of input map of stream network, ordered according to the convention used by r.watershed or Since streams network produced by r.watershed and might slightly differ in detail, it is required to use both stream and direction map produced by the same module. The stream background can have either NULL or zero values.
Stream categories to delineate basins for: All categories which are not in the stream map are ignored. It is possible to use the stream network created by r.watershed, or For, it is possible to select the order for which basins will be created. For example, to delineate only basins for the streams of second order, use cats=2. If you need unique categories for each basin, use -c flag.
Vector file containing basins outlets as vector points. Only points' categories are used to delineate the basins. Attached tables are ignored. Every point shall have its own unique category. In this mode, flags -l and -c are ignored.


The module produces one raster map with basins defined according to the user's rules.


To achieve good results, outlets markers created by the user shall overlap with the streams, otherwise basins could result with very small area. Input maps must be in CELL format (default output of r.watershed, or


To delineate all basins with categories of streams: direction=direction stream_rast=streams basins=bas_basins_elem

To determine major and minor basins defined by outlets, ignoring subbasins, use -l flag. This flag ignores all nodes and uses only real outlets (in most cases that on map border): -l direction=direction stream_rast=streams basins=bas_basins_last direction=direction coors=639936.623832,216939.836449

To delineate one or more particular basins defined by given streams, add simply stream categories: -lc direction=direction stream_rast=streams cats=2,7,184 basins=bas_basin

To delineate basins of particular order, the following procedure can be used: -lc direction=direction stream_rast=strahler cats=2 \

The usage of polygons as outlets markers is useful when the exact stream course cannot be clearly determined before running the analysis, but the area of its occurrence can be determined (mainly by iterative simulations). In the example, is used, but it can be substituted by any polygon created for example with v.digit: -b output=circle coordinate=639936.623832,216939.836449 max=200 -c direction=direction streams=circle basins=bas_simul

To determine areas of contribution to streams of particular order use as streams the result of ordering: direction=direction stream_rast=ord_strahler basins=bas_basin_strahler

Determination of areas of potential source of pollution. The example will be done for lake marked with FULL_HYDR 8056 in North Carolina sample dataset. The lake shall be extracted and converted to binary raster map.

v.extract -d input=lakes@PERMANENT output=lake8056 type=area layer=1 \
  where='FULL_HYDRO = 8056' new=-1 input=lake8056 output=lake8056 use=val type=area layer=1 value=1 direction=direction streams=lake8056 basins=bas_basin_lake

See also the tutorial:*


r.watershed,,,, r.mapcalc, r.reclass, r.patch r.water.outlet


Jarek Jasiewicz, Adam Mickiewicz University, Geoecology and Geoinformation Institute.

Last changed: $Date: 2015-07-19 17:52:07 +0200 (Sun, 19 Jul 2015) $


Available at: source code (history)

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2017 GRASS Development Team, GRASS GIS 7.2.3svn Reference Manual