1r.drain(1) Grass User's Manual r.drain(1)
2
6 r.drain - Traces a flow through an elevation model or cost surface on
7 a raster map.
8
10 raster, hydrology, cost surface
11
13 r.drain
14 r.drain --help
15 r.drain [-cand] input=name [direction=name] output=name [drain=name]
16 [start_coordinates=east,north] [start_points=name[,name,...]]
17 [--overwrite] [--help] [--verbose] [--quiet] [--ui]
18 Flags:
20 -c
21 Copy input cell values on output
22 -a
24 Accumulate input values along the path
25 -n
27 Count cell numbers along the path
28 -d
30 The input raster map is a cost surface (direction surface must also
31 be specified)
32 --overwrite
34 Allow output files to overwrite existing files
35 --help
37 Print usage summary
38 --verbose
40 Verbose module output
41 --quiet
43 Quiet module output
44 --ui
46 Force launching GUI dialog
47 Parameters:
49 input=name [required]
50 Name of input elevation or cost surface raster map
51 direction=name
53 Name of input movement direction map associated with the cost sur‐
54 face
55 Direction in degrees CCW from east
56 output=name [required]
58 Name for output raster map
59 drain=name
61 Name for output drain vector map
62 Recommended for cost surface made using knight’s move
63 start_coordinates=east,north
65 Coordinates of starting point(s) (E,N)
66 start_points=name[,name,...]
68 Name of starting vector points map(s)
69
71 r.drain traces a flow through a least-cost path in an elevation model
72 or cost surface. For cost surfaces, a movement direction map must be
73 specified with the direction option and the -d flag to trace a flow
74 path following the given directions. Such a movement direction map can
75 be generated with r.walk, r.cost, r.slope.aspect or r.watershed pro‐
76 vided that the direction is in degrees, measured counterclockwise from
77 east.
78 The output raster map will show one or more least-cost paths between
80 each user-provided location(s) and the minima (low category values) in
81 the raster input map. If the -d flag is used the output least-cost
82 paths will be found using the direction raster map. By default, the
83 output will be an integer CELL map with category 1 along the least cost
84 path, and null cells elsewhere.
85 With the -c (copy) flag, the input raster map cell values are copied
87 verbatim along the path. With the -a (accumulate) flag, the accumulated
88 cell value from the starting point up to the current cell is written on
89 output. With either the -c or the -a flags, the output map is created
90 with the same cell type as the input raster map (integer, float or dou‐
91 ble). With the -n (number) flag, the cells are numbered consecutively
92 from the starting point to the final point. The -c, -a, and -n flags
93 are mutually incompatible.
94 For an elevation surface, the path is calculated by choosing the
96 steeper "slope" between adjacent cells. The slope calculation accu‐
97 rately accounts for the variable scale in lat-lon projections. For a
98 cost surface, the path is calculated by following the movement direc‐
99 tion surface back to the start point given in r.walk or r.cost. The
100 path search stops as soon as a region border or a neighboring NULL cell
101 is encountered, because in these cases the direction can not be deter‐
102 mined (the path could continue outside the current region).
103 The start_coordinates parameter consists of map E and N grid coordi‐
105 nates of a starting point. Each x,y pair is the easting and northing
106 (respectively) of a starting point from which a least-cost corridor
107 will be developed. The start_points parameter can take multiple vector
108 maps containing additional starting points. Up to 1024 starting points
109 can be input from a combination of the start_coordinates and
110 start_points parameters.
111 Explanation of output values
113 Consider the following example:
114 Input: Output:
115 ELEVATION SURFACE LEAST COST PATH
116 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
117 . 19. 20. 18. 19. 16. 15. 15. . . . . . . . .
118 . . --- . . . . . . . . . . . . . . . . . . . . . . . . .
119 . 20| 19| 17. 16. 17. 16. 16. . . 1 . 1 . 1 . . . .
120 . . --- . . . . . . . . . . . . . . . . . . . . . . . . .
121 . 18. 18. 24. 18. 15. 12. 11. . . . . . 1 . . .
122 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
123 . 22. 16. 16. 18. 10. 10. 10. . . . . . 1 . . .
124 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
125 . 17. 15. 15. 15. 10. 8 . 8 . . . . . . . 1 . .
126 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
127 . 24. 16. 8 . 7 . 8 . 0 . 12. . . . . . . 1 . .
128 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
129 . 17. 9 . 8 . 7 . 8 . 6 . 12. . . . . . . . .
130 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
131 The user-provided starting location in the above example is the boxed
133 19 in the left-hand map. The path in the output shows the least-cost
134 corridor for moving from the starting box to the lowest (smallest) pos‐
135 sible point. This is the path a raindrop would take in this landscape.
136 With the -c (copy) flag, you get the following result:
138 Input: Output:
139 ELEVATION SURFACE LEAST COST PATH
140 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
141 . 19. 20. 18. 19. 16. 15. 15. . . . . . . . .
142 . . --- . . . . . . . . . . . . . . . . . . . . . . . . .
143 . 20| 19| 17. 16. 17. 16. 16. . . 19. 17. 16. . . .
144 . . --- . . . . . . . . . . . . . . . . . . . . . . . . .
145 . 18. 18. 24. 18. 15. 12. 11. . . . . . 15. . .
146 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
147 . 22. 16. 16. 18. 10. 10. 10. . . . . . 10. . .
148 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
149 . 17. 15. 15. 15. 10. 8 . 8 . . . . . . . 8 . .
150 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
151 . 24. 16. 8 . 7 . 8 . 0 .12 . . . . . . . 0 . .
152 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
153 . 17. 9 . 8 . 7 . 8 . 6 .12 . . . . . . . . .
154 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
155 Note that the last 0 will not be put in the null values map.
156 With the -a (accumulate) flag, you get the following result:
158 Input: Output:
159 ELEVATION SURFACE LEAST COST PATH
160 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
161 . 19. 20. 18. 19. 16. 15. 15. . . . . . . . .
162 . . --- . . . . . . . . . . . . . . . . . . . . . . . . .
163 . 20| 19| 17. 16. 17. 16. 16. . . 19. 36. 52. . . .
164 . . --- . . . . . . . . . . . . . . . . . . . . . . . . .
165 . 18. 18. 24. 18. 15. 12. 11. . . . . . 67. . .
166 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
167 . 22. 16. 16. 18. 10. 10. 10. . . . . . 77. . .
168 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
169 . 17. 15. 15. 15. 10. 8 . 8 . . . . . . . 85. .
170 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
171 . 24. 16. 8 . 7 . 8 . 0 .12 . . . . . . . 85. .
172 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
173 . 17. 9 . 8 . 7 . 8 . 6 .12 . . . . . . . . .
174 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
175 With the -n (number) flag, you get the following result:
177 Input: Output:
178 ELEVATION SURFACE LEAST COST PATH
179 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
180 . 19. 20. 18. 19. 16. 15. 15. . . . . . . . .
181 . . --- . . . . . . . . . . . . . . . . . . . . . . . . .
182 . 20| 19| 17. 16. 17. 16. 16. . . 1 . 2 . 3 . . . .
183 . . --- . . . . . . . . . . . . . . . . . . . . . . . . .
184 . 18. 18. 24. 18. 15. 12. 11. . . . . . 4 . . .
185 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
186 . 22. 16. 16. 18. 10. 10. 10. . . . . . 5 . . .
187 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
188 . 17. 15. 15. 15. 10. 8 . 8 . . . . . . . 6 . .
189 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
190 . 24. 16. 8 . 7 . 8 . 0 .12 . . . . . . . 7 . .
191 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
192 . 17. 9 . 8 . 7 . 8 . 6 .12 . . . . . . . . .
193 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
194 With the -d (direction) flag, the direction raster is used for the
195 input, rather than the elevation surface. The output is then created
196 according to one of the -can flags.
197 The directions are recorded as degrees CCW from East:
198 112.5 67.5 i.e. a cell with the value 135
199 157.5 135 90 45 22.5 means the next cell is to the North-West
200 180 x 0
201 202.5 225 270 315 337.5
202 247.5 292.5
203
205 If no direction input map is given, r.drain currently finds only the
206 lowest point (the cell having the smallest category value) in the input
207 file that can be reached through directly adjacent cells that are less
208 than or equal in value to the cell reached immediately prior to it;
209 therefore, it will not necessarily reach the lowest point in the input
210 file. It currently finds pits in the data, rather than the lowest point
211 in the entire input map. The r.fill.dir, r.terraflow, and r.basins.fill
212 modules can be used to fill in subbasins prior to processing with
213 r.drain.
214 r.drain will not give sane results at the region boundary. On outer
216 rows and columns bordering the edge of the region, the flow direction
217 is always directly out of the map. In this case, the user could try
218 adjusting the region extents slightly with g.region to allow additional
219 outlet paths for r.drain.
220
222 Path to the lowest point
223 In this example we compute drainage paths from two given points follow‐
224 ing decreasing elevation values to the lowest point. We are using the
225 full North Carolina sample dataset. First we create the two points
226 from a text file using v.in.ascii module (here the text file is CSV and
227 we are using unix here-file syntax with EOF, in GUI just enter the val‐
228 ues directly for the parameter input):
229 v.in.ascii input=- output=start format=point separator=comma <<EOF
230 638667.15686275,220610.29411765
231 638610.78431373,220223.03921569
232 EOF
233 Now we compute the drainage path:
234 r.drain input=elev_lid792_1m output=drain_path drain=drain start_points=start
235 Before we visualize the result, we set a color table for the elevation
236 we are using and we create a shaded relief map:
237 r.colors map=elev_lid792_1m color=elevation
238 r.relief input=elev_lid792_1m output=relief
239 Finally we visualize all the input and output data:
240 d.shade shade=relief color=elev_lid792_1m
241 d.vect map=drain_path color=0:0:61 width=4 legend_label="drainage paths"
242 d.vect map=start color=none fill_color=224:0:0 icon=basic/circle size=15 legend_label=origins
243 d.legend.vect -b
244 Figure: Drainage paths from two points flowing into the points with
245 lowest values
246 Path following directions
248 To continue flow even after it hits a depression, we need to supply a
249 direction raster map which will tell the r.drain module how to continue
250 from the depression. To get these directions, we use the r.watershed
251 module:
252 r.watershed elevation=elev_lid792_1m accumulation=accum drainage=drain_dir
253 The directions are categorical and we convert them to degrees using
254 raster algebra:
255 r.mapcalc "drain_deg = if(drain_dir != 0, 45. * abs(drain_dir), null())"
256 Together with directions, we need to provide the r.drain module with
257 cost values. We don’t have any cost to assign to specific cells, so we
258 create a constant surface:
259 r.mapcalc "const1 = 1"
260 Now we are ready to compute the drainage paths. We are using the two
261 points from the previous example.
262 r.drain -d input=const1 direction=drain_deg output=drain_path_2 drain=drain_2 start_points=start
263 We visualize the result in the same way as in the previous example.
264 Figure: Drainage paths from two points where directions from r.water‐
265 shed were used
266
268 Sometimes, when the differences among integer cell category values in
269 the r.cost cumulative cost surface output are small, this cumulative
270 cost output cannot accurately be used as input to r.drain (r.drain will
271 output bad results). This problem can be circumvented by making the
272 differences between cell category values in the cumulative cost output
273 bigger. It is recommended that if the output from r.cost is to be used
274 as input to r.drain, the user multiply the r.cost input cost surface
275 map by the value of the map’s cell resolution, before running r.cost.
276 This can be done using r.mapcalc. The map resolution can be found using
277 g.region. This problem doesn’t arise with floating point maps.
278
280 g.region, r.cost, r.fill.dir, r.basins.fill, r.watershed, r.terraflow,
281 r.mapcalc, r.walk
282
284 Completely rewritten by Roger S. Miller, 2001
285 July 2004 at WebValley 2004, error checking and vector points added by
286 Matteo Franchi (Liceo Leonardo Da Vinci, Trento) and Roberto Flor
287 (ITC-irst, Trento, Italy)
288 Last changed: $Date: 2018-01-26 12:37:35 +0100 (Fri, 26 Jan 2018) $
290
292 Available at: r.drain source code (history)
293 Main index | Raster index | Topics index | Keywords index | Graphical
295 index | Full index
296 © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
298GRASS 7.4.4 r.drain(1)