r.drain: use standard GRASS directions, update manual

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@54419 15284696-431f-4ddb-bdfa-cd5b030d7da7

raster/r.drain/main.c

@@ -682,70 +682,70 @@ struct point *drain_cost(int dir_fd, struct point *list, int nrow, int ncol)
 	    G_message(_("direction read: %lf, neighbour found: %i"),
 		      direction, neighbour);
 	switch (neighbour) {
-	case 1800:
-	    next_row = list->row;
-	    next_col = list->col + 1;
+	case 225: /* ENE */
+	    next_row = list->row - 1;
+	    next_col = list->col + 2;
 	    break;
-	case 0:
-	    next_row = list->row;
-	    next_col = list->col - 1;
+	case 450: /* NE */
+	    next_row = list->row - 1;
+	    next_col = list->col + 1;
 	    break;
-	case 900:
-	    next_row = list->row + 1;
-	    next_col = list->col;
+	case 675: /* NNE */
+	    next_row = list->row - 2;
+	    next_col = list->col + 1;
 	    break;
-	case 2700:
+	case 900: /* N */
 	    next_row = list->row - 1;
 	    next_col = list->col;
 	    break;
-	case 1350:
-	    next_col = list->col + 1;
-	    next_row = list->row + 1;
+	case 1125: /* NNW */
+	    next_row = list->row - 2;
+	    next_col = list->col - 1;
 	    break;
-	case 450:
+	case 1350: /* NW */
 	    next_col = list->col - 1;
-	    next_row = list->row + 1;
+	    next_row = list->row - 1;
 	    break;
-	case 3150:
+	case 1575: /* WNW */
+	    next_col = list->col - 2;
 	    next_row = list->row - 1;
+	    break;
+	case 1800: /* W*/
+	    next_row = list->row;
 	    next_col = list->col - 1;
 	    break;
-	case 2250:
-	    next_row = list->row - 1;
-	    next_col = list->col + 1;
+	case 2025: /* WSW */
+	    next_row = list->row + 1;
+	    next_col = list->col - 2;
 	    break;
-	case 1125:
-	    next_row = list->row + 2;
-	    next_col = list->col + 1;
+	case 2250: /* SW */
+	    next_row = list->row + 1;
+	    next_col = list->col - 1;
 	    break;
-	case 675:
+	case 2475: /* SSW */
 	    next_row = list->row + 2;
 	    next_col = list->col - 1;
 	    break;
-	case 2925:
-	    next_row = list->row - 2;
-	    next_col = list->col - 1;
+	case 2700: /* S */
+	    next_row = list->row + 1;
+	    next_col = list->col;
 	    break;
-	case 2475:
-	    next_row = list->row - 2;
+	case 2925: /* SSE */
+	    next_row = list->row + 2;
 	    next_col = list->col + 1;
 	    break;
-	case 1575:
+	case 3150: /* SE */
 	    next_row = list->row + 1;
-	    next_col = list->col + 2;
+	    next_col = list->col + 1;
 	    break;
-	case 225:
+	case 3375: /* ESE */
 	    next_row = list->row + 1;
-	    next_col = list->col - 2;
-	    break;
-	case 3375:
-	    next_row = list->row - 1;
-	    next_col = list->col - 2;
-	    break;
-	case 2025:
-	    next_row = list->row - 1;
 	    next_col = list->col + 2;
 	    break;
+	case 3600: /* E */
+	    next_row = list->row;
+	    next_col = list->col + 1;
+	    break;
 	    /* default:
 	       break;
 	       Should probably add something here for the possibility of a non-direction map

raster/r.drain/r.drain.html

@@ -1,10 +1,13 @@
 <h2>DESCRIPTION</h2>
 
 <em>r.drain</em> traces a flow through a least-cost path in an elevation
-model. If the <b>input</b> surface (a raster map layer) is a cumulative 
-cost map generated by the <em><a href="r.walk.html">r.walk</a></em> or 
-<em><a href="r.cost.html">r.cost</a></em> modules, the -d flag and a 
-movement direction surface <b>"indir"</b> must be specified.
+model. Alternatively, a movement direction map can be used with the 
+<b>indir</b> option and the <b>-d</b> flag to trace a flow path following 
+the given directions. Such a movement direction map can be generated with 
+<em><a href="r.walk.html">r.walk</a></em>, 
+<em><a href="r.cost.html">r.cost</a></em>, 
+<em><a href="r.slope.aspect.html">r.slope.aspect</a></em> or 
+<em><a href="r.watershed.html">r.watershed</a></em>.
 
 The <b>output</b> result (also a raster map layer) will show one or more 
 least-cost paths between each user-provided location(s) and the minima 
@@ -27,7 +30,10 @@ The <b>-c</b>, <b>-a</b>, and <b>-n</b> flags are mutually incompatible.
 "slope" between adjacent cells. The slope calculation accurately acounts 
 for the variable scale in lat-lon projections. For a cost surface, the path
 is calculated by following the movement direction surface back to the start 
-point given in <em>r.walk</em> or <em>r.cost</em>.
+point given in <em>r.walk</em> or <em>r.cost</em>. The path search stops 
+as soon as a region border or a neighboring NULL cell is encountered, 
+because in these cases the direction can not be determined (the path 
+could continue outside the current region).
 
 <p>The <b>coordinate</b> parameter consists of map E and N grid coordinates of
 a starting point. Each x,y pair is the easting and northing (respectively) of
@@ -39,9 +45,9 @@ Up to 1024 starting points can be input from a combination of the
 
 <h2>NOTES</h2>
 
-<em>r.drain</em> currently finds only the lowest point
-(the cell having the smallest category value) in the 
-input file that can be reached through directly adjacent cells 
+If no direction input map is given, <em>r.drain</em> currently finds 
+only the lowest point (the cell having the smallest category value) in 
+the input file that can be reached through directly adjacent cells 
 that are less than or equal in value to the cell reached immediately 
 prior to it; therefore, it will not necessarily reach the lowest point 
 in the input file. It currently finds <em>pits</em> in the data, rather 
@@ -62,18 +68,20 @@ Consider the following example:
 <div class="code"><pre>
 Input:                          Output:
   ELEVATION SURFACE               LEAST COST PATH
-. . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
+. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
+. 19. 20. 18. 19. 16. 15. 15.    .   .   .   .   .   .   .   .
+. .  ---  . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 20| 19| 17. 16. 17. 16. 16.    .   . 1 . 1 . 1 .   .   .   .
-. . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
+. .  ---  . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 1 .   .   .
 . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 1 .   .   .
 . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 1 .   .
 . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
-. 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 1 .   .
+. 24. 16. 8 . 7 . 8 . 0 . 12.    .   .   .   .   .   . 1 .   .
 . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
-. 17. 9 . 8 . 7 . 8 . 6 .12 .    .   .   .   .   .   .   .   .
+. 17. 9 . 8 . 7 . 8 . 6 . 12.    .   .   .   .   .   .   .   .
 . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
 </pre></div>
 
@@ -89,9 +97,11 @@ With the <b>-c</b> <em>(copy)</em> flag, you get the following result:
 <div class="code"><pre>
 Input:                          Output:
   ELEVATION SURFACE               LEAST COST PATH
-. . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
+. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
+. 19. 20. 18. 19. 16. 15. 15.    .   .   .   .   .   .   .   .
+. .  ---  . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 20| 19| 17. 16. 17. 16. 16.    .   . 19. 17. 16.   .   .   .
-. . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
+. .  ---  . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 15.   .   .
 . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 10.   .   .
@@ -112,9 +122,11 @@ With the <b>-a</b> <em>(accumulate)</em> flag, you get the following result:
 <div class="code"><pre>
 Input:                          Output:
   ELEVATION SURFACE               LEAST COST PATH
-. . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
+. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
+. 19. 20. 18. 19. 16. 15. 15.    .   .   .   .   .   .   .   .
+. .  ---  . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 20| 19| 17. 16. 17. 16. 16.    .   . 19. 36. 52.   .   .   .
-. . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
+. .  ---  . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 67.   .   .
 . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 77.   .   .
@@ -133,9 +145,11 @@ With the <b>-n</b> <em>(number)</em> flag, you get the following result:
 <div class="code"><pre>
 Input:                          Output:
   ELEVATION SURFACE               LEAST COST PATH
-. . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
+. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
+. 19. 20. 18. 19. 16. 15. 15.    .   .   .   .   .   .   .   .
+. .  ---  . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 20| 19| 17. 16. 17. 16. 16.    .   . 1 . 2 . 3 .   .   .   .
-. . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
+. .  ---  . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 4 .   .   .
 . . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
 . 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 5 .   .   .
@@ -152,10 +166,10 @@ With the <b>-d</b> <em>(direction)</em> flag, the direction raster is used
 for the input, rather than the elevation surface. The output is then created 
 according to one of the <b>-can</b> flags.
 <div class="code"><pre>
-The directions are recorded as GRASS standard directions:
+The directions are recorded as degrees CCW from East:
        112.5     67.5         i.e. a cell with the value 135 
-157.5  135   90  45   22.5    means the cell <b>before</b> it is 
-       180   x   0            to the south-east.
+157.5  135   90  45   22.5    means the next cell is to the North-West 
+       180   x   0            
 202.5  225  270  315  337.5
        247.5     292.5
 </pre></div>
@@ -166,7 +180,7 @@ The directions are recorded as GRASS standard directions:
 <p>Sometimes, when the differences among integer cell category values in the
 <em><a href="r.cost.html">r.cost</a></em> cumulative cost surface output are 
 small, this cumulative cost output cannot accurately be used as input to
-<em>r.drain</em> (<em>t.drain</em> will output bad results).
+<em>r.drain</em> (<em>r.drain</em> will output bad results).
 This problem can be circumvented by making the differences
 between cell category values in the cumulative cost output bigger. It
 is recommended that if the output from <em>r.cost</em> is to be used