r.terraflow(1grass) GRASS GIS User's Manual r.terraflow(1grass)
NAME
r.terraflow - Performs flow computation for massive grids.
KEYWORDS
raster, hydrology, flow, accumulation, sink
SYNOPSIS
r.terraflow
r.terraflow --help
r.terraflow [-s] elevation=name [filled=name] [direction=name]
[swatershed=name] [accumulation=name] [tci=name] [d8cut=float]
[memory=memory in MB] [directory=string] [stats=string] [--over-
write] [--help] [--verbose] [--quiet] [--ui]
Flags:
-s
SFD (D8) flow (default is MFD)
SFD: single flow direction, MFD: multiple flow direction
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
elevation=name [required]
Name of input elevation raster map
filled=name
Name for output filled (flooded) elevation raster map
direction=name
Name for output flow direction raster map
swatershed=name
Name for output sink-watershed raster map
accumulation=name
Name for output flow accumulation raster map
tci=name
Name for output topographic convergence index (tci) raster map
d8cut=float
Routing using SFD (D8) direction
If flow accumulation is larger than this value it is routed using
SFD (D8) direction (meaningful only for MFD flow). If no answer is
given it defaults to infinity.
memory=memory in MB
Maximum memory to be used (in MB)
Cache size for raster rows
Default: 300
directory=string
Directory to hold temporary files (they can be large)
stats=string
Name for output file containing runtime statistics
DESCRIPTION
r.terraflow takes as input a raster digital elevation model (DEM) and
computes the flow direction raster and the flow accumulation raster, as
well as the flooded elevation raster, sink-watershed raster (partition
into watersheds around sinks) and TCI (topographic convergence index)
raster maps.
r.terraflow computes these rasters using well-known approaches, with
the difference that its emphasis is on the computational complexity of
the algorithms, rather than on modeling realistic flow. r.terraflow
emerged from the necessity of having scalable software able to process
efficiently very large terrains. It is based on theoretically optimal
algorithms developed in the framework of I/O-efficient algorithms.
r.terraflow was designed and optimized especially for massive grids and
is able to process terrains which were impractical with similar func-
tions existing in other GIS systems.
Flow directions are computed using either the MFD (Multiple Flow Direc-
tion) model or the SFD (Single Flow Direction, or D8) model, illus-
trated below. Both methods compute downslope flow directions by in-
specting the 3-by-3 window around the current cell. The SFD method as-
signs a unique flow direction towards the steepest downslope neighbor.
The MFD method assigns multiple flow directions towards all downslope
neighbors.
Flow direction to steepest downslope neighbor (SFD). Flow direction to all downslope neighbors (MFD).
The SFD and the MFD method cannot compute flow directions for cells
which have the same height as all their neighbors (flat areas) or cells
which do not have downslope neighbors (one-cell pits).
• On plateaus (flat areas that spill out) r.terraflow routes flow
so that globally the flow goes towards the spill cells of the
plateaus.
• On sinks (flat areas that do not spill out, including one-cell
pits) r.terraflow assigns flow by flooding the terrain until
all the sinks are filled and assigning flow directions on the
filled terrain.
In order to flood the terrain, r.terraflow identifies all sinks and
partitions the terrain into sink-watersheds (a sink-watershed contains
all the cells that flow into that sink), builds a graph representing
the adjacency information of the sink-watersheds, and uses this
sink-watershed graph to merge watersheds into each other along their
lowest common boundary until all watersheds have a flow path outside
the terrain. Flooding produces a sink-less terrain in which every cell
has a downslope flow path leading outside the terrain and therefore ev-
ery cell in the terrain can be assigned SFD/MFD flow directions as
above.
Once flow directions are computed for every cell in the terrain, r.ter-
raflow computes flow accumulation by routing water using the flow di-
rections and keeping track of how much water flows through each cell.
If flow accumulation of a cell is larger than the value given by the
d8cut option, then the flow of this cell is routed to its neighbors us-
ing the SFD (D8) model. This option affects only the flow accumulation
raster and is meaningful only for MFD flow (i.e. if the -s flag is not
used); If this option is used for SFD flow it is ignored. The default
value of d8cut is infinity.
r.terraflow also computes the tci raster (topographic convergence in-
dex, defined as the logarithm of the ratio of flow accumulation and lo-
cal slope).
For more details on the algorithms see [1,2,3] below.
NOTES
One of the techniques used by r.terraflow is the space-time trade-off.
In particular, in order to avoid searches, which are I/O-expensive,
r.terraflow computes and works with an augmented elevation raster in
which each cell stores relevant information about its 8 neighbors, in
total up to 80B per cell. As a result r.terraflow works with interme-
diate temporary files that may be up to 80N bytes, where N is the num-
ber of cells (rows x columns) in the elevation raster (more precisely,
80K bytes, where K is the number of valid (not no-data) cells in the
input elevation raster).
All these intermediate temporary files are stored in the path specified
by the directory option. Note: directory must contain enough free disk
space in order to store up to 2 x 80N bytes.
The memory option can be used to set the maximum amount of main memory
(RAM) the module will use during processing. In practice its value
should be an underestimate of the amount of available (free) main mem-
ory on the machine. r.terraflow will use at all times at most this much
memory, and the virtual memory system (swap space) will never be used.
The default value is 300 MB.
The stats option defines the name of the file that contains the statis-
tics (stats) of the run.
r.terraflow has a limit on the number of rows and columns (max 32,767
each).
The internal type used by r.terraflow to store elevations can be de-
fined at compile-time. By default, r.terraflow is compiled to store el-
evations internally as floats. Other versions can be created by the
user if needed.
Hints concerning compilation with storage of elevations internally as
shorts: such a version uses less space (up to 60B per cell, up to 60N
intermediate file) and therefore is more space and time efficient.
r.terraflow is intended for use with floating point raster data
(FCELL), and r.terraflow (short) with integer raster data (CELL) in
which the maximum elevation does not exceed the value of a short
SHRT_MAX=32767 (this is not a constraint for any terrain data of the
Earth, if elevation is stored in meters). Both r.terraflow and r.ter-
raflow (short) work with input elevation rasters which can be either
integer, floating point or double (CELL, FCELL, DCELL). If the input
raster contains a value that exceeds the allowed internal range (short
for r.terraflow (short), float for r.terraflow), the program exits with
a warning message. Otherwise, if all values in the input elevation
raster are in range, they will be converted (truncated) to the internal
elevation type (short for r.terraflow (short), float for r.terraflow).
In this case precision may be lost and artificial flat areas may be
created. For instance, if r.terraflow (short) is used with floating
point raster data (FCELL or DCELL), the values of the elevation will be
truncated as shorts. This may create artificial flat areas, and the
output of r.terraflow (short) may be less realistic than those of
r.terraflow on floating point raster data. The outputs of r.terraflow
(short) and r.terraflow are identical for integer raster data (CELL
maps).
EXAMPLES
Example for small area in North Carolina sample dataset to calculate
flow accumulation:
g.region raster=elev_lid792_1m
r.terraflow elevation=elev_lid792_1m accumulation=elev_lid792_1m_accumulation
Flow accumulation
Spearfish sample data set:
g.region raster=elevation.10m -p
r.terraflow elev=elevation.10m filled=elevation10m.filled \
dir=elevation10m.mfdir swatershed=elevation10m.watershed \
accumulation=elevation10m.accu tci=elevation10m.tci
g.region raster=elevation.10m -p
r.terraflow elev=elevation.10m filled=elevation10m.filled \
dir=elevation10m.mfdir swatershed=elevation10m.watershed \
accumulation=elevation10m.accu tci=elevation10m.tci d8cut=500 memory=800 \
stats=elevation10mstats.txt
REFERENCES
1 The TerraFlow project at Duke University
2 I/O-efficient algorithms for problems on grid-based terrains.
Lars Arge, Laura Toma, and Jeffrey S. Vitter. In Proc. Workshop
on Algorithm Engineering and Experimentation, 2000. To appear in
Journal of Experimental Algorithms.
3 Flow computation on massive grids. Lars Arge, Jeffrey S. Chase,
Patrick N. Halpin, Laura Toma, Jeffrey S. Vitter, Dean Urban and
Rajiv Wickremesinghe. In Proc. ACM Symposium on Advances in Geo-
graphic Information Systems, 2001.
4 Flow computation on massive grid terrains. Lars Arge, Jeffrey
S. Chase, Patrick N. Halpin, Laura Toma, Jeffrey S. Vitter, Dean
Urban and Rajiv Wickremesinghe. In GeoInformatica, Interna-
tional Journal on Advances of Computer Science for Geographic
Information Systems, 7(4):283-313, December 2003.
SEE ALSO
r.flow, r.basins.fill, r.drain, r.topidx, r.topmodel, r.water.outlet,
r.watershed
AUTHORS
Original version of program: The TerraFlow
project, 1999, Duke University.
Lars Arge, Jeff Chase, Pat Halpin, Laura Toma, Dean Urban, Jeff
Vitter, Rajiv Wickremesinghe.
Porting to GRASS GIS, 2002:
Lars Arge, Helena Mitasova, Laura Toma.
Contact: Laura Toma
SOURCE CODE
Available at: r.terraflow source code (history)
Accessed: unknown
Main index | Raster index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 r.terraflow(1grass)
Generated by dwww version 1.14 on Sun Dec 29 18:57:13 CET 2024.