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 elevation model.
       The _e_l_e_v_a_t_i_o_n surface (a raster map layer input) might be  the  cumula-
       tive 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 verba-
       tim 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 command 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 (respectively) of a
	      starting point from which a least-cost corridor will  be	devel-
	      oped.   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 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 --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 immediately prior to it; therefore, it will not necessar-
       ily reach the lowest point in the input file. It currently  finds  _p_i_t_s
       in the data, rather than the lowest point present.


       Sometimes,  when  using	an  integer cell map and the differences 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 cir-
       cumvented by making the differences between cell category values in the
       cumulative cost output bigger.  It is recommended 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 pro-
       grams.  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)
