Geografic-Information-System/raster/r.stream.extract/r.stream.extract.html

<h2>DESCRIPTION</h2>

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

<h2>NOTES</h2>

<p>
NULL (nodata) cells in the input <b>elevation</b> 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
<em><a href="r.fillnulls.html">r.fillnulls</a></em>, to avoid distortions.

<p>
All non-NULL and non-zero cells of <b>depression</b> 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.

<p>
Option <b>threshold</b> defines the minimum (optionally modified) 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 <tt>(tan(local
slope))<sup>mexp</sup></tt> and then compared
to <b>threshold</b>. If <b>mexp</b> 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 <tt>(tan(local slope))<sup>mexp</sup></tt> and then compared
to <b>threshold</b>. 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. <b>mexp</b> values closer to 0 will produce streams more
similar to streams extracted with Montgomery disabled.
Larger <b>mexp</b> values decrease the number of streams in flat areas
and increase the number of streams in steep areas. If <b>weight</b> is
given, the weight is applied first.

<p>
Option <b>d8cut</b> 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.

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

<p>
Output <b>direction</b> 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.

<h3>Stream extraction</h3>

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

<p>
If <b>accumulation</b> is given than the accumulation values of the
provided <b>accumulation</b> map are used and not calculated from the
input <b>elevation</b> map. In this case the <b>elevation</b> map must
be exactly the same map used to calculate
<b>accumulation</b>. If <b>accumulation</b> was calculated with
<em><a href="r.terraflow.html">r.terraflow</a></em>, the filled
elevation output
of <em><a href="r.terraflow.html">r.terraflow</a></em> must be
used. Further on, the current region should be aligned to
the <b>accumulation</b> map. Flow direction is first calculated
from <b>elevation</b> and then adjusted to
<b>accumulation</b>. It is not necessary to provide <b>accumulation</b>
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.

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

<h3>Weighed flow accumulation</h3>

Flow accumulation can be calculated first, e.g. with
<em><a href="r.watershed.html">r.watershed</a></em>, and then modified before
using it as input for <em>r.stream.extract</em>. 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
<em><a href="r.mapcalc.html">r.mapcalc</a></em>. It is highly recommended to
evaluate the weighed flow accumulation map first, before using it as
input for <em>r.stream.extract</em>.
<p>
This allows e.g. to decrease the number of streams in dry areas and
increase the number of streams in wet areas by setting <b>weight</b>
to smaller than 1 in dry areas and larger than 1 in wet areas.
<p>
Another possibility is to restrict channel initiation to valleys
determined from terrain morphology. Valleys can be determined with
<em><a href="r.param.scale.html">r.param.scale</a></em> <tt>method=crosc</tt>
(cross-sectional or tangential curvature). Curvature values &lt; 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).

<h3>Defining a region of interest</h3>

The stream extraction procedure can be restricted to a certain region of 
interest, e.g. a subbasin, by setting the computational region with 
<em><a href="g.region.html">g.region</a></em> 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.

<h3>Stream output</h3>

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

<p>
Output <b>stream_raster</b> raster map stores extracted streams. Cell
values encode a unique ID for each stream segment.

<p>
Output <b>stream_vector</b> 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 <tt>cat int, stream_type varchar(), type_code
int</tt>. 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.

<h2>EXAMPLE</h2>

This example is based on the elevation map &quot;elev_ned_30m&quot; in the
North Carolina sample dataset and uses valleys determined with
<em><a href="r.param.scale.html">r.param.scale</a></em> to weigh an accumulation
map produced with <em><a href="r.watershed.html">r.watershed</a></em>.

<div class="code"><pre>
# 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 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 &lt; 0, -100 * tangential_curv_5, \
                    if(tangential_curv_7 &lt; 0, -100 * tangential_curv_7, \
		    if(tangential_curv_11 &lt; 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
</pre></div>

<p>
<a href="r_stream_extract_weights_zoom.png">
<img src="r_stream_extract_weights_zoom.png" width="400"></a><br>
Weight map (spatial subset with lake in the southern half)

<p>
<a href="r_stream_extract_accum_orig_zoom.png">
<img src="r_stream_extract_accum_orig_zoom.png" width="400"></a><br>
Original flow accumulation map (spatial subset with lake in the southern half)

<p>
<a href="r_stream_extract_accum_weighted_zoom.png">
<img src="r_stream_extract_accum_weighted_zoom.png" width="400"></a><br>
Weighed flow accumulation map (spatial subset with lake in the southern half)
<p>

Display both the original and the weighed accumulation map.
Compare them and proceed if the weighed accumulation map makes sense.

<div class="code"><pre>
# 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
r.stream.extract elevation=elev_ned_30m@PERMANENT \
                 accumulation=elev_ned_30m.acc.weighed \
		 threshold=1000 \
		 stream_rast=elev_ned_30m.streams
</pre></div>

<p>
Now display both stream maps and decide which one is more realistic.
<!-- 
d.shade color=elev_ned_30m_streams_noweight shade=elevation_shade brighten=20
-->
<p>
<a href="r_stream_extract_streams_noweight.png">
<img src="r_stream_extract_streams_noweight.png" width="400"></a><br>
Extracted streams from original flow accumulation map

<p>
<a href="r_stream_extract_streams_weighed.png">
<img src="r_stream_extract_streams_weighed.png" width="400"></a><br>
Extracted streams from weighed flow accumulation map


<h2>REFERENCES</h2>

<ul>
<li>Ehlschlaeger, C. (1989). <i>Using the A<sup>T</sup> Search
Algorithm to Develop Hydrologic Models from Digital Elevation
Data</i>,
<b>Proceedings of International Geographic Information Systems (IGIS)
Symposium '89</b>, pp 275-281 (Baltimore, MD, 18-19 March
1989). URL: <a href="http://faculty.wiu.edu/CR-Ehlschlaeger2/older/IGIS/paper.html">
http://faculty.wiu.edu/CR-Ehlschlaeger2/older/IGIS/paper.html</a></li>
<li>Holmgren, P. (1994). <i>Multiple flow direction algorithms for
runoff modelling in grid based elevation models: An empirical
evaluation.</i>
<b>Hydrological Processes</b> Vol 8(4), pp 327-334. DOI: <a href="http://dx.doi.org/10.1002/hyp.3360080405">10.1002/hyp.3360080405</a></li>
<li>Montgomery, D.R., Foufoula-Georgiou, E. (1993). <i>Channel network source
representation using digital elevation models.</i>
<b>Water Resources Research</b> Vol 29(12), pp 3925-3934.</li>
</ul>

<h2>SEE ALSO</h2>

<em>
<a href="r.mapcalc.html">r.mapcalc</a>,
<a href="r.param.scale.html">r.param.scale</a>,
<a href="https://grass.osgeo.org/grass7/manuals/addons/r.stream.channel.html">r.stream.channel</a> (Addon),
<a href="https://grass.osgeo.org/grass7/manuals/addons/r.stream.distance.html">r.stream.distance</a> (Addon),
<a href="https://grass.osgeo.org/grass7/manuals/addons/r.stream.order.html">r.stream.order</a> (Addon),
<a href="https://grass.osgeo.org/grass7/manuals/addons/r.stream.segment.html">r.stream.segment</a> (Addon),
<a href="https://grass.osgeo.org/grass7/manuals/addons/r.stream.slope.html">r.stream.slope</a> (Addon),
<a href="https://grass.osgeo.org/grass7/manuals/addons/r.stream.snap.html">r.stream.snap</a> (Addon),
<a href="https://grass.osgeo.org/grass7/manuals/addons/r.stream.stats.html">r.stream.stats</a> (Addon),
<a href="r.terraflow.html">r.terraflow</a>,
<a href="r.thin.html">r.thin</a>,
<a href="r.to.vect.html">r.to.vect</a>,
<a href="r.watershed.html">r.watershed</a>
</em>

<p>
See
also <a href="http://grasswiki.osgeo.org/wiki/R.stream.*_modules">r.streams.*
modules</a> wiki page.

<h2>AUTHOR</h2>

Markus Metz

<p>
<i>Last changed: $Date$</i>