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



NNAAMMEE
       rr..ccoosstt - Outputs a raster map layer showing the cumulative cost of mov-
       ing between different geographic locations on an input raster map layer
       whose cell category values represent 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__ccoooorrddiinnaattee==_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 original 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 contains 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 interactively. The pro-
       gram 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 information.

       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 representing  the  cost
       surface	map, the oouuttppuutt_n_a_m_e is the name of a raster map layer of cumu-
       lative cost, and each _x,_y coordinate 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__ccoooorr--
       ddiinnaatteess==_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 command line, with-
       out  program  arguments.  In  this  case, the user will be prompted for
       parameter values using the standard GRASS _p_a_r_s_e_r interface.

       _r_._c_o_s_t can be run with two different methods of identifying the	start-
       ing  point(s).  One or more points (geographic coordinate pairs) can be
       provided on the command line or site file.  In lieu  of	these  coordi-
       nates,  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 calcu-
       lations. 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 represent 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 coordinates 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, processing 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 cumula-
       tive  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 SURFACE
	. . . . . . . . . . . . . . .	  . . . . * * * * * . . . . . .
	. 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 location(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 programs, when used together, gen-
       erate  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 calculated 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; other-
       wise, its contents will be overwritten.

       Sometimes, when the differences among iinntteeggeerr cell category 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 out-
       put  bad  results). This problem can be circumvented by making the dif-
       ferences 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)
