dwww: tpablo.net

r.stream.extract(1grass) GRASS GIS User's Manual r.stream.extract(1grass)

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] [depres-
sion=name] threshold=float [d8cut=float] [mexp=float]
[stream_length=integer] [memory=memory in MB] [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 calcu-
lating 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.

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=memory in MB
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 com-
puted flow accumulation if a depression map is provided.

Option threshold defines the minimum (optionally modified) flow accumu-
lation value that will initiate a new stream. If Montgomery’s method
for channel initiation is used, the cell value of the accumulation in-
put map is multiplied by (tan(local slope))mexp and then compared to
threshold. If mexp is given, then the method of Montgomery and
Foufoula-Georgiou (1993) is used to initiate a stream with this value.
The cell value of the accumulation input map is multiplied by (tan(lo-
cal 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 accu-
mulation. 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 deter-
mined with a hydrological analysis similar to r.watershed. The algo-
rithm is MFD (FD8) after Holmgren 1994, as for r.watershed. The thresh-
old option determines the number of streams and detail of stream net-
works. 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, then 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.ter-
raflow, the filled elevation output of r.terraflow must be used. Fur-
ther 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 con-
tributing area in square meters or any other unit. When an original
flow accumulation map is adjusted or weighed, the adjustment or weigh-
ing should not convert valid accumulation values to NULL (nodata) val-
ues.

In case of getting the error message ERROR: Accumulation raster map is
NULL but elevation map is not NULL the computational region must be
carefully adjusted to exclude NULL pixels in the accumulation raster
map prior to stream extraction.

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 in-
crease 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 deter-
mined from terrain morphology. Valleys can be determined with
r.param.scale method=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 loca-
tions.

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 at-
tribute table for layer 1 holds information about the type of stream
segment: start segment, or intermediate segment with tributaries, and
about the stream network this stream or node belongs to. Columns are
cat int,stream_type varchar(),type_code int,network int. The network
attribute is the network ID of the stream/node. 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=elev_ned_30m.acc
# curvature to get narrow valleys
r.param.scale input=elev_ned_30m@PERMANENT output=tangential_curv_5 size=5 method=crosc
# curvature to get a bit broader valleys
r.param.scale input=elev_ned_30m@PERMANENT output=tangential_curv_7 size=7 method=crosc
# curvature to get broad valleys
r.param.scale input=elev_ned_30m@PERMANENT output=tangential_curv_11 size=11 method=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

Weight map (spatial subset with lake in the southern half)

Original flow accumulation map (spatial subset with lake in the south-
ern half)

Weighed flow accumulation map (spatial subset with lake in the southern
half)

Display both the original and the weighed accumulation map. Compare
them and proceed if the weighed accumulation map makes sense.
# 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
# extract streams from weighed map
# note that the weighed map is a bit smaller than the original map
r.stream.extract elevation=elev_ned_30m@PERMANENT \
accumulation=elev_ned_30m.acc.weighed \
threshold=1000 \
stream_rast=elev_ned_30m.streams

Now display both stream maps and decide which one is more realistic.

Extracted streams from original flow accumulation map

Extracted streams from weighed flow accumulation map

REFERENCES
• Ehlschlaeger, C. (1989). Using the AT Search Algorithm to De-
velop Hydrologic Models from Digital Elevation Data, Proceed-
ings 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/pa-
per.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.

SEE ALSO
r.mapcalc, r.param.scale, r.stream.channel (Addon), r.stream.distance
(Addon), r.stream.order (Addon), r.stream.segment (Addon),
r.stream.slope (Addon), r.stream.snap (Addon), r.stream.stats (Addon),
r.terraflow, r.thin, r.to.vect, r.watershed