1r.cost(1) Grass User's Manual r.cost(1)
2
6 r.cost - Outputs a raster map layer showing the cumulative cost of
7 moving between different geographic locations on an input raster map
8 layer whose cell category values represent cost.
9
11 raster, cost surface, cumulative costs
12
14 r.cost
15 r.cost help
16 r.cost [-knrv] input=name output=name [start_points=string]
17 [stop_points=string] [start_rast=string] [coordinate=x,y[,x,y,...]]
18 [stop_coordinate=x,y[,x,y,...]] [max_cost=cost] [null_cost=null
19 cost] [percent_memory=percent memory] [--overwrite] [--verbose]
20 [--quiet]
21 Flags:
23 -k
24 Use the 'Knight's move'; slower, but more accurate
25 -n
27 Keep null values in output map
28 -r
30 Start with values in raster map
31 -v
33 Run verbosely
34 --overwrite
36 Allow output files to overwrite existing files
37 --verbose
39 Verbose module output
40 --quiet
42 Quiet module output
43 Parameters:
45 input=name
46 Name of raster map containing grid cell cost information
47 output=name
49 Name for output raster map
50 start_points=string
52 Starting points vector map
53 stop_points=string
55 Stop points vector map
56 start_rast=string
58 Starting points raster map
59 coordinate=x,y[,x,y,...]
61 The map E and N grid coordinates of a starting point (E,N)
62 stop_coordinate=x,y[,x,y,...]
64 The map E and N grid coordinates of a stopping point (E,N)
65 max_cost=cost
67 An optional maximum cumulative cost
68 Default: 0
69 null_cost=null cost
71 Cost assigned to null cells. By default, null cells are excluded
72 percent_memory=percent memory
74 Percent of map to keep in memory
75 Default: 100
76
78 r.cost determines the cumulative cost of moving to each cell on a cost
79 surface (the input raster map) from other user-specified cell(s) whose
80 locations are specified by their geographic coordinate(s). Each cell in
81 the original cost surface map will contain a category value which rep‐
82 resents the cost of traversing that cell. r.cost will produce an output
83 raster map in which each cell contains the lowest total cost of
84 traversing the space between each cell and the user-specified points.
85 (Diagonal costs are multiplied by a factor that depends on the dimen‐
86 sions of the cell.) This program uses the current geographic region
87 settings. The output map will be of the same data format as the input
88 map, integer or floating point.
89
91 The input name is the name of a raster map whose category values repre‐
92 sent the surface cost. The output name is the name of the resultant
93 raster map of cumulative cost.
94 r.cost can be run with three different methods of identifying the
96 starting point(s). One or more points (geographic coordinate pairs) can
97 be provided as specified coordinates on the command line, from a vector
98 points file, or from a raster map. All non-NULL cells are considered
99 to be starting points. Each x,y coordinate pair gives the geographic
100 location of a point from which the transportation cost should be fig‐
101 ured. As many points as desired can be entered by the user. These
102 starting points can also be read from a vector points file through the
103 start_sites option or from a raster map through the start_rast option.
104 r.cost will stop cumulating costs when either max_cost is reached, or
106 one of the stop points given with stop_coordinates is reached. Alter‐
107 natively, the stop points can be read from a vector points file with
108 the stop_sites option. During execution, once the cumulative cost to
109 all stopping points has been determined, processing stops. Both sites
110 read from a vector points file and those given on the command line will
111 be processed.
112 The null cells in the input map can be assigned a (positive floating
114 point) cost with the null_cost option.
115 When input map null cells are given a cost with the null_cost option,
116 the corresponding cells in the output map are no longer null cells. By
117 using the -n flag, the null cells of the input map are retained as null
118 cells in the output map.
119 As r.cost can run for a very long time, it can be useful to use the -v
121 verbose flag to track progress.
122 The Knight's move (-k flag) may be used to improve the accuracy of the
124 output. In the diagram below, the center location (O) represents a grid
125 cell from which cumulative distances are calculated. Those neighbors
126 marked with an X are always considered for cumulative cost updates.
127 With the -k option, the neighbors marked with a K are also considered.
128 . . . . . . . . . . . . . . .
129 . . . K . . K . . .
130 . . . . . . . . . . . . . . .
131 . . K . X . X . X . K . .
132 . . . . . . . . . . . . . . .
133 . . . X . O . X . . .
134 . . . . . . . . . . . . . . .
135 . . K . X . X . X . K . .
136 . . . . . . . . . . . . . . .
137 . . . K . . K . . .
138 . . . . . . . . . . . . . . .
139 Knight's move example:
141 | Flat cost surface without (left pane) and with the knight's move
142 (right pane). The default is to grow the cost outwards in 8 direc‐
143 tions. Using the knight's move grows it outwards in 16 directions.
144
146 By default null cells in the input raster map are excluded from the
147 algorithm, and thus retained in the output map.
148 If one wants r.cost to transparently cross any region of null cells,
150 the null_cost=0.0 option should be used. Then null cells just propagate
151 the adjacent costs. These cells can be retained as null cells in the
152 output map by using the -n flag.
153
155 Sometimes, when the differences among integer cell category values in
156 the r.cost cumulative cost surface output are small, this cumulative
157 cost output cannot accurately be used as input to r.drain (r.drain will
158 output bad results). This problem can be circumvented by making the
159 differences between cell category values in the cumulative cost output
160 bigger. It is recommended that, if the output from r.cost is to be used
161 as input to r.drain, the user multiply the input cost surface map to
162 r.cost by the value of the map's cell resolution, before running
163 r.cost. This can be done using r.mapcalc. The map resolution can be
164 found using g.region. This problem doesn't arise with floating point
165 maps.
166 Algorithm notes
168 The fundamental approach to calculating minimum travel cost is as fol‐
169 lows:
170 The user generates a raster map indicating the cost of traversing each
172 cell in the north-south and east-west directions. This map, along with
173 a set of starting points are submitted to r.cost. The starting points
174 are put into a list cells from which costs to the adjacent cells are to
175 be calculated. The cell on the list with the lowest cumulative cost is
176 selected for computing costs to the neighboring cells. Costs are com‐
177 puted and those cells are put on the list and the originating cell is
178 finalized. This process of selecting the lowest cumulative cost cell,
179 computing costs to the neighbors, putting the neighbors on the list and
180 removing the originating cell from the list continues until the list is
181 empty.
182 The most time consuming aspect of this algorithm is the management of
184 the list of cells for which cumulative costs have been at least ini‐
185 tially computed. r.cost uses a binary tree with an linked list at each
186 node in the tree for efficiently holding cells with identical cumula‐
187 tive costs.
188 r.cost, like most all GRASS raster programs, is also made to be run on
190 maps larger that can fit in available computer memory. As the algorithm
191 works through the dynamic list of cells it can move almost randomly
192 around the entire area. r.cost divides the entire area into a number of
193 pieces and swaps these pieces in and out of memory (to and from disk)
194 as needed. This provides a virtual memory approach optimally designed
195 for 2-D raster maps. The amount of map to hold in memory at one time
196 can be controlled with the percent_memory option. For large maps this
197 value will have to be set to a lower value.
198
200 Consider the following example:
201 Input:
202 COST SURFACE
203 . . . . . . . . . . . . . . .
204 . 2 . 2 . 1 . 1 . 5 . 5 . 5 .
205 . . . . . . . . . . . . . . .
206 . 2 . 2 . 8 . 8 . 5 . 2 . 1 .
207 . . . . . . . . . . . . . . .
208 . 7 . 1 . 1 . 8 . 2 . 2 . 2 .
209 . . . . . . . . . . . . . . .
210 . 8 . 7 . 8 . 8 . 8 . 8 . 5 .
211 . . . . . . . . . . _____ . .
212 . 8 . 8 . 1 . 1 . 5 | 3 | 9 .
213 . . . . . . . . . . |___| . .
214 . 8 . 1 . 1 . 2 . 5 . 3 . 9 .
215 . . . . . . . . . . . . . . .
216 Output (using -k): Output (not using -k):
217 CUMULATIVE COST SURFACE CUMULATIVE COST SURFACE
218 . . . . . . . . . . . . . . . . . . . * * * * * . . . . . .
219 . 21. 21. 20. 19. 17. 15. 14. . 22. 21* 21* 20* 17. 15. 14.
220 . . . . . . . . . . . . . . . . . . . * * * * * . . . . . .
221 . 20. 19. 22. 19. 15. 12. 11. . 20. 19. 22* 20* 15. 12. 11.
222 . . . . . . . . . . . . . . . . . . . . . * * * * * . . . .
223 . 22. 18. 17. 17. 12. 11. 9. . 22. 18. 17* 18* 13* 11. 9.
224 . . . . . . . . . . . . . . . . . . . . . * * * * * . . . .
225 . 21. 14. 13. 12. 8. 6. 6. . 21. 14. 13. 12. 8. 6. 6.
226 . . . . . . . . . . _____. . . . . . . . . . . . . . . . .
227 . 16. 13. 8. 7. 4 | 0 | 6. . 16. 13. 8. 7 . 4. 0. 6.
228 . . . . . . . . . . |___|. . . . . . . . . . . . . . . . .
229 . 14. 9. 8. 9. 6. 3. 8. . 14. 9. 8. 9 . 6. 3. 8.
230 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
231 The user-provided ending location in the above example is the boxed 3
234 in the above input map. The costs in the output map represent the total
235 cost of moving from each box ("cell") to one or more (here, only one)
236 starting location(s). Cells surrounded by asterisks are those that are
237 different between operations using and not using the Knight's move (-k)
238 option.
239 Output analysis
241 The output map can be viewed, for example, as an elevation model in
242 which the starting location(s) is/are the lowest point(s). Outputs from
243 r.cost can be used as inputs to r.drain, in order to trace the least-
244 cost path given by this model between any given cell and the r.cost
245 starting location(s). The two programs, when used together, generate
246 least-cost paths or corridors between any two map locations (cells).
247 Shortest distance surfaces
249 The r.cost module allows for computing the shortest distance of each
250 pixel from raster lines, such as determining the shortest distances of
251 households to the nearby road. For this cost surfaces with cost value 1
252 are used. The calculation is done with r.cost as follows (example for
253 Spearfish region):
254 g.region rast=roads -p
255 r.mapcalc "area.one=1"
256 r.cost -k input=area.one output=distance start_rast=roads
257 d.rast distance
258 d.rast.num distance
259 #transform to metric distance from cell distance using the raster
260 resolution:
261 r.mapcalc "dist_meters=distance * (ewres()+nsres())/2."
262 d.rast dist_meters
263
266 The percentage done calculation reported in verbose mode is often not
267 linear and ends well before 100%. This does not affect output.
268
270 r.drain, r.walk, r.in.ascii, r.mapcalc, r.out.ascii
271
273 Antony Awaida,
274 Intelligent Engineering
275 Systems Laboratory,
276 M.I.T.
277 James Westervelt,
278 U.S.Army Construction Engineering Research Laboratory
279 Updated for Grass 5
281 Pierre de Mouveaux (pmx@audiovu.com)
282 Last changed: $Date: 2006-04-18 04:55:35 +0200 (Tue, 18 Apr 2006) $
284 Full index
286 © 2003-2008 GRASS Development Team
288GRASS 6.3.0 r.cost(1)