Provided by: grass-doc_7.0.3-1build1_all 
NAME
r.drain - Traces a flow through an elevation model or cost surface on a raster map.
KEYWORDS
raster, hydrology, cost surface
SYNOPSIS
r.drain
r.drain --help
r.drain [-cand] input=name [direction=name] output=name [drain=name]
[start_coordinates=east,north] [start_points=name[,name,...]] [--overwrite] [--help]
[--verbose] [--quiet] [--ui]
Flags:
-c
Copy input cell values on output
-a
Accumulate input values along the path
-n
Count cell numbers along the path
-d
The input raster map is a cost surface (direction surface must also be specified)
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
input=name [required]
Name of input elevation or cost surface raster map
direction=name
Name of input movement direction map associated with the cost surface
output=name [required]
Name for output raster map
drain=name
Name for output drain vector map
Recommended for cost surface made using knight’s move
start_coordinates=east,north
Coordinates of starting point(s) (E,N)
start_points=name[,name,...]
Name of starting vector points map(s)
DESCRIPTION
r.drain traces a flow through a least-cost path in an elevation model or cost surface. For
cost surfaces, a movement direction map must be specified with the direction option and
the -d flag to trace a flow path following the given directions. Such a movement direction
map can be generated with r.walk, r.cost, r.slope.aspect or r.watershed.
The output raster map will show one or more least-cost paths between each user-provided
location(s) and the minima (low category values) in the raster input map. If the -d flag
is used the output least-cost paths will be found using the direction raster map. By
default, the output will be an integer CELL map with category 1 along the least cost path,
and null cells elsewhere.
With the -c (copy) flag, the input raster map cell values are copied verbatim along the
path. With the -a (accumulate) flag, the accumulated cell value from the starting point up
to the current cell is written on output. With either the -c or the -a flags, the output
map is created with the same cell type as the input raster map (integer, float or double).
With the -n (number) flag, the cells are numbered consecutively from the starting point to
the final point. The -c, -a, and -n flags are mutually incompatible.
For an elevation surface, the path is calculated by choosing the steeper "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 r.walk or r.cost. 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).
The start_coordinates parameter consists of map E and N grid coordinates of a starting
point. Each x,y pair is the easting and northing (respectively) of a starting point from
which a least-cost corridor will be developed. The start_points parameter can take
multiple vector maps containing additional starting points. Up to 1024 starting points
can be input from a combination of the start_coordinates and start_points parameters.
NOTES
If no direction input map is given, r.drain 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 pits in the data, rather than the lowest point in the
entire input map. The r.fill.dir, r.terraflow, and r.basins.fill modules can be used to
fill in subbasins prior to processing with r.drain.
r.drain will not give sane results at the region boundary. On outer rows and columns
bordering the edge of the region, the flow direction is always directly out of the map. In
this case, the user could try adjusting the region extents slightly with g.region to allow
additional outlet paths for r.drain.
EXAMPLES
Consider the following example:
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 . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 17. 9 . 8 . 7 . 8 . 6 . 12. . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The user-provided starting location in the above example is the boxed 19 in the left-hand
map. The path in the output shows the least-cost corridor for moving from the starting box
to the lowest (smallest) possible point. This is the path a raindrop would take in this
landscape.
With the -c (copy) flag, you get the following result:
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. . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 17. 15. 15. 15. 10. 8 . 8 . . . . . . . 8 . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 24. 16. 8 . 7 . 8 . 0 .12 . . . . . . . 0 . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 17. 9 . 8 . 7 . 8 . 6 .12 . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Note that the last 0 will not be put in the null values map.
With the -a (accumulate) flag, you get the following result:
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. . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 17. 15. 15. 15. 10. 8 . 8 . . . . . . . 85. .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 24. 16. 8 . 7 . 8 . 0 .12 . . . . . . . 85. .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 17. 9 . 8 . 7 . 8 . 6 .12 . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
With the -n (number) flag, you get the following result:
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 . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 17. 15. 15. 15. 10. 8 . 8 . . . . . . . 6 . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 24. 16. 8 . 7 . 8 . 0 .12 . . . . . . . 7 . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 17. 9 . 8 . 7 . 8 . 6 .12 . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
With the -d (direction) flag, the direction raster is used for the input, rather than the
elevation surface. The output is then created according to one of the -can flags.
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 next cell is to the North-West
180 x 0
202.5 225 270 315 337.5
247.5 292.5
KNOWN ISSUES
Sometimes, when the differences among integer cell category values in the r.cost
cumulative cost surface output are small, this cumulative cost output cannot accurately be
used as input to r.drain (r.drain 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 r.cost is to be used as input to
r.drain, the user multiply the r.cost input cost surface map by the value of the map’s
cell resolution, before running r.cost. This can be done using r.mapcalc. The map
resolution can be found using g.region. This problem doesn’t arise with floating point
maps.
SEE ALSO
g.region, r.cost, r.fill.dir, r.basins.fill, r.terraflow, r.mapcalc, r.walk
AUTHORS
Completely rewritten by Roger S. Miller, 2001
July 2004 at WebValley 2004, error checking and vector points added by Matteo Franchi
(Liceo Leonardo Da Vinci, Trento) and Roberto Flor (ITC-irst, Trento, Italy)
Last changed: $Date: 2015-05-11 02:16:13 +0200 (Mon, 11 May 2015) $
Main index | Raster index | Topics index | Keywords index | Full index
© 2003-2016 GRASS Development Team, GRASS GIS 7.0.3 Reference Manual