src / pysoilmap / features.py

---

Topography

class Topography(dem, cellsize, diff=<function diff_finite>, indexing='xy', transform=None, crs=None, **kwargs)

Bases: object

Calculates various topographic indices at each pixel from on a given DEM.

Parameters:

• dem (ndarray) – DEM, i.e. z coordinates of each pixel

• cellsize (tuple) – Size of a pixel given as pair (width, height)

• diff (callable) – differentiation function. Either diff_finite(), or diff_gauss()

• indexing (str) – either xy or ij, same meaning as for numpy.meshgrid

• transform (Optional[list]) – list of 6 numbers that describe the transformation. Only used for latitude, rad_angle, and sun_exposure.

• crs (Optional[str]) – Name of the coordinate system. Only used for latitude, rad_angle, and sun_exposure.

• kwargs – keyword arguments for diff. Usually sigma=VALUE for the gaussian derivative

Note that the DEM is assumed to live on a regular rectangular grid.

Note that the object caches some of the calculated quantities for reuse. In order to free memory you should let go of the Topography instance after calculation of the quantities in which you are interested

Methods Summary

D1x()	Calculate the first derivative (slope) of the DEM in X direction.
D1y()	Calculate the first derivative (slope) of the DEM in Y direction.
D2x()	Calculate the 2nd derivative (curvature) of the DEM in X direction.
D2y()	Calculate the 2nd derivative (curvature) of the DEM in Y direction.
Dx2()	Return the square of the X slope.
Dy2()	Return the square of the Y slope.
aspect()	Returns the angle of the gradient direction in radians counted from north in clockwise direction.
curvature()	Returns the absolute value of the total curvature.
curvature_x()	Calculate the 2nd derivative (curvature) of the DEM in X direction.
curvature_y()	Calculate the 2nd derivative (curvature) of the DEM in Y direction.
diff(dx, dy)	Differentiate the DEM dx times in X direction and dy times in Y direction.
eastness()	Calculate the eastness, i.e. the sine-transformed aspect.
grad_dir()	Returns the angle of the gradient direction in radians counted from east in counter-clockwise direction (i.e.
latitude()	Get the latitude in radians at each pixel.
northness()	Calculate the northness, i.e. the cosine-transformed aspect.
plan_curvature()	Calculate the planform curvature, i.e. the curvature of the terrain surface in the horizontal plane.
prof_curvature()	Calculate the profile curvature., i.e. the curvature of a terrain cross-section on a vertical plane containing the gradient vector.
rad_angle([declination])	Return the cosine of the "radiation angle" according to Herbsta, et al 2006 [1].
slope()	Returns the absolute value of the total slope.
slope_angle()	Returns the slope angle, i.e. the angle between the horizontal plane and the gradient vector.
slope_angle_x()	Returns the x slope angle, i.e. the angle between the x axis and the surface in the xz plane.
slope_angle_y()	Returns the y slope angle, i.e. the angle between the y axis and the surface in the yz plane.
slope_x()	Calculate the first derivative (slope) of the DEM in X direction.
slope_y()	Calculate the first derivative (slope) of the DEM in Y direction.
sun_exposure([declination])	Return the cosine of the angle between surface normal and the sun at midday.
tang_curvature()	Calculate the tangential curvature, i.e. the curvature of a terrain cross-section on a vertical plane perpendicular to the gradient direction.
verticality()	Sine of the slope angle.
verticality_x()	Sine of the x slope angle.
verticality_y()	Sine of the y slope angle.

Methods Documentation

D1x()

Calculate the first derivative (slope) of the DEM in X direction. Same as self.diff(1, 0).

Return type:

ndarray

D1y()

Calculate the first derivative (slope) of the DEM in Y direction. Same as self.diff(0, 1).

Return type:

ndarray

D2x()

Calculate the 2nd derivative (curvature) of the DEM in X direction. Same as self.diff(2, 0).

Return type:

ndarray

D2y()

Calculate the 2nd derivative (curvature) of the DEM in Y direction. Same as self.diff(0, 2).

Return type:

ndarray

Dx2()

Return the square of the X slope. Same as D1x**2.

Return type:

ndarray

Dy2()

Return the square of the Y slope. Same as D1y**2.

Return type:

ndarray

aspect()

Returns the angle of the gradient direction in radians counted from north in clockwise direction.

Return type:

ndarray

curvature()

Returns the absolute value of the total curvature. Same as sqrt(D2x**2 + D2y**2).

Return type:

ndarray

curvature_x()

Calculate the 2nd derivative (curvature) of the DEM in X direction. Same as self.diff(2, 0).

Return type:

ndarray

curvature_y()

Calculate the 2nd derivative (curvature) of the DEM in Y direction. Same as self.diff(0, 2).

Return type:

ndarray

diff(dx, dy)

Differentiate the DEM dx times in X direction and dy times in Y direction.

Return type:

ndarray

eastness()

Calculate the eastness, i.e. the sine-transformed aspect.

This quantity can be understood as the projected length of the gradient direction on the east axis in the horizontal plane.

Return type:

ndarray

grad_dir()

Returns the angle of the gradient direction in radians counted from east in counter-clockwise direction (i.e. mathematical convention).

Return type:

ndarray

latitude()

Get the latitude in radians at each pixel.

Return type:

ndarray

northness()

Calculate the northness, i.e. the cosine-transformed aspect.

This quantity can be understood as the projected length of the gradient direction on the north axis in the horizontal plane.

Return type:

ndarray

plan_curvature()

Calculate the planform curvature, i.e. the curvature of the terrain surface in the horizontal plane.

See: - http://surferhelp.goldensoftware.com/gridops/plan_curvature.htm - Map Use: Reading, Analysis, Interpretation, Seventh Edition (p. 360)

Return type:

ndarray

prof_curvature()

Calculate the profile curvature., i.e. the curvature of a terrain cross-section on a vertical plane containing the gradient vector.

See: - http://surferhelp.goldensoftware.com/gridops/profile_curvature.htm - Map Use: Reading, Analysis, Interpretation, Seventh Edition (p. 360)

Return type:

ndarray

rad_angle(declination=0)

Return the cosine of the “radiation angle” according to Herbsta, et al 2006 [1].

Parameters:

declination – sun declination angle in radians. Can be used to adjust for seasonal changes.

All input arguments must be of the same shape or scalars.

The formulate is taken from Herbsta, et al. 2006 [1] who cite Moore, et al. 1988 [2] as source - which doesn’t mention the formula anywhere.

[1] (2006 Geostatistical co-regionalization of soil hydraulic properties in a microscale catchment using terrain attributes [Herbsta, et al.])

[2] Moore, I.D., Burch, G.J., Mackenzie, D.H., 1988. Topographic effects on the distribution of surface soil water and the location of ephemeral gullies. American Society of Agricultural Engi- neers 31 (4), 1098 – 1107.

Return type:

ndarray

slope()

Returns the absolute value of the total slope. Same as sqrt(D1x**2 + D1y**2).

Return type:

ndarray

slope_angle()

Returns the slope angle, i.e. the angle between the horizontal plane and the gradient vector. This is a non-negative value.

Return type:

ndarray

slope_angle_x()

Returns the x slope angle, i.e. the angle between the x axis and the surface in the xz plane.

Return type:

ndarray

slope_angle_y()

Returns the y slope angle, i.e. the angle between the y axis and the surface in the yz plane.

Return type:

ndarray

slope_x()

Calculate the first derivative (slope) of the DEM in X direction. Same as self.diff(1, 0).

Return type:

ndarray

slope_y()

Calculate the first derivative (slope) of the DEM in Y direction. Same as self.diff(0, 1).

Return type:

ndarray

sun_exposure(declination=0)

Return the cosine of the angle between surface normal and the sun at midday.

Parameters:

declination – sun declination angle in radians. Can be used to adjust for season. A positive value corresponds to a northward deviation. Zero means the sun is in the zenith over the equator.

This is very similar to rad_angle but not exactly the same.

Return type:

ndarray

tang_curvature()

Calculate the tangential curvature, i.e. the curvature of a terrain cross-section on a vertical plane perpendicular to the gradient direction.

See: - http://surferhelp.goldensoftware.com/gridops/tangential_curvature.htm - Map Use: Reading, Analysis, Interpretation, Seventh Edition (p. 360)

Return type:

ndarray

verticality()

Sine of the slope angle.

Return type:

ndarray

verticality_x()

Sine of the x slope angle.

Return type:

ndarray

verticality_y()

Sine of the y slope angle.

Return type:

ndarray