GeoEco.Datasets.Virtual.CannyEdgeGrid

class GeoEco.Datasets.Virtual.CannyEdgeGrid(grid, highThreshold=None, lowThreshold=None, sigma=1.4142, minSize=None)

Bases: Grid

A Grid that represents the edges in another Grid using the Canny edge detection algorithm..

To run this tool, you either must have MATLAB R2026a or MATLAB Runtime R2026a 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 R2026a must be used; other versions will not work. MATLAB Runtime allows multiple versions can be installed at the same time.

The Canny edge detection algorithm is a generic, widely-used algorithm for delineating edges between objects in digital images. The algorithm may be successfully applied to a wide variety of problems, including the problem of detecting fronts between water masses. Canny (1986) describes the algorithm in full detail, including its mathematical derivation. Some readers may find the paper difficult due to its length and technical detail. Shorter, more approachable descriptions may be found by searching the Internet for “Canny algorithm”.

Example usage:

# Load a sea surface temperature raster.

from GeoEco.Datasets.GDAL import GDALDataset
grid = GDALDataset.GetRasterBand(r'/home/jason/test/thetao_0000.5_20210101.img')

# Instantiate a CannyEdgeGrid using the default parameters. The edges
# won't be detected until data are requested from the CannyEdgeGrid
# instance, which will happen when we write the output raster below.

from GeoEco.Datasets.Virtual import CannyEdgeGrid
edgeGrid = CannyEdgeGrid(grid)

# Write the output raster.

GDALDataset.CreateRaster('/home/jason/test/thetao_0000.5_20210101_fronts.img', edgeGrid)

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

Parameters:

• grid (Grid) – Grid in which to detect edges. If it is 3D or 4D, edges will be detected in each 2D time and/or depth slice.

• highThreshold (float, optional) –

  High threshold for the Canny edge detection algorithm. The Canny algorithm uses the high threshold to find “strong edges”, which are pixels that have such a high gradient magnitude that they may confidently be classified as edges. These are pixels where those that surround them show a strong increase or decrease in value as you move across the image in some direction. The units of the Canny thresholds are the change in the units of the image per pixel traveled. For example, if the image represents sea surface temperature in degrees C, the units are change in degrees C per pixel.

  If you do not provide a value, one will be chosen automatically based on the data within the image. If you are detecting edges in multiple images, a value will be selected for each image separately.

  If you do not know what value to use, try the automatic selection and check the results carefully to see if they are acceptable for your problem. If not, you may select a value by trial and error. To see the values selected automatically, you enable verbose logging. (Please consult the MGET team for help with this, if necessary.)

  Increasing the high threshold will reduce the number of edges detected; reducing it will increase the number of edges detected.

  Must be greater than 0.0. Must be less than 1.0.

• lowThreshold (float, optional) –

  Low threshold for the Canny edge detection algorithm. If you supply a low threshold, you must also supply a high threshold. The low threshold must be less than the high threshold.

  After using the high threshold to find “strong edges”, the Canny algorithm uses the low threshold to find “weak edges”, which are those that have a gradient magnitude that is high enough that they might be edges, but not so high that they may be confidently classified as edges on the basis of their gradient magnitude alone. After identifying the weak edge pixels, the algorithm checks whether 8-connected groups of weak pixels are connected to strong ones (i.e. whether they touch them horizontally, vertically, or diagonally). Groups of weak pixels that do not touch a strong pixel are discarded. This approach essentially allows the strong edges to be “extended” by the weak ones.

  The units of the Canny thresholds are the change in the units of the image per pixel traveled. For example, if the image represents sea surface temperature in degrees C, the units are change in degrees C per pixel.

  If you do not provide a value, one will be chosen automatically based on the data within the image. If you are detecting edges in multiple images, a value will be selected for each image separately. The value selected will be the high threshold multiplied by 0.4.

  If you do not know what value to use, try the automatic selection and check the results carefully to see if they are acceptable for your problem. If not, you may select a value by trial and error. To see the values selected automatically, you enable verbose logging. (Please consult the MGET team for help with this, if necessary.)

  Increasing the low threshold will reduce the number of edges detected; reducing it will increase the number of edges detected.

  Must be greater than 0.0. Must be less than 1.0.

• sigma (float, optional) –

  Sigma parameter for the Gaussian filter applied by the Canny edge detection algorithm. As its first step, before performing edge detection, the Canny algorithm applies a Gaussian filter to the image to smooth out noise. The sigma parameter controls the degree of smoothing. Higher values producing more smoothing, resulting in fewer detected edges. Lower values yield less smoothing and more detected edges.

  If you do not provide a value, the square root of 2 will be used by default. This is a good value for many problems. If your image is very noisy, you might need a higher value. Try increasing it a little bit at a time (e.g. by 0.1 or 0.2). Be careful not to increase it too much; otherwise it may smooth out the edges that you are trying to detect. If your image is not very noisy–e.g. it is from an ocean model that produces theoretical results that do not contain noise–consider reducing the value to 1 or less (it must be greater than zero, however).

  It is not necessary to specify the window size of the Gaussian filter; the algorithm automatically selects the optimal window size based on the value of the sigma parameter.

  Must be greater than 0.0.

• minSize (int, optional) –

  Minimum number of pixels an individual edge must occupy for it to be retained. Edges with fewer number of pixels will be discarded. For this option, an “edge” is defined as the chain of pixels that are 8-connected (i.e. they are connected horizontally, vertically, or diagonally). The edge may be any shape, such as long and thin and branching or short and blob-like.

  This option is applied after the Canny algorithm is complete. If a value is not provided, all edges will be retained.

  Must be greater than 0.

Returns:

CannyEdgeGrid instance.

Return type:

CannyEdgeGrid

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