1r.terraflow(1) GRASS GIS User's Manual r.terraflow(1)
2
6 r.terraflow - Performs flow computation for massive grids.
7
9 raster, hydrology, flow, accumulation, sink
10
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 Flags:
20 -s
21 SFD (D8) flow (default is MFD)
22 SFD: single flow direction, MFD: multiple flow direction
23 --overwrite
25 Allow output files to overwrite existing files
26 --help
28 Print usage summary
29 --verbose
31 Verbose module output
32 --quiet
34 Quiet module output
35 --ui
37 Force launching GUI dialog
38 Parameters:
40 elevation=name [required]
41 Name of input elevation raster map
42 filled=name
44 Name for output filled (flooded) elevation raster map
45 direction=name
47 Name for output flow direction raster map
48 swatershed=name
50 Name for output sink-watershed raster map
51 accumulation=name
53 Name for output flow accumulation raster map
54 tci=name
56 Name for output topographic convergence index (tci) raster map
57 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 memory=memory in MB
65 Maximum memory to be used (in MB)
66 Cache size for raster rows
67 Default: 300
68 directory=string
70 Directory to hold temporary files (they can be large)
71 stats=string
73 Name for output file containing runtime statistics
74
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 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 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 in‐
95 specting the 3-by-3 window around the current cell. The SFD method as‐
96 signs a unique flow direction towards the steepest downslope neighbor.
97 The MFD method assigns multiple flow directions towards all downslope
98 neighbors.
99 Flow direction to steepest downslope neighbor (SFD). Flow direction to all downslope neighbors (MFD).
103 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 • 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 • 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 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 ev‐
126 ery cell in the terrain can be assigned SFD/MFD flow directions as
127 above. Flow directions are encoded using powers of two clockwise
128 starting from 20 for east to 27 for north-east.
129 Flow direction encoding clockwise starting from 20 for east to 27 for
130 north-east; 0 for undetermined (sinks) and 1 for undefined (null cells)
131 (source)
132 Once flow directions are computed for every cell in the terrain, r.ter‐
134 raflow computes flow accumulation by routing water using the flow di‐
135 rections and keeping track of how much water flows through each cell.
136 If flow accumulation of a cell is larger than the value given by the
138 d8cut option, then the flow of this cell is routed to its neighbors us‐
139 ing the SFD (D8) model. This option affects only the flow accumulation
140 raster and is meaningful only for MFD flow (i.e. if the -s flag is not
141 used); If this option is used for SFD flow it is ignored. The default
142 value of d8cut is infinity.
143 r.terraflow also computes the tci raster (topographic convergence in‐
145 dex, defined as the logarithm of the ratio of flow accumulation and lo‐
146 cal slope).
147 For more details on the algorithms see [1,2,3] below.
149
151 One of the techniques used by r.terraflow is the space-time trade-off.
152 In particular, in order to avoid searches, which are I/O-expensive,
153 r.terraflow computes and works with an augmented elevation raster in
154 which each cell stores relevant information about its 8 neighbors, in
155 total up to 80B per cell. As a result r.terraflow works with interme‐
156 diate temporary files that may be up to 80N bytes, where N is the num‐
157 ber of cells (rows x columns) in the elevation raster (more precisely,
158 80K bytes, where K is the number of valid (not no-data) cells in the
159 input elevation raster).
160 All these intermediate temporary files are stored in the path specified
162 by the directory option. Note: directory must contain enough free disk
163 space in order to store up to 2 x 80N bytes.
164 The memory option can be used to set the maximum amount of main memory
166 (RAM) the module will use during processing. In practice its value
167 should be an underestimate of the amount of available (free) main mem‐
168 ory on the machine. r.terraflow will use at all times at most this much
169 memory, and the virtual memory system (swap space) will never be used.
170 The default value is 300 MB.
171 The stats option defines the name of the file that contains the statis‐
173 tics (stats) of the run.
174 r.terraflow has a limit on the number of rows and columns (max 32,767
176 each).
177 The internal type used by r.terraflow to store elevations can be de‐
179 fined at compile-time. By default, r.terraflow is compiled to store el‐
180 evations internally as floats. Other versions can be created by the
181 user if needed.
182 Hints concerning compilation with storage of elevations internally as
184 shorts: such a version uses less space (up to 60B per cell, up to 60N
185 intermediate file) and therefore is more space and time efficient.
186 r.terraflow is intended for use with floating point raster data
187 (FCELL), and r.terraflow (short) with integer raster data (CELL) in
188 which the maximum elevation does not exceed the value of a short
189 SHRT_MAX=32767 (this is not a constraint for any terrain data of the
190 Earth, if elevation is stored in meters). Both r.terraflow and r.ter‐
191 raflow (short) work with input elevation rasters which can be either
192 integer, floating point or double (CELL, FCELL, DCELL). If the input
193 raster contains a value that exceeds the allowed internal range (short
194 for r.terraflow (short), float for r.terraflow), the program exits with
195 a warning message. Otherwise, if all values in the input elevation
196 raster are in range, they will be converted (truncated) to the internal
197 elevation type (short for r.terraflow (short), float for r.terraflow).
198 In this case precision may be lost and artificial flat areas may be
199 created. For instance, if r.terraflow (short) is used with floating
200 point raster data (FCELL or DCELL), the values of the elevation will be
201 truncated as shorts. This may create artificial flat areas, and the
202 output of r.terraflow (short) may be less realistic than those of
203 r.terraflow on floating point raster data. The outputs of r.terraflow
204 (short) and r.terraflow are identical for integer raster data (CELL
205 maps).
206
208 Example for small area in North Carolina sample dataset to calculate
209 flow accumulation:
210 g.region raster=elev_lid792_1m
211 r.terraflow elevation=elev_lid792_1m accumulation=elev_lid792_1m_accumulation
212 Flow accumulation
213 Spearfish sample data set:
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
219 g.region raster=elevation.10m -p
220 r.terraflow elev=elevation.10m filled=elevation10m.filled \
221 dir=elevation10m.mfdir swatershed=elevation10m.watershed \
222 accumulation=elevation10m.accu tci=elevation10m.tci d8cut=500 memory=800 \
223 stats=elevation10mstats.txt
224
226 1 The TerraFlow project at Duke University
227 2 I/O-efficient algorithms for problems on grid-based terrains.
229 Lars Arge, Laura Toma, and Jeffrey S. Vitter. In Proc. Workshop
230 on Algorithm Engineering and Experimentation, 2000. To appear in
231 Journal of Experimental Algorithms.
232 3 Flow computation on massive grids. Lars Arge, Jeffrey S. Chase,
234 Patrick N. Halpin, Laura Toma, Jeffrey S. Vitter, Dean Urban and
235 Rajiv Wickremesinghe. In Proc. ACM Symposium on Advances in Geo‐
236 graphic Information Systems, 2001.
237 4 Flow computation on massive grid terrains. Lars Arge, Jeffrey
239 S. Chase, Patrick N. Halpin, Laura Toma, Jeffrey S. Vitter, Dean
240 Urban and Rajiv Wickremesinghe. In GeoInformatica, Interna‐
241 tional Journal on Advances of Computer Science for Geographic
242 Information Systems, 7(4):283-313, December 2003.
243
245 r.flow, r.basins.fill, r.drain, r.topidx, r.topmodel, r.water.outlet,
246 r.watershed
247
249 Original version of program: The TerraFlow
250 project, 1999, Duke University.
251 Lars Arge, Jeff Chase, Pat Halpin, Laura Toma, Dean Urban, Jeff
252 Vitter, Rajiv Wickremesinghe.
253 Porting to GRASS GIS, 2002:
255 Lars Arge, Helena Mitasova, Laura Toma.
256 Contact: Laura Toma
258
260 Available at: r.terraflow source code (history)
261 Accessed: Saturday Oct 28 18:18:19 2023
263 Main index | Raster index | Topics index | Keywords index | Graphical
265 index | Full index
266 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
268GRASS 8.3.1 r.terraflow(1)