Spatial Module

Module for spatial functions, considering a set of polygons obtained by image segmentation.

stmetrics.spatial.aspect_ratio(geom)

This function computes the aspect ratio of a given geometry.

The Aspect Ratio is the ratio of the length and the width of the minimum bounding rectangle of a polygon.

Parameters:geom (shapely.geometry.Polygon) – Polygon geometry
Returns aspect_ratio:
 Polygon aspect_ratio.
stmetrics.spatial.distance(c_series, ic, jc, subim, S, m, rmin, cmin, window=None, max_dist=None, max_step=None, max_diff=None, penalty=None, psi=None, pruning=False)

This function computes the spatial-temporal distance between two pixels using the DTW distance.

Parameters:
  • c_series (numpy.ndarray) – average time series of cluster.
  • ic (int) – X coordinate of cluster center.
  • jc (int) – Y coordinate of cluster center.
  • subim (int) – Block of image from the cluster under analysis.
  • S (int) – Pattern spacing value.
  • m (float) – Compactness value.
  • rmin (int) – Minimum row.
  • cmin (int) – Minimum column.
  • window – Only allow for maximal shifts from the two diagonals smaller than this number. It includes the diagonal, meaning that an Euclidean distance is obtained by setting window=1.
  • max_dist – Stop if the returned values will be larger than this value.
  • max_step – Do not allow steps larger than this value.
  • max_diff – Return infinity if length of two series is larger.
  • penalty – Penalty to add if compression or expansion is applied.
  • psi – Psi relaxation parameter (ignore start and end of matching). Useful for cyclical series.
  • use_pruning – Prune values based on Euclidean distance.
Returns D:

numpy.ndarray distance.
stmetrics.spatial.distance_fast(c_series, ic, jc, subim, S, m, rmin, cmin, window=None, max_dist=None, max_step=None, max_diff=None, penalty=None, psi=None)

This function computes the spatial-temporal distance between two pixels using the dtw distance with C implementation.

Parameters:
  • c_series (numpy.ndarray) – average time series of cluster.
  • ic (int) – X coordinate of cluster center.
  • jc (int) – Y coordinate of cluster center.
  • subim (int) – Block of image from the cluster under analysis.
  • S (int) – Pattern spacing value.
  • m (float) – Compactness value.
  • rmin (int) – Minimum row.
  • cmin (int) – Minimum column.
  • window – Only allow for maximal shifts from the two diagonals smaller than this number. It includes the diagonal, meaning that an Euclidean distance is obtained by setting window=1.
  • max_dist – Stop if the returned values will be larger than this value.
  • max_step – Do not allow steps larger than this value.
  • max_diff – Return infinity if length of two series is larger.
  • penalty – Penalty to add if compression or expansion is applied.
  • psi – Psi relaxation parameter (ignore start and end of matching). Useful for cyclical series.
Returns D:

numpy.ndarray distance.
stmetrics.spatial.dtw_filter(dataset, kernel_size=3, window=None, max_dist=None, max_step=None, max_length_diff=None, penalty=None, psi=None, pruning=False)

This function performs a spatio-temporal filtering of datacube using the DTW distance.

Parameters:
  • dataset (shapely.geometry.Polygon) – SITS dataset.
  • kernel_size (int) – Size of convolutional kernel.
  • window – Only allow for maximal shifts from the two diagonals smaller than this number. It includes the diagonal, meaning that an Euclidean distance is obtained by setting window=1.
  • max_dist – Stop if the returned values will be larger than this value.
  • max_step – Do not allow steps larger than this value.
  • max_diff – Return infinity if length of two series is larger.
  • penalty – Penalty to add if compression or expansion is applied.
  • psi – Psi relaxation parameter (ignore start and end of matching). Useful for cyclical series.
  • use_pruning – Prune values based on Euclidean distance.
Returns edge:

Edge image as numpy.ndarray.
stmetrics.spatial.extract_features(dataset, segmentation, features=['mean', 'std', 'min', 'max', 'majority', 'area', 'perimeter', 'width', 'length', 'aspect_ratio', 'symmetry', 'compactness', 'rectangular_fit'], nodata=-9999)

This function computes features using polygon geometries.

Regarding image features, this function computes 5 features: Mean, Standard Deviation, Minimum, Maximum and Majority (mode). Along side with the image features, 8 shape features can be computed for each polygon: Area, Perimeter, Width, Length, Aspect Ratio ratio, Symmetry, Compactness and Rectangular fit.

Parameters:
  • dataset (Rasterio, Xarray.Dataset or string) – Images or path to images that compose time series.
  • segmentation (geopandas.Dataframe) – Spatio-temporal Segmentation.
  • features (list) – List of features to be extracted
  • nodata (int) – Nodata value
Returns segmentation:
 

GeoPandas DataFrame with the features.
stmetrics.spatial.init_cluster_hex

This function initialize the clusters for SNITC using a hexagonal pattern.

Parameters:
  • rows (int) – Number of rows of image.
  • columns (int) – Number of columns of image.
  • ki (int) – Number of desired superpixel.
  • img (numpy.ndarray) – Input image.
  • bands (int) – Number of bands (lenght of time series).
Returns C:

ND-array containing cluster centres information.
Returns S:

Spacing between clusters.
Returns l:

Matrix label.
Returns d:

Distance matrix from cluster centres.
Returns k:

Number of superpixels that will be produced.
stmetrics.spatial.init_cluster_regular

This function initialize the clusters for SNITC using a square pattern.

Parameters:
  • rows (int) – Number of rows of image.
  • columns (int) – Number of columns of image.
  • ki (int) – Number of desired superpixel.
  • img (numpy.ndarray) – Input image.
  • bands (int) – Number of bands (lenght of time series).
Returns C:

ND-array containing cluster centres information.
Returns S:

Spacing between clusters.
Returns l:

Matrix label.
Returns d:

Distance matrix from cluster centres.
Returns k:

Number of superpixels that will be produced.
stmetrics.spatial.length(geom)

This function computes the lenght of a geometry.

Parameters:geom (shapely.geometry.Polygon) – Polygon geometry.
Returns length:Polygon length.
stmetrics.spatial.postprocessing(raster, S)

Post processing function to enforce connectivity.

Parameters:
  • raster (numpy.ndarray) – Labelled image.
  • S (int) – Spacing between superpixels.
Returns final:

Labelled image with connectivity enforced.
stmetrics.spatial.rectangular_fit(geom)

This function computes the rectangular fit of a geometry. The rectangular fit is defined as:

\[RectFit = (AR - AD) / AO\]

where AO is the area of the original object, AR is the area of the equal rectangle (AO = AR) and AD is the overlaid difference between the equal rectangle and the original object (Sun et al. 2015).

Parameters:geom (shapely.geometry.Polygon) – Polygon geometry
Returns rectangular_fit:
 Polygon rectangular fit.

Tip

To know more about it:

Sun, Z., Fang, H., Deng, M., Chen, A., Yue, P. and Di, L. “Regular Shape Similarity Index:Novel Index for Accurate Extraction of Regular Objects From Remote Sensing Images,” IEEE Transactions on Geoscience and Remote Sensing, v.53, 2015, p. 3737. doi:10.1109/TGRS.2014.2382566

stmetrics.spatial.reock_compactness(geom)

This function computes the reock compactness of a given geometry.

The Reock Score (R) is the ratio of the area of a polygon P to the area of a minimum bounding cirle (AMBC) that encloses the geometry. This score falls within the range of [0,1] and high values indicates a more compact geometry.

\[Reock = A_p/A_{MBC}\]
Parameters:geom (shapely.geometry.Polygon) – Polygon geometry.
Returns reock:Polygon reock compactness.

Tip

To know more about it:

Reock, Ernest C. 1961. “A note: Measuring compactness as a requirement of legislative apportionment.” Midwest Journal of Political Science 1(5), 70–74.

stmetrics.spatial.seg_metrics(dataframe, bands=None, metrics_dict={'basics': ['all'], 'fractal': ['all'], 'polar': ['all']}, features=['mean'], num_cores=-1)

This function compute time series metrics from a geopandas with time features. Currently, basic, polar and fractal metrics are extracted. but you can set the metrics you to compute using a dictionary.

Parameters:
  • dataframe (pandas DataFrame) – Pandas DataFrame with time series information.
  • bands (list) – List of bands from which the metrics should be computed.
  • metrics_dict (dictionary) – Dictionary of metrics to be computed.
  • features (list) – List of features to be used for computation. This parameter allows you to use the features extracted with extract_features function and compute metrics over image features (mean, max, min, std and mode). If it is None, the code expect that the DataFrame has only one variable.
Returns out_dataframe:
 

Geopandas dataframe with the features added.
stmetrics.spatial.snitc(dataset, ki, m, nodata=0, scale=10000, iter=10, pattern='hexagonal', output='shp', window=None, max_dist=None, max_step=None, max_diff=None, penalty=None, psi=None, pruning=False)

This function create spatial-temporal superpixels using a Satellite Image Time Series (SITS). Version 1.4

Parameters:
  • image (Rasterio dataset object or a xarray.DataArray.) – SITS dataset.
  • k (int) – Number or desired superpixels.
  • m (int) – Compactness value. Bigger values led to regular superpixels.
  • nodata (float) – If you dataset contain nodata, it will be replace by this value. This value is necessary to be possible the use the DTW distance. Ideally your dataset must not contain nodata.
  • scale (int) – Adjust the time series, to 0-1. Necessary to distance calculation.
  • iter (int) – Number of iterations to be performed. Default = 10.
  • pattern (int) – Type of pattern initialization. Hexagonal (default) or regular (as SLIC).
  • output (string) – Type of output to be produced. Default is shp (Shapefile). The two possible values are shp and matrix (returns a numpy array).
  • window – Only allow for maximal shifts from the two diagonals smaller than this number. It includes the diagonal, meaning that an Euclidean distance is obtained by setting window=1.
  • max_dist – Stop if the returned values will be larger than this value.
  • max_step – Do not allow steps larger than this value.
  • max_diff – Return infinity if length of two series is larger.
  • penalty – Penalty to add if compression or expansion is applied.
  • psi – Psi relaxation parameter (ignore start and end of matching). Useful for cyclical series.
Returns segmentation:
 

Segmentation produced.
..Note::
Reference: Soares, A. R., Körting, T. S., Fonseca, L. M. G., Bendini, H. N. Simple Nonlinear Iterative Temporal Clustering. IEEE Transactions on Geoscience and Remote, 2020 (Early Access).
stmetrics.spatial.symmetry(geom)

This function computes the symmetry of a given geometry.

Symmetry is calculated by dividing the overlapping area (AO), between a polygon P and its reflection across the horizontal axis by the area of the polygon P (A_p). The range of this score falls between [0,1] and a score closer to 1 indicates a more compact and regular geometry.

\[Symmetry = AO/A_p\]
Parameters:geom (shapely.geometry.Polygon) – Polygon geometry
Returns symmetry:
 Polygon symmetry.
stmetrics.spatial.update_cluster

This function update clusters.

Parameters:
  • img (numpy.ndarray) – Input image.
  • la (numpy.ndarray) – Matrix label.
  • rows (int) – Number of rows of image.
  • columns (int) – Number of columns of image.
  • bands (int) – Number of bands (lenght of time series).
  • k (int) – Number of superpixel.
Returns C_new:

ND-array containing updated cluster centres information.
stmetrics.spatial.width(geom)

This function computes the width of a geometry.

Parameters:geom (shapely.geometry.Polygon) – Polygon geometry.
Returns width:Polygon width.
stmetrics.spatial.write_pandas(segmentation, transform, crs)

This function creates a GeoPandas DataFrame of the segmentation.

Parameters:
  • segmentation (numpy.ndarray) – Segmentation numpy array.
  • transform (list) – Transformation parameters.
  • crs (PROJ4 dict) – Coordinate Reference System.
Returns gdf:

Segmentation as a geopandas geodataframe.