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

<h2>DESCRIPTION</h2>

<h2>OPTIONS</h2>
<dl>
<dt><b>-r</b></dt>
<dd>Directions and azimut output in radians. Default is degrees.</dd>

<dt><b>-m</b></dt>
<dd>Only for very large data sets. Use segment library to optimize memory
consumption during analysis</dd>

<dt><b>stream_rast</b></dt>
<dd>Stream network: name of input stream map. Streams shall be ordered according
one of the <em>r.stream.order</em> ordering system as well as unordered (with original
stream identifiers)  Because streams network produced by <em>r.watershed</em> and
<em>r.stream.extract</em> may slightly differ in detail, it is required to use both stream
and direction map produced by the same module. Stream background shall have NULL
value or zero value. Background values of NULL are by default produced by
<em>r.watershed</em> and <em>r.stream.extract</em>. If not 0 or NULL use <em><a
href="r.mapcalc.html">r.mapcalc</a></em> to set background values to null.  
</dd>

<dt><b>direction</b></dt>
<dd>Flow direction: name of input direction map produced by <em>r.watershed</em> or
<em>r.stream.extract</em>. If r.stream.extract output map is used, it only has non-NULL
values in places where streams occur. NULL (nodata) cells are ignored, zero and
negative values are valid direction data if they vary from -8 to 8 (CCW from
East in steps of 45 degrees). Direction map shall be of type CELL values. Region
resolution and map resolution must be the same. 
Also <em>stream_rast</em> network map must have the same resolution. It is checked by
default. If resolutions differ the module informs about it and stops. Region
boundary and maps boundary may be differ but it may lead to unexpected
results.</dd>

<dt><b>elevation</b></dt>
<dd>Elevation: name of input elevation map. Map can be of type CELL, FCELL or
DCELL. It is not restricted to resolution of region settings as stream_rast and
direction.</dd>

<dt><b>length</b></dt>
<dd>Integer values indicating the search length (in cells) to determine straight
line. The longest length parameter the module treats more tolerant local stream
undulation and inequalities. Default value of 15 is suitable for 30 meters
DEMs. More detail DEMs may requre longer length.</dd>

<dt><b>skip</b></dt>
<dd>Integer values indicating the length (in cells) local short segment to skip
and join them to the longer neighbour. The shortest length parameter the more
short segments will be produced by the module due to undulation and
inequalities. Default value of 5 is suitable for 30 meters DEMS. More details
DEMS may require longer length.</dd>

<dt><b>threshold</b></dt>
<dd>real value indicates the internal angle between upstream and downstream
direction to treat actual cell as lying on the straight line. Greater values (up to
180 degrees) produce more segments. Lower values produce less segments.
Values below 90 in most cases will not produce any additional segments to those
resulting from ordering.</dl>

<dl>
<h2>OUTPUTS</h2>
<p>The module produces two vector maps: one representing original segments
(where a segment is a streamline where its order remains unchanged) and the second
divided into near straight line sectors resulting form segmentation process.
Most of the segment and sectors attributes are the same as in <em>r.stream.order</em> vector
output.</p>

<dl>
<dt><b>segments</b></dt>
<dd>
Vector map where every segment has its own category and following attributes:
<ul>
<li><b>segment</b>: integer, segment identifier
<li><b>next_segment</b>: integer, topological next segment identifier
<li><b>s_order</b>: integer, segment order
<li><b>next_order</b>: integer, topological next segment order
<li><b>direction</b>: double precision, full segment direction (0-360)
<li><b>azimuth</b>: double precision, full segment azimuth (0-180) 
<li><b>length</b>: double precision, segment length
<li><b>straight</b>: double precision, length of straight line between segment
nodes
<li><b>sinusoid</b>: double precision, sinusoid (length/straight)
<li><b>elev_min</b>: double precision, minimum elevation (elevation at segment
start)
<li><b>elev_max</b>: double precision, maximum elevation (elevation at segment
end)
<li><b>s_drop</b>: double precision, difference between start and end of the
segment
<li><b>gradient</b>: double precision, drop/length
<li><b>out_direction</b>: double precision, direction (0-360) of segment end
sector
<li><b>out_azimuth</b>: double precision,  azimuth (0-180) of segment end sector
<li><b>out_length</b>: double precision, length of segment end sector
<li><b>out_drop</b>: double precision, drop of segment end sector
<li><b>out_gradient</b>: double precision, gradient of segment end sector
<li><b>tangent_dir</b>: double precision, direction of tangent in segment outlet
to the next stream 
<li><b>tangent_azimuth</b>: double precision, azimuth of tangent in segment
outlet to the next stream 
<li><b>next_direction</b>: double precision, direction of next stream in join
with current segment 
<li><b>next_azimuth</b>: double precision, azimuth of next stream in join with
current segment 
</ul>
<img src="dirs.png">
</dd>
<dt><b>sectors</b></dt>
<dd>Vector map where every sector has its own category and following attributes:
<ul>
<li><b>sector</b>: integer, sector category
<li><b>segment</b>: integer, segment category (to establish relationship)
<li><b>s_order</b>: integer, segment order
<li><b>direction</b>: double precision, sector direction
<li><b>azimuth</b>: double precision, sector azimuth
<li><b>length</b>: double precision, sector length
<li><b>straight</b>: double precision, length of straight line between sector
nodes
<li><b>sinusoid</b>: double precision, sinusoid (length/straight)
<li><b>elev_min</b>: double precision, minimum elevation (elevation at sector
start)
<li><b>elev_max</b>: double precision, minimum elevation (elevation at sector
end)
<li><b>s_drop</b>: double precision, difference between start and end of the
sector
<li><b>gradient</b>: double precision, drop/length
</ul>
<img src="sectors.png">
Relation between segments and sector may be set up by segment key.
</dd>
</dl>
<p>
The main idea comes from works of Horton (1932) and Howard (1971, 1990). The
module is designed to investigate network lineaments and calculate angle
relations between tributaries and its major streams. The main problem in
calculating directional parameters is that streams usually are not straight
lines. Therefore as the first step of the procedure, partitioning of streams
into near-straight-line segments is required.
<p>
The segmentation process uses a method similar to the one used by Van & Ventura
(1997) to detect corners and partition curves into straight lines and gentle
arcs. Because it is almost impossible to determine exactly straight sections
without creating numerous very short segments, the division process requires
some approximation. The approximation is made based on three parameters: (1) the
downstream/upstream search length, (2) the short segment skipping threshold, and
(3) the maximum angle between downstream/upstream segments to be considered as a
straight line. In order to designate straight sections of the streams, the
algorithm is searching for those points where curves significantly change their
direction.
The definition of stream segments depends on the ordering method selected by the
user, Strahler's, Horton's or Hack's main stream, or the network may remain
unordered. All junctions of streams to streams of higher order are always split
points, but for ordered networks, streams of higher order may be divided into
sections which ignore junctions with streams of lower order. In unordered
networks all junctions are always split points.
In extended mode the module also calculates the direction of a stream to its
higher order stream. If the higher order stream begins at the junction with the
current stream (Strahler's ordering only) or if the network is unordered, the
direction is calculated as the direction of the line between junction point and
downstream point (Howard 1971) within the user-defined global search distance.
If a higher order stream continues at the junction, its direction is calculated
as the direction of the tangent line to the stream of higher order at the
junction point. To avoid local fluctuation, the tangent line is approximated as
a secant line joining downstream/upstream points at a distance globally defined
by the search length parameter (1). Such a definition of the angle between
streams is not fully compatible with Horton's original criterion.

<h2>NOTES</h2>
<p>
The module can work only if direction map, stream_rast map and region have the same
settings. It is also required that stream_rast map and direction map come from the
same source. For lots of reason this limitation probably cannot be omitted.  
This means that if stream_rast map comes from <em>r.stream.extract</em>, also direction map from
<em>r.stream.extract</em> must be used. If stream_rast network was generated with MFD method,
also MFD direction map must be used.

<h2>EXAMPLE</h2>

<div class="code"><pre>
g.region -p -a rast=elevation
r.watershed elevation=elevation threshold=10000 drainage=direction stream=streams
r.stream.order stream_vect=streams direction=direction strahler=riverorder_strahler
r.stream.segment stream_rast=riverorder_strahler direction=direction \
  elevation=elevation segments=river_segment sectors=river_sector
</pre></div>

<h2>REFERENCES</h2>

<p>Horton, R. E., (1932). Drainage basin characteristics: Am. Geophys. Union
Trans., (3), 350-361.
<p>Howard, A.D. (1971). Optimal angles of stream junction: Geometric, Stability
to capture and Minimum Power Criteria, Water Resour. Res. 7(4), 863-873.
<p>Howard, A.D. (1990). Theoretical model of optimal drainage networks Water
Resour. Res., 26(9),  2107-2117.
<p>Van, W., Ventura, J.A. (1997). Segmentation of Planar Curves into
Straight-Line Segments and Elliptical Arcs, Graphical Models and Image
Processing 59(6), 484-494.

<h2>SEE ALSO</h2>

<em>

<a href="r.mapcalc.html">r.mapcalc</a>,
<a href="r.stream.channel.html">r.stream.channel</a>,
<a href="r.stream.distance.html">r.stream.distance</a>,
<a href="r.stream.extract.html">r.stream.extract</a>,
<a href="r.stream.order.html">r.stream.order</a>,
<a href="r.stream.slope.html">r.stream.slope</a>,
<a href="r.stream.snap.html">r.stream.snap</a>,
<a href="r.stream.stats.html">r.stream.stats</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>

Jarek Jasiewicz, Adam Mickiewicz University, Geoecology and Geoinformation
Institute.

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