1r.watershed(1) Grass User's Manual r.watershed(1)
2
6 r.watershed - Watershed basin analysis program.
7
9 raster
10
12 r.watershed
13 r.watershed help
14 r.watershed [-m4] elevation=name [depression=string] [flow=string]
15 [disturbed.land=string] [blocking=string] [threshold=integer]
16 [max.slope.length=float] [accumulation=string] [drainage=string]
17 [basin=string] [stream=string] [half.basin=string] [vis‐
18 ual=string] [length.slope=string] [slope.steepness=string]
19 [--overwrite] [--verbose] [--quiet]
20 Flags:
22 -m
23 Enable disk swap memory option: Operation is slow
24 -4
26 Allow only horizontal and vertical flow of water
27 --overwrite
29 Allow output files to overwrite existing files
30 --verbose
32 Verbose module output
33 --quiet
35 Quiet module output
36 Parameters:
38 elevation=name
39 Input map: elevation on which entire analysis is based
40 depression=string
42 Input map: locations of real depressions
43 flow=string
45 Input map: amount of overland flow per cell
46 disturbed.land=string
48 Input map or value: percent of disturbed land, for USLE
49 blocking=string
51 Input map: terrain blocking overland surface flow, for USLE
52 threshold=integer
54 Input value: minimum size of exterior watershed basin
55 max.slope.length=float
57 Input value: maximum length of surface flow, for USLE
58 accumulation=string
60 Output map: number of cells that drain through each cell
61 drainage=string
63 Output map: drainage direction
64 basin=string
66 Output map: unique label for each watershed basin
67 stream=string
69 Output map: stream segments
70 half.basin=string
72 Output map: each half-basin is given a unique value
73 visual=string
75 Output map: useful for visual display of results
76 length.slope=string
78 Output map: slope length and steepness (LS) factor for USLE
79 slope.steepness=string
81 Output map: slope steepness (S) factor for USLE
82
84 r.watershed generates a set of maps indicating: 1) the location of
85 watershed basins, and 2) the LS and S factors of the Revised Universal
86 Soil Loss Equation (RUSLE).
87
89 -m
90 Without this flag set, the entire analysis is run in memory
91 maintained by the operating system. This can be limiting, but
92 is relatively fast. Setting the flag causes the program to man‐
93 age memory on disk which allows larger maps to be processes but
94 is considerably slower.
95 -4
97 Allow only horizontal and vertical flow of water. Stream and
98 slope lengths are approximately the same as outputs from default
99 surface flow (allows horizontal, vertical, and diagonal flow of
100 water). This flag will also make the drainage basins look more
101 homogeneous.
102 elevation
104 Input map: Elevation on which entire analysis is based.
105 depression
107 Input map: Map layer of actual depressions or sinkholes in the
108 landscape that are large enough to slow and store surface runoff
109 from a storm event. Any non-zero values indicate depressions.
110 flow
112 Input map: amount of overland flow per cell. This map indicates
113 the amount of overland flow units that each cell will contribute
114 to the watershed basin model. Overland flow units represent the
115 amount of overland flow each cell contributes to surface flow.
116 If omitted, a value of one (1) is assumed. The algorithm is D8
117 flow accumulation.
118 disturbed.land
120 Raster map input layer or value containing the percent of dis‐
121 turbed land (i.e., croplands, and construction sites) where the
122 raster or input value of 17 equals 17%. If no map or value is
123 given, r.watershed assumes no disturbed land. This input is
124 used for the RUSLE calculations.
125 blocking
127 Input map: terrain that will block overland surface flow. Ter‐
128 rain that will block overland surface flow and restart the slope
129 length for the RUSLE. Any non-zero values indicate blocking
130 terrain.
131 threshold
133 The minimum size of an exterior watershed basin in cells, if no
134 flow map is input, or overland flow units when a flow map is
135 given. Warning: low threshold values will dramactically
136 increase run time and generate difficult too read basin and
137 half.basin results. This parameter also controls the level of
138 detail in the stream segments map.
139 max.slope.length
141 Input value indicating the maximum length of overland surface
142 flow in meters. If overland flow travels greater than the maxi‐
143 mum length, the program assumes the maximum length (it assumes
144 that landscape characteristics not discernible in the digital
145 elevation model exist that maximize the slope length). This
146 input is used for the RUSLE calculations and is a sensitive
147 parameter.
148 accumulation
150 Output map: The absolute value of each cell in this output map
151 layer is the amount of overland flow that traverses the cell.
152 This value will be the number of upland cells plus one if no
153 overland flow map is given. If the overland flow map is given,
154 the value will be in overland flow units. Negative numbers
155 indicate that those cells possibly have surface runoff from out‐
156 side of the current geographic region. Thus, any cells with neg‐
157 ative values cannot have their surface runoff and sedimentation
158 yields calculated accurately.
159 drainage
161 Output map: drainage direction. Provides the "aspect" for each
162 cell. Multiplying positive values by 45 will give the direction
163 in degrees that the surface runoff will travel from that cell.
164 The value -1 indicates that the cell is a depression area
165 (defined by the depression input map). Other negative values
166 indicate that surface runoff is leaving the boundaries of the
167 current geographic region. The absolute value of these negative
168 cells indicates the direction of flow.
169 basin
171 Output map: Unique label for each watershed basin. Each basin
172 will be given a unique positive even integer. Areas along edges
173 may not be large enough to create an exterior watershed basin.
174 0 values indicate that the cell is not part of a complete water‐
175 shed basin in the current geographic region.
176 stream
178 Output map: stream segments. Values correspond to the watershed
179 basin values.
180 half.basin
182 Output map: each half-basin is given a unique value. Watershed
183 basins are divided into left and right sides. The right-hand
184 side cell of the watershed basin (looking upstream) are given
185 even values corresponding to the values in basin. The left-hand
186 side cells of the watershed basin are given odd values which are
187 one less than the value of the watershed basin.
188 visual
190 Output map: useful for visual display of results. Surface
191 runoff accumulation with the values modified to provide for easy
192 display. All negative accumulation values are changed to zero.
193 All positive values above the basin threshold are given the
194 value of the threshold parameter.
195 length.slope
197 Output map: slope length and steepness (LS) factor. Contains
198 the LS factor for the Revised Universal Soil Loss Equation.
199 Equations taken from Revised Universal Soil Loss Equation for
200 Western Rangelands (Weltz et al. 1987). Since the LS factor is
201 a small number, it is multiplied by 100 for the GRASS output
202 map.
203 slope.steepness
205 Output map: slope steepness (S) factor for RUSLE. Contains the
206 revised S factor for the Universal Soil Loss Equation. Equa‐
207 tions taken from article entitled Revised Slope Steepness Factor
208 for the Universal Soil Loss Equation (McCool et al. 1987).
209 Since the S factor is a small number (usually less than one), it
210 is multiplied by 100 for the GRASS output map layer.
211
213 r.watershed uses an algorithm designed to minimize the impact of DEM
214 data errors. This algorithm works slower than r.terraflow but provides
215 more accurate results in areas of low slope as well as DEMs constructed
216 with techniques that mistake canopy tops as the ground elevation. Kin‐
217 ner et al. (2005), for example, used SRTM and IFSAR DEMs to compare
218 r.watershed against r.terraflow results in Panama. r.terraflow was
219 unable to replicate stream locations in the larger valleys while
220 r.watershed performed much better. Thus, if forest canopy exists in
221 valleys, SRTM, IFSAR, and similar data products will cause major errors
222 in r.terraflow stream output. Under similar conditions, r.watershed
223 will generate better stream and half.basin results. If watershed
224 divides contain flat to low slope, r.watershed will generate better
225 basin results than r.terraflow. (r.terraflow uses the same type of
226 algorithm as ESRI's ArcGIS watershed software which fails under these
227 conditions.) Also, if watershed divides contain forest canopy mixed
228 with uncanopied areas using SRTM, IFSAR, and similar data products,
229 r.watershed will generate better basin results than r.terraflow.
230 There are two versions of this program: ram and seg. Which is version
232 is run depends on whether the -m flag is set.
233 The ram version uses virtual memory managed by the operating system to
234 store all the data structures and is faster than the seg version; seg
235 uses the GRASS segmentation library which manages data in disk files.
236 Thus seg uses much less system memory (RAM) allowing other processes to
237 operate on the same CPU, even when the current geographic region is
238 huge.
239 Due to memory requirements of both programs, it is quite easy to run
240 out of memory when working with huge map regions. If the ram version
241 runs out of memory and the resolution size of the current geographic
242 region cannot be increased, either more memory needs to be added to
243 the computer, or the swap space size needs to be increased. If seg
244 runs out of memory, additional disk space needs to be freed up for the
245 program to run.
246 Both versions use the AT least-cost search algorithm to determine the
248 flow of water over the landscape (see SEE ALSO section). The algorithm
249 produces results similar to those obtained when running r.cost and
250 r.drain on every cell on the map.
251 In many situations, the elevation data will be too finely detailed for
253 the amount of time or memory available. Running r.watershed may
254 require use of a coarser resolution. To make the results more closely
255 resemble the finer terrain data, create a map layer containing the low‐
256 est elevation values at the coarser resolution. This is done by: 1)
257 Setting the current geographic region equal to the elevation map layer
258 with g.region, and 2) Use the r.neighbors or r.resamp.stats command to
259 find the lowest value for an area equal in size to the desired resolu‐
260 tion. For example, if the resolution of the elevation data is 30
261 meters and the resolution of the geographic region for r.watershed will
262 be 90 meters: use the minimum function for a 3 by 3 neighborhood.
263 After changing to the resolution at which r.watershed will be run,
264 r.watershed should be run using the values from the neighborhood output
265 map layer that represents the minimum elevation within the region of
266 the coarser cell.
267 The minimum size of drainage basins, defined by the threshold parame‐
269 ter, is only relevant for those watersheds with a single stream having
270 at least the threshold of cells flowing into it. (These watersheds are
271 called exterior basins.) Interior drainage basins contain stream seg‐
272 ments below multiple tributaries. Interior drainage basins can be of
273 any size because the length of an interior stream segment is determined
274 by the distance between the tributaries flowing into it.
275 The r.watershed program does not require the user to have the current
277 geographic region filled with elevation values. Areas without eleva‐
278 tion data MUST be masked out, by creating a raster map (or raster
279 reclassification) named MASK. Areas masked out will be treated as if
280 they are off the edge of the region. MASKs will reduce the memory nec‐
281 essary to run the program. Masking out unimportant areas can signifi‐
282 cantly reduce processing time if the watersheds of interest occupy a
283 small percentage of the overall area.
284 Zero data values will be treated as elevation data (not no_data).
286 To isolate an individual river network using the output of this module,
288 a number of approaches may be considered. Use a resample of the basins
289 catchment raster map as a MASK.
290 The equivalent vector map method is similar using v.select or v.over‐
291 lay. Use the r.cost module with a point in the river as a starting
292 point. Use the v.net.iso module with a node in the river as a starting
293 point.
294 To create river mile segmentation from a vectorized streams map, try
296 the v.net.iso or v.lrs.segment modules.
297
299 These examples use the Spearfish sample dataset.
300 Convert r.watershed streams map output to a vector layer.
302 If you want a detailed stream network, set the threshold option small
304 to create lots of catchment basins, as only one stream is presented per
305 catchment. The r.to.vect -v flag preserves the catchment ID as the vec‐
306 tor category number.
307 r.watershed elev=elevation.dem stream=rwater.stream
308 r.to.vect -v in=rwater.stream out=rwater_stream
309 Set a nice color table for the accumulation map:
312 MAP=rwater.accum
313 r.watershed elev=elevation.dem accum=$MAP
314 eval `r.univar -g "$MAP"`
315 stddev_x_2=`echo $stddev | awk '{print $1 * 2}'`
316 stddev_div_2=`echo $stddev | awk '{print $1 / 2}'`
317 r.colors $MAP col=rules << EOF
318 0% red
319 -$stddev_x_2 red
320 -$stddev yellow
321 -$stddev_div_2 cyan
322 -$mean_of_abs blue
323 0 white
324 $mean_of_abs blue
325 $stddev_div_2 cyan
326 $stddev yellow
327 $stddev_x_2 red
328 100% red
329 EOF
330 Create a more detailed stream map using the accumulation map and con‐
333 vert it to a vector output map. The accumulation cut-off, and therefore
334 fractal dimension, is arbitrary; in this example we use the map's mean
335 number of upstream catchment cells (calculated in the above example by
336 r.univar) as the cut-off value.
337 r.watershed elev=elevation.dem accum=rwater.accum
338 r.mapcalc 'MASK = if(!isnull(elevation.dem))'
339 r.mapcalc "rwater.course = \
340 if( abs(rwater.accum) > $mean_of_abs, \
341 abs(rwater.accum), \
342 null() )"
343 r.colors -g rwater.course col=bcyr
344 g.remove MASK
345 # Thinning is required before converting raster lines to vector
346 r.thin in=rwater.course out=rwater.course.Thin
347 r.colors -gn rwater.course.Thin color=grey
348 r.to.vect in=rwater.course.Thin out=rwater_course feature=line
349 v.db.dropcol map=rwater_course column=label
350 Create watershed basins map and convert to a vector polygon map
353 r.watershed elev=elevation.dem basin=rwater.basin thresh=15000
354 r.to.vect -s in=rwater.basin out=rwater_basins feature=area
355 v.db.dropcol map=rwater_basins column=label
356 v.db.renamecol map=rwater_basins column=value,catchment
357 Display output in a nice way
360 r.shaded.relief map=elevation.dem
361 d.shadedmap rel=elevation.dem.shade drape=rwater.basin bright=40
362 d.vect rwater_course color=orange
363
366 Ehlschlaeger, C. (1989). Using the AT Search Algorithm to Develop
367 Hydrologic Models from Digital Elevation Data, Proceedings of Interna‐
368 tional Geographic Information Systems (IGIS) Symposium '89, pp 275-281
369 (Baltimore, MD, 18-19 March 1989).
370 URL: http://faculty.wiu.edu/CR-Ehlschlaeger2/older/IGIS/paper.html
371 Kinner D., H. Mitasova, R. Harmon, L. Toma, R., Stallard. (2005). GIS-
373 based Stream Network Analysis for The Chagres River Basin, Republic of
374 Panama. The Rio Chagres: A Multidisciplinary Profile of a Tropical
375 Watershed, R. Harmon (Ed.), Springer/Kluwer, p.83-95.
376 URL: http://skagit.meas.ncsu.edu/~helena/measwork/panama/panama.html
377 McCool et al. (1987). Revised Slope Steepness Factor for the Universal
379 Soil Loss Equation, Transactions of the ASAE Vol 30(5).
380 Weltz M. A., K. G. Renard, J. R. Simanton (1987). Revised Universal
382 Soil Loss Equation for Western Rangelands, U.S.A./Mexico Symposium of
383 Strategies for Classification and Management of Native Vegetation for
384 Food Production In Arid Zones (Tucson, AZ, 12-16 Oct. 1987).
385
387 g.region, r.cost, r.drain, r.flow, r.neighbors, r.param.scale,
388 r.resamp.interp, r.terraflow, r.topidx, r.water.outlet
389
391 Charles Ehlschlaeger, U.S. Army Construction Engineering Research Labo‐
392 ratory
393 Last changed: $Date: 2008-02-23 19:20:42 +0100 (Sat, 23 Feb 2008) $
395 Full index
397 © 2003-2008 GRASS Development Team
399GRASS 6.3.0 r.watershed(1)