.TH r.drain
.SH NAME
\fIr.drain\fR \- Traces a flow through an elevation model on a raster map layer.
.br
.I (GRASS Raster Program)
.SH SYNOPSIS
\fBr.drain\fR
.br
\fBr.drain help\fR
.br
\fBr.drain input\*=\fIname \fBoutput\*=\fIname \fR[\fBcoordinate\*=\fIx,y\fR[,\fIx,y\fR,...]]
.SH DESCRIPTION
\fIr.drain\fR traces a flow through a least-cost path in an elevation model.
The \fIelevation\fR surface (a raster map layer input)
might be the cumulative cost map generated by the \fIr.cost\fR program.
The \fIoutput\fR result (also a raster map layer) will show one or more
least-cost paths between each user-provided location(s) and the low spot
(low category values) in the input model.
.LP
The program will be run non-interactively, if the user specifies
the names of raster map layers and any desired options on the
command line, using the form
.LP
.RS
\fBr.drain input\*=\fIname \fBoutput\*=\fIname \fR[\fBcoordinate\*=\fIx,y\fR[,\fIx,y\fR,...]]
.RE
.LP
where the input \fIname\fR is the name of a raster map layer to
be used in calculating drainage,
the output \fIname\fR is the name of the raster map layer to contain output,
and each \fIx,y\fR coordinate pair is the geographic location of a point
from which drainage is to be calculated.
.LP
Alternately, the user can simply type \fBr.drain\fR on the command line,
without program arguments.  In this case, the user will be prompted for
needed parameter values using the standard GRASS parser interface
described in the manual entry for \fIparser\fR.
.SH OPTIONS
Program parameters are as follows.
.LP
\fBParameters:\fR
.IP \fBinput\*=\fIname\fR 20
Name of raster map layer containing cell cost information.
.IP \fBoutput\*=\fIname\fR 20
Name of raster map layer to contain program output.
.IP \fBcoordinate\*=\fIx,y\fR[,\fIx,y\fR,...] 20
Each x,y pair is the easting and northing (respectively) of 
a starting point from which a least-cost corridor will be developed.
As many points as desired can be input.
(But, see BUGS below.)
.SH EXAMPLE
Consider the following example:
.LP
.NF
Input:                            Output:
   ELEVATION SURFACE                 LEAST COST PATH
 . . ----- . . . . . . . . . .      . . . . . . . . . . . . . . .
 . 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 .      .   .   .   .   .   .   .   .
 . . . . . . . . . . . . . . .      . . . . . . . . . . . . . . .
.FI

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.
.SH BUGS
Currently, \fIr.drain\fR will not actually provide output for more
than one pair of input coordinates stated on the command line.

\fIr.drain\fR also 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 present.

Only one least-cost path is currently printed to the output file for the user.

Sometimes, when the differences among 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
(\fIr.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 input cost surface map
to \fIr.cost\fR by the value of the map resolution, before running
\fIr.cost\fR.  This can be done using \fIr.mapcalc\fR or other programs.
The map resolution can be found using \fIg.region\fR.
.SH SEE ALSO
.I g.region,
.I r.cost,
.I r.mapcalc,
and
.I parser
.SH AUTHOR
Kewan Q. Khawaja, Intelligent Engineering Systems Laboratory, M.I.T.