r.stream.extractgrass - Online in the Cloud

PROGRAM:

NAME

r.stream.extract - Performs stream network extraction.

KEYWORDS

raster, hydrology, stream network

SYNOPSIS

r.stream.extract
r.stream.extract --help
r.stream.extract elevation=name [accumulation=name] [depression=name] threshold=float
[d8cut=float] [mexp=float] [stream_length=integer] [memory=integer]
[stream_raster=name] [stream_vector=name] [direction=name] [--overwrite] [--help]
[--verbose] [--quiet] [--ui]

Flags:
--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:
elevation=name [required]
Name of input elevation raster map

accumulation=name
Name of input accumulation raster map
Stream extraction will use provided accumulation instead of calculating it anew

depression=name
Name of input raster map with real depressions
Streams will not be routed out of real depressions

threshold=float [required]
Minimum flow accumulation for streams
Must be > 0

d8cut=float
Use SFD above this threshold
If accumulation is larger than d8cut, SFD is used instead of MFD. Applies only if no
accumulation map is given.
Default: infinity

mexp=float
Montgomery exponent for slope, disabled with 0
Montgomery: accumulation is multiplied with pow(slope,mexp) and then compared with
threshold
Default: 0

stream_length=integer
Delete stream segments shorter than stream_length cells
Applies only to first-order stream segments (springs/stream heads)
Default: 0

memory=integer
Maximum memory to be used (in MB)
Cache size for raster rows
Default: 300

stream_raster=name
Name for output raster map with unique stream ids

stream_vector=name
Name for output vector map with unique stream ids

direction=name
Name for output raster map with flow direction

DESCRIPTION

r.stream.extract extracts streams in both raster and vector format from a required input
elevation map and optional input accumulation map.

NOTES

NULL (nodata) cells in the input elevation map are ignored, zero and negative values are
valid elevation data. Gaps in the elevation map that are located within the area of
interest must be filled beforehand, e.g. with r.fillnulls, to avoid distortions.

All non-NULL and non-zero cells of depression map will be regarded as real depressions.
Streams will not be routed out of depressions. If an area is marked as depression but the
elevation model has no depression at this location, streams will not stop there. If a flow
accumulation map and a map with real depressions are provided, the flow accumulation map
must match the depression map such that flow is not distributed out of the indicated
depressions. It is recommended to use internally computed flow accumulation if a
depression map is provided.

Option threshold defines the minimum (optionally modifed) flow accumulation value that
will initiate a new stream. If Montgomery’s method for channel initiation is used, the
cell value of the accumulation input map is multiplied by (tan(local slope))mexp and then
compared to threshold. If mexp is given than the method of Montgomery and
Foufoula-Georgiou (1993) to initiate a stream with this value. The cell value of the
accumulation input map is multiplied by (tan(local slope))mexp and then compared to
threshold. If threshold is reached or exceeded, a new stream is initiated. The default
value 0 disables Montgomery. Montgomery and Foufoula-Georgiou (1993) generally recommend
to use 2.0 as exponent. mexp values closer to 0 will produce streams more similar to
streams extracted with Montgomery disabled. Larger mexp values decrease the number of
streams in flat areas and increase the number of streams in steep areas. If weight is
given, the weight is applied first.

Option d8cut defines minimum amount of overland flow (accumulation) when SFD (D8) will be
used instead of MFD (FD8) to calculate flow accumulation. Only applies if no accumulation
map is provided. Setting to 0 disables MFD completely.

Option stream_length defines minimum stream length in number of cells for first-order
(head/spring) stream segments. All first-order stream segments shorter than stream_length
will be deleted.

Output direction raster map contains flow direction for all non-NULL cells in input
elevation. Flow direction is of D8 type with a range of 1 to 8. Multiplying values with
45 gives degrees CCW from East. Flow direction was adjusted during thinning, taking
shortcuts and skipping cells that were eliminated by the thinning procedure.

Stream extraction
If no accumulation input map is provided, flow accumulation is determined with a
hydrological analysis similar to r.watershed. The algorithm is MFD (FD8) after Holmgren
1994, as for r.watershed. The threshold option determines the number of streams and detail
of stream networks. Whenever flow accumulation reaches threshold, a new stream is started
and traced downstream to its outlet point. As for r.watershed, flow accumulation is
calculated as the number of cells draining through a cell.

If accumulation is given than the accumulation values of the provided accumulation map are
used and not calculated from the input elevation map. In this case the elevation map must
be exactly the same map used to calculate accumulation. If accumulation was calculated
with r.terraflow, the filled elevation output of r.terraflow must be used. Further on, the
current region should be aligned to the accumulation map. Flow direction is first
calculated from elevation and then adjusted to accumulation. It is not necessary to
provide accumulation as the number of cells, it can also be the optionally adjusted or
weighed total contributing area in square meters or any other unit. When an original flow
accumulation map is adjusted or weighed, the adjustment or weighing should not convert
valid accumulation values to NULL (nodata) values.

Weighed flow accumulation
Flow accumulation can be calculated first, e.g. with r.watershed, and then modified before
using it as input for r.stream.extract. In its general form, a weighed accumulation map is
generated by first creating a weighing map and then multiplying the accumulation map with
the weighing map using r.mapcalc. It is highly recommended to evaluate the weighed flow
accumulation map first, before using it as input for r.stream.extract.

This allows e.g. to decrease the number of streams in dry areas and increase the number of
streams in wet areas by setting weight to smaller than 1 in dry areas and larger than 1 in
wet areas.

Another possibility is to restrict channel initiation to valleys determined from terrain
morphology. Valleys can be determined with r.param.scale param=crosc (cross-sectional or
tangential curvature). Curvature values < 0 indicate concave features, i.e. valleys. The
size of the processing window determines whether narrow or broad valleys will be
identified (See example below).

Defining a region of interest
The stream extraction procedure can be restricted to a certain region of interest, e.g. a
subbasin, by setting the computational region with g.region and/or creating a MASK. Such
region of interest should be a complete catchment area, complete in the sense that the
complete area upstream of an outlet point is included and buffered with at least one cell.

Stream output
The output raster and vector contains stream segments with unique IDs. Note that these IDs
are different from the IDs assigned by r.watershed. The vector output also contains points
at the location of the start of a stream segment, at confluences and at stream network
outlet locations.

Output stream_raster raster map stores extracted streams. Cell values encode a unique ID
for each stream segment.

Output stream_vector vector map stores extracted stream segments and points. Points are
written at the start location of each stream segment and at the outlet of a stream
network. In layer 1, categories are unique IDs, identical to the cell value of the raster
output. The attribute table for layer 1 holds information about the type of stream
segment: start segment, or intermediate segment with tributaries. Columns are cat int,
stream_type varchar(), type_code int. The encoding for type_code is 0 = start, 1 =
intermediate. In layer 2, categories are identical to type_code in layer 1 with additional
category 2 = outlet for outlet points. Points with category 1 = intermediate in layer 2
are at the location of confluences.

EXAMPLE

This example is based on the elevation map "elev_ned_30m" in the North Carolina sample
dataset and uses valleys determined with r.param.scale to weigh an accumulation map
produced with r.watershed.
# set region
g.region -p raster=elev_ned_30m@PERMANENT
# calculate flow accumulation
r.watershed ele=elev_ned_30m@PERMANENT acc=elevation.10m.acc
# curvature to get narrow valleys
r.param.scale input=elev_ned_30m@PERMANENT output=tangential_curv_5 size=5 param=crosc
# curvature to get a bit broader valleys
r.param.scale input=elev_ned_30m@PERMANENT output=tangential_curv_7 size=7 param=crosc
# curvature to get broad valleys
r.param.scale input=elev_ned_30m@PERMANENT output=tangential_curv_11 size=11 param=crosc
# create weight map
r.mapcalc "weight = if(tangential_curv_5 < 0, -100 * tangential_curv_5, \
if(tangential_curv_7 < 0, -100 * tangential_curv_7, \
if(tangential_curv_11 < 0, -100 * tangential_curv_11, 0.000001)))"
# weigh accumulation map
r.mapcalc expr="elev_ned_30m.acc.weighed = elev_ned_30m.acc * weight"
# copy color table from original accumulation map
r.colors map=elev_ned_30m.acc.weighed raster=elev_ned_30m.acc
Display both the original and the weighed accumulation map. Compare them and proceed if
the weighed accumulation map makes sense.
# extract streams
r.stream.extract elevation=elev_ned_30m@PERMANENT \
accumulation=elev_ned_30m.acc.weighed \
threshold=1000 \
stream_rast=elev_ned_30m.streams
# extract streams using the original accumulation map
r.stream.extract elevation=elev_ned_30m@PERMANENT \
accumulation=elev_ned_30m.acc \
threshold=1000 \
stream_rast=elev_ned_30m.streams.noweight
Now display both stream maps and decide which one is more realistic.

REFERENCES

· Ehlschlaeger, C. (1989). Using the AT Search Algorithm to Develop Hydrologic
Models from Digital Elevation Data, Proceedings of International Geographic
Information Systems (IGIS) Symposium ’89, pp 275-281 (Baltimore, MD, 18-19 March
1989). URL: http://faculty.wiu.edu/CR-Ehlschlaeger2/older/IGIS/paper.html

· Holmgren, P. (1994). Multiple flow direction algorithms for runoff modelling in
grid based elevation models: An empirical evaluation. Hydrological Processes Vol
8(4), pp 327-334. DOI: 10.1002/hyp.3360080405

· Montgomery, D.R., Foufoula-Georgiou, E. (1993). Channel network source
representation using digital elevation models. Water Resources Research Vol
29(12), pp 3925-3934.

Use r.stream.extractgrass online using onworks.net services