raster_tools.distance package#

Submodules#

raster_tools.distance.cost_distance module#

raster_tools.distance.cost_distance.cda_allocation(costs, sources, elevation=None)[source]#

Calculate just the cost distance allocation for a cost surface.

See cost_distance_analysis for a full description.

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.

Returns

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

Return type

Raster

See also

cost_distance_analysis

Full cost distance solution

raster_tools.distance.cost_distance.cda_cost_distance(costs, sources, elevation=None)[source]#

Calculate just the cost distance for a cost surface

See cost_distance_analysis for a full description.

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.

Returns

cost_distance – The accumulated cost distance solution. This is the same shape as the costs input Raster.

Return type

Raster

See also

cost_distance_analysis

Full cost distance solution

raster_tools.distance.cost_distance.cda_traceback(costs, sources, elevation=None)[source]#

Calculate just the cost distance traceback for a cost surface.

See cost_distance_analysis for a full description.

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.

Returns

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

Return type

Raster

See also

cost_distance_analysis

Full cost distance solution

raster_tools.distance.cost_distance.cost_distance_analysis(costs, sources, elevation=None)[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. 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.

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.

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.

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.

  • 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

raster_tools.distance.cost_distance.cost_distance_analysis_numpy(costs, sources, sources_null_value, elevation=None, elevation_null_value=0, scaling=1.0)[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. This produces 3 2D arrays. 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 provided scaling factor informs the actual distance scaling to use. Source locations have a cost of 0. If elevation is provided, the length calculation incorporates the elevation data to make the algorithm 3D aware.

The second array 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:

5 6 7 4 X 0 3 2 1

Here, X indicates the current pixel and the numbers are the neighbor pixel positions. 0 indicates the neighbor immediately to the right and 6 indicates the neighbor immediately above. In terms of rows and columns, these are the neighbor one column over and one row above, respectively. a value of -1 indicates that the current pixel is a source pixel and -2 indicates that the pixel was not traversed (no data or a barrier).

The third array contians 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 array at the corresponding source location.

Parameters

  • costs (2D ndarray) – A 2D array representing a cost surface.

  • sources (2D int64 ndarray) – An array of sources. The values at each valid location, as determined using sources_null_value, are used for the allocation output.

  • sources_null_value (int) – The value in sources that indicates a null value.

  • elevation (2D ndarray, optional) – An array of elevation values. Same shape as costs. If provided, the elevation is used when determining the move length between pixels.

  • elevation_null_value (scalar, optional) – The null value for elevation data. Default is 0.

  • scaling (scalar or 1D sequence, optional) – The scaling to use in each direction. For a grid with 30m scale, this would be 30. Default is 1.

Returns

  • cost_distance (2D ndarray) – The accumulated cost distance solution. This is the same shape as the costs input array.

  • traceback (2D ndarray) – The traceback result. This is the same shape as the costs input array.

  • allocation (2D ndarray) – The allocation result. This is the same shape as the costs input array.

raster_tools.distance.proximity module#

raster_tools.distance.proximity.pa_allocation(raster, target_values=None, distance_metric='euclidean', max_distance=inf, double_precision=False)[source]#

Compute the proximity allocation of each cell to the closest source cell.

Allocation assigns each raster cell the value of the nearest source cell. This function takes a source raster and uses it to compute a proximity allocation raster. For large max_distance values, this forms the raster analogue of a Voronoi diagram. distance_metric selects the function to use for calculating distances between cells.

This is very similar to ESRI’s Euclidean Allocation tool.

Parameters

  • raster (Raster, path str) – The input source raster. If target_values is not specified or empty, any non-null, finite, non-zero cell is considered a source. If target_values is specified, it will be used to find source cells with the given values.

  • target_values (array-like, optional) – A 1D sequence of values to use to find source cells in raster. If not specified, all non-null, finite, non-zero cells are considered sources.

  • max_distance (scalar, optional) – The maximum distance (in georeferenced units) to consider when computing proximities. Distances greater than this value will not be computed and the corresponding cells will be skipped. This value also determines how much of raster is loaded into memory when carrying out the computation. A larger value produces a larger memory footprint. The default is infinity which causes the entire raster to be loaded at computation time. No cells will be skipped in this case.

  • distance_metric (str) –

    The name of the distance metric to use for computing distances. Default is ‘euclidean’.

    ’euclidean’

    The euclidean distance between two points: sqrt((x1 - x2)^2 + (y1 - y2)^2)

    ’taxi’ ‘taxicab’ ‘manhatten’ ‘city_block’

    The taxicab distance between two points: |x1 - x2| + |y1 - y2|

    ’chebyshev’ ‘chessboard’

    The chebyshev or chessboard distance: max(|x1 - x2|, |y1 - y2|)

    ’haversine’ ‘great_circle’

    The great circle distance between points on a sphere. This implementation uses the WGS84 mean earth radius of 6,371,009 m. Coordinates are assumed to be in degrees. Latitude must be in the range [-90, 90] and longitude must be in the range [-180, 180].

  • double_precision (bool) – If True, distances will will be computed with 64-bit precision, otherwise 32-bit floats are used. Default is False.

Returns

The allocation raster.

Return type

Raster

References

See also

pa_proximity, pa_direction, proximity_analysis

raster_tools.distance.proximity.pa_direction(raster, target_values=None, distance_metric='euclidean', max_distance=inf, double_precision=False)[source]#

Compute the direction of each cell to the closest source cell.

This function takes a source raster and uses it to compute a direction raster. Each cell contains the direction in degrees to the nearest source cell as determined by the distance metric. distance_metric selects the function to use for calculating distances between cells. Directions are in degrees on the range [0, 360]. 0 indicates that a source cell. 360 is North, 90 East, 180 South, and 270 indicates West. They indicate the direction to, not from, the nearest source cell.

This is very similar to ESRI’s Euclidean Direction tool.

Parameters

  • raster (Raster, path str) – The input source raster. If target_values is not specified or empty, any non-null, finite, non-zero cell is considered a source. If target_values is specified, it will be used to find source cells with the given values.

  • target_values (array-like, optional) – A 1D sequence of values to use to find source cells in raster. If not specified, all non-null, finite, non-zero cells are considered sources.

  • max_distance (scalar, optional) – The maximum distance (in georeferenced units) to consider when computing proximities. Distances greater than this value will not be computed and the corresponding cells will be skipped. This value also determines how much of raster is loaded into memory when carrying out the computation. A larger value produces a larger memory footprint. The default is infinity which causes the entire raster to be loaded at computation time. No cells will be skipped in this case.

  • distance_metric (str) –

    The name of the distance metric to use for computing distances. Default is ‘euclidean’.

    ’euclidean’

    The euclidean distance between two points: sqrt((x1 - x2)^2 + (y1 - y2)^2)

    ’taxi’ ‘taxicab’ ‘manhatten’ ‘city_block’

    The taxicab distance between two points: |x1 - x2| + |y1 - y2|

    ’chebyshev’ ‘chessboard’

    The chebyshev or chessboard distance: max(|x1 - x2|, |y1 - y2|)

    ’haversine’ ‘great_circle’

    The great circle distance between points on a sphere. This implementation uses the WGS84 mean earth radius of 6,371,009 m. Coordinates are assumed to be in degrees. Latitude must be in the range [-90, 90] and longitude must be in the range [-180, 180].

  • double_precision (bool) – If True, distances will will be computed with 64-bit precision, otherwise 32-bit floats are used. Default is False.

Returns

The direction raster.

Return type

Raster

References

See also

pa_proximity, pa_allocation, proximity_analysis

raster_tools.distance.proximity.pa_proximity(raster, target_values=None, max_distance=inf, distance_metric='euclidean', double_precision=False)[source]#

Compute the proximity of each cell to the closest source cell.

This function takes a source raster and uses it to compute a proximity raster. The proximity raster’s cells contain the distances, as determined by the distance_metric input, to the nearest source cell. distance_metric selects the function to use for calculating distances between cells.

This is very similar to ESRI’s Euclidean Distance tool and GDAL’s proximity function.

Parameters

  • raster (Raster, path str) – The input source raster. If target_values is not specified or empty, any non-null, finite, non-zero cell is considered a source. If target_values is specified, it will be used to find source cells with the given values.

  • target_values (array-like, optional) – A 1D sequence of values to use to find source cells in raster. If not specified, all non-null, finite, non-zero cells are considered sources.

  • max_distance (scalar, optional) – The maximum distance (in georeferenced units) to consider when computing proximities. Distances greater than this value will not be computed and the corresponding cells will be skipped. This value also determines how much of raster is loaded into memory when carrying out the computation. A larger value produces a larger memory footprint. The default is infinity which causes the entire raster to be loaded at computation time. No cells will be skipped in this case.

  • distance_metric (str) –

    The name of the distance metric to use for computing distances. Default is ‘euclidean’.

    ’euclidean’

    The euclidean distance between two points: sqrt((x1 - x2)^2 + (y1 - y2)^2)

    ’taxi’ ‘taxicab’ ‘manhatten’ ‘city_block’

    The taxicab distance between two points: |x1 - x2| + |y1 - y2|

    ’chebyshev’ ‘chessboard’

    The chebyshev or chessboard distance: max(|x1 - x2|, |y1 - y2|)

    ’haversine’ ‘great_circle’

    The great circle distance between points on a sphere. This implementation uses the WGS84 mean earth radius of 6,371,009 m. Coordinates are assumed to be in degrees. Latitude must be in the range [-90, 90] and longitude must be in the range [-180, 180].

  • double_precision (bool) – If True, distances will will be computed with 64-bit precision, otherwise 32-bit floats are used. Default is False.

Returns

The proximity raster.

Return type

Raster

References

See also

pa_allocation, pa_direction, proximity_analysis

raster_tools.distance.proximity.proximity_analysis(raster, target_values=None, distance_metric='euclidean', max_distance=inf, double_precision=False)[source]#

Compute the proximity, allocation, and direction for a given source raster.

This function uses proximity analysis to compute the proximity, allocation, and direction rasters for a given source raster. See the individual functions for more details:

This is very similar to ESRI’s Proximity Analysis tools.

Parameters

  • raster (Raster, path str) – The input source raster. If target_values is not specified or empty, any non-null, finite, non-zero cell is considered a source. If target_values is specified, it will be used to find source cells with the given values.

  • target_values (array-like, optional) – A 1D sequence of values to use to find source cells in raster. If not specified, all non-null, finite, non-zero cells are considered sources.

  • max_distance (scalar, optional) – The maximum distance (in georeferenced units) to consider when computing proximities. Distances greater than this value will not be computed and the corresponding cells will be skipped. This value also determines how much of raster is loaded into memory when carrying out the computation. A larger value produces a larger memory footprint. The default is infinity which causes the entire raster to be loaded at computation time. No cells will be skipped in this case.

  • distance_metric (str) –

    The name of the distance metric to use for computing distances. Default is ‘euclidean’.

    ’euclidean’

    The euclidean distance between two points: sqrt((x1 - x2)^2 + (y1 - y2)^2)

    ’taxi’ ‘taxicab’ ‘manhatten’ ‘city_block’

    The taxicab distance between two points: |x1 - x2| + |y1 - y2|

    ’chebyshev’ ‘chessboard’

    The chebyshev or chessboard distance: max(|x1 - x2|, |y1 - y2|)

    ’haversine’ ‘great_circle’

    The great circle distance between points on a sphere. This implementation uses the WGS84 mean earth radius of 6,371,009 m. Coordinates are assumed to be in degrees. Latitude must be in the range [-90, 90] and longitude must be in the range [-180, 180].

  • double_precision (bool) – If True, distances will will be computed with 64-bit precision, otherwise 32-bit floats are used. Default is False.

Returns

  • proximity (Raster) – The proximity raster.

  • direction (Raster) – The direction raster.

  • allocation (Raster) – The allocation raster.

References

See also

pa_proximity, pa_direction, pa_allocation

Module contents#

raster_tools.distance.cda_allocation(costs, sources, elevation=None)[source]#

Calculate just the cost distance allocation for a cost surface.

See cost_distance_analysis for a full description.

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.

Returns

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

Return type

Raster

See also

cost_distance_analysis

Full cost distance solution

raster_tools.distance.cda_cost_distance(costs, sources, elevation=None)[source]#

Calculate just the cost distance for a cost surface

See cost_distance_analysis for a full description.

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.

Returns

cost_distance – The accumulated cost distance solution. This is the same shape as the costs input Raster.

Return type

Raster

See also

cost_distance_analysis

Full cost distance solution

raster_tools.distance.cda_traceback(costs, sources, elevation=None)[source]#

Calculate just the cost distance traceback for a cost surface.

See cost_distance_analysis for a full description.

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.

Returns

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

Return type

Raster

See also

cost_distance_analysis

Full cost distance solution

raster_tools.distance.cost_distance_analysis(costs, sources, elevation=None)[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. 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.

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.

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.

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.

  • 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

raster_tools.distance.pa_allocation(raster, target_values=None, distance_metric='euclidean', max_distance=inf, double_precision=False)[source]#

Compute the proximity allocation of each cell to the closest source cell.

Allocation assigns each raster cell the value of the nearest source cell. This function takes a source raster and uses it to compute a proximity allocation raster. For large max_distance values, this forms the raster analogue of a Voronoi diagram. distance_metric selects the function to use for calculating distances between cells.

This is very similar to ESRI’s Euclidean Allocation tool.

Parameters

  • raster (Raster, path str) – The input source raster. If target_values is not specified or empty, any non-null, finite, non-zero cell is considered a source. If target_values is specified, it will be used to find source cells with the given values.

  • target_values (array-like, optional) – A 1D sequence of values to use to find source cells in raster. If not specified, all non-null, finite, non-zero cells are considered sources.

  • max_distance (scalar, optional) – The maximum distance (in georeferenced units) to consider when computing proximities. Distances greater than this value will not be computed and the corresponding cells will be skipped. This value also determines how much of raster is loaded into memory when carrying out the computation. A larger value produces a larger memory footprint. The default is infinity which causes the entire raster to be loaded at computation time. No cells will be skipped in this case.

  • distance_metric (str) –

    The name of the distance metric to use for computing distances. Default is ‘euclidean’.

    ’euclidean’

    The euclidean distance between two points: sqrt((x1 - x2)^2 + (y1 - y2)^2)

    ’taxi’ ‘taxicab’ ‘manhatten’ ‘city_block’

    The taxicab distance between two points: |x1 - x2| + |y1 - y2|

    ’chebyshev’ ‘chessboard’

    The chebyshev or chessboard distance: max(|x1 - x2|, |y1 - y2|)

    ’haversine’ ‘great_circle’

    The great circle distance between points on a sphere. This implementation uses the WGS84 mean earth radius of 6,371,009 m. Coordinates are assumed to be in degrees. Latitude must be in the range [-90, 90] and longitude must be in the range [-180, 180].

  • double_precision (bool) – If True, distances will will be computed with 64-bit precision, otherwise 32-bit floats are used. Default is False.

Returns

The allocation raster.

Return type

Raster

References

See also

pa_proximity, pa_direction, proximity_analysis

raster_tools.distance.pa_direction(raster, target_values=None, distance_metric='euclidean', max_distance=inf, double_precision=False)[source]#

Compute the direction of each cell to the closest source cell.

This function takes a source raster and uses it to compute a direction raster. Each cell contains the direction in degrees to the nearest source cell as determined by the distance metric. distance_metric selects the function to use for calculating distances between cells. Directions are in degrees on the range [0, 360]. 0 indicates that a source cell. 360 is North, 90 East, 180 South, and 270 indicates West. They indicate the direction to, not from, the nearest source cell.

This is very similar to ESRI’s Euclidean Direction tool.

Parameters

  • raster (Raster, path str) – The input source raster. If target_values is not specified or empty, any non-null, finite, non-zero cell is considered a source. If target_values is specified, it will be used to find source cells with the given values.

  • target_values (array-like, optional) – A 1D sequence of values to use to find source cells in raster. If not specified, all non-null, finite, non-zero cells are considered sources.

  • max_distance (scalar, optional) – The maximum distance (in georeferenced units) to consider when computing proximities. Distances greater than this value will not be computed and the corresponding cells will be skipped. This value also determines how much of raster is loaded into memory when carrying out the computation. A larger value produces a larger memory footprint. The default is infinity which causes the entire raster to be loaded at computation time. No cells will be skipped in this case.

  • distance_metric (str) –

    The name of the distance metric to use for computing distances. Default is ‘euclidean’.

    ’euclidean’

    The euclidean distance between two points: sqrt((x1 - x2)^2 + (y1 - y2)^2)

    ’taxi’ ‘taxicab’ ‘manhatten’ ‘city_block’

    The taxicab distance between two points: |x1 - x2| + |y1 - y2|

    ’chebyshev’ ‘chessboard’

    The chebyshev or chessboard distance: max(|x1 - x2|, |y1 - y2|)

    ’haversine’ ‘great_circle’

    The great circle distance between points on a sphere. This implementation uses the WGS84 mean earth radius of 6,371,009 m. Coordinates are assumed to be in degrees. Latitude must be in the range [-90, 90] and longitude must be in the range [-180, 180].

  • double_precision (bool) – If True, distances will will be computed with 64-bit precision, otherwise 32-bit floats are used. Default is False.

Returns

The direction raster.

Return type

Raster

References

See also

pa_proximity, pa_allocation, proximity_analysis

raster_tools.distance.pa_proximity(raster, target_values=None, max_distance=inf, distance_metric='euclidean', double_precision=False)[source]#

Compute the proximity of each cell to the closest source cell.

This function takes a source raster and uses it to compute a proximity raster. The proximity raster’s cells contain the distances, as determined by the distance_metric input, to the nearest source cell. distance_metric selects the function to use for calculating distances between cells.

This is very similar to ESRI’s Euclidean Distance tool and GDAL’s proximity function.

Parameters

  • raster (Raster, path str) – The input source raster. If target_values is not specified or empty, any non-null, finite, non-zero cell is considered a source. If target_values is specified, it will be used to find source cells with the given values.

  • target_values (array-like, optional) – A 1D sequence of values to use to find source cells in raster. If not specified, all non-null, finite, non-zero cells are considered sources.

  • max_distance (scalar, optional) – The maximum distance (in georeferenced units) to consider when computing proximities. Distances greater than this value will not be computed and the corresponding cells will be skipped. This value also determines how much of raster is loaded into memory when carrying out the computation. A larger value produces a larger memory footprint. The default is infinity which causes the entire raster to be loaded at computation time. No cells will be skipped in this case.

  • distance_metric (str) –

    The name of the distance metric to use for computing distances. Default is ‘euclidean’.

    ’euclidean’

    The euclidean distance between two points: sqrt((x1 - x2)^2 + (y1 - y2)^2)

    ’taxi’ ‘taxicab’ ‘manhatten’ ‘city_block’

    The taxicab distance between two points: |x1 - x2| + |y1 - y2|

    ’chebyshev’ ‘chessboard’

    The chebyshev or chessboard distance: max(|x1 - x2|, |y1 - y2|)

    ’haversine’ ‘great_circle’

    The great circle distance between points on a sphere. This implementation uses the WGS84 mean earth radius of 6,371,009 m. Coordinates are assumed to be in degrees. Latitude must be in the range [-90, 90] and longitude must be in the range [-180, 180].

  • double_precision (bool) – If True, distances will will be computed with 64-bit precision, otherwise 32-bit floats are used. Default is False.

Returns

The proximity raster.

Return type

Raster

References

See also

pa_allocation, pa_direction, proximity_analysis

raster_tools.distance.proximity_analysis(raster, target_values=None, distance_metric='euclidean', max_distance=inf, double_precision=False)[source]#

Compute the proximity, allocation, and direction for a given source raster.

This function uses proximity analysis to compute the proximity, allocation, and direction rasters for a given source raster. See the individual functions for more details:

This is very similar to ESRI’s Proximity Analysis tools.

Parameters

  • raster (Raster, path str) – The input source raster. If target_values is not specified or empty, any non-null, finite, non-zero cell is considered a source. If target_values is specified, it will be used to find source cells with the given values.

  • target_values (array-like, optional) – A 1D sequence of values to use to find source cells in raster. If not specified, all non-null, finite, non-zero cells are considered sources.

  • max_distance (scalar, optional) – The maximum distance (in georeferenced units) to consider when computing proximities. Distances greater than this value will not be computed and the corresponding cells will be skipped. This value also determines how much of raster is loaded into memory when carrying out the computation. A larger value produces a larger memory footprint. The default is infinity which causes the entire raster to be loaded at computation time. No cells will be skipped in this case.

  • distance_metric (str) –

    The name of the distance metric to use for computing distances. Default is ‘euclidean’.

    ’euclidean’

    The euclidean distance between two points: sqrt((x1 - x2)^2 + (y1 - y2)^2)

    ’taxi’ ‘taxicab’ ‘manhatten’ ‘city_block’

    The taxicab distance between two points: |x1 - x2| + |y1 - y2|

    ’chebyshev’ ‘chessboard’

    The chebyshev or chessboard distance: max(|x1 - x2|, |y1 - y2|)

    ’haversine’ ‘great_circle’

    The great circle distance between points on a sphere. This implementation uses the WGS84 mean earth radius of 6,371,009 m. Coordinates are assumed to be in degrees. Latitude must be in the range [-90, 90] and longitude must be in the range [-180, 180].

  • double_precision (bool) – If True, distances will will be computed with 64-bit precision, otherwise 32-bit floats are used. Default is False.

Returns

  • proximity (Raster) – The proximity raster.

  • direction (Raster) – The direction raster.

  • allocation (Raster) – The allocation raster.

References

See also

pa_proximity, pa_direction, pa_allocation