.TH r.drain 1grass "" "GRASS 6.4.2" "Grass User's Manual"
.SH NAME
\fI\fBr.drain\fR\fR  - Traces a flow through an elevation model on a raster map.
.SH KEYWORDS
raster, hydrology
.SH SYNOPSIS
\fBr.drain\fR
.br
\fBr.drain help\fR
.br
\fBr.drain\fR [-\fBcan\fR] \fBinput\fR=\fIname\fR \fBoutput\fR=\fIname\fR  [\fBcoordinate\fR=\fIx,y\fR[,\fIx,y\fR,...]]   [\fBvector_points\fR=\fIname\fR[,\fIname\fR,...]]   [--\fBoverwrite\fR]  [--\fBverbose\fR]  [--\fBquiet\fR] 
.SS Flags:
.IP "\fB-c\fR" 4m
.br
Copy input cell values on output
.IP "\fB-a\fR" 4m
.br
Accumulate input values along the path
.IP "\fB-n\fR" 4m
.br
Count cell numbers along the path
.IP "\fB--overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB--verbose\fR" 4m
.br
Verbose module output
.IP "\fB--quiet\fR" 4m
.br
Quiet module output
.PP
.SS Parameters:
.IP "\fBinput\fR=\fIname\fR" 4m
.br
Name of elevation raster map
.IP "\fBoutput\fR=\fIname\fR" 4m
.br
Name for output raster map
.IP "\fBcoordinate\fR=\fIx,y[,\fIx,y\fR,...]\fR" 4m
.br
Map coordinates of starting point(s) (E,N)
.IP "\fBvector_points\fR=\fIname[,\fIname\fR,...]\fR" 4m
.br
Name of vector map(s) containing starting point(s)
.PP
.SH DESCRIPTION
\fIr.drain\fR traces a flow through a least-cost path in an elevation
model. The \fBinput\fR elevation surface (a raster map layer) might
be a cumulative cost map generated by the
\fIr.cost\fR program.
The \fBoutput\fR result (also a raster map layer) will show one or more 
least-cost paths between each user-provided location(s) and the minima 
(low category values) in the \fBinput\fR map. By default, the \fBoutput\fR
will be an integer CELL map with 1 along the least cost path,
and null cells elsewhere.
.PP
With the \fB-c\fR (\fIcopy\fR) flag, the input map cell values are
copied verbatim along the path. With the \fB-a\fR (\fIaccumulate\fR)
flag, the accumulated cell value from the starting point up to the current
cell is written on output. With either the \fB-c\fR or the \fB-a\fR flags, the
\fBoutput\fR map is created with the same cell type as the \fBinput\fR map (integer,
float or double).
With the \fB-n\fR (\fInumber\fR) flag, the cells are numbered consecutively from the
starting point to the final point.
The \fB-c\fR, \fB-a\fR, and \fB-n\fR flags are mutually incompatible.
.PP
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.
.PP
The \fBcoordinate\fR 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 \fBvector_points\fR parameter can take multiple vector maps containing 
additional starting points.
Up to 1024 starting points can be input from a combination of the
\fBcoordinate\fR and \fBvector_points\fR parameters.
.SH NOTES
\fIr.drain\fR 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 \fIpits\fR in the data, rather 
than the lowest point in the entire input map. The \fIr.fill.dir\fR,
\fIr.terraflow\fR, and \fIr.basins.fill\fR modules can be used to
fill in subbasins prior to processing with \fIr.drain\fR.
.PP
\fIr.drain\fR 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 
\fIg.region\fR to allow additional outlet paths for \fIr.drain\fR.
.SH EXAMPLES
Consider the following example: 
\fC
.DS
.br
Input:                          Output:
.br
  ELEVATION SURFACE               LEAST COST PATH
.br
. . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 20| 19| 17. 16. 17. 16. 16.    .   . 1 . 1 . 1 .   .   .   .
.br
. . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 1 .   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 1 .   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 1 .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 1 .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 17. 9 . 8 . 7 . 8 . 6 .12 .    .   .   .   .   .   .   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
.DE
\fR
.PP
The user-provided starting location in the above example is 
the boxed \fB19\fR 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.
.PP
With the \fB-c\fR \fI(copy)\fR flag, you get the following result:
\fC
.DS
.br
Input:                          Output:
.br
  ELEVATION SURFACE               LEAST COST PATH
.br
. . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 20| 19| 17. 16. 17. 16. 16.    .   . 19. 17. 16.   .   .   .
.br
. . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 15.   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 10.   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 8 .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 0 .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 17. 9 . 8 . 7 . 8 . 6 .12 .    .   .   .   .   .   .   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
.br
Note that the last \fI0\fR will not be put in the null values map.
.br
.DE
\fR
.PP
With the \fB-a\fR \fI(accumulate)\fR flag, you get the following result:
\fC
.DS
.br
Input:                          Output:
.br
  ELEVATION SURFACE               LEAST COST PATH
.br
. . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 20| 19| 17. 16. 17. 16. 16.    .   . 19. 36. 52.   .   .   .
.br
. . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 67.   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 77.   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 85.   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 85.   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 17. 9 . 8 . 7 . 8 . 6 .12 .    .   .   .   .   .   .   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
.DE
\fR
.PP
With the \fB-n\fR \fI(number)\fR flag, you get the following result:
\fC
.DS
.br
Input:                          Output:
.br
  ELEVATION SURFACE               LEAST COST PATH
.br
. . ----- . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 20| 19| 17. 16. 17. 16. 16.    .   . 1 . 2 . 3 .   .   .   .
.br
. . |___| . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 18. 18. 24. 18. 15. 12. 11.    .   .   .   .   . 4 .   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 22. 16. 16. 18. 10. 10. 10.    .   .   .   .   . 5 .   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 17. 15. 15. 15. 10. 8 . 8 .    .   .   .   .   .   . 6 .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 24. 16. 8 . 7 . 8 . 0 .12 .    .   .   .   .   .   . 7 .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
. 17. 9 . 8 . 7 . 8 . 6 .12 .    .   .   .   .   .   .   .   .
.br
. . . . . . . . . . . . . . .    . . . . . . . . . . . . . . .
.br
.DE
\fR
.PP
.SH BUGS
.PP
Sometimes, when the differences among integer cell category values in the
\fIr.cost\fR cumulative cost surface output are 
small, this cumulative cost output cannot accurately be used as input to
\fIr.drain\fR (\fIt.drain\fR 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 \fIr.cost\fR is to be used
as input to \fIr.drain\fR, the user multiply the \fIr.cost\fR
input cost surface map by the value of the map's cell resolution,
before running \fIr.cost\fR. This can be done using
\fIr.mapcalc\fR. The map resolution can be
found using \fIg.region\fR.
This problem doesn't arise with floating point maps.
.SH SEE ALSO
\fIg.region\fR,
\fIr.cost\fR,
\fIr.fill.dir\fR,
\fIr.basins.fill\fR,
\fIr.terraflow\fR,
\fIr.mapcalc\fR,
\fIr.walk\fR
.SH AUTHOR
Completely rewritten by Roger S. Miller, 2001
.PP
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)
.PP
\fILast changed: $Date: 2008-05-16 21:09:06 +0200 (Fri, 16 May 2008) $\fR
.PP
Full index
.PP
© 2003-2011 GRASS Development Team