Geografic-Information-System/raster/r.flow/r.flow.html

<h2>DESCRIPTION</h2>

<em>r.flow</em> generates flowlines using a combined raster-vector
approach
(see <a href="http://www4.ncsu.edu/~hmitaso/gmslab/papers/hmg.rev1.ps">Mitasova
and Hofierka 1993</a>
and <a href="http://www4.ncsu.edu/~hmitaso/gmslab/papers/ijgis.html">Mitasova
et al. 1995</a>) from an input <b>elevation</b> raster map (integer or
floating point), and optionally an input <b>aspect</b> raster map
and/or an input <b>barrier</b> raster map.

<p>
There are three possible output raster maps which can be produced in any
combination simultaneously: a vector map <b>flowline</b> of flowlines,
a raster map
<b>flowlength</b> of flowpath lengths, and a raster map
<b>flowaccumulation</b> of flowline densities (which are equal upslope
contributed areas per unit width, when multiplied by resolution).

<h2>NOTES</h2>

Aspect used for input must follow the same rules as aspect computed in
other modules (see <em><a href="v.surf.rst.html">v.surf.rst</a></em>
or <em><a href="r.slope.aspect.html">r.slope.aspect</a></em>).
<p>
Output <b>flowline</b> is generated downhill. The line segments of
flowline vectors have endpoints on edges of a grid formed by drawing
imaginary lines through the centers of the cells in the elevation
map. Flowlines are generated from each cell downhill by default; they
can be generated uphill using the flag <b>-u</b>. A flowline stops if
its next segment would reverse the direction of flow (from up to down
or vice-versa), cross a barrier, or arrive at a cell with undefined
elevation or aspect. Another option, <b>skip</b>, indicates that
only the flowlines from every val-th cell are to be included
in <b>flowline</b>.  The default <b>skip</b> is <tt>max(1,&nbsp;&lt;rows
in elevation&gt;/50,&nbsp;&lt;cols in elevation&gt;/50)</tt>.  A
high <b>skip</b> usually speeds up processing time and often improves
the readability of a visualization of <b>flowline</b>.
<p>
Flowpath length output is given in a raster map <b>flowlength</b>. The value
in each grid cell is the sum of the planar lengths of all segments of the
flowline generated from that cell. If the flag <b>-3</b> is given, elevation
is taken into account in calculating the length of each segment.

<p>Flowline density downhill or uphill output is given in a raster map
<b>flowaccumulation.</b> The value in each grid cell is the number of
flowlines which pass through that grid cell, that means the number of
flowlines from thec entire map which have segment endpoints within that cell.


With the <b>-m</b> flag less memory is used as aspect at each cell is
computed on the fly. This option incurs a severe performance penalty. If
this flag is given, the <b>aspect</b> input map (if any) will be ignored.

<!-- doesn't exist
<p><b>-M</b> Use a fixed size memory and utilize page-swapping to handle
large input files. This option incurs a severe performance penalty but
is the only way to handle arbitrarily-large data files. If this flag is
given, the <b>-m</b> flag will be ignored.
-->

The <b>barrier</b> parameter is a raster map name with non-zero
values representing barriers as input.

<p>
For best results, use input elevation maps with high precision units (e.g.,
centimeters) so that flowlines do not terminate prematurely in flat areas.
To prevent the creation of tiny flowline segments with imperceivable changes
in elevation, an endpoint which would land very close to the center of
a grid cell is quantized to the exact center of that cell. The maximum
distance between the intercepts along each axis of a single diagonal segment
and another segment of 1/2 degree different aspect is taken to be "very
close" for that axis. Note that this distance (the so-called &quot;quantization
error&quot;) is about 1-2% of the resolution on maps with square cells.

<p>The values in length maps computed using the <b>-u</b> flag represent
the distances from each cell to an upland flat or singular point. Such
distances are useful in water erosion modeling for computation of the LS
factor in the standard form of USLE. Uphill flowlines merge on ridge lines;
by redirecting the order of the flowline points in the output vector map,
dispersed waterflow can be simulated. The density map can be used for the
extraction of ridge lines.

<p>Computing the flowlines downhill simulates the actual flow (also known
as the raindrop method). These flowlines tend to merge in valleys; they
can be used for localization of areas with waterflow accumulation and for
the extraction of channels. The downslope flowline density multiplied by
the resolution can be used as an approximation of the upslope contributing
area per unit contour width. This area is a measure of potential water
flux for the steady state conditions and can be used in the modeling of
water erosion for the computation of the unit stream power based LS factor
or sediment transport capacity.

<p><em>r.flow</em> has been designed for modeling erosion on
hillslopes and has rather strict conditions for ending flowlines. It
is therefore not very suitable for the extraction of stream networks
or delineation of watersheds unless a DEM without pits or flat areas
is available (<em><a href="r.fill.dir.html">r.fill.dir</a></em> can be
used to fill pits).

<p> To label the vector flowlines automatically, the user can use
<em><a href="v.category.html">v.category</a></em> (add categories).

<h3>Algorithm background</h3> 

<p>
<em>r.flow</em> uses an original vector-grid algorithm which uses an
infinite number of directions between 0.0000... and 360.0000...  and
traces the flow as a line (vector) in the direction of gradient
(rather than from cell to cell in one of the 8 directions = D-infinity
algorithm). They are traced in any direction using aspect (so there is
no limitation to 8 directions here). The D8 algorithm produces zig-zag
lines. The value in the outlet is very similar for <em>r.flow</em>
algorithm (because it is essentially the watershed area), however the
spatial distribution of flow, especially on hillslopes is quite
different. It is still a 1D flow routing so the dispersal flow is not
accurately described, but still better than D8.

<p>
<em>r.flow</em> uses a single flow algorithm, i.e. all flow is
transported to a single cell downslope.

<!--
Differences between <em>r.flow</em> and <em>r.flowmd</em>
<p>
<ol>

<li> <em>r.flow</em> has an option to compute slope and aspect internally thus making
the program capable to process much larger data sets than <em>r.flowmd</em>. It has
also 2 additional options for handling of large data sets but it is not
known that they work properly.
<li> the programs handle the special cases when the flowline passes exactly
(or very close) through the grid vertices differently.
<li> <em>r.flowmd</em> has the simplified multiple flow addition so the results are
smoother.
</ol>

In conclusion, <em>r.flowmd</em> produces nicer results but is slower and it does not
support as large data sets as <em>r.flow</em>.
-->

<h3>Diagnostics</h3>

<div class="code"><pre>
Elevation raster map resolution differs from current region resolution
</pre></div>

The resolutions of all input raster maps and the current region must
match (see <em><a href="g.region.html">g.region</a></em>).

<div class="code"><pre>
Resolution too unbalanced
</pre></div>

The difference in length between the two axes of a grid cell is so
great that quantization error is larger than one of the
dimensions. Resample the map and try again.

<h2>EXAMPLE</h2>

In this example a flow line vector map, a flow path length raster map and
a flow accumulation raster map are computed from an elevation raster map
(North Carolina sample dataset):

<div class="code"><pre>
g.region raster=elevation -p
r.flow elevation=elevation skip=3 flowline=flowline flowlength=flowlength \
       flowaccumulation=flowaccumulation
</pre></div>

<center>
<img src="r_flow_line.png" alt="flow line">
<img src="r_flow_length.png" alt="flow path length">
<img src="r_flow_accumulation.png" alt="flow accumulation map">
<p>
Figure: Flow lines with underlying elevation map;
flow lines with underlying flow path lengths (in map units: meters);
flow accumulation map (zoomed view)
</center>

<!--
d.vect map=flowline
d.rast map=flowlength
d.rastmap=flowaccumulation
-->

<h2>REFERENCES</h2>

<ul>
<li>Mitasova, H., L. Mitas, 1993, Interpolation by regularized spline with
tension : I. Theory and implementation. Mathematical Geology 25, p. 641-655.
(<a href="http://www4.ncsu.edu/~hmitaso/gmslab/papers/lmg.rev1.ps">online</a>)

<li>Mitasova and Hofierka 1993 : Interpolation by Regularized Spline with
Tension: II. Application to Terrain Modeling and Surface Geometry Analysis.
Mathematical Geology 25(6), 657-669
(<a href="http://www4.ncsu.edu/~hmitaso/gmslab/papers/hmg.rev1.ps">online</a>).

<li>Mitasova, H., Mitas, L., Brown, W.M., Gerdes, D.P., Kosinovsky, I.,
Baker, T., 1995: Modeling spatially and temporally distributed phenomena:
New methods and tools for GRASS GIS. International Journal of Geographical
Information Systems 9(4), 433-446. 

<li>Mitasova, H., J. Hofierka, M. Zlocha, L.R. Iverson, 1996, Modeling
topographic potential for erosion and deposition using GIS. Int. Journal of
Geographical Information Science, 10(5), 629-641. (reply to a comment to
this paper appears in 1997 in Int. Journal of Geographical Information
Science, Vol. 11, No. 6)

<li>Mitasova, H.(1993): Surfaces and modeling. Grassclippings (winter and
spring) p.18-19.
</ul>

<h2>SEE ALSO</h2>

<em>
<a href="r.basins.fill.html">r.basins.fill</a>,
<a href="r.drain.html">r.drain</a>,
<a href="r.fill.dir.html">r.fill.dir</a>,
<a href="r.water.outlet.html">r.water.outlet</a>,
<a href="r.watershed.html">r.watershed</a>,
<a href="v.category.html">v.category</a>,
<a href="v.to.rast.html">v.to.rast</a>
</em>

<h2>AUTHORS</h2>

<i>Original version of program:</i> Maros Zlocha and Jaroslav
Hofierka, Comenius University, Bratislava, Slovakia

<p>
<i>The current version of the program (adapted for GRASS 5.0)</i>:
Joshua Caplan, Mark Ruesink, Helena Mitasova, University of Illinois
at Urbana-Champaign with support from USA CERL.
<a href="http://www4.ncsu.edu/~hmitaso/gmslab/">GMSL/University of Illinois
at Urbana-Champaign</a>

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