1r.terraflow(1)              GRASS GIS 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=memory  in MB]   [directory=string]   [stats=string]   [--over‐
17       write]  [--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=memory in MB
65           Maximum memory to be used (in MB)
66           Cache size for raster rows
67           Default: 300
68
69       directory=string
70           Directory to hold temporary files (they can be large)
71
72       stats=string
73           Name for output file containing runtime statistics
74

DESCRIPTION

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

NOTES

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

EXAMPLES

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

REFERENCES

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

SEE ALSO

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

AUTHORS

245       Original  version of program: The                             TerraFlow
246       project, 1999, Duke University.
247           Lars Arge, Jeff Chase, Pat Halpin, Laura  Toma,  Dean  Urban,  Jeff
248           Vitter, Rajiv Wickremesinghe.
249
250       Porting to GRASS GIS, 2002:
251           Lars Arge, Helena Mitasova, Laura Toma.
252
253       Contact:  Laura Toma
254

SOURCE CODE

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