man r.cost () - 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 represent cost.

NAME

r.cost - 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 represent cost.

SYNOPSIS

r.cost

r.cost help

r.cost [-vknr] input=string output=string [start_points=string] [stop_points=string] [start_rast=string] [coordinate=x,y[,x,y,...]] [stop_coordinate=x,y[,x,y,...]] [max_cost=cost] [null_cost=null cost] [percent_memory=percent memory]

Flags:

"-v
Run verbosely
"-k
Use the 'Knight's move'; slower, but more accurate
"-n
Keep null values in output map
"-r
Start with values in raster map

Parameters:

"input=string
Name of raster map containing grid cell cost information
"output=string
Name of raster map to contain results
"start_points=string
Starting points vector map
"stop_points=string
Stop points vector map
"start_rast=string
Starting points raster file
"coordinate=x,y[,x,y,...]
The map E and N grid coordinates of a starting point (E,N)
"stop_coordinate=x,y[,x,y,...]
The map E and N grid coordinates of a stopping point (E,N)
"max_cost=cost
An optional maximum cumulative cost Default: 0
"null_cost=null Cost assigned to null cells. By default, null cells are excluded
"percent_memory=percent Percent of map to keep in memory Default: 25

DESCRIPTION

r.cost determines the cumulative cost of moving to each cell on a cost surface (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.cost 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.

OPTIONS

r.cost can be run either non-interactively or interactively. 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.

Flags:

"-v
Run verbosely.
"-k
Use the 'Knight's move'; slower, but more accurate.
"-n
Keep null values in output map

Parameters:

"input=name
Name of raster map containing grid cell cost information.
"output=name
Name of raster map to contain results.
"start_sites=name
Starting points site file.
"stop_sites=name
Stop points site file.
"start_rast=name
Starting points raster file.
"coordinate=x,y[,x,y,...]
The map E and N grid coordinates of a starting point (E,N).
"stop_coordinate=x,y[,x,y,...]
The map E and N grid coordinates of a stopping point (E,N).
"max_cost=cost
An optional maximum cumulative cost (default: 0).
"null_value=value
Cost assigned to null cells. By default, null cells are excluded.

The inputname is the name of a raster map layer representing the cost surface map, the output=name is the name of a raster map layer of cumulative 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 start_sites=name option or from a raster map through the start_rast=name option. r.cost will stop cumulating costs when either maxcost is reached, or one of the stop points given with the stop_coordinates=x,y is reached. Alternatively, the stop points can be read from a site file through the stop_sites=name 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 null_value option.

Alternately, the user can simply type r.cost on the command line, without program arguments. In this case, the user will be prompted for parameter values using the standard GRASS parser interface.

r.cost can be run with two different methods of identifying the starting point(s). One or more points (geographic coordinate pairs) can be provided on the command line, sites file or raster map. All non-NULL cells are considered to be starting points.

Flags:

-v

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

-k

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 -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 . . .

. . . . . . . . . . . . . . .

-n

When input map null cells are given a cost with the null_value 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.

Parameters:

input=name

Name of input raster map layer whose category values represent surface cost.

output=name

Name of raster map layer to contain output.

start_sites=name

name is the name of a site file that holds the coordinates of starting points from which the transportation cost should be figured.

stop_sites=name

name 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.

coordinate=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.

stop_coordinate=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.

max_cost=maxcost

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

null_value=value

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

EXAMPLE

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

NULL CELLS

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

If one wants r.cost to transparently cross the null cells, one must use the option null_value=0.0. Then, null cells just propagate adjacent costs. These cells could then be retained as null cells into the output map through the -n flag.

NOTES

Sometimes, when the differences among integer cell category values the r.cost cumulative cost surface output are small, this cumulative cost output cannot accurately be used as input to r.drain (r.drain 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.cost is to be used as input to r.drain, the user multiply the input cost surface map to r.cost by the value of the map's cell resolution, before running r.cost. This can be done using r.mapcalc or other programs. The map resolution can be found using g.region. This problem doesn't arise with floating point maps.

Shortest distance surfaces

The command r.cost 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 rast=roads -p

r.mapcalc "area.one=1"

r.cost -k input=area.one output=distance start_rast=roads

d.rast distance

d.rast.num distance

#transform to metric distances using the raster resolution:

r.mapcalc "dist_meters=distance * (ewres()+nsres())/2."

d.rast dist_meters

Algorithm notes

The fundamental approach to calculating minimum travel cost is as follows: 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 list cells from which costs to the adjacent cells are to be calculated. The cell on the list with the lowest cumulative cost is selected for computing costs to the neighboring cells. Costs are computed and those cells are put on the list 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 list and removing the originating cell from the list continues until the list is empty.

The most time consuming aspect of this algorithm is the management of the list of cells for which cumulative costs have been at least initially computed. r.cost uses a binary tree with an linked list at each node in the tree for efficiently holding cells with identical 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 list 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.

SEE ALSO

g.copy

g.region

g.rename

r.drain

r.in.ascii

r.mapcalc

r.out.ascii

parser

AUTHOR

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)

Last changed: $Date: 2004/07/14 12:06:07 $

Help Index