GeoEco.DataProducts.CMEMS.CMEMSARCOArray.CannyEdgesAsArcGISRasters

classmethod CMEMSARCOArray.CannyEdgesAsArcGISRasters(username, password, datasetID, variableShortName, outputWorkspace, mode='Add', log10Transform=False, highThreshold=None, lowThreshold=None, sigma=1.4142, minSize=None, xCoordType='center', yCoordType='center', zCoordType='center', tCoordType='min', rotationOffset=None, spatialExtent=None, minDepth=None, maxDepth=None, startDate=None, endDate=None, rasterExtension='.img', rasterNameExpressions=None, calculateStatistics=True, buildPyramids=False, buildRAT=True)

Creates rasters indicating the positions of fronts identified with the Canny edge detection algorithm in a 2D, 3D, or 4D gridded dataset published by Copernicus Marine Service.

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.

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

Requires: ArcGIS Pro 3.2.0 or later or ArcGIS Server equivalent to ArcGIS Pro 3.2.0 or later, 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, Python numpy module, Python copernicusmarine module.

Parameters:

  • username (str) – Copernicus Marine Service user name. Minimum length꞉ 1.

  • password (str) – Copernicus Marine Service password. Minimum length꞉ 1.

  • datasetID (str) – Dataset ID to access. You can find the Dataset ID by going to the Copernicus Marine Data Store, viewing your product of interest, clicking on Data Access, and scrolling to the Dataset ID table. The dataset must have 2, 3, or 4 dimensions. Two of the dimensions must be longitude and latitude. The third and fourth dimension can be depth or time. Minimum length꞉ 1.

  • variableShortName (str) – “Short name” of the variable to access. You can find the variable’s short name by going to to the Copernicus Marine Data Store, viewing your product of interest, clicking on Data Access, scrolling to the Dataset ID table, and clicking on Form under the Subset column. When the form appears, look under the Variables heading. Each variable has a long description in black font, followed by the variable short name and units (in brackets) in a lighter color. Do not include the units as part of the short name. Minimum length꞉ 1.

  • outputWorkspace (str) –

    Directory or geodatabase to receive the rasters. Unless you have a specific reason to store the rasters in a geodatabase, we recommend you store them in a directory because it will be faster and allow the rasters to be organized in a tree. The tree structure and raster names will be generated automatically unless you provide a value for the Raster Name Expressions parameter. Minimum length꞉ 1.

    The rasters will have an integer data type, with the value 1 where a front was detected, 0 where a front was not detected, and NoData where there was land, or data were missing for some other reason.

  • mode (str, optional) –

    Overwrite mode, one of:

    • Add - create rasters that do not exist and skip those that already exist. This is the default.

    • Replace - create rasters that do not exist and overwrite those that already exist.

    The ArcGIS Overwrite Output environment setting has no effect on this tool. If ‘Replace’ is selected the rasters will be overwritten, regardless of the ArcGIS Overwrite Output setting.

    Allowed values꞉ 'Add', 'Replace'.

  • log10Transform (bool, optional) –

    “If True, a log10 (base 10 logarithm) function will be applied to the data after it is downloaded before further processing. This transformation may be useful when working with data that are always positive but heavily skewed, such as chlorophyll concentration or other biological oceanographic data. For example, it is a common practice to log10 transform chlorophyll data before detecting chlorophyll fronts or utilizing chlorophyll in a species distribution model.

    Note that it is only possible to take the logarithm of a positive number. If the data contain values less than or equal to zero, a warning will be issued and they will be treated as missing values.

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

  • xCoordType (str, optional) – Specifies whether the latitude coordinates used by Copernicus for this dataset are the left edges ('min'), the centers ('center'), or the right edges ('max') of the cells. This cannot be determined automatically but for most Copernicus datasets the longitude coordinates are the centers of the cells. To determine the appropriate value for your dataset of interest, consult the dataset’s documentation or contact Copernicus for help. Alternatively, download the dataset to a raster using 'center', load it into a GIS, and overlay a high resolution shoreline. Examine the overlap to determine whether 'min' or 'max' would provide a better match up between the raster and the shoreline. Allowed values꞉ 'min', 'center', 'max'.

  • yCoordType (str, optional) – Specifies whether the latitude coordinates used by Copernicus for this dataset are the bottom edges ('min'), the centers ('center'), or the top edges ('max') of the cells. This cannot be determined automatically but for most Copernicus datasets the latitude coordinates are the centers of the cells. To determine the appropriate value for your dataset of interest, consult the dataset’s documentation or contact Copernicus for help. Alternatively, download the dataset to a raster using 'center', load it into a GIS, and overlay a high resolution shoreline. Examine the overlap to determine whether 'min' or 'max' would provide a better match up between the raster and the shoreline. Allowed values꞉ 'min', 'center', 'max'.

  • zCoordType (str, optional) – Specifies whether the depth coordinates used by Copernicus for this dataset are the shallow edges ('min'), the centers ('center'), or the deep edges ('max') of the cells. This cannot be determined automatically but for most Copernicus datasets the depth coordinates are the centers of the cells. To determine the appropriate value for your dataset of interest, consult the dataset’s documentation or contact Copernicus for help. Allowed values꞉ 'min', 'center', 'max'.

  • tCoordType (str, optional) – Specifies whether the time coordinates used by Copernicus for this dataset are the starting times ('min'), the center times ('center'), or the ending times ('max') of the time slices. This cannot be determined automatically but most Copernicus datasets that are “instantaneous” use center times, while most datasets that represent mean values (e.g. daily or monthly means) use starting times. To determine the appropriate value for your dataset of interest, consult the dataset’s documentation or contact Copernicus for help. Allowed values꞉ 'min', 'center', 'max'.

  • rotationOffset (float, optional) – Degrees to rotate the outputs about the polar axis. This parameter may only be used for global products. The outputs can only be rotated in whole cells. The value you provide will be rounded off to the closest cell. The value may be positive or negative.

  • spatialExtent (str, optional) – Spatial extent of the outputs, in degrees. This parameter is applied after the rotation parameter and uses coordinates that result after rotation. The outputs can only be clipped in whole grid cells. The values you provide will be rounded off to the closest cell. Minimum length꞉ 1. Must match regular expression꞉ ([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?).

  • minDepth (float, optional) –

    Minimum depth, in meters, for the outputs to create. This parameter is ignored if the dataset does not have a depth coordinate. Its value must be between 0 and 20000, inclusive. Outputs will be created for layers with depths that are greater than or equal to the minimum depth and less than or equal to the maximum depth. If you do not specify a minimum depth, the minimum depth of the dataset will be used.

    The value 20000 is a special code representing conditions at the seafloor. Use this value if you need an estimate of “bottom temperature” or the value of another variable at the seafloor. If this value is requested, an output will be created with a fake depth of 20000 meters. The cells of this output will be assigned by stacking all of the depth layers and selecting the deepest cells that have data.

    Note that some Copernicus datasets offer a variable representing values at the seafloor that Copernicus computed ahead of time. This tool is not aware of those variables and cannot access them automatically. But you can manually access such a variable just like any other by providing its name for the Variable Short Name parameter. Accessing those precomputed variables will be faster than using a depth of 20000 to compute them yourself. Variables of that kind will be treated by this tool as not having a depth coordinate.

    Minimum value꞉ 0.0. Maximum value꞉ 20000.0.

  • maxDepth (float, optional) –

    Maximum depth, in meters, for the outputs to create. This parameter is ignored if the dataset does not have a depth coordinate. Its value must be between 0 and 20000, inclusive. Outputs will be created for images with depths that are greater than or equal to the minimum depth and less than or equal to the maximum depth. If you do not specify a maximum depth, the maximum depth of the dataset will be used.

    The value 20000 is a special code representing conditions at the seafloor. Please see the documenation for the Minimum Depth parameter for discussions of this value.

    Minimum value꞉ 0.0. Maximum value꞉ 20000.0.

  • startDate (datetime, optional) – Start date for the outputs to create. This parameter is ignored if the dataset does not have a time coordinate. Outputs will be created for images that occur on or after the start date and on or before the end date. If you do not provide a start date, the date of the first available time slice will be used.

  • endDate (datetime, optional) – End date for the outputs to create. This parameter is ignored if the dataset does not have a time coordinate. Outputs will be created for images that occur on or after the start date and on or before the end date. If you do not specify an end date, the date of the most recent time slice will be used.

  • rasterExtension (str, optional) – File extension to use for output rasters. This parameter is ignored if the rasters are stored in a geodatabase rather than the file system, or if the Raster Name Expressions parameter is provided (in which case it determines the file extension). The default is ‘.img’, for ERDAS IMAGINE format. Another popular choice is ‘.tif’, the GeoTIFF format. Please see the ArcGIS documentation for the extensions of the supported formats. Minimum length꞉ 1.

  • rasterNameExpressions (list of str, optional) –

    List of expressions specifying how the output rasters should be named. If you do not provide anything, a default naming scheme will be used.

    If the output workspace is a file system directory, you may provide one or more expressions. Each expression defines a level in a directory tree. The final expression specifies the raster file name. If the output workspace is a geodatabase, you should provide only one expression, which specifies the raster name.

    Each expression may contain any sequence of characters permitted by the output workspace. Each expression may optionally contain one or more of the following case-sensitive codes. The tool replaces the codes with appropriate values when creating each raster:

    • %(DatasetID)s - Copernicus dataset ID.

    • %(ShortVariableName)s - Copernicus short variable name.

    • %(Depth)s - depth of the raster. Only avilable for datasets that have depth coordinates.

    • %%Y - four-digit year of the raster. This and the following codes are only available for datasets that have time coordinates.

    • %%m - two-digit month of the raster.

    • %%d - two-digit day of the month of the raster.

    • %%j - three-digit day of the year of the raster.

    • %%H - two-digit hour of the raster.

    • %%M - two-digit minute of the raster.

    • %%S - two-digit second of the raster.

    Minimum length꞉ 1.

  • calculateStatistics (bool, optional) – If True, statistics will be calculated for the output rasters. This is usually a good idea for most raster formats because ArcGIS will only display them with helpful colors and gradients if statistics have been calculated. For certain formats, the explicit calculation of statistics is not necessary because it happens automatically when the rasters are created. If you’re using one of those formats, you can set this option to False to speed up the creation of the output rasters.

  • buildPyramids (bool, optional) – If True, pyramids will be built for the output rasters using the ArcGIS Build Pyramids tool. Pyramids, also known as overviews, are reduced resolution versions of the rasters that can improve the speed at which they are displayed in the ArcGIS user interface.

  • buildRAT (bool, optional) – If True and the output rasters use an integer data type, raster attribute tables (RATs) will be built for the output rasters using the ArcGIS Build Raster Attribute Table tool. Raster attribute tables are essentially histograms: they store the counts of cells having each value. If you do not need this information, you can skip the building of raster attribute tables to speed up the creation of the output rasters. Note that for certain raster formats, such as ArcInfo Binary Grid, the explicit buliding of raster attribute tables is not necessary because it happens automatically when the rasters are created. This option is ignored if the output rasters use a floating point data type.

Returns:

Updated output workspace.

Return type:

str