xrspatial.curvature.curvature#

xrspatial.curvature.curvature(agg: xarray.core.dataarray.DataArray, name: Optional[str] = 'curvature') xarray.core.dataarray.DataArray[source]#

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) – 2D NumPy, CuPy, NumPy-backed Dask xarray DataArray of elevation values. Must contain res attribute.

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

Returns

curvature_agg – 2D aggregate array of curvature values. All other input attributes are preserved.

Return type

xarray.DataArray, of the same type as agg

References

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)