Skip to content

r.water.outlet

Creates watershed basins from a drainage direction map.

r.water.outlet input=name output=name coordinates=east,north [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.water.outlet input=name output=name coordinates=east,north

grass.script.run_command("r.water.outlet", input, output, coordinates, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.water.outlet", input="name", output="name", coordinates=east,north)

Parameters

input=name [required]
    Name of input drainage direction map
output=name [required]
    Name for output watershed basin map
coordinates=east,north [required]
    Coordinates of outlet point
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str, required
    Name of input drainage direction map
    Used as: input, raster, name
output : str, required
    Name for output watershed basin map
    Used as: output, raster, name
coordinates : tuple[float, float] | list[float] | str, required
    Coordinates of outlet point
    Used as: input, coords, east,north
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.water.outlet generates a watershed basin from a drainage direction map and a set of coordinates representing the outlet point of watershed.

Input drainage direction map indicates the "aspect" for each cell. Multiplying positive values by 45 will give the direction in degrees that the surface runoff will travel from that cell. The value -1 indicates that the cell is a depression area. Other negative values indicate that surface runoff is leaving the boundaries of the current geographic region. The absolute value of these negative cells indicates the direction of flow. This raster map is generated from r.watershed.

Output raster map values of one (1) indicate the watershed basin. Values of zero (0) are not in the watershed basin.

NOTES

In the context of this program, a watershed basin is the region upstream of an outlet point. Thus, if the user chooses an outlet point on a hill slope, the resulting map will be a thin silver of land representing the overland slope uphill of the point.

EXAMPLE

A watershed in the North Carolina sample dataset region:

g.region raster=elev_lid792_1m -p
# the watershed outlet position should be placed on a stream (from
# accumulation map):
r.watershed elev_lid792_1m threshold=5000 accumulation=accum_5K drainage=draindir_5K basin=basin_5K
r.water.outlet input=draindir_5K output=basin_A30 coordinates=638740.423248,220271.519225

d.mon wx0
d.rast map=accum_5K
d.rast map=basin_A30

# overlay with transparency
r.colors map=basin_A30 color=grey
d.his h=accum_5K i=basin_A30

# report outlet size in ha
r.report map=basin_A30 units=h

Figure: Watershed draped over flow accumulation
Figure: Watershed draped over flow accumulation

SEE ALSO

r.wateroutlet.lessmem (addon), d.where, r.basins.fill, r.watershed, r.topidx

AUTHOR

Charles Ehlschlaeger, U.S. Army Construction Engineering Research Laboratory

SOURCE CODE

Available at: r.water.outlet source code (history)
Latest change: Tuesday Feb 18 17:20:26 2025 in commit 688e625