Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
r.cost(1)		    GRASS GIS User's Manual		     r.cost(1)

NAME
       r.cost	-  Creates  a raster map showing the cumulative	cost of	moving
       between different geographic locations on an  input  raster  map	 whose
       cell category values represent cost.

KEYWORDS
       raster, cost surface, cumulative	costs, cost allocation

SYNOPSIS
       r.cost
       r.cost --help
       r.cost  [-knrib]	input=name output=name	[solver=name]	[nearest=name]
       [outdir=name]	      [start_points=name]	    [stop_points=name]
       [start_raster=name]     [start_coordinates=east,north[,east,north,...]]
       [stop_coordinates=east,north[,east,north,...]]	      [max_cost=value]
       [null_cost=value]    [memory=memory  in	MB]    [--overwrite]  [--help]
       [--verbose]  [--quiet]  [--ui]

   Flags:
       -k
	   Use the 'Knight's move'; slower, but	more accurate

       -n
	   Keep	null values in output raster map

       -r
	   Start with values in	raster map

       -i
	   Print info about disk space and memory requirements and exit

       -b
	   Create bitmask encoded directions

       --overwrite
	   Allow output	files to overwrite existing files

       --help
	   Print usage summary

       --verbose
	   Verbose module output

       --quiet
	   Quiet module	output

       --ui
	   Force launching GUI dialog

   Parameters:
       input=nameA [required]
	   Name	of input raster	map containing grid cell cost information

       output=nameA [required]
	   Name	for output raster map

       solver=name
	   Name	of input raster	map solving equal costs
	   Helper variable to pick a direction if two  directions  have	 equal
	   cumulative costs (smaller is	better)

       nearest=name
	   Name	for output raster map with nearest start point

       outdir=name
	   Name	for output raster map to contain movement directions

       start_points=name
	   Name	of starting vector points map
	   Or data source for direct OGR access

       stop_points=name
	   Name	of stopping vector points map
	   Or data source for direct OGR access

       start_raster=name
	   Name	of starting raster points map

       start_coordinates=east,north[,east,north,...]
	   Coordinates of starting point(s) (E,N)

       stop_coordinates=east,north[,east,north,...]
	   Coordinates of stopping point(s) (E,N)

       max_cost=value
	   Maximum cumulative cost
	   Default: 0

       null_cost=value
	   Cost	assigned to null cells.	By default, null cells are excluded

       memory=memory in	MB
	   Maximum memory to be	used (in MB)
	   Cache size for raster rows
	   Default: 300

DESCRIPTION
       r.cost  determines the cumulative cost of moving	to each	cell on	a cost
       surface (the input raster map) 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  rep-
       resents	the  cost  of  traversing that cell. r.cost will produce 1) an
       output raster map 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	dimen-
       sions  of  the cell) and	2) a second raster map layer showing the move-
       ment direction to the next cell on the path back	 to  the  start	 point
       (see  Movement  Direction). This	module uses the	current	geographic re-
       gion settings. The output map will be of	the same data  format  as  the
       input map, integer or floating point.

OPTIONS
       The input name is the name of a raster map whose	category values	repre-
       sent the	surface	cost. The output name is the  name  of	the  resultant
       raster  map  of cumulative cost.	The outdir name	is the name of the re-
       sultant raster map of movement directions (see Movement Direction).

       r.cost can be run with  three  different	 methods  of  identifying  the
       starting	point(s). One or more points (geographic coordinate pairs) can
       be provided as specified	start_coordinates on the command line, from  a
       vector  points file, or from a raster map.  All non-NULL	cells are con-
       sidered to be starting points.

       Each x,y	start_coordinates pair gives  the  geographic  location	 of  a
       point  from  which  the	transportation cost should be figured. As many
       points as desired can be	entered	by the user. These starting points can
       also  be	read from a vector points file through the start_points	option
       or from a raster	map through the	start_raster option.

       r.cost will stop	cumulating costs when either max_cost is  reached,  or
       one  of the stop	points given with stop_coordinates is reached.	Alter-
       natively, the stop points can be	read from a vector  points  file  with
       the  stop_points	 option. During	execution, once	the cumulative cost to
       all stopping points has been determined,	processing stops.
       Both sites read from a vector points file and those given on  the  com-
       mand line will be processed.

       The  null  cells	 in the	input map can be assigned a (positive floating
       point) cost with	the null_cost option.
       When input map null cells are given a cost with the  null_cost  option,
       the  corresponding cells	in the output map are no longer	null cells. By
       using the -n flag, the null cells of the	input map are retained as null
       cells in	the output map.

       As r.cost can run for a very long time, it can be useful	to use the --v
       verbose flag to track progress.

       The Knight's move (-k flag) may be used to improve 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	-k 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 .	.   .
	. . . .	. . . .	. . . .	. . .

       Knight's	move example:

       Flat cost surface without (left pane) and with the  knight's
       move (right pane).  The default is to grow the cost outwards
       in 8 directions.	 Using the knight's move grows it  outwards
       in 16 directions.

       If the nearest output parameter is specified, the module	will calculate
       for each	cell its nearest starting point	based on the minimized accumu-
       lative cost while moving	over the cost map.

       The  solver  option  helps  to select a particular direction in case of
       multiple	directions with	equal costs. Sometimes fields with equal cumu-
       lative  costs exist and multiple	paths with equal costs would lead from
       a start point to	a stop point. By default, a path  along	 the  edge  of
       such  a	field  would be	produced or multiple paths of equal costs with
       the -b flag. An additional variable can be supplied with	the solver op-
       tion to help the	algorithm pick a particular direction.

       Example for solving multiple directions:

       A  field	 of  equal  cumulative	costs  with  multiple paths
       (black).	By default a path along	the edge will  be  selected
       (red).  Path selection can be controlled	with the solver	op-
       tion (blue).

       Multiple	directions can be solved as in the above example with the fol-
       lowing steps:

       1      Create multiple directions with r.cost/r.walk using the -b flag

       2      Extract paths using r.path format=bitmask

       3      Calculate	  the	distance   from	 NULL  cells  to  paths	 using
	      r.grow.distance -n input=<paths from r.path>

       4      Invert the sign of the distances with r.mapcalc because for  the
	      solver  smaller is better, and here we want to get the center of
	      an area with multiple directions

       5      Use thise	negative distances as solver  for  a  second  pass  of
	      r.cost

       6      Extract paths again with r.path to get a geometrically optimized
	      solution

NULL CELLS
       By default null cells in	the input raster map are excluded from the al-
       gorithm,	and thus retained in the output	map.

       If  one	wants  r.cost to transparently cross any region	of null	cells,
       the null_cost=0.0 option	should be used.	Then null cells	just propagate
       the  adjacent  costs.  These cells can be retained as null cells	in the
       output map by using the -n flag.

NOTES
       Paths from any point to the nearest starting point of r.cost can	be ex-
       tracted with r.path by using the	direction output map of	r.cost.

   Algorithm notes
       The  fundamental	approach to calculating	minimum	travel cost is as fol-
       lows:

       The user	generates a raster map indicating the cost of traversing  each
       cell in the north-south and east-west directions.  This map, along with
       a set of	starting points	are submitted to r.cost. The  starting	points
       are put into a heap of cells from which costs to	the adjacent cells are
       to be calculated. The cell on the heap with the lowest cumulative  cost
       is  selected  for  computing  costs to the neighboring cells. Costs are
       computed	and those cells	are put	on the heap and	the  originating  cell
       is  finalized.  This  process  of  selecting the	lowest cumulative cost
       cell, computing costs to	the neighbors, putting the  neighbors  on  the
       heap  and  removing  the	originating cell from the heap continues until
       the heap	is empty.

       The most	time consuming aspect of this algorithm	is the	management  of
       the  heap  of  cells for	which cumulative costs have been at least ini-
       tially computed.	r.cost uses a minimum heap  for	 efficiently  tracking
       the next	cell with the lowest cumulative	costs.

       r.cost,	like most all GRASS raster programs, is	also made to be	run on
       maps larger that	can fit	in available computer memory. As the algorithm
       works  through  the  dynamic  heap of cells it can move almost randomly
       around the entire area. r.cost divides the entire area into a number of
       pieces  and  swaps these	pieces in and out of memory (to	and from disk)
       as needed. This provides	a virtual memory approach  optimally  designed
       for  2-D	 raster	maps. The amount of memory to be used by r.cost	can be
       controlled with the memory option, default is 300 MB. For systems  with
       less memory this	value will have	to be set to a lower value.

EXAMPLES
       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):
	  CUMULATIVE 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 starting location in the above	example	is the boxed 3
       in the above input 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 (-k)
       option.

   Output analysis
       The 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.cost can be used as  inputs  to  r.path  ,  in	 order	to  trace  the
       least-cost  path	 given	by  this  model	between	any given cell and the
       r.cost starting location(s). The	two programs, when used	together, gen-
       erate  least-cost  paths	 or  corridors	between	 any two map locations
       (cells).

   Shortest distance surfaces
       The r.cost module allows	for computing the shortest  distance  of  each
       pixel  from raster lines, such as determining the shortest distances of
       households to the nearby	road. For this cost surfaces with cost value 1
       are  used.  The calculation is done with	r.cost as follows (example for
       Spearfish region):
	 g.region raster=roads -p
	 r.mapcalc "area.one = 1"
	 r.cost	-k input=area.one output=distance start_raster=roads
	 d.rast	distance
	 d.rast.num distance
	 #transform to metric distance from cell distance using	the raster resolution:
	 r.mapcalc "dist_meters	= distance * (ewres()+nsres())/2."
	 d.rast	dist_meters

Movement Direction
       The movement direction surface is created to  record  the  sequence  of
       movements that created the cost accumulation surface. This movement di-
       rection surface can be used by r.path to	recover	a  path	 from  an  end
       point  back  to the start point.	 The direction of each cell points to-
       wards the next cell.  The directions are	recorded as degrees  CCW  from
       East:
	      112.5	 67.5	      i.e. a cell with the value 135
       157.5  135   90	 45   22.5    means the	next cell is to	the north-west
	      180   x	360
       202.5  225  270	315  337.5
	      247.5	292.5

   Cost	allocation
       Example:	calculation of the cost	allocation map "costalloc" and the cu-
       mulative	cost map "costsurf" for	given starting points (map  "sources")
       and given cost raster map "costs":
       r.cost input=costs start_raster=sources output=costsurf nearest=costalloc

   Find	the minimum cost path
       Once r.cost computes the	cumulative cost	map and	an associated movement
       direction map, r.path can be used to find the minimum cost path.

SEE ALSO
	r.walk,	r.path,	r.in.ascii, r.mapcalc, r.out.ascii

AUTHORS
       Antony Awaida, Intelligent Engineering Systems Laboratory, M.I.T.
       James Westervelt, U.S.Army Construction Engineering Research Laboratory
       Updated for Grass 5 by Pierre de	Mouveaux (pmx@audiovu.com)
       Markus Metz
       Multiple	path directions	sponsored by mundialis

SOURCE CODE
       Available at: r.cost source code	(history)

       Main index | Raster index | Topics index	| Keywords index  |  Graphical
       index | Full index

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.5 Reference	Manual

GRASS 7.8.5							     r.cost(1)

NAME | KEYWORDS | SYNOPSIS | DESCRIPTION | OPTIONS | NULL CELLS | NOTES | EXAMPLES | Movement Direction | SEE ALSO | AUTHORS | SOURCE CODE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=r.cost&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help