Provided by: grass-doc_6.4.3-3_all bug


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


       raster, hydrology


       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]

           SFD (D8) flow (default is MFD)


           Allow output files to overwrite existing files

           Verbose module output

           Quiet module output

           Name of elevation raster map

           Name for output filled (flooded) elevation raster map

           Name for output flow direction raster map

           Name for output sink-watershed raster map

           Name for output flow accumulation raster map

           Name for output topographic convergence index (tci) raster map

           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

           Maximum runtime memory size (in MB)
           Default: 300

           Directory to hold temporary files (they can be large)

           Name of file containing runtime statistics
           Default: stats.out


       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

       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.


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


       Spearfish sample data set:
       g.region rast=elevation.10m -p
       r.terraflow elev=elevation.10m filled=elevation10m.filled \
           dir=elevation10m.mfdir swatershed=elevation10m.watershed \

       g.region rast=elevation.10m -p
       r.terraflow elev=elevation.10m filled=elevation10m.filled \
           dir=elevation10m.mfdir swatershed=elevation10m.watershed \
           accumulation=elevation10m.accu d8cut=500 memory=800 \


        r.flow, r.basins.fill, r.drain, r.topidx, r.topmodel, r.water.outlet, r.watershed


       Original version of program: The <a
              href="*/terraflow/">TerraFlow   project,    1999,    Duke
              Lars  Arge,  Jeff  Chase,  Pat  Halpin,  Laura Toma, Dean Urban, Jeff Vitter, Rajiv

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

       Contact:  Laura Toma


               The TerraFlow project at Duke University

       2      <A                                                             NAME="arge:drainage"
              HREF="*/terraflow/papers/">   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="*/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="*/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