Ubuntu Manpage: r.flow - Construction of slope curves (flowlines), flowpath lengths, and flowline densities (upslope

NAME

       r.flow   -  Construction  of  slope curves (flowlines), flowpath lengths, and flowline densities (upslope
       areas) from a raster digital elevation model (DEM).

KEYWORDS

       raster, hydrology

SYNOPSIS

       r.flow
       r.flow help
       r.flow  [-u3m]  elevin=string    [aspin=string]     [barin=string]     [skip=integer]     [bound=integer]
       [flout=string]   [lgout=string]   [dsout=string]   [--verbose]  [--quiet]

   Flags:
       -u
           Compute upslope flowlines instead of default downhill flowlines

       -3
           3-D lengths instead of 2-D

       -m
           Use less memory, at a performance penalty

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       elevin=string
           Input elevation raster map

       aspin=string
           Input aspect raster map

       barin=string
           Input barrier raster map

       skip=integer
           Number of cells between flowlines
           Options: 1-360
           Default: 7

       bound=integer
           Maximum number of segments per flowline
           Options: 0-1609
           Default: 1609

       flout=string
           Output flowline vector map

       lgout=string
           Output flowpath length raster map

       dsout=string
           Output flowline density raster map

DESCRIPTION

This program generates flowlines using a combined raster-vector approach (see Mitasova and Hofierka 1993
and Mitasova et al. 1995) from an input elevation raster map elevin (integer or floating point), and
optionally an input aspect raster map aspin and/or an input barrier raster map barin. There are three
possible output maps which can be produced in any combination simultaneously: a vector map flout of
flowlines, a raster map lgout of flowpath lengths, and a raster map dsout of flowline densities (which
are equal upslope contributed areas per unit width, when multiplied by resolution).

Aspect used for input must follow the same rules as aspect computed in other GRASS programs (see
v.surf.rst or r.slope.aspect).

Flowline output is given in a vector map flout, (flowlines 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 -u. 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, skip=val, indicates that only the flowlines from every val-th cell are to be
included in flout. The default skip is max(1, /50, /50). A high skip usually speeds up processing time
and often improves the readability of a visualization of flout.

Flowpath length output is given in a raster map lgout. 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 -3 is given,
elevation is taken into account in calculating the length of each segment.

Flowline density downhill or uphill output is given in a raster map dsout. The value in each grid cell is
the number of flowlines which pass through that grid cell, that means the number of flowlines from the
entire map which have segment endpoints within that cell. With the -m 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 aspect input map (if any) will be ignored. The barin parameter is a raster map name with non-
zero values representing barriers as input.

NOTES

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 "quantization error") is about 1-2% of
the resolution on maps with square cells.

The values in length maps computed using the -u 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.

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.

The program 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 (r.fill.dir can be used to fill pits).

To label the vector flowlines automatically, the user can use v.category (add categories).

Algorithm background
1. Construction of flow-lines (slope-lines): r.flow 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 both r.flow
and r.flowmd (GRASS 5 only) algorithms (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.

2. Computation of contributing areas: r.flow uses a single flow algorithm, i.e. all flow is transported
to a single cell downslope.

Differences between r.flow and r.flowmd
1
r.flow has an option to compute slope and aspect internally thus making the program capable to
process much larger data sets than r.flowmd. It has also 2 additional options for handling of
large data sets but it is not known that they work properly.

2
the programs handle the special cases when the flowline passes exactly (or very close) through
the grid vertices differently.

3
r.flowmd has the simplified multiple flow addition so the results are smoother.

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

Diagnostics
"ERROR: r.flow: " input " file's resolution differs from current" region resolution

The resolutions of all input files and the current region must match.

"ERROR: r.flow: resolution too unbalanced (" val " x " val ")" 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.

REFERENCES

       Mitasova,  H.,  L.  Mitas,  1993,  Interpolation  by  regularized  spline  with  tension  : I. Theory and
       implementation. Mathematical Geology 25, p. 641-655.  (online)

       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. (online)

       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.

       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)

       Mitasova, H.(1993): Surfaces and modeling. Grassclippings (winter and spring) p.18-19.

AUTHORS

       Original version of program:
       Maros Zlocha and Jaroslav Hofierka, Comenius University, Bratislava, Slovakia,

       The current version of the program (adapted for GRASS5.0):
       Joshua  Caplan,  Mark  Ruesink,  Helena Mitasova, University of Illinois at Urbana-Champaign with support
       from USA CERL.
       GMSL/University of Illinois at Urbana-Champaign

       Last changed: $Date: 2008-05-15 12:30:26 -0700 (Thu, 15 May 2008) $

       Full index

       © 2003-2013 GRASS Development Team

GRASS 6.4.3                                                                                       r.flow(1grass)