GeoEco.Datasets.Virtual.FastMarchingDistanceGrid

class GeoEco.Datasets.Virtual.FastMarchingDistanceGrid(grid, minDist=None, maxDist=None)

Bases: Grid

A Grid representing distances to features in another Grid, computed with a fast marching algorithm.

To compute fast marching distances, FastMarchingDistanceGrid first classifies the cells of the provided Grid based on their values:

Cells with values of zero or less represent features to which distances should be calculated, called inside cells below.
Cells with positive values represent areas that can be moved through, e.g. the ocean, called outside cells.
Cells of NoData represent obstacles that cannot be moved through (e.g. land), called barrier cells.

The interfaces where inside and outside cells touch each other are called the feature edges. Where inside and outside cells touch along a straight row or column, the edge is a straight line located exactly where the cells meet. When the feature has a “corner”, the edge is rounded and curved within the inside cell.

Fast marching distances are computed for both inside and outside cells. Distances are negative for inside cells and positive for outside cells. Distances are computed as the shortest path from the given cell to the closest edge, and will be positive for outside cells and negative for inside cells. If you instead want the distances for inside cells to zero throughout the feature, set minDist to zero.

Example usage:

# Load the study area raster and get the first band as a GDALRasterGrid.

from GeoEco.Datasets.GDAL import GDALDataset
dataset = GDALDataset('/home/jason/fast_marching_test/Study_Area.img')
grid = dataset.QueryDatasets(reportProgress=False)[0]

# This band uses an int32 data type and has values of 0 for land and 1 for
# water. Every cell has data. First, extract the band's data as a numpy array.
# Then, in that array, set land (0) to NoData. Note that we do not want set
# values of grid.Data itself (e.g. grid.Data[...] = ...) because this will
# write values into the raster file, which we do not want to change. Also,
# Grid does not support indexing with numpy arrays (e.g. data == 0).

data = grid.Data[:]
data[data == 0] = grid.NoDataValue

# We are now representing land as NoData, which FastMarchingDistanceGrid
# expects. Now set several cells that are currently marked as 1 to 0. These
# new 0 cells represent the feature we will computing distances to. We know
# the approximate coordinates of the centers of these cells and use a Grid
# function to look up their integer indices, and then use those to set the
# cell values. (These are in a projected coordinate system with meters as the
# linear unit, which is why they are very large.)

cellCoordsYX = [(1607000, 2882000),
                (1602000, 2882000),
                (1597000, 2882000),
                (1592000, 2882000),
                (1587000, 2882000),
                (1582000, 2882000),
                (1577000, 2877000),
                (1572000, 2877000),
                (1567000, 2877000),
                (1562000, 2877000),]

cellIndicesYX = [grid.GetIndicesForCoords(coords) for coords in cellCoordsYX]

for indices in cellIndicesYX:
    data[indices[0], indices[1]] = -1

# Create a NumpyGrid from the original band, then write our new data into it.

from GeoEco.Datasets import NumpyGrid
numpyGrid = NumpyGrid.CreateFromGrid(grid)
numpyGrid.Data[:] = data

# Construct the FastMarchingDistanceGrid. Set minDist to 0, so that cells
# within the feature we defined above will have a distance of 0, rather than a
# negative distance (from the cell center to the edge). Constructing this grid
# does not perform the calculation; that is deferred until the grid's Data
# property is accessed.

from GeoEco.Datasets.Virtual import FastMarchingDistanceGrid
fmdGrid = FastMarchingDistanceGrid(numpyGrid, minDist=0)

# We want to write the FastMarchingDistanceGrid out as a raster with GDAL.
# Construct a DirectoryTree that we can import it into. Note that because we
# are just going to import this single raster, we can specify the destination
# file name in pathCreationExpressions, and not have to define a
# QueryableAttribute that gives the file name.

from GeoEco.Datasets.Collections import DirectoryTree
dirTree = DirectoryTree(path='/home/jason/fast_marching_test',
                        datasetType=GDALDataset,
                        pathCreationExpressions=['Distance.img'])

# Import the grid into the DirectoryTree.

dirTree.ImportDatasets([fmdGrid], mode='Replace', calculateStatistics=True)

Requires: Python skfmm module.

Parameters:

grid (Grid) – Grid for which distances should be computed. Typically, it has 2 dimensions. If it has 3 or 4 dimensions, distances will be computed for each 2D slice.
minDist (float, optional) – Minimum allowed distance. If it is provided, distances less than this will be rounded up to it.
maxDist (float, optional) – Maximum allowed distance. If it is provided, distances greater than this will be rounded down to it.

Returns:

FastMarchingDistanceGrid instance.

Return type:

FastMarchingDistanceGrid

Properties

property CenterCoords: (object) Coordinates of the grid cell centers, indexed using the 1-character dimension of interest and optionally a range to retrieve a numpy.ndarray of coordinates (e.g. CenterCoords['x', 0:4]) or an integer to retrieve a float for a single coordinate (e.g. CenterCoords['x', 10]). Coordinates for the t dimension are returned as datetime instances. Read only.

property CoordDependencies: (tuple of str) Same length as Dimensions. Dimensions that each dimension depends on for determining its coordinates. None for dimensions that have a constant coordinate increment. Read only.

property CoordIncrements: (tuple of float) Same length as Dimensions. Coordinate increment for each dimension. None for dimensions that do not have a constant coordinate increment. Read only.

property Data: (object) This grid’s data, indexable using slices (e.g. grid.Data[:, 5:10, -10:]) or integers (e.g. grid.Data[0,1,-2]) or both in combination. Strides and negative indexes are supported in the traditional manner. If the grid is writable, Data can be assigned to write values to the grid, e.g. grid.Data[0,1] = 5 or grid.Data[:,:] = numpy.zeros(grid.Shape). Returns and accepts numpy.ndarray, float, and int. Read only.

property DataIsScaled: (bool) If True, the underlying raw data are stored as the UnscaledDataType to save storage space and then transformed by a scaling equation on the fly when they are returned by Data. The raw data can be accessed with UnscaledData. If False, the raw data are returned as is, with no transformation needed, and UnscaledDataType and DataType are the same, and UnscaledData returns the same values as Data. Read only.

property DataType: (str) Numeric data type of the grid, after the scaling function (if any) has been applied to the raw data. numpy.ndarrays returned by Data have this type. Read only. Allowed values꞉ 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64'. Case sensitive.

property Dimensions: (str) Dimensions of this grid. Read only. Allowed values꞉ 'yx', 'zyx', 'tyx', 'tzyx'. Case sensitive.

property DisplayName: (str) Informal name of this object, suitable to be displayed to the user. Read only. Minimum length꞉ 1.

property MaxCoords: (object) Maximum coordinate value for each cell (i.e., the coordinates of the cells’ right edges), indexed using the 1-character dimension of interest and optionally a range to retrieve a numpy.ndarray of coordinates (e.g. MaxCoords['x', 0:4]) or an integer to retrieve a float for a single coordinate (e.g. MaxCoords['x', 10]). Coordinates for the t dimension are returned as datetime instances. Read only.

property MaxDist: (float or None) Maximum allowed distance. If it is provided, distances greater than this will be rounded down to it. Read only.

property MinCoords: (object) Minimum coordinate value for each cell (i.e., the coordinates of the cells’ left edges), indexed using the 1-character dimension of interest and optionally a range to retrieve a numpy.ndarray of coordinates (e.g. MinCoords['x', 0:4]) or an integer to retrieve a float for a single coordinate (e.g. MinCoords['x', 10]). Coordinates for the t dimension are returned as datetime instances. Read only.

property MinDist: (float or None) Minimum allowed distance. If it is provided, distances less than this will be rounded up to it. Read only.

property NoDataValue: (object or None) int, float, or single-element numpy array giving the value that indicates that cells of Data should be interpreted as having no data (these are also known as missing, NA, or NULL cells), or None if all cells must have data. Read only.

property ParentCollection: (DatasetCollection or None) Parent DatasetCollection that this object is part of (if any). Read only.

property Shape: (tuple of int) Same length as Dimensions. Length (number of grid cells) of each dimension. Read only.

property TCountPerSemiRegularPeriod: (int or None) Number of time slices per semi-regular period (i.e. per year). None if the grid’s dimensions do not contain a t coordinate or the t coordinate is not semi-regular. Read only.

property TIncrementUnit: (str or None) Unit of the t coordinate. None if the grid’s dimensions do not contain a t coordinate. Read only. Allowed values꞉ 'year', 'month', 'day', 'hour', 'minute', 'second'. Case sensitive.

property TSemiRegularity: (str or None) Type of semi-regularity used for the t coordinate. None if the grid’s dimensions do not contain a t coordinate or the t coordinate is not semi-regular. Read only. Allowed values꞉ 'annual'. Case sensitive.

property UnscaledData: (object) This grid’s data underlying raw data, before it has been transformed by a scaling equation. UnscaledData is indexable using slices (e.g. grid.UnscaledData[:, 5:10, -10:]) or integers (e.g. grid.UnscaledData[0,1,-2]) or both in combination. Strides and negative indexes are supported in the traditional manner. If the grid is writable, UnscaledData can be assigned to write values to the grid, e.g. grid.UnscaledData[0,1] = 5 or grid.UnscaledData[:,:] = numpy.zeros(grid.Shape). Returns and accepts numpy.ndarray, float, and int. Read only.

property UnscaledDataType: (str) Numeric data type of the grid’s raw data, before it has been transformed by a scaling equation. numpy.ndarrays returned by UnscaledData have this type. If no transformation is needed (DataIsScaled is False), then UnscaledDataType and ScaledDataType are the same, and UnscaledData returns the same values as Data. Read only. Allowed values꞉ 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64'. Case sensitive.

property UnscaledNoDataValue: (object or None) int or float value that indicates that cells of UnscaledData should be interpreted as having no data (these are also known as missing, NA, or NULL cells), or None if all cells must have data. Read only.

Methods

`Close`	Closes any open files or connections associated with this object and releases any other resources allocated to access it.
`ConvertSpatialReference`	Converts a spatial reference from one format to another, such as an OGC WKT string to a Proj4 string.
`DeleteLazyPropertyValue`	Deletes the lazy property with the specified name.
`GetAllQueryableAttributes`	Returns a list of all queryable attributes.
`GetIndicesForCoords`	Given a `tuple` or `list` of coordinates, returns a `list` of `int` indices into `Data` for the cell that contains the coordinates.
`GetLazyPropertyValue`	Returns the value of the lazy property with the specified name.
`GetQueryableAttribute`	Returns the queryable attribute with the specified name.
`GetQueryableAttributeValue`	Returns the value of the queryable attribute with the specified name.
`GetQueryableAttributesWithDataType`	Returns a list queryable attributes having the specified data type.
`GetSpatialReference`	Returns the spatial reference of this dataset.
`HasLazyPropertyValue`	Returns True if the specified lazy property has a value.
`SetLazyPropertyValue`	Sets the lazy property with the specified name to the specified value.
`SetSpatialReference`	Sets the spatial reference of this dataset.
`TestCapability`	Tests whether a capability is supported by this class or an instance of it.
`numpy_equal_nan`