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 [-knri] input=name output=name [nearest=name] [outdir=name]
17 [start_points=name] [stop_points=name] [start_raster=name]
18 [start_coordinates=east,north[,east,north,...]] [stop_coordi‐
19 nates=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 --overwrite
37 Allow output files to overwrite existing files
38 --help
40 Print usage summary
41 --verbose
43 Verbose module output
44 --quiet
46 Quiet module output
47 --ui
49 Force launching GUI dialog
50 Parameters:
52 input=name [required]
53 Name of input raster map containing grid cell cost information
54 output=name [required]
56 Name for output raster map
57 nearest=name
59 Name for output raster map with nearest start point
60 outdir=name
62 Name for output raster map to contain movement directions
63 start_points=name
65 Name of starting vector points map
66 Or data source for direct OGR access
67 stop_points=name
69 Name of stopping vector points map
70 Or data source for direct OGR access
71 start_raster=name
73 Name of starting raster points map
74 start_coordinates=east,north[,east,north,...]
76 Coordinates of starting point(s) (E,N)
77 stop_coordinates=east,north[,east,north,...]
79 Coordinates of stopping point(s) (E,N)
80 max_cost=value
82 Maximum cumulative cost
83 Default: 0
84 null_cost=value
86 Cost assigned to null cells. By default, null cells are excluded
87 memory=value
89 Maximum memory to be used in MB
90 Default: 300
91
93 r.cost determines the cumulative cost of moving to each cell on a cost
94 surface (the input raster map) from other user-specified cell(s) whose
95 locations are specified by their geographic coordinate(s). Each cell in
96 the original cost surface map will contain a category value which rep‐
97 resents the cost of traversing that cell. r.cost will produce 1) an
98 output raster map in which each cell contains the lowest total cost of
99 traversing the space between each cell and the user-specified points
100 (diagonal costs are multiplied by a factor that depends on the dimen‐
101 sions of the cell) and 2) a second raster map layer showing the move‐
102 ment direction to the next cell on the path back to the start point
103 (see Movement Direction). This module uses the current geographic
104 region settings. The output map will be of the same data format as the
105 input map, integer or floating point.
106
108 The input name is the name of a raster map whose category values repre‐
109 sent the surface cost. The output name is the name of the resultant
110 raster map of cumulative cost. The outdir name is the name of the
111 resultant raster map of movement directions (see Movement Direction).
112 r.cost can be run with three different methods of identifying the
114 starting point(s). One or more points (geographic coordinate pairs) can
115 be provided as specified start_coordinates on the command line, from a
116 vector points file, or from a raster map. All non-NULL cells are con‐
117 sidered to be starting points.
118 Each x,y start_coordinates pair gives the geographic location of a
120 point from which the transportation cost should be figured. As many
121 points as desired can be entered by the user. These starting points can
122 also be read from a vector points file through the start_points option
123 or from a raster map through the start_raster option.
124 r.cost will stop cumulating costs when either max_cost is reached, or
126 one of the stop points given with stop_coordinates is reached. Alter‐
127 natively, the stop points can be read from a vector points file with
128 the stop_points option. During execution, once the cumulative cost to
129 all stopping points has been determined, processing stops.
130 Both sites read from a vector points file and those given on the com‐
131 mand line will be processed.
132 The null cells in the input map can be assigned a (positive floating
134 point) cost with the null_cost option.
135 When input map null cells are given a cost with the null_cost option,
136 the corresponding cells in the output map are no longer null cells. By
137 using the -n flag, the null cells of the input map are retained as null
138 cells in the output map.
139 As r.cost can run for a very long time, it can be useful to use the --v
141 verbose flag to track progress.
142 The Knight’s move (-k flag) may be used to improve the accuracy of the
144 output. In the diagram below, the center location (O) represents a grid
145 cell from which cumulative distances are calculated. Those neighbors
146 marked with an X are always considered for cumulative cost updates.
147 With the -k option, the neighbors marked with a K are also considered.
148 . . . . . . . . . . . . . . .
149 . . . K . . K . . .
150 . . . . . . . . . . . . . . .
151 . . K . X . X . X . K . .
152 . . . . . . . . . . . . . . .
153 . . . X . O . X . . .
154 . . . . . . . . . . . . . . .
155 . . K . X . X . X . K . .
156 . . . . . . . . . . . . . . .
157 . . . K . . K . . .
158 . . . . . . . . . . . . . . .
159 Knight’s move example:
161 Flat cost surface without (left pane) and with the knight’s
163 move (right pane). The default is to grow the cost outwards
164 in 8 directions. Using the knight’s move grows it outwards
165 in 16 directions.
166 If the nearest output parameter is specified, the module will calculate
169 for each cell its nearest starting point based on the minimized accumu‐
170 lative cost while moving over the cost map.
171
173 By default null cells in the input raster map are excluded from the
174 algorithm, and thus retained in the output map.
175 If one wants r.cost to transparently cross any region of null cells,
177 the null_cost=0.0 option should be used. Then null cells just propagate
178 the adjacent costs. These cells can be retained as null cells in the
179 output map by using the -n flag.
180
182 Sometimes, when the differences among integer cell category values in
183 the r.cost cumulative cost surface output are small, this cumulative
184 cost output cannot accurately be used as input to r.drain (r.drain will
185 output bad results). This problem can be circumvented by making the
186 differences between cell category values in the cumulative cost output
187 bigger. It is recommended that, if the output from r.cost is to be used
188 as input to r.drain, the user multiply the input cost surface map to
189 r.cost by the value of the map’s cell resolution, before running
190 r.cost. This can be done using r.mapcalc. The map resolution can be
191 found using g.region. This problem doesn’t arise with floating point
192 maps.
193 Algorithm notes
195 The fundamental approach to calculating minimum travel cost is as fol‐
196 lows:
197 The user generates a raster map indicating the cost of traversing each
199 cell in the north-south and east-west directions. This map, along with
200 a set of starting points are submitted to r.cost. The starting points
201 are put into a list cells from which costs to the adjacent cells are to
202 be calculated. The cell on the list with the lowest cumulative cost is
203 selected for computing costs to the neighboring cells. Costs are com‐
204 puted and those cells are put on the list and the originating cell is
205 finalized. This process of selecting the lowest cumulative cost cell,
206 computing costs to the neighbors, putting the neighbors on the list and
207 removing the originating cell from the list continues until the list is
208 empty.
209 The most time consuming aspect of this algorithm is the management of
211 the list of cells for which cumulative costs have been at least ini‐
212 tially computed. r.cost uses a binary tree with an linked list at each
213 node in the tree for efficiently holding cells with identical cumula‐
214 tive costs.
215 r.cost, like most all GRASS raster programs, is also made to be run on
217 maps larger that can fit in available computer memory. As the algorithm
218 works through the dynamic list of cells it can move almost randomly
219 around the entire area. r.cost divides the entire area into a number of
220 pieces and swaps these pieces in and out of memory (to and from disk)
221 as needed. This provides a virtual memory approach optimally designed
222 for 2-D raster maps. The amount of memory to be used by r.cost can be
223 controlled with the memory option, default is 300 MB. For systems with
224 less memory this value will have to be set to a lower value.
225
227 Consider the following example:
228 Input:
229 COST SURFACE
230 . . . . . . . . . . . . . . .
231 . 2 . 2 . 1 . 1 . 5 . 5 . 5 .
232 . . . . . . . . . . . . . . .
233 . 2 . 2 . 8 . 8 . 5 . 2 . 1 .
234 . . . . . . . . . . . . . . .
235 . 7 . 1 . 1 . 8 . 2 . 2 . 2 .
236 . . . . . . . . . . . . . . .
237 . 8 . 7 . 8 . 8 . 8 . 8 . 5 .
238 . . . . . . . . . . _____ . .
239 . 8 . 8 . 1 . 1 . 5 | 3 | 9 .
240 . . . . . . . . . . |___| . .
241 . 8 . 1 . 1 . 2 . 5 . 3 . 9 .
242 . . . . . . . . . . . . . . .
243 Output (using -k): Output (not using -k):
244 CUMULATIVE COST SURFACE CUMULATIVE COST SURFACE
245 . . . . . . . . . . . . . . . . . . . * * * * * . . . . . .
246 . 21. 21. 20. 19. 17. 15. 14. . 22. 21* 21* 20* 17. 15. 14.
247 . . . . . . . . . . . . . . . . . . . * * * * * . . . . . .
248 . 20. 19. 22. 19. 15. 12. 11. . 20. 19. 22* 20* 15. 12. 11.
249 . . . . . . . . . . . . . . . . . . . . . * * * * * . . . .
250 . 22. 18. 17. 17. 12. 11. 9. . 22. 18. 17* 18* 13* 11. 9.
251 . . . . . . . . . . . . . . . . . . . . . * * * * * . . . .
252 . 21. 14. 13. 12. 8. 6. 6. . 21. 14. 13. 12. 8. 6. 6.
253 . . . . . . . . . . _____. . . . . . . . . . . . . . . . .
254 . 16. 13. 8. 7. 4 | 0 | 6. . 16. 13. 8. 7 . 4. 0. 6.
255 . . . . . . . . . . |___|. . . . . . . . . . . . . . . . .
256 . 14. 9. 8. 9. 6. 3. 8. . 14. 9. 8. 9 . 6. 3. 8.
257 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
258 The user-provided starting location in the above example is the boxed 3
260 in the above input map. The costs in the output map represent the total
261 cost of moving from each box ("cell") to one or more (here, only one)
262 starting location(s). Cells surrounded by asterisks are those that are
263 different between operations using and not using the Knight’s move (-k)
264 option.
265 Output analysis
267 The output map can be viewed, for example, as an elevation model in
268 which the starting location(s) is/are the lowest point(s). Outputs from
269 r.cost can be used as inputs to r.drain with the direction flag -d, in
270 order to trace the least-cost path given by this model between any
271 given cell and the r.cost starting location(s). The two programs, when
272 used together, generate least-cost paths or corridors between any two
273 map locations (cells).
274 Shortest distance surfaces
276 The r.cost module allows for computing the shortest distance of each
277 pixel from raster lines, such as determining the shortest distances of
278 households to the nearby road. For this cost surfaces with cost value 1
279 are used. The calculation is done with r.cost as follows (example for
280 Spearfish region):
281 g.region raster=roads -p
282 r.mapcalc "area.one = 1"
283 r.cost -k input=area.one output=distance start_raster=roads
284 d.rast distance
285 d.rast.num distance
286 #transform to metric distance from cell distance using the raster resolution:
287 r.mapcalc "dist_meters = distance * (ewres()+nsres())/2."
288 d.rast dist_meters
289
291 The movement direction surface is created to record the sequence of
292 movements that created the cost accumulation surface. Without it
293 r.drain would not correctly create a path from an end point back to the
294 start point. The direction of each cell points towards the next cell.
295 The directions are recorded as degrees CCW from East:
296 112.5 67.5 i.e. a cell with the value 135
297 157.5 135 90 45 22.5 means the next cell is to the north-west
298 180 x 360
299 202.5 225 270 315 337.5
300 247.5 292.5
301 Cost allocation
303 Example: calculation of the cost allocation map "costalloc" and the
304 cumulative cost map "costsurf" for given starting points (map
305 "sources") and given cost raster map "costs":
306 r.cost input=costs start_raster=sources output=costsurf nearest=costalloc
307 Find the minimum cost path
309 Once r.cost computes the cumulative cost map, r.drain can be used to
310 find the minimum cost path. Make sure to use the -d flag and the move‐
311 ment direction raster map when running r.drain to ensure the path is
312 computed according to the proper movement directions.
313
315 r.drain, r.walk, r.in.ascii, r.mapcalc, r.out.ascii
316
318 Antony Awaida, Intelligent Engineering Systems Laboratory, M.I.T.
319 James Westervelt, U.S.Army Construction Engineering Research Laboratory
320 Updated for Grass 5 by Pierre de Mouveaux (pmx@audiovu.com)
321 Last changed: $Date: 2015-01-23 20:38:50 +0100 (Fri, 23 Jan 2015) $
323
325 Available at: r.cost source code (history)
326 Main index | Raster index | Topics index | Keywords index | Graphical
328 index | Full index
329 © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
331GRASS 7.4.4 r.cost(1)