1r.terraflow(1) Grass User's Manual r.terraflow(1)
2
6 r.terraflow - Flow computation for massive grids (Float version).
7
10 r.terraflow
11 r.terraflow help
12 r.terraflow [-sq] elev=string filled=string direction=string swater‐
13 shed=string accumulation=string tci=string [d8cut=float] [mem‐
14 ory=integer] [STREAM_DIR=string] [stats=string] [--overwrite]
15 [--verbose] [--quiet]
16 Flags:
18 -s
19 SFD (D8) flow (default is MFD)
20 -q
22 Quiet
23 --overwrite
25 Allow output files to overwrite existing files
26 --verbose
28 Verbose module output
29 --quiet
31 Quiet module output
32 Parameters:
34 elev=string
35 Input elevation grid
36 filled=string
38 Output (filled) elevation grid
39 direction=string
41 Output direction grid
42 swatershed=string
44 Output sink-watershed grid
45 accumulation=string
47 Output accumulation grid
48 tci=string
50 Output tci grid
51 d8cut=float
53 If flow accumulation is larger than this value it is routed using
54 SFD (D8) direction
55 (meaningfull only for MFD flow)
56 Default: infinity
57 memory=integer
59 Main memory size (in MB)
60 Default: 300
61 STREAM_DIR=string
63 Location of intermediate STREAMs
64 Default: /var/tmp
65 stats=string
67 Stats file
68 Default: stats.out
69
71 direction, flow accumulation and other basic topographic terrain
72 indices from a raster digital elevation model (DEM).
73 (GRASS Raster Program)
75
77 r.terraflow
78 r.terraflow help
79 r.terraflow [ -sq ] elev=name filled=name direction=name swater‐
80 shed=name accumulation=name tci=name [d8cut=value] [memory=value]
81 [STREAM_DIR=name] [stats=name]
82
84 r.terraflow takes as input a raster digital elevation model (DEM) and
85 computes the flow direction raster and the flow accumulation raster, as
86 well as the flooded elevation raster, sink-watershed raster (partition
87 into watersheds around sinks) and tci (topographic convergence index)
88 raster.
89 r.terraflow computes these rasters using well-known approaches, with
91 the difference that its emphasis is on the computational complexity of
92 the algorithms, rather than on modeling realistic flow. r.terraflow
93 emerged from the necessity of having scalable software able to process
94 efficiently very large terrains. It is based on theoretically optimal
95 algorithms developed in the framework of I/O-efficient algorithms.
96 r.terraflow was designed and optimized especially for massive grids and
97 is able to process terrains which were impractical with similar func‐
98 tions existing in other GIS systems.
99 Flow directions are computed using either the MFD (Multiple Flow Direc‐
101 tion) model or the SFD (Single Flow Direction, or D8) model, illus‐
102 trated below. Both methods compute downslope flow directions by
103 inspecting the 3-by-3 window around the current cell. The SFD method
104 assigns a unique flow direction towards the steepest downslope neigh‐
105 bor. The MFD method assigns multiple flow directions towards all downs‐
106 lope neighbors.
107 Flow direction to steepest
109 downslope neighbor (SFD). Flow direction to all
110 downslope neighbors (MFD).
111 The SFD and the MFD method cannot compute flow directions for cells
113 which have the same height as all their neighbors (flat areas) or cells
114 which do not have downslope neighbors (one-cell pits).
115 On plateaus (flat areas that spill out) r.terraflow
117 routes flow so that globally the flow goes towards the
118 spill cells of the plateaus.
119 On sinks (flat areas that do not spill out, including
121 one-cell pits) r.terraflow assigns flow by flooding the
122 terrain until all the sinks are filled and assigning flow
123 directions on the filled terrain.
124 In order to flood the terrain, r.terraflow identifies all sinks and
126 partitions the terrain into sink-watersheds (a sink-watershed contains
127 all the cells that flow into that sink), builds a graph representing
128 the adjacency information of the sink-watersheds, and uses this sink-
129 watershed graph to merge watersheds into each other along their lowest
130 common boundary until all watersheds have a flow path outside the ter‐
131 rain. Flooding produces a sink-less terrain in which every cell has a
132 downslope flow path leading outside the terrain and therefore every
133 cell in the terrain can be assigned SFD/MFD flow directions as above.
134 Once flow directions are computed for every cell in the terrain, r.ter‐
136 raflow computes flow accumulation by routing water using the flow
137 directions and keeping track of how much water flows through each cell.
138 r.terraflow also computes the tci raster (topographic convergence
139 index, defined as the logarithm of the ratio of flow accumulation and
140 local slope).
141 For more details on the algorithms see [1,2,3].
143
145 The program will run non-interactively if the user specifies program
146 arguments and flag settings on the command line using the following
147 form:
148 r.terraflow [ -sq ] elev=name filled=name direction=name swater‐
150 shed=name accumulation=name tci=name [d8cut=value] [memory=value]
151 [STREAM_DIR=name] [stats=name]
152 Alternatively, the user can simply type r.terraflow on the command line
154 and the program will ask for parameter values and flag settings inter‐
155 actively, using the standard GRASS parser interface.
156 Flags:
158 -s
159 Use SFD (D8) flow. By default MFD flow is used.
160 -q
162 Run quietly (do not display status messages). By default
163 Parameters:
165 elev=name
166 Input elevation raster. Required.
167 filled=name
169 Output filled (flooded) elevation raster. Required.
170 direction =name
172 Output flow direction raster. Required.
173 swatershed =name
175 Output sink-watershed raster. Required.
176 accumulation =name
178 Output flow accumulation raster. Required.
179 tci =name
181 Output topographic convergence index (tci) raster. Required.
182 [d8cut =value]
184 If flow accumulation of a cell is larger than this value, then
185 the flow of this cell is routed to its neighbors using the SFD
186 (D8) model. This option affects only the flow accumulation
187 raster and is meaningfull only for MFD flow (i.e. if the -s flag
188 is not used); If this option is used for SFD flow it is ignored.
189 The default value of d8cut is infinity.
190 [memory =value (in MB)]
192 The main memory size (in MB) to be used by r.terraflow. In
193 practice value should be an underestimate of the amount of
194 available (free) main memory on the machine. r.terraflow will
195 use at all times at most this much memory, and the virtual mem‐
196 ory system will never be in use. The default value is 300 MB.
197 [STREAM_DIR =path name]
199 Location of the intermediate files generated by r.terraflow.
200 The default location is /var/tmp.
201 [stats =name]
203 The name of the file that contains the statistics (stats) of
204 the run. The default name is stats.out (in the current direc‐
205 tory).
206 Examples
208 r.terraflow elev=spearfish filled=spearfish-filled
209 dir=spearfish-mfdir swatershed=spearfish-watershed accu‐
210 mulation=spearfish-accu tci=spearfish-tci
211 r.terraflow elev=spearfish filled=spearfish-filled
213 dir=spearfish-mfdir swatershed=spearfish-watershed accu‐
214 mulation=spearfish-accu tci=spearfish-tci d8cut=500 mem‐
215 ory=800 STREAM-DIR=/var/tmp/ stats=spearfish-stats.txt
216
218 One of the techniques used by r.terraflow is the space-time trade-off.
219 In particular, in order to avoid searches, which are I/O-expensive,
220 r.terraflow computes and works with an augmented elevation raster in
221 which each cell stores relevant information about its 8 neighbors, in
222 total up to 80B per cell. As a result r.terraflow works with interme‐
223 diate temporary files that may be up to 80N bytes, where N is the num‐
224 ber of cells (rows x columns) in the elevation raster (more precisely,
225 80K bytes, where K is the number of valid (not nodata) cells in the
226 input elevation raster). All this intermediate temporary files are
227 stored in the path specified by STREAM_DIR. Note: STREAM_DIR must con‐
228 tain enough free disk space in order to store up to 2 x 80N bytes.
229 The internal type used by r.terraflow to store elevations can be
231 defined at compile-time. By default, r.terraflow is compiled to store
232 elevations internally as floats. A version which is compiled to store
233 elevations internally as shorts is available as r.terraflow.short.
234 Other versions can be created by the user if needed.
235 r.terraflow.short uses less space (up to 60B per cell, up to 60N inter‐
237 mediate file) and therefore is more space and time efficient. r.ter‐
238 raflow is intended for use with floating point raster data (FCELL), and
239 r.terraflow.short with integer raster data (CELL) in which the maximum
240 elevation does not exceed the value of a short SHRT_MAX=32767 (this is
241 not a constraint for any terrain data of the Earth, if elevation is
242 stored in meters).
243 Both r.terraflow and r.terraflow.short work with input elevation
245 rasters which can be either integer, floating point or double (CELL,
246 FCELL, DCELL). If the input raster contains a value that exceeds the
247 allowed internal range (short for r.terraflow.short, float for r.ter‐
248 raflow), the program exits with a warning message. Otherwise, if all
249 values in the input elevation raster are in range, they will be con‐
250 verted (truncated) to the internal elevation type (short for r.ter‐
251 raflow.short, float for r.terraflow). In this case precision may be
252 lost and artificial flat areas may be created.
253 For instance, if r.terraflow.short is used with floating point raster
255 data (FCELL or DCELL), the values of the elevation will be truncated as
256 shorts. This may create artificial flat areas, and the outpus of r.ter‐
257 raflow.short may be less realistic than those of r.terraflow on float‐
258 ing point raster data. The outputs of r.terraflow.short and r.ter‐
259 raflow are identical on integer raster data (CELL).
260
262 The <a href="http://www.cs.duke.edu/geo*/terraflow/">Ter‐
263 raFlow project at Duke University
264 r.flow, r.basins.fill, r.drain, r.topidx, r.topmodel,
266 r.water.outlet, r.watershed
267
269 Original version of program: The <a
270 href="http://www.cs.duke.edu/geo*/terraflow/">TerraFlow project,
271 1999, Duke University.
272 Lars Arge, Jeff Chase, Pat Halpin, Laura Toma, Dean Urban, Jeff
273 Vitter, Rajiv Wickremesinghe.
274 Porting for GRASS, 2002:
276 Lars Arge, Helena Mitasova, Laura Toma.
277 Contact: Laura Toma
279
281 1 <A NAME="arge:drainage" HREF="http://www.cs.duke.edu/geo*/ter‐
282 raflow/papers/alenex00_drainage.ps.gz"> I/O-efficient algorithms
283 for problems on grid-based terrains. Lars Arge, Laura Toma, and
284 Jeffrey S. Vitter. In Proc. Workshop on Algorithm Engineering
285 and Experimentation, 2000. To appear in Journal of Experimental
286 Algorithms.
287 2 <A NAME="terraflow:acmgis01"
289 HREF="http://www.cs.duke.edu/geo*/terraflow/papers/acmgis01_ter‐
290 raflow.pdf"> Flow computation on massive grids. Lars Arge, Jef‐
291 frey S. Chase, Patrick N. Halpin, Laura Toma, Jeffrey S. Vitter,
292 Dean Urban and Rajiv Wickremesinghe. In Proc. ACM Symposium on
293 Advances in Geographic Information Systems, 2001.
294 3 <A NAME="terraflow:geoinformatica"
296 HREF="http://www.cs.duke.edu/geo*/terraflow/papers/journal_ter‐
297 raflow.pdf"> Flow computation on massive grid terrains. Lars
298 Arge, Jeffrey S. Chase, Patrick N. Halpin, Laura Toma, Jeffrey
299 S. Vitter, Dean Urban and Rajiv Wickremesinghe. To appear in
300 GeoInformatica, International Journal on Advances of Computer
301 Science for Geographic Information Systems.
302 Last changed: $Date: 2006-09-22 16:57:14 +0200 (Fri, 22 Sep 2006) $
304GRASS 6.3.0 r.terraflow(1)