r.drain <main>	      GRASS Reference Manual	   <main> r.drain



NAME
     r.drain - Traces a flow through an elevation model on a
     raster map layer.
     (GRASS Raster Program)

SYNOPSIS
     r.drain
     r.drain help
     r.drain input=name output=name [coordinate=x,y[,x,y,...]]

DESCRIPTION
     r.drain traces a flow through a least-cost path in an
     elevation model.  The elevation surface (a raster map layer
     input) might be the cumulative cost map generated by the
     r.cost program.  The output 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.

     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

	  r.drain input=name output=name
	  [coordinate=x,y[,x,y,...]]

     where the input name is the name of a raster map layer to be
     used in calculating drainage, the output name is the name of
     the raster map layer to contain output, and each x,y
     coordinate pair is the geographic location of a point from
     which drainage is to be calculated.

     Alternately, the user can simply type r.drain 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 parser.

OPTIONS
     Program parameters are as follows.

     Parameters:

     input=name		 Name of raster map layer containing cell
			 cost information.

     output=name	 Name of raster map layer to contain
			 program output.

     coordinate=x,y[,x,y,...]
			 Each x,y pair is the easting and
			 northing (respectively) of a starting



GRASS 5.0beta6	      GRASS Development Team			1






r.drain <main>	      GRASS Reference Manual	   <main> r.drain



			 point from which a least-cost corridor
			 will be developed.  As many points as
			 desired can be input.	(But, see BUGS
			 below.)

EXAMPLE
     Consider the following example:

     :
     H
     .
     .
     .
     .
     .
     .
     .
     .
     .
     .
     .
     .
     .

     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.

BUGS
     Currently, r.drain will not actually provide output for more
     than one pair of input coordinates stated on the command
     line.

     r.drain 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 pits 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 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



2		      GRASS Development Team	   GRASS 5.0beta6






r.drain <main>	      GRASS Reference Manual	   <main> r.drain



     recommended that, if the output from r.cost is to be used as
     input to r.drain, the user multiply the input cost surface
     map to r.cost by the value of the map resolution, before
     running r.cost.  This can be done using r.mapcalc or other
     programs.	The map resolution can be found using g.region.

SEE ALSO
     g.region, r.cost, r.mapcalc, and parser

AUTHOR
     Kewan Q. Khawaja, Intelligent Engineering Systems
     Laboratory, M.I.T.











































GRASS 5.0beta6	      GRASS Development Team			3