xrspatial.aspect.aspect#

xrspatial.aspect.aspect(agg: DataArray, name: str | None = 'aspect', method: str = 'planar', z_unit: str = 'meter', boundary: str = 'nan') → DataArray[source]#

Calculates the aspect value of an elevation aggregate.

Calculates, for all cells in the array, the downward slope direction of each cell based on the elevation of its neighbors in a 3x3 grid. The value is measured clockwise in degrees with 0 (due north), and 360 (again due north). Values along the edges are not calculated.

Direction of the aspect can be determined by its value: From 0 to 22.5: North From 22.5 to 67.5: Northeast From 67.5 to 112.5: East From 112.5 to 157.5: Southeast From 157.5 to 202.5: South From 202.5 to 247.5: Southwest From 247.5 to 292.5: West From 292.5 to 337.5: Northwest From 337.5 to 360: North

Note that values of -1 denote flat areas.

Parameters:

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

  • name (str, default='aspect') – Name of ouput DataArray.

  • method (str, default='planar') – 'planar' uses the classic Horn algorithm, scaling the gradients by the x and y cell sizes so non-square cells are handled correctly. 'geodesic' converts cells to Earth-Centered Earth-Fixed (ECEF) coordinates and fits a 3D plane, yielding accurate results for geographic (lat/lon) coordinate systems.

  • z_unit (str, default='meter') – Unit of the elevation values. Only used when method='geodesic'. Accepted values: 'meter', 'foot', 'kilometer', 'mile' (and common aliases).

  • 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:

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

Return type:

xarray.DataArray or xr.Dataset

Notes

The 'planar' method uses the coordinate spacing directly as the cell size. If the coordinates are in degrees (lat/lon) but the elevation values are in meters, the result is wrong by orders of magnitude. When this mismatch is detected, a UserWarning is emitted suggesting you reproject to a projected CRS or use method='geodesic'.

References

Examples

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

>>> import numpy as np
>>> import xarray as xr
>>> from xrspatial import aspect

>>> data = np.array([
    [1, 1, 1, 1, 1],
    [1, 1, 1, 2, 0],
    [1, 1, 1, 0, 0],
    [4, 4, 9, 2, 4],
    [1, 5, 0, 1, 4],
    [1, 5, 0, 5, 5]
], dtype=np.float32)
>>> raster = xr.DataArray(data, dims=['y', 'x'], name='raster')
>>> aspect_agg = aspect(raster)
On this page
Show Source