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

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)

xrspatial.aspect.aspect

xrspatial.hillshade.hillshade