r.drain(1)	       Grass User's Manual	       r.drain(1)



NNAAMMEE
       rr..ddrraaiinn	 -  Traces a flow through an elevation model on a
       raster map layer.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..ddrraaiinn
       rr..ddrraaiinn hheellpp
       rr..ddrraaiinn [--cc] [--aa]  [--nn]	iinnppuutt==_n_a_m_e  oouuttppuutt==_n_a_m_e  [ccoooorrddii--
       nnaattee==_x_,_y[,_x_,_y,...]]

DDEESSCCRRIIPPTTIIOONN
       _r_._d_r_a_i_n traces a flow through a least-cost path in an ele-
       vation model. The _e_l_e_v_a_t_i_o_n surface (a  raster  map  layer
       input)  might  be the cumulative cost map generated by the
       _r_._c_o_s_t program.	The _o_u_t_p_u_t  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. By default, the output will be
       an integer cell map with _1 along the least cost path,  and
       null cells elsewhere.

	With  the  --cc (_c_o_p_y) flag, the input map cells values are
       copied verbatim along the path. With the  --aa  (_a_c_c_u_m_u_l_a_t_e)
       flag,  the accumulated cells value from the starting point
       up to the current cell is written on output. With  the  --cc
       and the --aa flags, the output map is created withe the same
       cell type than the input map (integer, float  or  double).
       The --cc and --aa flags are mutually incompatible. If both are
       specified, the --aa flag will superceed the --cc flag,  and	a
       warning	message  will  be  issued.   With the --nn (_n_u_m_b_e_r)
       flag, the cells are numbered from the  starting	point  to
       the final point.


       The  path  is  calculated  by choosing the stepper "slope"
       beetwen adjacent cells.	The slope calculation  accurately
       acounts for the variable scale in lat-lon projections.


       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 rr..ddrraaiinn [--cc]
       [--aa]	[--nn]	 iinnppuutt==_n_a_m_e	oouuttppuutt==_n_a_m_e	 [ccoooorrddii--
       nnaattee==_x_,_y[,_x_,_y,...]]

       where  the input _n_a_m_e is the name of a raster map layer to
       be used in calculating drainage, the output  _n_a_m_e  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 rr..ddrraaiinn on the com-
       mand line, without program arguments. In  this  case,  the
       user  will  be  prompted for needed parameter values using
       the standard GRASS parser interface.

OOPPTTIIOONNSS
       Program parameters are as follows.

   FFllaaggss::
       --cc     Input map cells values are  copied  verbatim  along
	      the least cost path.

       --aa     Accumulated  input map cells values along the least
	      cost path are written on output.

       --nn     Count cell numbers along the path


   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e
	      Name of  raster  map  layer  containing  cell  cost
	      information.

       oouuttppuutt==_n_a_m_e
	      Name of raster map layer to contain program output.

       ccoooorrddiinnaattee==_x_,_y[,_x_,_y,...]
	      Each x,y pair is the easting and northing  (respec-
	      tively) 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.)


EEXXAAMMPPLLEESS
       Consider the following example:

       Input:			       Output:
	 ELEVATION SURFACE		 LEAST COST PATH



       The  user-provided  starting location in the above example
       is the boxed 1199 in the left-hand map. The path in the out-
       put  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 --cc _(_c_o_p_y_) flag, you get the following result:

       Input:			       Output:
	 ELEVATION SURFACE		 LEAST COST PATH


       Note  that  the	last _0 will not be put in the null values
       map.



       With the --aa  _(_a_c_c_u_m_u_l_a_t_e_)  flag,  you  get  the	following
       result:

       Input:			       Output:
	 ELEVATION SURFACE		 LEAST COST PATH



       With the --nn _(_n_u_m_b_e_r_) flag, you get the following result:

       Input:			       Output:
	 ELEVATION SURFACE		 LEAST COST PATH




BBUUGGSS
       _r_._d_r_a_i_n	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  immedi-
       ately  prior  to  it;  therefore,  it will not necessarily
       reach the lowest point in the  input  file.  It	currently
       finds  _p_i_t_s in the data, rather than the lowest point pre-
       sent.


       Sometimes, when using an integer cell map and the  differ-
       ences  among cell category values in the _r_._c_o_s_t cumulative
       cost surface output are small, this cumulative cost output
       cannot  accurately  be  used  as input to _r_._d_r_a_i_n (_r_._d_r_a_i_n
       will output bad results).  This	problem  can  be  circum-
       vented  by  making  the	differences between cell category
       values in the cumulative cost output bigger.  It is recom-
       mended  that,  if  the output from _r_._c_o_s_t is to be used as
       input to _r_._d_r_a_i_n, the user multiply the input cost surface
       map  to	_r_._c_o_s_t by the value of the map resolution, before
       running _r_._c_o_s_t.	This can be done using _r_._m_a_p_c_a_l_c or other
       programs.  The map resolution can be found using _g_._r_e_g_i_o_n.

SSEEEE AALLSSOO
       _g_._r_e_g_i_o_n

       _r_._c_o_s_t

       _r_._m_a_p_c_a_l_c

       _p_a_r_s_e_r

AAUUTTHHOORR
       Completely rewritten by Roger S. Miller

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_3_/_0_1 _0_0_:_0_8_:_3_1 _$



GRASS 5.0					       r.drain(1)
