GeoEco.Datasets.Virtual.InpaintedGrid

class GeoEco.Datasets.Virtual.InpaintedGrid(grid, method='Del2a', maxHoleSize=None, xEdgesWrap=False, minValue=None, maxValue=None)

Bases: Grid

A Grid that fills missing (NoData) values in another Grid using a partial differential equation method.

This tool is implemented in MATLAB using the inpaint_nans function developed by John D’Errico. Many thanks to him for developing and sharing this function. Please see GeoEco’s LICENSE file for the relevant copyright statement.

To run this tool, you either must have MATLAB R2024b or MATLAB Runtime R2024b installed. The MATLAB Runtime is free and may be downloaded from https://www.mathworks.com/help/compiler/install-the-matlab-runtime.html. Please follow the installation instructions carefully. Version R2024b must be used; other versions will not work. MATLAB Runtime allows multiple versions can be installed at the same time.

Example usage:

# Load a chlorophyll concentration raster that is missing some values.

from GeoEco.Datasets.GDAL import GDALDataset
grid = GDALDataset.GetRasterBand('/home/jason/inpaint_test/GSMChl_2006160.img')

# Fill in contiguous blocks of missing values that are less than 200 cells
# in size. This size was chosen arbitrarily for this example. You might
# prefer a smaller or larger size for your application.

from GeoEco.Datasets.Virtual import InpaintedGrid
inpaintedGrid = InpaintedGrid(grid, maxHoleSize=200)

# Write the output raster.

GDALDataset.CreateRaster('/home/jason/inpaint_test/GSMChl_2006160_filled.img', inpaintedGrid)

Requires: MATLAB Runtime R2024b (which can be freely downloaded from https://www.mathworks.com/products/compiler/matlab-runtime.html) or the full version of MATLAB R2024b.

Parameters:

• grid (Grid) – Grid to fill. Its ScaledDataType must be float32 or float64.

• method (str, optional) –

  Method to use for interpolation and extrapolation of NoData values. One of:

  • Del2a - Performs Laplacian interpolation and linear extrapolation.

  • Del2b - Same as Del2a but does not build as large a linear system of equations. May use less memory and be faster than Del2a, at the cost of some accuracy. Use this method if Del2a fails due to insufficient memory or if it is too slow.

  • Del2c - Same as Del2a but solves a direct linear system of equations for the NoData values. Faster than both Del2a and Del2b but is the least robust to noise on the boundaries of NoData cells and least able to interpolate accurately for smooth surfaces. Use this method if Del2a and Del2b both fail due to insufficient memory or are too slow.

  • Del4 - Same as Del2a but instead of the Laplace operator (also called the ∇² operator) it uses the biharmoic operator (also called the ∇⁴ operator). May result in more accurate interpolations, at some cost in speed.

  • Spring - Uses a spring metaphor. Assumes springs (with a nominal length of zero) connect each cell with every neighbor (horizontally, vertically and diagonally). Since each cell tries to be like its neighbors, extrapolation is as a constant function where this is consistent with the neighboring nodes.

  Allowed values꞉ 'Del2a', 'Del2b', 'Del2c', 'Del4', 'Spring'.

• maxHoleSize (int, optional) – Maximum size, in cells, that a region of 4-connected NoData cells may be for it to be filled in. Use this option to prevent the filling of large NoData regions (e.g. large clouds in remote sensing images) when you are concerned that values cannot be accurately guessed for those regions. If this option is omitted, all regions will be filled, regardless of size. Must be greater than 0.

• xEdgesWrap (bool, optional) – If True, the left and right edges of the grid are assumed to be connected and computations along those edges will consider the values on the opposite side of the grid.

• minValue (float, optional) –

  Minimum allowed value to use when NoData cells are interpolated (or extrapolated). If this parameter is provided, all cells with less than the minimum value will be rounded up to the minimum. This includes not just the cells that had NoData in the original grid and were then interpolated or extrapolated, but also the cells that had values in the original grid.

  Use this parameter when the interpolation/extrapolation algorithm produces impossibly low values. For example, consider a situation in which a chlorophyll concentration grid coincidentally shows a negative gradient approaching a cloud that straddles the edge of the grid. Missing pixels at the edge of the grid will be filled by extrapolation. If the negative gradient is strong enough, the algorithm might extrapolate negative concentrations for the cloudy pixels. This should be impossible; chlorophyll concentration must be zero or higher. To enforce that, you could specify a minimum value of zero (or a very small non-zero number, if exactly zero would be problematic, as might occur if the values were in a log scale).

• maxValue (float, optional) –

  Maximum allowed value to use when NoData cells are interpolated (or extrapolated). If this parameter is provided, all cells with greater than the maximum value will be rounded up to the maximum. This includes not just the cells that had NoData in the original grid and were then interpolated or extrapolated, but also the cells that had values in the original grid.

  Use this parameter when the interpolation/extrapolation algorithm produces impossibly high values. For example, consider a situation in which a percent sea ice concentration grid shows a positive gradient approaching the coastline but does not provide data right up to shore. Say you wanted to fill the missing cells close to shore and were willing to assume that whatever gradient occurred nearby was reasonable for filling them in. If the positive gradient is strong enough, the algorithm might extrapolate ice concentration values greater than 100 percent, which is impossible. To prevent values from exceeding 100 percent, you could specify a maximum value of 100.

Returns:

InpaintedGrid instance.

Return type:

InpaintedGrid

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 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 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