![GRASS logo](grass_logo.png)
NAME
r.stream.extract - Stream network extraction
KEYWORDS
raster
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] [stream_rast=name] [stream_vect=name] [direction=name] [--overwrite] [--verbose] [--quiet]
Flags:
- --overwrite
- Allow output files to overwrite existing files
- --verbose
- Verbose module output
- --quiet
- Quiet module output
Parameters:
- elevation=name
- Elevation map
- Elevation on which entire analysis is based
- accumulation=name
- Accumulation map
- Stream extraction will use provided accumulation instead of calculating it anew
- depression=name
- Map with real depressions
- Streams will not be routed out of real depressions
- threshold=float
- 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
- stream_rast=name
- Output raster map with unique stream ids
- stream_vect=name
- Output vector with unique stream ids
- direction=name
- 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.
OPTIONS
- elevation
- Input map, required: Elevation on which entire analysis is based.
NULL (nodata) cells 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.
- accumulation
- Input map, optional: Accumulation values of the provided
accumulation map are used and not calculated from the input
elevation map. If accumulation is given,
elevation 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.
- depression
- Input map, optional: All non-NULL and non-zero cells 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.
- threshold
- Required: threshold for stream initiation by overland flow:
the minumum (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.
- d8cut
- 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.
- mexp
- Use the method of Montgomery and Foufoula-Georgiou (1993) to
initiate a stream with exponent mexp. 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.
- stream_length
- 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.
- stream_rast
- Output raster map with extracted streams. Cell values encode unique
ID for each stream segment.
- stream_vect
- Output vector map with 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.
- direction
- Output raster map with 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.
NOTES
Stream extraction
If no accumulation input map is provided, flow accumulation is
determined with a hydrological anaylsis 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.
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 stream_rast 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.
EXAMPLE
This example is based on the elevation map elevation.10m in the
sample dataset spearfish60 and uses valleys determined with
r.param.scale to weigh an accumulation
map produced with r.watershed.
# set region
g.region -p rast=elevation.10m@PERMANENT
# calculate flow accumulation
r.watershed ele=elevation.10m@PERMANENT acc=elevation.10m.acc -f
# curvature to get narrow valleys
r.param.scale input="elevation.10m@PERMANENT" output="tangential_curv_5" size=5 param=crosc
# curvature to get a bit broader valleys
r.param.scale input="elevation.10m@PERMANENT" output="tangential_curv_7" size=7 param=crosc
# curvature to get broad valleys
r.param.scale input="elevation.10m@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 "elevation.10m.acc.weighed = elevation.10m.acc * weight"
# copy color table from original accumulation map
r.colors map=elevation.10m.acc.weighed raster=elevation.10m.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=elevation.10m@PERMANENT \
accumulation=elevation.10m.acc.weighed \
threshold=1000 \
stream_rast=elevation.10m.streams
# extract streams using the original accumulation map
r.stream.extract elevation=elevation.10m@PERMANENT \
accumulation=elevation.10m.acc \
threshold=1000 \
stream_rast=elevation.10m.streams.noweight
Now display both stream maps and decide which one is more realistic.
SEE ALSO
r.watershed,
r.terraflow,
r.param.scale,
r.mapcalc,
r.thin,
r.to.vect
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.
AUTHOR
Markus Metz
Last changed: $Date: 2012-04-09 12:11:22 -0700 (Mon, 09 Apr 2012) $
Main index - raster index - Full index
© 2003-2014 GRASS Development Team