Surface

Aspect

xrspatial.aspect.aspect(agg: xarray.core.dataarray.DataArray, name: Optional[str] = 'aspect') xarray.core.dataarray.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 and 360 at due north. Flat areas are given a value of -1. Values along the edges are not calculated.

Parameters
  • agg (xarray.DataArray) – 2D NumPy, CuPy, NumPy-backed Dask, or Cupy-backed Dask array of elevation values.

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

Returns

aspect_agg – 2D aggregate array of calculated aspect values. All other input attributes are preserved.

Return type

xarray.DataArray of the same type as agg

References

Examples

>>> print(terrain_agg[200:203, 200:202])
<xarray.DataArray 'Elevation' (lat: 3, lon: 2)>
array([[707.57051795, 704.3194383 ],
       [706.36271613, 705.4514285 ],
       [699.46372883, 703.7514251 ]])
Coordinates:
* lon      (lon) float64 -9.975e+06 -9.925e+06
* lat      (lat) float64 -6.633e+06 -6.567e+06 -6.5e+06
Attributes:
    res:            (50000.0, 66666.66666666667)
    Description:    Example Terrain
    units:          km
    Max Elevation:  4000
>>> print(aspect_agg[200:203, 200:202])
<xarray.DataArray 'Aspect' (lat: 3, lon: 2)>
array([[155.07530658, 146.26526699],
       [194.81685088, 136.55836607],
       [203.14170549, 187.97760934]])
Coordinates:
* lon      (lon) float64 -9.975e+06 -9.925e+06
* lat      (lat) float64 -6.633e+06 -6.567e+06 -6.5e+06
Attributes:
    res:            (50000.0, 66666.66666666667)
    Description:    Example Aspect
    units:          deg
    Max Elevation:  4000

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, or Cupy-backed Dask array 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

>>> print(terrain_agg[200:203, 200:202])
<xarray.DataArray 'Elevation' (lat: 3, lon: 2)>
array([[1264.02296597, 1261.947921  ],
       [1285.37105519, 1282.48079719],
       [1306.02339636, 1303.4069579 ]])
Coordinates:
* lon      (lon) float64 -3.96e+06 -3.88e+06
* lat      (lat) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:            (80000.0, 133333.3333333333)
    Description:    Example Terrain
    units:          km
    Max Elevation:  4000
>>> print(curvature_agg[200:203, 200:202])
<xarray.DataArray 'Curvature' (lat: 3, lon: 2)>
array([[-8.14280993e-08, -5.46873377e-08],
       [ 2.85253552e-08,  1.24471207e-08],
       [ 8.91172878e-08,  1.58492666e-07]])
Coordinates:
* lon      (lon) float64 -3.96e+06 -3.88e+06
* lat      (lat) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:            (80000.0, 133333.3333333333)
    Description:    Curvature
    units:          rad
    Max Elevation:  4000

Hillshade

xrspatial.hillshade.hillshade(agg: xarray.core.dataarray.DataArray, azimuth: int = 225, angle_altitude: int = 25, name: Optional[str] = 'hillshade') xarray.core.dataarray.DataArray[source]

Calculates, for all cells in the array, an illumination value of each cell based on illumination from a specific azimuth and altitude.

Parameters
  • agg (xarray.DataArray) – 2D NumPy, CuPy, NumPy-backed Dask, or Cupy-backed Dask array of elevation values.

  • angle_altitude (int, default=25) – Altitude angle of the sun specified in degrees.

  • azimuth (int, default=225) – The angle between the north vector and the perpendicular projection of the light source down onto the horizon specified in degrees.

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

Returns

hillshade_agg – 2D aggregate array of illumination values.

Return type

xarray.DataArray, of same type as agg

References

Examples

>>> print(hillshade_agg)
<xarray.DataArray 'hillshade' (y: 5, x: 5)>
array([[       nan,        nan,        nan,        nan,        nan],
       [       nan, 0.71130913, 0.44167341, 0.71130913,        nan],
       [       nan, 0.95550163, 0.71130913, 0.52478473,        nan],
       [       nan, 0.71130913, 0.88382559, 0.71130913,        nan],
       [       nan,        nan,        nan,        nan,        nan]])
Coordinates:
  * y        (y) int32 4 3 2 1 0
  * x        (x) int32 0 1 2 3 4

Slope

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

Returns slope of input aggregate in degrees.

Parameters
  • agg (xr.DataArray) – 2D array of elevation data.

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

Returns

slope_agg – 2D array of slope values. All other input attributes are preserved.

Return type

xr.DataArray of same type as agg

References

Examples

>>> print(terrain_agg[200:203, 200:202])
<xarray.DataArray 'Elevation' (lat: 3, lon: 2)>
array([[1264.02296597, 1261.947921  ],
       [1285.37105519, 1282.48079719],
       [1306.02339636, 1303.4069579 ]])
Coordinates:
* lon      (lon) float64 -3.96e+06 -3.88e+06
* lat      (lat) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:            (80000.0, 133333.3333333333)
    Description:    Example Terrain
    units:          km
    Max Elevation:  4000

>>> print(slope_agg[200:203, 200:202])
<xarray.DataArray 'Slope' (lat: 3, lon: 2)>
array([[0.00757718, 0.00726441],
       [0.00893266, 0.00916095],
       [0.00773291, 0.00699103]], dtype=float32)
Coordinates:
* lon      (lon) float64 -3.96e+06 -3.88e+06
* lat      (lat) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:            (80000.0, 133333.3333333333)
    Description:    Example Slope
    units:          deg
    Max Elevation:  4000

Terrain Generation

xrspatial.terrain.generate_terrain(agg: xarray.core.dataarray.DataArray, x_range: tuple = (0, 500), y_range: tuple = (0, 500), seed: int = 10, zfactor: int = 4000, full_extent: Optional[Union[Tuple, List]] = None, name: str = 'terrain') xarray.core.dataarray.DataArray[source]

Generates a pseudo-random terrain which can be helpful for testing raster functions.

Parameters
  • x_range (tuple, default=(0, 500)) – Range of x values.

  • x_range – Range of y values.

  • seed (int, default=10) – Seed for random number generator.

  • zfactor (int, default=4000) – Multipler for z values.

  • full_extent (str, default=None) – bbox<xmin, ymin, xmax, ymax>. Full extent of coordinate system.

Returns

terrain – 2D array of generated terrain values.

Return type

xr.DataArray

References

Examples

>>> print(terrain)
<xarray.DataArray 'terrain' (y: 3, x: 4)>
array([[ 6.8067746,  5.263137 ,  4.664292 ,  6.821344 ],
       [ 7.4834156,  6.9849734,  4.3545456,  0.       ],
       [ 6.7674546, 10.       ,  7.0946655,  7.015267 ]], dtype=float32)  # noqa
Coordinates:
  * x        (x) float64 -1.5e+07 -5e+06 5e+06 1.5e+07
  * y        (y) float64 -1.333e+07 0.0 1.333e+07
Attributes:
    res:      (10000000.0, -13333333.333333334)

Viewshed

xrspatial.viewshed.viewshed(raster: xarray.core.dataarray.DataArray, x: Union[int, float], y: Union[int, float], observer_elev: float = 0, target_elev: float = 0) xarray.core.dataarray.DataArray[source]

Calculate viewshed of a raster (the visible cells in the raster) for the given viewpoint (observer) location.

Parameters
  • raster (xr.DataArray) – Input raster image.

  • x (int, float) – x-coordinate in data space of observer location.

  • y (int, float) – y-coordinate in data space of observer location.

  • observer_elev (float) – Observer elevation above the terrain.

  • target_elev (float) – Target elevation offset above the terrain.

Returns

viewshed – A cell x in the visibility grid is recorded as follows: If it is invisible, then x is set to INVISIBLE. If it is visible, then x is set to the vertical angle w.r.t the viewpoint.

Return type

xarray.DataArray

Examples

>>> print(terrain_agg[200:203, 200:202])
<xarray.DataArray 'Elevation' (lat: 3, lon: 2)>
array([[1264.02296597, 1261.947921  ],
       [1285.37105519, 1282.48079719],
       [1306.02339636, 1303.4069579 ]])
Coordinates:
* lon      (lon) float64 -3.96e+06 -3.88e+06
* lat      (lat) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:            (80000.0, 133333.3333333333)
    Description:    Example Terrain
    units:          km
    Max Elevation:  4000

>>> print(volcano_agg[200:203, 200:202])
<xarray.DataArray 'Volcano' (y: 3, x: 2)>
array([[0., 0.],
       [0., 0.],
       [0., 0.]])
Coordinates:
* x        (x) float64 -3.96e+06 -3.88e+06
* y        (y) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:          (80000.0, 133333.3333333333)
    Description:  Volcano

>>> print(view[200:203, 200:202])
<xarray.DataArray (y: 3, x: 2)>
array([[90., 90.],
       [90., 90.],
       [90., 90.]])
Coordinates:
* x        (x) float64 -3.96e+06 -3.88e+06
* y        (y) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:          (80000.0, 133333.3333333333)
    Description:  Volcano

Perlin Noise

xrspatial.perlin.perlin(agg: xarray.core.dataarray.DataArray, freq: tuple = (1, 1), seed: int = 5, name: str = 'perlin') xarray.core.dataarray.DataArray[source]

Generate perlin noise aggregate.

Parameters
  • agg (xr.DataArray) – 2D array of size width x height, will be used to determine height/ width and which platform to use for calculation.

  • freq (tuple, default=(1,1)) – (x, y) frequency multipliers.

  • seed (int, default=5) – Seed for random number generator.

Returns

perlin_agg – 2D array of perlin noise values.

Return type

xarray.DataArray

References

Examples

>>> print(perlin_noise)
<xarray.DataArray 'perlin' (y: 3, x: 4)>
array([[0.39268944, 0.27577767, 0.01621884, 0.05518942],
       [1.        , 0.8229485 , 0.2935367 , 0.        ],
       [1.        , 0.8715414 , 0.41902685, 0.02916668]], dtype=float32)  # noqa
Dimensions without coordinates: y, x

Bump Mapping

xrspatial.bump.bump(width: int, height: int, count: Optional[int] = None, height_func=None, spread: int = 1) xarray.core.dataarray.DataArray[source]

Generate a simple bump map to simulate the appearance of land features.

Using a user-defined height function, determines at what elevation a specific bump height is acceptable. Bumps of number count are applied over the area width x height.

Parameters
  • width (int) – Total width, in pixels, of the image.

  • height (int) – Total height, in pixels, of the image.

  • count (int) – Number of bumps to generate.

  • height_func (function which takes x, y and returns a height value) – Function used to apply varying bump heights to different elevations.

  • spread (int, default=1) – Number of pixels to spread on all sides.

Returns

bump_agg – 2D aggregate array of calculated bump heights.

Return type

xarray.DataArray

References

Examples

>>> print(terrain_agg[200:203, 200:202])
<xarray.DataArray 'Elevation' (lat: 3, lon: 2)>
array([[1264.02296597, 1261.947921  ],
       [1285.37105519, 1282.48079719],
       [1306.02339636, 1303.4069579 ]])
Coordinates:
* lon      (lon) float64 -3.96e+06 -3.88e+06
* lat      (lat) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:            (80000.0, 133333.3333333333)
    Description:    Example Terrain
    units:          km
    Max Elevation:  4000
>>> print(bump_agg[200:205, 200:206])
<xarray.DataArray 'Bump Height' (y: 5, x: 6)>
array([[nan, nan, nan, nan,  5.,  5.],
       [nan, nan, nan, nan, nan,  5.],
       [nan, nan, nan, nan, nan, nan],
       [nan, nan, nan, nan, nan, nan],
       [nan, nan, nan, nan, nan, nan]])
Coordinates:
* x        (x) float64 -3.96e+06 -3.88e+06 -3.8e+06 ... -3.64e+06 -3.56e+06
* y        (y) float64 6.733e+06 6.867e+06 7e+06 7.133e+06 7.267e+06
Attributes:
    res:          1
    Description:  Example Bump Map
    units:        km