1r.terraflow(1)                Grass User's Manual               r.terraflow(1)
2
3
4

NAME

6       r.terraflow  - Performs flow computation for massive grids.
7

KEYWORDS

9       raster, hydrology, flow, accumulation, sink
10

SYNOPSIS

12       r.terraflow
13       r.terraflow --help
14       r.terraflow   [-s]   elevation=name   [filled=name]    [direction=name]
15       [swatershed=name]    [accumulation=name]    [tci=name]    [d8cut=float]
16       [memory=integer]    [directory=string]   [stats=string]   [--overwrite]
17       [--help]  [--verbose]  [--quiet]  [--ui]
18
19   Flags:
20       -s
21           SFD (D8) flow (default is MFD)
22           SFD: single flow direction, MFD: multiple flow direction
23
24       --overwrite
25           Allow output files to overwrite existing files
26
27       --help
28           Print usage summary
29
30       --verbose
31           Verbose module output
32
33       --quiet
34           Quiet module output
35
36       --ui
37           Force launching GUI dialog
38
39   Parameters:
40       elevation=name [required]
41           Name of input elevation raster map
42
43       filled=name
44           Name for output filled (flooded) elevation raster map
45
46       direction=name
47           Name for output flow direction raster map
48
49       swatershed=name
50           Name for output sink-watershed raster map
51
52       accumulation=name
53           Name for output flow accumulation raster map
54
55       tci=name
56           Name for output topographic convergence index (tci) raster map
57
58       d8cut=float
59           Routing using SFD (D8) direction
60           If flow accumulation is larger than this value it is  routed  using
61           SFD  (D8) direction (meaningful only for MFD flow). If no answer is
62           given it defaults to infinity.
63
64       memory=integer
65           Maximum memory to be used (in MB)
66           Default: 300
67
68       directory=string
69           Directory to hold temporary files (they can be large)
70
71       stats=string
72           Name for output file containing runtime statistics
73

DESCRIPTION

75       r.terraflow takes as input a raster digital elevation model  (DEM)  and
76       computes the flow direction raster and the flow accumulation raster, as
77       well as the flooded elevation raster, sink-watershed raster  (partition
78       into  watersheds  around sinks) and TCI (topographic convergence index)
79       raster maps.
80
81       r.terraflow computes these rasters using  well-known  approaches,  with
82       the  difference that its emphasis is on the computational complexity of
83       the algorithms, rather than on modeling  realistic  flow.   r.terraflow
84       emerged  from the necessity of having scalable software able to process
85       efficiently very large terrains.  It is based on theoretically  optimal
86       algorithms  developed  in  the  framework  of I/O-efficient algorithms.
87       r.terraflow was designed and optimized especially for massive grids and
88       is  able  to process terrains which were impractical with similar func‐
89       tions existing in other GIS systems.
90
91       Flow directions are computed using either the MFD (Multiple Flow Direc‐
92       tion)  model  or  the  SFD (Single Flow Direction, or D8) model, illus‐
93       trated  below.  Both  methods  compute  downslope  flow  directions  by
94       inspecting  the  3-by-3  window around the current cell. The SFD method
95       assigns a unique flow direction towards the steepest  downslope  neigh‐
96       bor. The MFD method assigns multiple flow directions towards all downs‐
97       lope neighbors.
98
99
100
101       Flow direction to steepest downslope neighbor (SFD).         Flow direction to all downslope neighbors (MFD).
102
103
104       The SFD and the MFD method cannot compute  flow  directions  for  cells
105       which have the same height as all their neighbors (flat areas) or cells
106       which do not have downslope neighbors (one-cell pits).
107
108           ·   On plateaus (flat areas that spill out) r.terraflow routes flow
109               so  that  globally the flow goes towards the spill cells of the
110               plateaus.
111
112           ·   On sinks (flat areas that do not spill out, including  one-cell
113               pits)  r.terraflow  assigns  flow by flooding the terrain until
114               all the sinks are filled and assigning flow directions  on  the
115               filled terrain.
116
117       In  order  to  flood  the terrain, r.terraflow identifies all sinks and
118       partitions the terrain into sink-watersheds (a sink-watershed  contains
119       all  the  cells  that flow into that sink), builds a graph representing
120       the  adjacency  information  of  the  sink-watersheds,  and  uses  this
121       sink-watershed  graph  to  merge watersheds into each other along their
122       lowest common boundary until all watersheds have a  flow  path  outside
123       the  terrain. Flooding produces a sink-less terrain in which every cell
124       has a downslope flow path leading outside  the  terrain  and  therefore
125       every  cell  in  the terrain can be assigned SFD/MFD flow directions as
126       above.
127
128       Once flow directions are computed for every cell in the terrain, r.ter‐
129       raflow  computes  flow  accumulation  by  routing  water using the flow
130       directions and keeping track of how much water flows through each cell.
131
132       If flow accumulation of a cell is larger than the value  given  by  the
133       d8cut  option,  then  the  flow of this cell is routed to its neighbors
134       using the SFD (D8) model. This option affects only the  flow  accumula‐
135       tion raster and is meaningful only for MFD flow (i.e. if the -s flag is
136       not used); If this option is used for  SFD  flow  it  is  ignored.  The
137       default value of d8cut is infinity.
138
139       r.terraflow  also  computes  the  tci  raster  (topographic convergence
140       index, defined as the logarithm of the ratio of flow  accumulation  and
141       local slope).
142
143       For more details on the algorithms see [1,2,3] below.
144

NOTES

146       One  of the techniques used by r.terraflow is the space-time trade-off.
147       In particular, in order to avoid  searches,  which  are  I/O-expensive,
148       r.terraflow  computes  and  works with an augmented elevation raster in
149       which each cell stores relevant information about its 8  neighbors,  in
150       total  up to 80B per cell.  As a result r.terraflow works with interme‐
151       diate temporary files that may be up to 80N bytes, where N is the  num‐
152       ber  of cells (rows x columns) in the elevation raster (more precisely,
153       80K bytes, where K is the number of valid (not no-data)  cells  in  the
154       input elevation raster).
155
156       All these intermediate temporary files are stored in the path specified
157       by the directory option. Note: directory must contain enough free  disk
158       space in order to store up to 2 x 80N bytes.
159
160       The  memory option can be used to set the maximum amount of main memory
161       (RAM) the module will use during  processing.  In  practice  its  value
162       should  be an underestimate of the amount of available (free) main mem‐
163       ory on the machine. r.terraflow will use at all times at most this much
164       memory,  and the virtual memory system (swap space) will never be used.
165       The default value is 300 MB.
166
167       The stats option defines the name of the file that contains the statis‐
168       tics (stats) of the run.
169
170       r.terraflow  has  a limit on the number of rows and columns (max 32,767
171       each).
172
173       The internal type used  by  r.terraflow  to  store  elevations  can  be
174       defined  at  compile-time. By default, r.terraflow is compiled to store
175       elevations internally as floats. Other versions can be created  by  the
176       user if needed.
177
178       Hints  concerning  compilation with storage of elevations internally as
179       shorts: such a version uses less space (up to 60B per cell, up  to  60N
180       intermediate  file)  and  therefore  is  more space and time efficient.
181       r.terraflow is  intended  for  use  with  floating  point  raster  data
182       (FCELL),  and  r.terraflow  (short)  with integer raster data (CELL) in
183       which the maximum elevation does  not  exceed  the  value  of  a  short
184       SHRT_MAX=32767  (this  is  not a constraint for any terrain data of the
185       Earth, if elevation is stored in meters).  Both r.terraflow and  r.ter‐
186       raflow  (short)  work  with input elevation rasters which can be either
187       integer, floating point or double (CELL, FCELL, DCELL).  If  the  input
188       raster  contains a value that exceeds the allowed internal range (short
189       for r.terraflow (short), float for r.terraflow), the program exits with
190       a  warning  message.  Otherwise,  if  all values in the input elevation
191       raster are in range, they will be converted (truncated) to the internal
192       elevation  type (short for r.terraflow (short), float for r.terraflow).
193       In this case precision may be lost and artificial  flat  areas  may  be
194       created.   For  instance,  if r.terraflow (short) is used with floating
195       point raster data (FCELL or DCELL), the values of the elevation will be
196       truncated  as  shorts.  This  may create artificial flat areas, and the
197       output of r.terraflow (short) may  be  less  realistic  than  those  of
198       r.terraflow  on floating point raster data.  The outputs of r.terraflow
199       (short) and r.terraflow are identical for  integer  raster  data  (CELL
200       maps).
201

EXAMPLES

203       Example  for  small  area in North Carolina sample dataset to calculate
204       flow accumulation:
205       g.region raster=elev_lid792_1m
206       r.terraflow elevation=elev_lid792_1m accumulation=elev_lid792_1m_accumulation
207       Flow accumulation
208
209       Spearfish sample data set:
210       g.region raster=elevation.10m -p
211       r.terraflow elev=elevation.10m filled=elevation10m.filled \
212           dir=elevation10m.mfdir swatershed=elevation10m.watershed \
213           accumulation=elevation10m.accu tci=elevation10m.tci
214       g.region raster=elevation.10m -p
215       r.terraflow elev=elevation.10m filled=elevation10m.filled \
216           dir=elevation10m.mfdir swatershed=elevation10m.watershed \
217           accumulation=elevation10m.accu tci=elevation10m.tci d8cut=500 memory=800 \
218           stats=elevation10mstats.txt
219

REFERENCES

221       1      The TerraFlow project at Duke University
222
223       2      I/O-efficient algorithms for problems  on  grid-based  terrains.
224              Lars  Arge, Laura Toma, and Jeffrey S. Vitter. In Proc. Workshop
225              on Algorithm Engineering and Experimentation, 2000. To appear in
226              Journal of Experimental Algorithms.
227
228       3      Flow computation on massive grids.  Lars Arge, Jeffrey S. Chase,
229              Patrick N. Halpin, Laura Toma, Jeffrey S. Vitter, Dean Urban and
230              Rajiv Wickremesinghe. In Proc. ACM Symposium on Advances in Geo‐
231              graphic Information Systems, 2001.
232
233       4      Flow computation on massive grid terrains.  Lars  Arge,  Jeffrey
234              S. Chase, Patrick N. Halpin, Laura Toma, Jeffrey S. Vitter, Dean
235              Urban and Rajiv  Wickremesinghe.   In  GeoInformatica,  Interna‐
236              tional  Journal  on  Advances of Computer Science for Geographic
237              Information Systems, 7(4):283-313, December 2003.
238

SEE ALSO

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

AUTHORS

244       Original  version of program: The                             TerraFlow
245       project, 1999, Duke University.
246           Lars Arge, Jeff Chase, Pat Halpin, Laura  Toma,  Dean  Urban,  Jeff
247           Vitter, Rajiv Wickremesinghe.
248
249       Porting to GRASS GIS, 2002:
250           Lars Arge, Helena Mitasova, Laura Toma.
251
252       Contact:  Laura Toma
253
254       Last changed: $Date: 2017-02-11 22:22:16 +0100 (Sat, 11 Feb 2017) $
255

SOURCE CODE

257       Available at: r.terraflow source code (history)
258
259       Main  index  | Raster index | Topics index | Keywords index | Graphical
260       index | Full index
261
262       © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
263
264
265
266GRASS 7.4.4                                                     r.terraflow(1)
Impressum