Provided by: grass-doc_8.3.0-1_all bug

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]    [--overwrite]   [--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 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 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 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  stats option defines the name of the file that contains the statistics (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 defined at  compile-time.
       By  default,  r.terraflow  is  compiled  to  store  elevations 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.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).

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 Geographic 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,   International   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: Tuesday Jun 27 11:13:36 2023

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2023 GRASS Development Team, GRASS GIS 8.3.0 Reference Manual