Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision | |||
|
calc_cost_map [2026/06/29 14:57] chrystian Add usage examples to functor documentation |
calc_cost_map [2026/08/28 02:24] (current) hermann Sync from local documentation review |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ===== Description ===== | ===== Description ===== | ||
| - | This functor calculates an accumulated cost surface from source features using a friction map. | + | This functor calculates an accumulated cost surface from source features, using a friction map. |
| ===== Inputs ===== | ===== Inputs ===== | ||
| ^ Name ^ Type ^ Description ^ | ^ Name ^ Type ^ Description ^ | ||
| - | | Sources | [[Map Type]] | Source feature map. A map of non-null cells representing source features. If null value is not defined, an error will be reported. | | + | | Sources | [[Map Type]] | Map whose non-null cells correspond to source features. If Sources does not define a null value, this functor reports an error. | |
| - | | Frictions | [[Map Type]] | Map expressing the difficulty to cross each cell. Difficulty is proportional to the cell value. An insurmountable cell can be represented by very high value. Null value cells will be passed to the cost map. Friction values must be positive, otherwise an error will be reported. | | + | | Frictions | [[Map Type]] | Map expressing the difficulty of crossing each cell. The difficulty is proportional to the cell value; for a cell to be treated as impassable it must have a value much greater than the others. Null-value cells in Frictions produce null-value cells in the cost map. Negative or zero friction values that do not correspond to Frictions' null value are not allowed, and reported as an error during execution. | |
| - | | Also Calculate Cost Direction Map | [[Boolean Value Type]] | If true, the cost direction map will also be generated during the cost calculation and placed in the "Directions" output port. Otherwise, that output port will be left empty. Directions are represented using a Moore neighborhood (NONE=0, NW=1, N=2, NE=3, E=4, SE=5, S=6, SW=7, and W=8). | | + | | Also Calculate Cost Direction Map | [[Boolean Value Type]] | If true, the cost direction map is also calculated and placed in Directions; otherwise, Directions is left empty. Directions are represented using a Moore neighborhood: None=0, NW=1, N=2, NE=3, E=4, SE=5, S=6, SW=7, and W=8. | |
| ===== Optional Inputs ===== | ===== Optional Inputs ===== | ||
| - | ^ Name ^ Type ^ Description ^ Default Value ^ | + | ^ Name ^ Type ^ Description ^ Default Value ^ |
| - | | Cell Type | [[Cell Type Type]] | Data cell type of the cost map must be compatible to the source feature and friction data cell types, otherwise an error will be reported. | Signed 32 Bit Integer | | + | | Cell Type | [[Cell Type Type]] | Cell type of the cost map. It must be compatible with the values in Sources and Frictions, or this functor reports an error during execution. | Signed 32 Bit Integer | |
| - | | Null Value | [[Null Value Type]] | Null value of the cost map. This value cannot be equal to zero because zero value represents source features on the cost map. If it is set to zero, an error will be reported. | Default((Based on the value of the Cell Type input.)) | | + | | Null Value | [[Null Value Type]] | Null value of the cost map. It cannot be 0, since that value is used to indicate source features on the cost map; using 0 is reported as an error during execution. | .default | |
| - | | Diagonals Cost More | [[Boolean Value Type]] | If true, diagonal movements are more expensive than orthogonal movements (horizontal / vertical). In this case, the cost of a diagonal movement is multiplied by 1.414213562. | True | | + | | Diagonals Cost More | [[Boolean Value Type]] | If true, diagonal movements cost more than orthogonal (horizontal/vertical) movements: a diagonal movement's cost is multiplied by 1.414213562. This is an advanced port. | Yes | |
| - | | Maximum Number Of Passes | [[Non Negative Integer Value Type]] | Maximum number of passes that are used to calculate the cost map. The value 0 (zero) indicates that this functor will execute as many steps as needed in order to produce the best cost (optimized) map. Usually two passes are enough to produce optimized cost maps. | 0 | | + | | Maximum Number Of Passes | [[Non Negative Integer Value Type]] | Maximum number of passes used to calculate the cost map. 0 means as many passes as needed to obtain the optimal cost map are performed. This is an advanced port. | 0 | |
| - | | Frictions Are Relative | [[Boolean Value Type]] | If true, the friction values are relative to map resolution and represent friction units per meter. In this case, the friction values are automatically multiplied by the cell resolution (in meters). | False | | + | | Frictions Are Relative | [[Boolean Value Type]] | If true, the friction values are relative to the map resolution and represent units per meter; in this case, they are automatically multiplied by the cell resolution, in meters. This is an advanced port. | No | |
| ===== Outputs ===== | ===== Outputs ===== | ||
| ^ Name ^ Type ^ Description ^ | ^ Name ^ Type ^ Description ^ | ||
| - | | Costs | [[Map Type]] | Accumulated cost surface map from each feature source. Output map has the same dimensions of the source feature map. | | + | | Costs | [[Map Type]] | Map of the cost to reach one of the source features from any point. Costs has the same dimensions as Sources. | |
| - | | Directions | [[Map Type]] | Map showing the directions following the least costly path in the cost map. Directions are represented using Moore neighborhood (NONE=0, NW=1, N=2, NE=3, E=4, SE=5, S=6, SW=7, and W=8). | | + | | Directions | [[Map Type]] | Map of the direction toward the least-cost neighboring cell from any point. Directions has the same dimensions as Sources, and only has a value when Also Calculate Cost Direction Map is true; otherwise it is left empty. | |
| ===== Group ===== | ===== Group ===== | ||
| - | [[Functor List#Map Algebra|Map Algebra]] | + | [[Functor List#Map Algebra | Map Algebra]] |
| ===== Notes ===== | ===== Notes ===== | ||
| - | [{{ :cost_calculation_example.png?nolink&600 |Cost calculation example}}] | + | The cost-map algorithm is "Push broom," though its spatial performance approximates the so-called "Pushgrow" algorithm, especially when using two or more passes. |
| - | The algorithm that calculates the cost map is general type of "Pushbroom". However, its spatial performance approximates to the so called "Pushgrow" algorithm, especially when using two or more passes. | + | Penalizing diagonal movements is effective only when cell dimensions (width and height) are taken into account in the cost calculation, friction values are high, or the cost map uses real-numbered cells. |
| - | Penalization for diagonal movements is effective only when the cell dimensions (width and height) are considered in the calculation of cost, friction values are high, or the cost map is represented using real numbers. | + | A Sources or Frictions map with real-numbered cells requires a cost map with real-numbered cells, or this functor may report an error retrieving a friction or source-feature value. |
| - | A friction map with cells represented by real numbers requires a cost map with cells represented by real numbers or an error will be reported. | + | Each "pass" used to calculate the cost map actually corresponds to four passes, one in each of the four cardinal directions. |
| - | Each pass used to calculate the cost map corresponds to four map passes originating from opposite directions. | + | Parts of the friction map that are unreachable from every source feature are excluded from the cost map, and represented there by the null value. Costs are not accumulated across null-value cells, so a region entirely surrounded by null-value cells will not have its costs calculated unless a source feature lies inside that region. |
| - | + | ||
| - | Unreachable places on the friction map are excluded on the cost map and thus represented as null value cells. Costs are not accumulated across null value cells, thus regions surrounded by null value cells will not have their cell costs calculated, unless there is a source feature inside this region. | + | |
| - | + | ||
| - | [{{ :cost_calculation_theory1.png?nolink&500 |Math behind cost calculation}}] | + | |
| - | [{{ :cost_calculation_theory2.png?nolink&500 |Cost calculation passes}}] | + | |
| ===== Internal Name ===== | ===== Internal Name ===== | ||
| Line 55: | Line 50: | ||
| See practical examples of this functor in [[lesson_17|Lesson 17: Building a land-use and land-cover change simulation model]] | See practical examples of this functor in [[lesson_17|Lesson 17: Building a land-use and land-cover change simulation model]] | ||
| + | |||