1r.cost(1) Grass User's Manual r.cost(1)
2
6 r.cost - Creates a raster map showing the cumulative cost of moving
7 between different geographic locations on an input raster map whose
8 cell category values represent cost.
9
11 raster, cost surface, cumulative costs, cost allocation
12
14 r.cost
15 r.cost --help
16 r.cost [-knrib] input=name output=name [solver=name] [nearest=name]
17 [outdir=name] [start_points=name] [stop_points=name]
18 [start_raster=name] [start_coordinates=east,north[,east,north,...]]
19 [stop_coordinates=east,north[,east,north,...]] [max_cost=value]
20 [null_cost=value] [memory=value] [--overwrite] [--help] [--ver‐
21 bose] [--quiet] [--ui]
22 Flags:
24 -k
25 Use the ’Knight’s move’; slower, but more accurate
26 -n
28 Keep null values in output raster map
29 -r
31 Start with values in raster map
32 -i
34 Print info about disk space and memory requirements and exit
35 -b
37 Create bitmask encoded directions
38 --overwrite
40 Allow output files to overwrite existing files
41 --help
43 Print usage summary
44 --verbose
46 Verbose module output
47 --quiet
49 Quiet module output
50 --ui
52 Force launching GUI dialog
53 Parameters:
55 input=name [required]
56 Name of input raster map containing grid cell cost information
57 output=name [required]
59 Name for output raster map
60 solver=name
62 Name of input raster map solving equal costs
63 Helper variable to pick a direction if two directions have equal
64 cumulative costs (smaller is better)
65 nearest=name
67 Name for output raster map with nearest start point
68 outdir=name
70 Name for output raster map to contain movement directions
71 start_points=name
73 Name of starting vector points map
74 Or data source for direct OGR access
75 stop_points=name
77 Name of stopping vector points map
78 Or data source for direct OGR access
79 start_raster=name
81 Name of starting raster points map
82 start_coordinates=east,north[,east,north,...]
84 Coordinates of starting point(s) (E,N)
85 stop_coordinates=east,north[,east,north,...]
87 Coordinates of stopping point(s) (E,N)
88 max_cost=value
90 Maximum cumulative cost
91 Default: 0
92 null_cost=value
94 Cost assigned to null cells. By default, null cells are excluded
95 memory=value
97 Maximum memory to be used in MB
98 Default: 300
99
101 r.cost determines the cumulative cost of moving to each cell on a cost
102 surface (the input raster map) from other user-specified cell(s) whose
103 locations are specified by their geographic coordinate(s). Each cell in
104 the original cost surface map will contain a category value which rep‐
105 resents the cost of traversing that cell. r.cost will produce 1) an
106 output raster map in which each cell contains the lowest total cost of
107 traversing the space between each cell and the user-specified points
108 (diagonal costs are multiplied by a factor that depends on the dimen‐
109 sions of the cell) and 2) a second raster map layer showing the move‐
110 ment direction to the next cell on the path back to the start point
111 (see Movement Direction). This module uses the current geographic
112 region settings. The output map will be of the same data format as the
113 input map, integer or floating point.
114
116 The input name is the name of a raster map whose category values repre‐
117 sent the surface cost. The output name is the name of the resultant
118 raster map of cumulative cost. The outdir name is the name of the
119 resultant raster map of movement directions (see Movement Direction).
120 r.cost can be run with three different methods of identifying the
122 starting point(s). One or more points (geographic coordinate pairs) can
123 be provided as specified start_coordinates on the command line, from a
124 vector points file, or from a raster map. All non-NULL cells are con‐
125 sidered to be starting points.
126 Each x,y start_coordinates pair gives the geographic location of a
128 point from which the transportation cost should be figured. As many
129 points as desired can be entered by the user. These starting points can
130 also be read from a vector points file through the start_points option
131 or from a raster map through the start_raster option.
132 r.cost will stop cumulating costs when either max_cost is reached, or
134 one of the stop points given with stop_coordinates is reached. Alter‐
135 natively, the stop points can be read from a vector points file with
136 the stop_points option. During execution, once the cumulative cost to
137 all stopping points has been determined, processing stops.
138 Both sites read from a vector points file and those given on the com‐
139 mand line will be processed.
140 The null cells in the input map can be assigned a (positive floating
142 point) cost with the null_cost option.
143 When input map null cells are given a cost with the null_cost option,
144 the corresponding cells in the output map are no longer null cells. By
145 using the -n flag, the null cells of the input map are retained as null
146 cells in the output map.
147 As r.cost can run for a very long time, it can be useful to use the --v
149 verbose flag to track progress.
150 The Knight’s move (-k flag) may be used to improve the accuracy of the
152 output. In the diagram below, the center location (O) represents a grid
153 cell from which cumulative distances are calculated. Those neighbors
154 marked with an X are always considered for cumulative cost updates.
155 With the -k option, the neighbors marked with a K are also considered.
156 . . . . . . . . . . . . . . .
157 . . . K . . K . . .
158 . . . . . . . . . . . . . . .
159 . . K . X . X . X . K . .
160 . . . . . . . . . . . . . . .
161 . . . X . O . X . . .
162 . . . . . . . . . . . . . . .
163 . . K . X . X . X . K . .
164 . . . . . . . . . . . . . . .
165 . . . K . . K . . .
166 . . . . . . . . . . . . . . .
167 Knight’s move example:
169 Flat cost surface without (left pane) and with the knight’s
171 move (right pane). The default is to grow the cost outwards
172 in 8 directions. Using the knight’s move grows it outwards
173 in 16 directions.
174 If the nearest output parameter is specified, the module will calculate
177 for each cell its nearest starting point based on the minimized accumu‐
178 lative cost while moving over the cost map.
179 The solver option helps to select a particular direction in case of
181 multiple directions with equal costs. Sometimes fields with equal cumu‐
182 lative costs exist and multiple paths with equal costs would lead from
183 a start point to a stop point. By default, a path along the edge of
184 such a field would be produced or multiple paths of equal costs with
185 the -b flag. An additional variable can be supplied with the solver
186 option to help the algorithm pick a particular direction.
187 Example for solving multiple directions:
189 A field of equal cumulative costs with multiple paths
191 (black). By default a path along the edge will be selected
192 (red). Path selection can be controlled with the solver
193 option (blue).
194
197 By default null cells in the input raster map are excluded from the
198 algorithm, and thus retained in the output map.
199 If one wants r.cost to transparently cross any region of null cells,
201 the null_cost=0.0 option should be used. Then null cells just propagate
202 the adjacent costs. These cells can be retained as null cells in the
203 output map by using the -n flag.
204
206 Paths from any point to the nearest starting point of r.cost can be
207 extracted with r.path by using the direction output map of r.cost.
208 Algorithm notes
210 The fundamental approach to calculating minimum travel cost is as fol‐
211 lows:
212 The user generates a raster map indicating the cost of traversing each
214 cell in the north-south and east-west directions. This map, along with
215 a set of starting points are submitted to r.cost. The starting points
216 are put into a heap of cells from which costs to the adjacent cells are
217 to be calculated. The cell on the heap with the lowest cumulative cost
218 is selected for computing costs to the neighboring cells. Costs are
219 computed and those cells are put on the heap and the originating cell
220 is finalized. This process of selecting the lowest cumulative cost
221 cell, computing costs to the neighbors, putting the neighbors on the
222 heap and removing the originating cell from the heap continues until
223 the heap is empty.
224 The most time consuming aspect of this algorithm is the management of
226 the heap of cells for which cumulative costs have been at least ini‐
227 tially computed. r.cost uses a minimum heap for efficiently tracking
228 the next cell with the lowest cumulative costs.
229 r.cost, like most all GRASS raster programs, is also made to be run on
231 maps larger that can fit in available computer memory. As the algorithm
232 works through the dynamic heap of cells it can move almost randomly
233 around the entire area. r.cost divides the entire area into a number of
234 pieces and swaps these pieces in and out of memory (to and from disk)
235 as needed. This provides a virtual memory approach optimally designed
236 for 2-D raster maps. The amount of memory to be used by r.cost can be
237 controlled with the memory option, default is 300 MB. For systems with
238 less memory this value will have to be set to a lower value.
239
241 Consider the following example:
242 Input:
243 COST SURFACE
244 . . . . . . . . . . . . . . .
245 . 2 . 2 . 1 . 1 . 5 . 5 . 5 .
246 . . . . . . . . . . . . . . .
247 . 2 . 2 . 8 . 8 . 5 . 2 . 1 .
248 . . . . . . . . . . . . . . .
249 . 7 . 1 . 1 . 8 . 2 . 2 . 2 .
250 . . . . . . . . . . . . . . .
251 . 8 . 7 . 8 . 8 . 8 . 8 . 5 .
252 . . . . . . . . . . _____ . .
253 . 8 . 8 . 1 . 1 . 5 | 3 | 9 .
254 . . . . . . . . . . |___| . .
255 . 8 . 1 . 1 . 2 . 5 . 3 . 9 .
256 . . . . . . . . . . . . . . .
257 Output (using -k): Output (not using -k):
258 CUMULATIVE COST SURFACE CUMULATIVE COST SURFACE
259 . . . . . . . . . . . . . . . . . . . * * * * * . . . . . .
260 . 21. 21. 20. 19. 17. 15. 14. . 22. 21* 21* 20* 17. 15. 14.
261 . . . . . . . . . . . . . . . . . . . * * * * * . . . . . .
262 . 20. 19. 22. 19. 15. 12. 11. . 20. 19. 22* 20* 15. 12. 11.
263 . . . . . . . . . . . . . . . . . . . . . * * * * * . . . .
264 . 22. 18. 17. 17. 12. 11. 9. . 22. 18. 17* 18* 13* 11. 9.
265 . . . . . . . . . . . . . . . . . . . . . * * * * * . . . .
266 . 21. 14. 13. 12. 8. 6. 6. . 21. 14. 13. 12. 8. 6. 6.
267 . . . . . . . . . . _____. . . . . . . . . . . . . . . . .
268 . 16. 13. 8. 7. 4 | 0 | 6. . 16. 13. 8. 7 . 4. 0. 6.
269 . . . . . . . . . . |___|. . . . . . . . . . . . . . . . .
270 . 14. 9. 8. 9. 6. 3. 8. . 14. 9. 8. 9 . 6. 3. 8.
271 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
272 The user-provided starting location in the above example is the boxed 3
274 in the above input map. The costs in the output map represent the total
275 cost of moving from each box ("cell") to one or more (here, only one)
276 starting location(s). Cells surrounded by asterisks are those that are
277 different between operations using and not using the Knight’s move (-k)
278 option.
279 Output analysis
281 The output map can be viewed, for example, as an elevation model in
282 which the starting location(s) is/are the lowest point(s). Outputs from
283 r.cost can be used as inputs to r.path , in order to trace the
284 least-cost path given by this model between any given cell and the
285 r.cost starting location(s). The two programs, when used together, gen‐
286 erate least-cost paths or corridors between any two map locations
287 (cells).
288 Shortest distance surfaces
290 The r.cost module allows for computing the shortest distance of each
291 pixel from raster lines, such as determining the shortest distances of
292 households to the nearby road. For this cost surfaces with cost value 1
293 are used. The calculation is done with r.cost as follows (example for
294 Spearfish region):
295 g.region raster=roads -p
296 r.mapcalc "area.one = 1"
297 r.cost -k input=area.one output=distance start_raster=roads
298 d.rast distance
299 d.rast.num distance
300 #transform to metric distance from cell distance using the raster resolution:
301 r.mapcalc "dist_meters = distance * (ewres()+nsres())/2."
302 d.rast dist_meters
303
305 The movement direction surface is created to record the sequence of
306 movements that created the cost accumulation surface. This movement
307 direction surface can be used by r.path to recover a path from an end
308 point back to the start point. The direction of each cell points
309 towards the next cell. The directions are recorded as degrees CCW from
310 East:
311 112.5 67.5 i.e. a cell with the value 135
312 157.5 135 90 45 22.5 means the next cell is to the north-west
313 180 x 360
314 202.5 225 270 315 337.5
315 247.5 292.5
316 Cost allocation
318 Example: calculation of the cost allocation map "costalloc" and the
319 cumulative cost map "costsurf" for given starting points (map
320 "sources") and given cost raster map "costs":
321 r.cost input=costs start_raster=sources output=costsurf nearest=costalloc
322 Find the minimum cost path
324 Once r.cost computes the cumulative cost map and an associated movement
325 direction map, r.path can be used to find the minimum cost path.
326
328 r.walk, r.path, r.in.ascii, r.mapcalc, r.out.ascii
329
331 Antony Awaida, Intelligent Engineering Systems Laboratory, M.I.T.
332 James Westervelt, U.S.Army Construction Engineering Research Laboratory
333 Updated for Grass 5 by Pierre de Mouveaux (pmx@audiovu.com)
334 Markus Metz
335 Multiple path directions sponsored by mundialis
336
338 Available at: r.cost source code (history)
339 Main index | Raster index | Topics index | Keywords index | Graphical
341 index | Full index
342 © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
344GRASS 7.8.2 r.cost(1)