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



NNAAMMEE
       rr..ccoosstt - Outputs a raster map layer showing the cumulative
       cost of moving between different geographic  locations  on
       an  input raster map layer whose cell category values rep-
       resent cost.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..ccoosstt
       rr..ccoosstt hheellpp
       rr..ccoosstt	[--vv]	[--kk]	[--nn]	iinnppuutt==_n_a_m_e    oouuttppuutt==_n_a_m_e
       [ssttaarrtt__ssiitteess==_n_a_m_e]   [ssttoopp__ssiitteess==_n_a_m_e]	[ssttaarrtt__rraasstt==_n_a_m_e]
       [ccoooorrddiinnaattee==_x,_y[,_x,_y,...]]		    [ssttoopp__ccoooorrddii--
       nnaattee==_x,_y[,_x,_y,...]]  [mmaaxx__ccoosstt==_c_o_s_t] [nnuullll__vvaalluuee==_v_a_l_u_e]

DDEESSCCRRIIPPTTIIOONN
       _r_._c_o_s_t  determines  the	cumulative cost of moving to each
       cell on a _c_o_s_t _s_u_r_f_a_c_e (the input raster map  layer)  from
       other user-specified cell(s) whose locations are specified
       by their geographic coordinate(s). Each cell in the origi-
       nal  cost  surface map will contain a category value which
       represents the cost of traversing that cell.  _r_._c_o_s_t  will
       produce an output raster map layer in which each cell con-
       tains the  lowest  total  cost  of  traversing  the  space
       between each cell and the user-specified points. (Diagonal
       costs are multiplied by	a  factor  that  depends  on  the
       dimensions  of  the  cell.)  This program uses the current
       geographic region settings.  The output map will be of the
       same  data  format than the input map, integer or floating
       point.

OOPPTTIIOONNSS
       _r_._c_o_s_t can be run  either  non-interactively  or  interac-
       tively.	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.

   FFllaaggss::
       --vv     Run verbosely.

       --kk     Use the 'Knight's move'; slower, but more accurate.

       --nn     Keep null values in output map


   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e
	      Name of raster map containing grid cell cost infor-
	      mation.

       oouuttppuutt==_n_a_m_e
	      Name of raster map to contain results.

       ssttaarrtt__ssiitteess==_n_a_m_e
	      Starting points site file.

       ssttoopp__ssiitteess==_n_a_m_e
	      Stop points site file.

       ssttaarrtt__rraasstt==_n_a_m_e
	      Starting points raster file.

       ccoooorrddiinnaattee==_x,_y[,_x,_y,...]
	      The  map	E  and	N  grid coordinates of a starting
	      point (E,N).

       ssttoopp__ccoooorrddiinnaattee==_x,_y[,_x,_y,...]
	      The map E and N  grid  coordinates  of  a  stopping
	      point (E,N).

       mmaaxx__ccoosstt==_c_o_s_t
	      An optional maximum cumulative cost (default: 0).

       nnuullll__vvaalluuee==_v_a_l_u_e
	      Cost assigned to null cells. By default, null cells
	      are excluded.


       The iinnppuutt_n_a_m_e is the name of a raster map layer represent-
       ing  the cost surface map, the oouuttppuutt_n_a_m_e is the name of a
       raster map layer of cumulative cost, and each _x,_y  coordi-
       nate  pair  gives  the geographic location of a point from
       which the transportation cost  should  be  figured.  These
       starting  points  could	be read from a sites file through
       the ssttaarrtt__ssiitteess==_n_a_m_e option or from a raster  map  through
       the  ssttaarrtt__rraasstt==_n_a_m_e  option.  _r_._c_o_s_t will stop cumulating
       costs when either _m_a_x_c_o_s_t is reached, or one of	the  stop
       points  given  with  the  ssttoopp__ccoooorrddiinnaatteess==_x_,_y is reached.
       Alternatively, the stop points can be  read  from  a  site
       file  through the ssttoopp__ssiitteess==_n_a_m_e option. Both points read
       from a site file and those given o the command  line  will
       be  processd.  The  null  cells	in  the  input map can be
       assigned  a  (positive  floating  point)  cost  with   the
       _n_u_l_l___v_a_l_u_e option.

       Alternately,  the  user can simply type rr..ccoosstt on the com-
       mand line, without program arguments. In  this  case,  the
       user will be prompted for parameter values using the stan-
       dard GRASS _p_a_r_s_e_r interface.

       _r_._c_o_s_t can be run with two different methods of	identify-
       ing  the starting point(s). One or more points (geographic
       coordinate pairs) can be provided on the command  line  or
       site  file.   In lieu of these coordinates, the output map
       (e.g., oouuttppuutt) is presumed to contain starting points. All
       non-zero  cells	are  considered  to  be  starting points.
       BBeewwaarree:: doing this will overwrite oouuttppuutt with the  results
       of  the	calculations. If oouuttppuutt does exist and points are
       also given on the command line or through a site file, the
       oouuttppuutt file is ignored.

   FFllaaggss::
       --vv

       Processing  is tracked verbosely. This program can run for
       a very long time.

       --kk

       The Knight's move is used which improves the  accuracy  of
       the  output. In the diagram below, the center location (O)
       represents a grid cell from which cumulative distances are
       calculated.  Those  neighbors  marked with an X are always
       considered  for	cumulative  cost  updates.  With  the  --kk
       option, the neighbors marked with a K are also considered.

	.   .	. K .	. K .	.   .
	. . . . . . . . . . . . . . .
	.   . K . X . X . X . K .   .
	. . . . . . . . . . . . . . .
	.   .	. X . O . X .	.   .
	. . . . . . . . . . . . . . .
	.   . K . X . X . X . K .   .
	. . . . . . . . . . . . . . .
	.   .	. K .	. K .	.   .
	. . . . . . . . . . . . . . .



       --nn

       When input map null  cells  are	given  a  cost	with  the
       nnuullll__vvaalluuee  option,  the corresponding cells in the output
       map are no longer null cells. With this option,	the  null
       cells  of  the input map are retained as null cells in the
       output map.

   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e

       Name of input raster map layer whose category values  rep-
       resent surface cost.

       oouuttppuutt==_n_a_m_e

       Name  of  raster  map layer to contain output. Also can be
       used as the map layer of the input starting points. If  so
       used,  the input starting point map will be overwritten by
       the output.


       ssttaarrtt__ssiitteess==_n_a_m_e

	_n_a_m_e is the name of a site file that  holds  the  coordi-
       nates  of  starting  points  from which the transportation
       cost should be figured.


       ssttoopp__ssiitteess==_n_a_m_e

	_n_a_m_e is the name of a site file that hold the coordinates
       of  stopping points. During execution, once the cumulative
       cost to all stopping points has been determined,  process-
       ing stops.

       ccoooorrddiinnaattee==_x,_y[,_x,_y,...]

       Each  x,y  coordinate  pair gives the easting and northing
       (respectively) geographic coordinates of a starting  point
       from  which  to figure cumulative transportation costs for
       each cell. As many points as desired can be entered by the
       user.

       ssttoopp__ccoooorrddiinnaattee==_x,_y[,_x,_y,...]

       Each  x,y  coordinate  pair gives the easting and northing
       (respectively) geographic coordinates of a stopping point.
       During execution, once the cumulative cost to all stopping
       points has been	determined,  processing  stops.  As  many
       points as desired can be entered by the user.

       mmaaxx__ccoosstt==_m_a_x_c_o_s_t

       This  is  the cost limit that forces rr..ccoosstt to restart the
       current point to be considered a stop point.

       nnuullll__vvaalluuee==_v_a_l_u_e

       The optional value that will be assigned to the null cells
       in the input map. This is a positive floating point value.

EEXXAAMMPPLLEE
       Consider the following example:

	      Input:
		COST SURFACE
	      . . . . . . . . . . . . . . .
	      . 2 . 2 . 1 . 1 . 5 . 5 . 5 .
	      . . . . . . . . . . . . . . .
	      . 2 . 2 . 8 . 8 . 5 . 2 . 1 .
	      . . . . . . . . . . . . . . .
	      . 7 . 1 . 1 . 8 . 2 . 2 . 2 .
	      . . . . . . . . . . . . . . .
	      . 8 . 7 . 8 . 8 . 8 . 8 . 5 .
	      . . . . . . . . . . _____ . .
	      . 8 . 8 . 1 . 1 . 5 | 3 | 9 .
	      . . . . . . . . . . |___| . .
	      . 8 . 1 . 1 . 2 . 5 . 3 . 9 .
	      . . . . . . . . . . . . . . .

       Output (using -k):		 Output (not using -k):
	  COST SURFACE			    CUMULATIVE COST  SUR-
       FACE
	. . . . . . . . . . . . . . .	  . . . . * * * * * . . .
       . . .
	. 21. 21. 20. 19. 17. 15. 14.	  . 22. 21* 21*  20*  17.
       15. 14.
	. . . . . . . . . . . . . . .	  . . . . * * * * * . . .
       . . .
	. 20. 19. 22. 19. 15. 12. 11.	  . 20. 19. 22*  20*  15.
       12. 11.
	. . . . . . . . . . . . . . .	  . . . . . . * * * * * .
       . . .
	. 22. 18. 17. 17. 12. 11.  9.	  . 22. 18. 17*  18*  13*
       11.  9.
	. . . . . . . . . . . . . . .	  . . . . . . * * * * * .
       . . .
	. 21. 14. 13. 12.  8.  6.  6.	  . 21. 14. 13.  12.   8.
       6.  6.
	. . . . . . . . . . _____ . .	  . . . . . . . . . . . .
       . . .
	. 16. 13.  8.  7.  4|  0|  6.	  . 16. 13.  8. 7  .   4.
       0.  6.
	. . . . . . . . . . |___| . .	  . . . . . . . . . . . .
       . . .
	. 14.  9.  8.  9.  6.  3.  8.	  . 14.  9.  8. 9  .   6.
       3.  8.
	. . . . . . . . . . . . . . .	  . . . . . . . . . . . .
       . . .



       The user-provided ending location in the above example  is
       the  boxed 33 in the left-hand map. The costs in the output
       map represent the total	cost  of  moving  from	each  box
       ("cell")  to  one  or more (here, only one) starting loca-
       tion(s). Cells surrounded by asterisks are those that  are
       different  between  operations  using  and  not	using the
       Knight's move (--kk) option. This output map can be  viewed,
       for  example,  as an elevation model in which the starting
       location(s)  is/are  the  lowest  point(s).  Outputs  from
       _r_._c_o_s_t can be used as inputs to _r_._d_r_a_i_n, in order to trace
       the least-cost path given in this model between any  given
       cell  and  the  _r_._c_o_s_t  starting location(s). The two pro-
       grams, when used together, generate  least-cost	paths  or
       corridors between any two map locations (cells).

NNUULLLL CCEELLLLSS
       By  defaults,  null  cells  in  the  input  raster map are
       excluded from the algorithm, and thus retained on  output.

       If one wants rr..ccoosstt to transparently cross the null cells,
       one must use the option nnuullll__vvaalluuee==_0_._0..	Then, null  cells
       just  propagate	adjacent costs. These cells could then be
       retained as null cells into the output map through the  --nn
       flag.

NNOOTTEESS
       If  you	submit the starting point map on the command line
       by specifying:

       oouuttppuutt==ssttaarrtt__pptt__mmaapp

       the starting point map will be overwritten by  the  calcu-
       lated  output.  It  is wise to copy or rename (e.g., using
       _g_._c_o_p_y or _g_._r_e_n_a_m_e) the map of starting points to  another
       name  before  submitting it to _r_._c_o_s_t; otherwise, its con-
       tents will be overwritten.

       Sometimes, when the differences among iinntteeggeerr  cell  cate-
       gory  values 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 circumvented 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's cell 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.  This problem
       doesn't arise with floating point maps.

SSEEEE AALLSSOO
       _g_._c_o_p_y

       _g_._r_e_g_i_o_n

       _g_._r_e_n_a_m_e

       _r_._d_r_a_i_n

       _r_._i_n_._a_s_c_i_i

       _r_._m_a_p_c_a_l_c

       _r_._o_u_t_._a_s_c_i_i

       _p_a_r_s_e_r

AAUUTTHHOORR
       Antony Awaida,

       Intelligent Engineering

       Systems Laboratory,

       M.I.T.

       James Westervelt,

       U.S.Army Construction Engineering Research Laboratory

       Updated for Grass 5

       Pierre de Mouveaux (pmx@audiovu.com)

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0						r.cost(1)
