Debian Codegraph @

raster/r.drain/r.drain.html

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