r.drain(1grass) GRASS GIS User's Manual r.drain(1grass)
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[,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 sur-
face
Direction in degrees CCW from east
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[,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 pro-
vided that the direction is in degrees, measured counterclockwise from
east.
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 dou-
ble). 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 accu-
rately accounts for the variable scale in lat-lon projections. For a
cost surface, the path is calculated by following the movement direc-
tion 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 deter-
mined (the path could continue outside the current region).
The start_coordinates parameter consists of map E and N grid coordi-
nates 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.
Explanation of output values
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) pos-
sible 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 in-
put, rather than the elevation surface. The output is then created ac-
cording 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
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 ad-
justing the region extents slightly with g.region to allow additional
outlet paths for r.drain.
EXAMPLES
Path to the lowest point
In this example we compute drainage paths from two given points follow-
ing decreasing elevation values to the lowest point. We are using the
full North Carolina sample dataset. First we create the two points
from a text file using v.in.ascii module (here the text file is CSV and
we are using unix here-file syntax with EOF, in GUI just enter the val-
ues directly for the parameter input):
v.in.ascii input=- output=start format=point separator=comma <<EOF
638667.15686275,220610.29411765
638610.78431373,220223.03921569
EOF
Now we compute the drainage path:
r.drain input=elev_lid792_1m output=drain_path drain=drain start_points=start
Before we visualize the result, we set a color table for the elevation
we are using and we create a shaded relief map:
r.colors map=elev_lid792_1m color=elevation
r.relief input=elev_lid792_1m output=relief
Finally we visualize all the input and output data:
d.shade shade=relief color=elev_lid792_1m
d.vect map=drain_path color=0:0:61 width=4 legend_label="drainage paths"
d.vect map=start color=none fill_color=224:0:0 icon=basic/circle size=15 legend_label=origins
d.legend.vect -b
Figure: Drainage paths from two points flowing into the points with
lowest values
Path following directions
To continue flow even after it hits a depression, we need to supply a
direction raster map which will tell the r.drain module how to continue
from the depression. To get these directions, we use the r.watershed
module:
r.watershed elevation=elev_lid792_1m accumulation=accum drainage=drain_dir
The directions are categorical and we convert them to degrees using
raster algebra:
r.mapcalc "drain_deg = if(drain_dir != 0, 45. * abs(drain_dir), null())"
Together with directions, we need to provide the r.drain module with
cost values. We don’t have any cost to assign to specific cells, so we
create a constant surface:
r.mapcalc "const1 = 1"
Now we are ready to compute the drainage paths. We are using the two
points from the previous example.
r.drain -d input=const1 direction=drain_deg output=drain_path_2 drain=drain_2 start_points=start
We visualize the result in the same way as in the previous example.
Figure: Drainage paths from two points where directions from r.water-
shed were used
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.watershed, 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)
SOURCE CODE
Available at: r.drain source code (history)
Accessed: unknown
Main index | Raster index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 r.drain(1grass)
Generated by dwww version 1.14 on Sun Dec 29 18:56:56 CET 2024.