xrspatial.curvature.curvature

xrspatial.curvature.curvature(agg: DataArray, name: str | None = 'curvature', boundary: str = 'nan') → DataArray

Calculates, for all cells in the array, the curvature (second derivative) of each cell based on the elevation of its neighbors in a 3x3 grid. A positive curvature indicates the surface is upwardly convex. A negative value indicates it is upwardly concave. A value of 0 indicates a flat surface.

Units of the curvature output raster are one hundredth (1/100) of a z-unit.

Parameters:

• agg (xarray.DataArray or xr.Dataset) – 2D NumPy, CuPy, NumPy-backed Dask xarray DataArray of elevation values. Must contain res attribute. If a Dataset is passed, the operation is applied to each data variable independently.

• name (str, default='curvature') – Name of output DataArray.

• boundary (str, default='nan') – How to handle edges where the kernel extends beyond the raster. 'nan' — fill missing neighbours with NaN (default). 'nearest' — repeat edge values. 'reflect' — mirror at boundary. 'wrap' — periodic / toroidal.

Returns:

curvature_agg – If agg is a DataArray, returns a DataArray of the same type. If agg is a Dataset, returns a Dataset with curvature computed for each data variable. 2D aggregate array of curvature values. All other input attributes are preserved.

Return type:

xarray.DataArray or xr.Dataset

References

• arcgis: https://pro.arcgis.com/en/pro-app/latest/tool-reference/spatial-analyst/how-curvature-works.htm # noqa

Examples

Curvature works with NumPy backed xarray DataArray .. sourcecode:: python

>>> import numpy as np
>>> import dask.array as da
>>> import xarray as xr
>>> from xrspatial import curvature
>>> flat_data = np.zeros((5, 5), dtype=np.float32)
>>> flat_raster = xr.DataArray(flat_data, attrs={'res': (1, 1)})
>>> flat_curv = curvature(flat_raster)
>>> print(flat_curv)
<xarray.DataArray 'curvature' (dim_0: 5, dim_1: 5)>
array([[nan, nan, nan, nan, nan],
       [nan, -0., -0., -0., nan],
       [nan, -0., -0., -0., nan],
       [nan, -0., -0., -0., nan],
       [nan, nan, nan, nan, nan]])
Dimensions without coordinates: dim_0, dim_1
Attributes:
    res:      (1, 1)

Curvature works with Dask with NumPy backed xarray DataArray .. sourcecode:: python

>>> convex_data = np.array([
    [0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0],
    [0, 0, -1, 0, 0],
    [0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0]], dtype=np.float32)
>>> convex_raster = xr.DataArray(
    da.from_array(convex_data, chunks=(3, 3)),
    attrs={'res': (10, 10)}, name='convex_dask_numpy_raster')
>>> print(convex_raster)
<xarray.DataArray 'convex_dask_numpy_raster' (dim_0: 5, dim_1: 5)>
dask.array<array, shape=(5, 5), dtype=float32, chunksize=(3, 3), chunktype=numpy.ndarray>
Dimensions without coordinates: dim_0, dim_1
Attributes:
    res:      (10, 10)
>>> convex_curv = curvature(convex_raster, name='convex_curvature')
>>> print(convex_curv)  # return a xarray DataArray with Dask-backed array
<xarray.DataArray 'convex_curvature' (dim_0: 5, dim_1: 5)>
dask.array<_trim, shape=(5, 5), dtype=float32, chunksize=(3, 3), chunktype=numpy.ndarray>
Dimensions without coordinates: dim_0, dim_1
Attributes:
    res:      (10, 10)
>>> print(convex_curv.compute())
<xarray.DataArray 'convex_curvature' (dim_0: 5, dim_1: 5)>
array([[nan, nan, nan, nan, nan],
       [nan, -0.,  1., -0., nan],
       [nan,  1., -4.,  1., nan],
       [nan, -0.,  1., -0., nan],
       [nan, nan, nan, nan, nan]])
Dimensions without coordinates: dim_0, dim_1
Attributes:
    res:      (10, 10)

Curvature works with CuPy backed xarray DataArray. .. sourcecode:: python

>>> import cupy
>>> concave_data = np.array([
    [0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0],
    [0, 0, 1, 0, 0],
    [0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0]], dtype=np.float32)
>>> concave_raster = xr.DataArray(
    cupy.asarray(concave_data),
    attrs={'res': (10, 10)}, name='concave_cupy_raster')
>>> concave_curv = curvature(concave_raster)
>>> print(type(concave_curv.data))
<class 'cupy.core.core.ndarray'>
>>> print(concave_curv)
<xarray.DataArray 'curvature' (dim_0: 5, dim_1: 5)>
array([[nan, nan, nan, nan, nan],
       [nan, -0., -1., -0., nan],
       [nan, -1.,  4., -1., nan],
       [nan, -0., -1., -0., nan],
       [nan, nan, nan, nan, nan]], dtype=float32)
Dimensions without coordinates: dim_0, dim_1
Attributes:
    res:      (10, 10)