r.watersheds - GRASS GIS manual

NAME

r.watersheds - Delineates a large number of watersheds using the Memory-Efficient Watershed Delineation (MESHED) OpenMP parallel algorithm by Cho (2025).

KEYWORDS

raster, hydrology, watershed delineation

SYNOPSIS

r.watersheds

r.watersheds --help

r.watersheds [-m] direction=name format=string outlets=name [layer=string] [column=name] output=name [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-m: Use less memory
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

direction=name [required]: Name of input direction raster map
format=string [required]: Format of input direction raster map; Options: auto, degree, 45degree, power2; Default: auto; auto: auto-detect direction format; degree: degrees CCW from East; 45degree: degrees CCW from East divided by 45 (e.g. r.watershed); power2: powers of 2 CW from East (e.g., r.terraflow, ArcGIS)
outlets=name [required]: Name of input outlets vector map; Or data source for direct OGR access
layer=string: Layer number or name; Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.; Default: 1
column=name: Name of attribute column for watershed IDs (using a non-default column is slower); Default: cat
output=name [required]: Name for output watersheds raster map

DESCRIPTION
NOTES
EXAMPLES
SEE ALSO
REFERENCES
AUTHOR

DESCRIPTION

r.watersheds delineates a large number of watersheds from a flow direction raster map and an outlets vector map using the Memory-Efficient Watershed Delineation (MESHED) OpenMP parallel algorithm by Cho (2025).

NOTES

r.watersheds uses a flow direction raster map and an outlets vector map to delineate a large number of watersheds in parallel using OpenMP.

The module recognizes three different formats of flow directions:

r.watershed (singular) can be used to create an input flow direction raster map. It can also create watersheds, but it uses an elevation map instead of a flow direction map, which is actually one of its outputs, and does not take outlets as input. r.watersheds is more similar to r.water.outlet and r.stream.basins. Both modules take an input flow direction map from r.watershed, but r.water.outlet can delineate a watershed for one outlet point at a time and r.stream.basins is a sequential module for multiple watersheds. Unlike r.stream.basins, r.watersheds can use a column for watershed IDs, but using a non-default column is slower than using the default category (cat) column because of database queries.

For comparisons, using an i7-1370P CPU with 64GB memory and a 30-meter flow direction map for the entire Texas (1.8 billion cells), r.watersheds took 1 minute 27 seconds to delineate the entire state using 60,993 outlet cells draining away (see below how to extract draining cells) while r.stream.basins 5 minutes 28 seconds, both using the category column. However, r.watersheds with a non-category column took 6 minutes 21 seconds because of heavy database queries.

EXAMPLES

These examples use the North Carolina sample dataset.

Calculate flow accumulation using r.watershed and delineate all watersheds from draining cells using r.watersheds:

# set computational region
g.region -ap raster=elevation

# calculate drainage directions using r.watershed
r.watershed -s elevation=elevation drainage=drain

# extract draining cells
r.mapcalc ex="dcells=if(\
        (isnull(drain[-1,-1])&&abs(drain)==3)||\
        (isnull(drain[-1,0])&&abs(drain)==2)||\
        (isnull(drain[-1,1])&&abs(drain)==1)||\
        (isnull(drain[0,-1])&&abs(drain)==4)||\
        (isnull(drain[0,1])&&abs(drain)==8)||\
        (isnull(drain[1,-1])&&abs(drain)==5)||\
        (isnull(drain[1,0])&&abs(drain)==6)||\
        (isnull(drain[1,1])&&abs(drain)==7),1,null())"
r.to.vect input=dcells type=point output=dcells

# delineate all watersheds using r.watersheds
r.watersheds dir=drain outlets=dcells output=wsheds nprocs=$(nproc)

Perform the same analysis for 10,938 bridges in North Carolina:

# set computational region
g.region -ap raster=elev_state_500m

# calculate drainage directions using r.watershed
r.watershed -s elevation=elev_state_500m drainage=drain_state

# delineate all watersheds using r.watersheds
r.watersheds dir=drain_state outlets=bridges output=bridge_wsheds nproc=$(nproc)

REFERENCES

Huidae Cho, January 2025. Avoid Backtracking and Burn Your Inputs: CONUS-Scale Watershed Delineation Using OpenMP. Environmental Modelling & Software 183, 106244. doi:10.1016/j.envsoft.2024.106244.

AUTHOR

Huidae Cho, New Mexico State University

SOURCE CODE

Available at: r.watersheds source code (history)

Latest change: Sunday Dec 08 00:14:19 2024 in commit: f77724eed755334eb548323f6ad6fdf36bbef9fb