xrspatial.convolution.convolution_2d#

xrspatial.convolution.convolution_2d(agg, kernel, name='convolution_2d')[source]#

Calculates, for all inner cells of an array, the 2D convolution of each cell. Convolution is frequently used for image processing, such as smoothing, sharpening, and edge detection of images by eliminating spurious data or enhancing features in the data. Note that edges of output data array are filled with NaNs.

Parameters

agg (xarray.DataArray) – 2D array of values to processed. Can be NumPy backed, CuPybacked, or Dask with NumPy backed DataArray.
kernel (array-like object) – Impulse kernel, determines area to apply impulse function for each cell.

Returns

convolve_agg – 2D array representation of the impulse function. The backend array type is the same as of input.

Return type

xarray.DataArray

Examples

convolution_2d() works with NumPy backed DataArray. .. sourcecode:: python

>>> import numpy as np
>>> import xarray as xr
>>> from xrspatial.convolution import circle_kernel
>>> kernel = circle_kernel(1, 1, 1)
>>> kernel
array([[0., 1., 0.],
       [1., 1., 1.],
       [0., 1., 0.]])
>>> h, w = 4, 6
>>> data = np.arange(h*w).reshape(h, w)
>>> raster = xr.DataArray(data)
>>> raster
<xarray.DataArray (dim_0: 4, dim_1: 6)>
array([[ 0,  1,  2,  3,  4,  5],
       [ 6,  7,  8,  9, 10, 11],
       [12, 13, 14, 15, 16, 17],
       [18, 19, 20, 21, 22, 23]])
Dimensions without coordinates: dim_0, dim_1
>>> from xrspatial.convolution import convolution_2d
>>> convolved_agg = convolution_2d(raster, kernel)
>>> convolved_agg
<xarray.DataArray 'convolution_2d' (dim_0: 4, dim_1: 6)>
array([[nan, nan, nan, nan, nan, nan],
       [nan, 35., 40., 45., 50., nan],
       [nan, 65., 70., 75., 80., nan],
       [nan, nan, nan, nan, nan, nan]], dtype=float32)
Dimensions without coordinates: dim_0, dim_1

convolution_2d() works with Dask with NumPy backed DataArray. .. sourcecode:: python

>>> from xrspatial.convolution import annulus_kernel
>>> kernel = annulus_kernel(1, 1, 1.5, 0.5)
>>> kernel
array([[0., 1., 0.],
       [1., 0., 1.],
       [0., 1., 0.]])
>>> import dask.array as da
>>> data_da = da.from_array(np.ones((h, w)), chunks=(2, 2))
>>> raster_da = xr.DataArray(data_da, name='raster_da')
>>> raster_da
<xarray.DataArray 'raster_da' (dim_0: 4, dim_1: 6)>
dask.array<array, shape=(4, 6), dtype=float64, chunksize=(2, 2), chunktype=numpy.ndarray>  # noqa
Dimensions without coordinates: dim_0, dim_1
>>> convolved_agg = convolution_2d(raster_da, kernel)
>>> convolved_agg
<xarray.DataArray 'convolution_2d' (dim_0: 4, dim_1: 6)>
dask.array<_trim, shape=(4, 6), dtype=float64, chunksize=(2, 2), chunktype=numpy.ndarray>  # noqa
Dimensions without coordinates: dim_0, dim_1
>>> convolved_agg.compute()
<xarray.DataArray 'convolution_2d' (dim_0: 4, dim_1: 6)>
array([[nan, nan, nan, nan, nan, nan],
       [nan,  4.,  4.,  4.,  4., nan],
       [nan,  4.,  4.,  4.,  4., nan],
       [nan, nan, nan, nan, nan, nan]], dtype=float32)

convolution_2d() works with CuPy backed DataArray. .. sourcecode:: python

>>> from xrspatial.convolution import custom_kernel
>>> kernel = custom_kernel(np.array([
...    [1, 0, 0],
...    [1, 1, 0],
...    [1, 0, 0]
... ]))
>>> import cupy
>>> data_cupy = cupy.arange(0, w * h * 2, 2).reshape(h, w)
>>> raster_cupy = xr.DataArray(data_cupy, name='raster_cupy')
>>> print(raster_cupy)
<xarray.DataArray 'raster_cupy' (dim_0: 4, dim_1: 6)>
array([[ 0,  2,  4,  6,  8, 10],
       [12, 14, 16, 18, 20, 22],
       [24, 26, 28, 30, 32, 34],
       [36, 38, 40, 42, 44, 46]])
Dimensions without coordinates: dim_0, dim_1
>>> convolved_agg = convolution_2d(raster_cupy, kernel)
>>> type(convolved_agg.data)
<class 'cupy.core.core.ndarray'>
>>> convolved_agg
<xarray.DataArray 'convolution_2d' (dim_0: 4, dim_1: 6)>
array([[ nan,  nan,  nan,  nan,  nan,  nan],
       [ nan,  50.,  58.,  66.,  74.,  nan],
       [ nan,  98., 106., 114., 122.,  nan],
       [ nan,  nan,  nan,  nan,  nan,  nan]], dtype=float32)
Dimensions without coordinates: dim_0, dim_1

xrspatial.focal.mean

xrspatial.convolution.annulus_kernel