Ubuntu Manpage: r.terraflow - Flow computation for massive grids (float version).

NAME

       r.terraflow  - Flow computation for massive grids (float version).

KEYWORDS

       raster, hydrology

SYNOPSIS

       r.terraflow
       r.terraflow help
       r.terraflow    [-sq]    elevation=name    filled=name    direction=name    swatershed=name
       accumulation=name   tci=name    [d8cut=float]     [memory=integer]     [STREAM_DIR=string]
       [stats=string]   [--overwrite]  [--verbose]  [--quiet]

   Flags:
       -s
           SFD (D8) flow (default is MFD)

       -q
           Quiet

       --overwrite
           Allow output files to overwrite existing files

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       elevation=name
           Name of 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
           (meaningfull only  for MFD flow)
           Default: infinity

       memory=integer
           Maximum runtime memory size (in MB)
           Default: 300

       STREAM_DIR=string
           Directory to hold temporary files (they can be large)

       stats=string
           Name of file containing runtime statistics
           Default: stats.out

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.

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 functions existing in other GIS systems.

Flow directions are computed using either the MFD (Multiple Flow Direction) model or the
SFD (Single Flow Direction, or D8) model, illustrated below. Both methods compute
downslope flow directions by inspecting the 3-by-3 window around the current cell. The SFD
method assigns 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 every 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.terraflow computes flow
accumulation by routing water using the flow directions 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 using 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 index, defined as the
logarithm of the ratio of flow accumulation and local 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 intermediate
temporary files that may be up to 80N bytes, where N is the number 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 STREAM_DIR
option. Note: STREAM_DIR 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 memory 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 internal type used by r.terraflow to store elevations can be defined at compile-time.
By default, r.terraflow is compiled to store elevations internally as floats. A version
which is compiled to store elevations internally as shorts is available as
r.terraflow.short. Other versions can be created by the user if needed.

r.terraflow.short 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.terraflow.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).

The stats option defines the name of the file that contains the statistics (stats) of the
run. The default name is stats.out (in the current directory).

EXAMPLES

       Spearfish sample data set:
       g.region rast=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 rast=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

AUTHORS

       Original version of program: The <a
              href="http://www.cs.duke.edu/geo*/terraflow/">TerraFlow   project,    1999,    Duke
              University.
              Lars  Arge,  Jeff  Chase,  Pat  Halpin,  Laura Toma, Dean Urban, Jeff Vitter, Rajiv
              Wickremesinghe.

       Porting for GRASS, 2002:
               Lars Arge, Helena Mitasova, Laura Toma.

       Contact:  Laura Toma

REFERENCES

       1
               The TerraFlow project at Duke University

       2      <A                                                             NAME="arge:drainage"
              HREF="http://www.cs.duke.edu/geo*/terraflow/papers/alenex00_drainage.ps.gz">   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      <A                                                        NAME="terraflow:acmgis01"
              HREF="http://www.cs.duke.edu/geo*/terraflow/papers/acmgis01_terraflow.pdf">    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 Geographic Information Systems, 2001.

       4      <A                                                  NAME="terraflow:geoinformatica"
              HREF="http://www.cs.duke.edu/geo*/terraflow/papers/journal_terraflow.pdf">     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,  International  Journal  on  Advances  of  Computer   Science   for
              Geographic Information Systems, 7(4):283-313, December 2003.

       Last changed: $Date: 2011-11-08 03:29:50 -0800 (Tue, 08 Nov 2011) $

       Full index

       © 2003-2013 GRASS Development Team