raster_tools.distance.cost_distance_analysis#

raster_tools.distance.cost_distance_analysis(costs, sources, elevation=None, connectivity=8)[source]#

Calculate accumulated cost distance, traceback, and allocation.

This function uses Dijkstra’s algorithm to compute the many-sources shortest-paths solution for a given cost surface. Valid moves are from a given pixel to its 8 nearest neighbors (or, with connectivity=4, to the 4 orthogonal neighbors only). This produces 3 rasters. The first is the accumulated cost distance, which contains the distance-weighted accumulated minimum cost to each pixel. The cost to move from one pixel to the next is length * mean(costs[i], costs[i+1]), where length is 1 for horizontal and vertical moves and sqrt(2) for diagonal moves. The costs raster’s resolution informs the actual scaling to use. Source locations have a cost of 0. If elevation provided, the length calculation incorporates the elevation data to make the algorithm 3D aware. Cells that cannot be reached by any source, along with cells that are null in costs, are null in all three output rasters. This matches the convention used by other GIS tools such as ESRI and GRASS.

The second raster contains the traceback values for the solution. At each pixel, the stored value indicates the neighbor to move to in order to get closer to the cost-relative nearest source. The numbering is as follows:

6  7  8
5  X  1
4  3  2

Here, X indicates the current pixel and the numbers are the neighbor pixel positions. 1 indicates the neighbor immediately to the right and 7 indicates the neighbor immediately above. In terms of rows and columns, these are the neighbor +1 column over and +1 row above, respectively. a value of 0 indicates that the current pixel is a source pixel and -1 indicates that the pixel was not traversed due to a null value. With connectivity=4 only the orthogonal codes {1, 3, 5, 7} (1=right, 3=down, 5=left, 7=up) appear. 4-connectivity prevents paths from corner-cutting diagonally between adjacent barrier or null cells.

The third raster contains the source allocation for each pixel. Each pixel is labeled based on the source location that is closest in terms of cost distance. The label is the value stored in the sources raster at the corresponding source location.

Parameters

  • costs (Raster or raster path) – A raster representing a cost surface. Values less than 0 are treated as null values.

  • sources (Raster or raster path, or sequence) – A raster or sequence of indices. If a raster, pixels that are not null are used as source locations. The raster must have a null value set. The values at valid locations are used as the corresponding values in the allocation output. If a sequence, must have shape (M, 2) where M is the number of source pixels. Each item represents an index into costs to be used as a source. The element number, starting at 0, is used as the corresponding allocation value.

  • elevation (Raster or raster path, optional) – A raster containing elevation values on the same grid as costs. If provided, the elevation values are used when calculating the travel distance between pixels. This makes the algorithm 3D aware.

  • connectivity (int, optional) – The number of neighbor moves to allow. 8 (default) permits moves to all 8 neighbors; 4 restricts moves to the 4 orthogonal neighbors, which prevents paths from corner-cutting diagonally between adjacent barrier or null cells. Any other value raises a ValueError.

Returns

  • cost_distance (Raster) – The accumulated cost distance solution. This is the same shape as the costs input Raster and has the same null value, or the default null value for float64 if costs has none set.

  • traceback (Raster) – The traceback result. This is the same shape as the costs input Raster.

  • allocation (Raster) – The allocation result. This is the same shape as the costs input Raster.

References