r.flow manual page

(click on highlighted words to view images and animations)

r.flow - construction of slope curves (flowlines), flowpath lengths, and flowline densities from a raster DEM

SYNOPSIS

r.flow .

r.flow help r.flow [ -uzmq ] elevin = name [ aspin = name ] [ barin = name ] [ skip = val ] [ bound = val ] [ flout = name ] [ lgout = name ] [ dsout = name ]

DESCRIPTION

r.flow 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, 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 file flout of flowlines, a raster map lgout of flowpath lengths, and a raster map dsout of flowline densities.

Aspect used for input must follow the same rules as aspect computed in other GRASS4.1 programs (see s.surf.tps 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, elevin/50, elevin/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 -z 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 in the entire map which have segment endpoints within that cell.

OPTIONS

If the user specifies program arguments and flag settings on the command line, the program will immediately begin working. Alternatively, the user can simply type r.flow on the command line and the program will ask for parameter values and flag settings interactively, using the standard GRASS parser interface.

Flags:

-u Generate flowlines uphill (default generates flowlines downhill).

-z Compute three-dimensional lengths (default is two-dimensional).

-m Use less memory and compute aspect at each cell on the fly. This option incurs a severe performance penalty. If this flag is given, the aspect input map (if any) will be ignored.

-q Quiet operation. Do not print diagnostic messages indicating progress.

Parameters:

elevin=name

Use the existing raster file name with elevations as input (required).

aspin=name

Use the existing raster file name with aspects as input.

barin=name

Use the existing raster file name with non-zero values representing barriers as input.

skip=val

Set the number of cells between flowlines in the flout output map to val.

bound=val

Set the maximum number of segments of each flowline to val (default is the maximum possible).

flout=name

Output coordinates of flowlines to a vector file name.

lgout=name

Output flowpath length values to a raster file name.

dsout=name

Output flowline density values to a raster file name.

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.

DIAGNOSTICS

ERROR: GISRC - variable not set

The program was run outside of GRASS.

Usage: r.flow [-uzmq] elevin=name [aspin=name] [barin=name] [skip=value] [bound=value] [flout=name] [lgout=name] [dsout=name]

Invalid options were specified on the command line.

ERROR: r.flow: error getting current region

ERROR: r.flow: unable to reset current region

ERROR: r.flow: cannot open vector file

"ERROR: r.flow: cell file " filename " not found"

"ERROR: r.flow: cannot get header for " filename

"ERROR: r.flow: unable to create raster map " filename

Self-explanatory or beyond explanation.

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

The resolutions of all input files and the current region must match. In future versions this error will be demoted to a warning.

"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.