Calculate Texture Metric for Single Pixel

Description

Calculates the various texture metrics over a window centered on an individual pixel. This function is modified slightly from the calculate_lsm_focal function in the landscapemetrics package (Hesselbarth et al. 2019).

Usage

.calculate_met_focal(landscape, n_row, n_col, points, what, ...)

Arguments

Details

Metrics from geodiv package:

1. 'sa': average surface roughness

2. 'sq': root mean square roughness

3. 's10z': ten-point height

4. 'sdq': root mean square slope of surface, 2-point method

5. 'sdq6': root mean square slope of surface, 7-point method

6. 'sdr': surface area ratio

7. 'sbi': surface bearing index

8. 'sci': core fluid retention index

9. 'ssk': skewness

10. 'sku': kurtosis

11. 'sds': summit density

12. 'sfd': 3d fractal dimension

13. 'srw': dominant radial wavelength, radial wavelength index, mean half wavelength

14. 'std': angle of dominating texture, texture direction index

15. 'svi': valley fluid retention index

16. 'stxr': texture aspect ratio

17. 'ssc': mean summit curvature

18. 'sv': maximum valley depth

19. 'sph': maximum peak height

20. 'sk': core roughness depth

21. 'smean': mean peak height

22. 'svk': reduced valley depth

23. 'spk': reduced peak height

24. 'scl': correlation length

25. 'sdc': bearing area curve height interval

Value

The metric value over the window.

References

1. Hesselbarth, M.H.K., Sciaini, M., With, K.A., Wiegand, K., Nowosad, J. 2019. landscapemetrics: an open-source R tool to calculate landscape metrics. - Ecography 42:1648-1657(ver. 0).

Degree to Radian Conversion

Description

Converts degree value(s) to radians.

Usage

.deg2rad(x)

Arguments

Value

Numeric of degree value(s).

Estimate Maximum Correlation Length

Description

Internal function to calculates the maximum distances to specified autocorrelation values (e.g., 0.2) of the areal autocorrelation function (AACF). All 180 degrees from the origin of the AACF image are considered for the calculation.

Usage

.maxdist(threshold, aacfimg, distimg)

Arguments

Value

A list containing the maximum distances from an autocorrelation value of 1 to the specified autocorrelation value < 1. Distances are meters if original raster was unprojected, and are in map units (usually meters) if raster was projected (see raster::distance documentation for more details).

Estimate Minimum Correlation Length

Description

Internal function to calculates the minimum distances to specified autocorrelation values (e.g., 0.2) of the areal autocorrelation function (AACF). All 180 degrees from the origin of the AACF image are considered for the calculation.

Usage

.mindist(threshold, aacfimg, distimg)

Arguments

Value

A list containing the minimum distances from an autocorrelation value of 1 to the specified autocorrelation value < 1. Distances are meters if original raster was unprojected, and are in map units (usually meters) if raster was projected (see raster::distance documentation for more details).

Radian to Degree Conversion

Description

Converts radian value(s) to degrees.

Usage

.rad2deg(x)

Arguments

Value

Numeric of degree value(s).

Estimate the Areal Autocorrelation Function

Description

Calculates the areal autocorrelation function (AACF) as the inverse of the Fourier power spectrum. aacf(x) returns the AACF in both matrix and raster format.

Usage

aacf(x)

Arguments

Value

A raster or matrix representation of the AACF. Both raster and matrix values are normalized so that the maximum is equal to 1.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate aacf img and matrix
aacf_out <- aacf(normforest)

# plot resulting aacf image
terra::plot(aacf_out)

Area Above the Bearing Area Curve

Description

Calculates the area above the bearing area curve from points a to b. If a box is drawn around a function with the upper-left at a and the bottom-right at b, this function extracts the area above the function within the box.

Usage

area_above(f, a, b, n = 100)

Arguments

Details

The area under the curve used to calculate area above the curve is calculated as the numerical integral of the Bearing Area function from a to b using the trapezoid rule with n subdivisions. Assume a < b and n is a positive integer.

Value

A numeric value representing the area above the curve with x bounds a and b.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# basic values
z <- terra::values(normforest)

# calculate cumulative probability density function of surface 'height' (= ndvi)
mod <- ecdf((1 - z))

# valley fluid retention index = void volume in 'valley' zone
Svi <- area_above(f = mod, b = 1, a = 0.8, n = 500)

Calculates the Rotated Bearing Area Curve

Description

Finds a rotated version of the Bearing Area (Abbott-Firestone) curve from a raster or matrix. The resulting function should be rotated 90 degrees clockwise to get the actual Bearing Area curve.

Usage

bearing_area(x)

Arguments

Value

A function describing the rotated Bearing Area curve.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# find the rotated Bearing Area curve.
ba_func <- bearing_area(normforest)

# rotate the values and re-plot
xval <- environment(ba_func)$y
yval <- (1 - environment(ba_func)$x)
plot(yval ~ xval)

Finds the Best Fit Polynomial Surface

Description

Finds the best fit polynomial surface for a raster or matrix. This function tests least squares polynomial fits with orders of 0 - 3 and determines which order minimizes the error when the fit is subtracted from the original image.

Usage

bestfitplane(x)

Arguments

Value

A raster or matrix of the same size as the input with values predicted from the best polynomial fit.

Examples

# import raster image
data(orforest)
orforest <- terra::unwrap(orforest)

# find the least squares polynomial surface
poly <- bestfitplane(orforest)

# plot the fit
terra::plot(poly)

Fourier Transform Shift

Description

This function serves to shift the zero-frequency component of the Fourier transform to the center of the matrix.

Usage

fftshift(x, dim = -1)

Arguments

Value

An n x n matrix with the zero-frequency component of the Fourier transform in the center.

References

#' This function was created from code posted by rayryeng at: https://stackoverflow.com/questions/38230794/how-to-write-fftshift-and-ifftshift-in-r.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# convert to matrix form
M <- ncol(normforest)
N <- nrow(normforest)
zmat <- matrix(terra::values(normforest), ncol = M, nrow = N, byrow = TRUE)

# calculate fourier transform and shift
ftmat <- fft(zmat)
ftshift <- fftshift(ftmat)

# plot real component
r <- terra::setValues(normforest, Re(ftshift))
terra::plot(r)

Finds the Flattest Part of the Bearing Area Curve

Description

Locates the flattest x percentage of the Bearing Area curve. Meant to locate the flattest 40 percent of the Bearing Area curve as used in several roughness parameter calculations.

Usage

find_flat(x, perc = 0.4)

Arguments

Value

A list containing the equation for the best fit line, the predicted values from that line, the high and low y-intercept values for the intersection points of the line with the Bearing Area curve, and the high and low x-intercept values for the intersection points of the line with the Bearing Area curve.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# locate the flattest 40% of the bearing area curve
line_data <- find_flat(normforest, perc = 0.4)

# extract the equation of the line
bf_line <- line_data[[1]]

Find Local Peaks

Description

Locates local peaks on a raster or matrix. A peak is defined as any pixel where all 8 surrounding pixels have lower values, and the center pixel has a positive value.

Usage

findpeaks(x)

Arguments

Value

A dataframe of local peak locations (x, y) and values (val). The raster or matrix location index (ind), row (row), and column (col) are also listed.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# locate peaks
peaks <- findpeaks(normforest)

# calculate the summit density (# peaks/area)
N <- ncol(normforest)
M <- nrow(normforest)
Sds <- nrow(peaks) / ((N - 1) * (M - 1))

Find Local Valleys

Description

Locates local valleys on a raster or matrix. A valley is defined as any pixel where all 8 surrounding pixels have higher values, and the center pixel has a negative value.

Usage

findvalleys(x)

Arguments

Value

A dataframe of local valley locations (x, y) and values (val). The raster or matrix location index (ind), row (row), and column (col) are also listed.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# locate peaks and valleys
peaks <- findpeaks(normforest)
valleys <- findvalleys(normforest)

# find top 5 peaks, valleys
top_peaks <- peaks[order(peaks$val, decreasing = TRUE)[1:5],]
bottom_valleys <- valleys[order(valleys$val)[1:5],]

# calculate the ten-point height
S10z <- (sum(top_peaks$val) + sum(abs(bottom_valleys$val))) / 5

Calculate a Least Squares Polynomial Surface

Description

Fits a polynomial surface of order n to a raster or matrix.

Usage

fitplane(x, order)

Arguments

Value

A matrix with values predicted from the polynomial fit.

Examples

# import raster image
data(orforest)
orforest <- terra::unwrap(orforest)

# find the 2nd order least squares polynomial surface
polyfit <- fitplane(orforest, order = 2)

# create raster of polyfit
x <- terra::setValues(orforest, polyfit)

# plot the fit
terra::plot(x)

Flattened Surface Area

Description

Calculates the surface area of a flat raster or matrix with the same x, y bounds as the study surface.

Usage

flatsa(x)

Arguments

Details

This function scales both x and y to between 0 and 1. This is done because most satellite data have units where the x, y units do not equal the z units and because the flat surface area is usually compared to the actual surface area. Surface area is calculated over the sample area (N-1, M-1).

Value

A numeric value representing the scaled surface area of a flattened surface with the same x, y bounds.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate flattened surface area
flatsa(normforest)

Calculate Texture Metrics per Pixel

Description

Calculates the various texture metrics over windows centered on individual pixels. This creates a continuous surface of the texture metric. This function is a modified version of the window_lsm function from the landscapemetrics package (Hesselbarth et al. 2019).

Usage

focal_metrics(x, window, metrics, progress, ...)

Arguments

Details

Metrics available from geodiv package:

1. 'sa': average surface roughness

2. 'sq': root mean square roughness

3. 's10z': ten-point height

4. 'sdq': root mean square slope of surface, 2-point method

5. 'sdq6': root mean square slope of surface, 7-point method

6. 'sdr': surface area ratio

7. 'sbi': surface bearing index

8. 'sci': core fluid retention index

9. 'ssk': skewness

10. 'sku': kurtosis

11. 'sds': summit density

12. 'sfd': 3d fractal dimension

13. 'srw': dominant radial wavelength, radial wavelength index, mean half wavelength

14. 'std': angle of dominating texture, texture direction index

15. 'svi': valley fluid retention index

16. 'stxr': texture aspect ratio

17. 'ssc': mean summit curvature

18. 'sv': maximum valley depth

19. 'sph': maximum peak height

20. 'sk': core roughness depth

21. 'smean': mean peak height

22. 'svk': reduced valley depth

23. 'spk': reduced peak height

24. 'scl': correlation length

25. 'sdc': bearing area curve height interval

Value

A raster of the metric calculated in windows over the raster or matrix. If the input was a matrix, the function will return a raster with an extent of [0, 1, 0, 1].

References

1. Hesselbarth, M.H.K., Sciaini, M., With, K.A., Wiegand, K., Nowosad, J. 2019. landscapemetrics: an open-source R tool to calculate landscape metrics. - Ecography 42:1648-1657(ver. 0).

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# crop raster to smaller area
x <- terra::crop(normforest, terra::ext(normforest[1:100, 1:100, drop = FALSE]))

# get a surface of root mean square roughness
sa_img <- focal_metrics(x = x, window = matrix(1, 5, 5),
                        metrics = list('sa'), progress = TRUE)

# plot the result
terra::plot(sa_img$sa)

Value of the Bearing Area Curve at a Specified Value

Description

Determines the value of the bearing area curve for a specific value along the x-axis (xval).

Usage

height_ba(x, xval)

Arguments

Value

A numeric value of the bearing area function corresponding to xval.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# determine the bearing area function value
# corresponding to an x value of 0.4
val <- height_ba(normforest, 0.4)

NDVI errors for a portion of southwestern Oregon, USA.

Description

A raster image of Normalized Difference Vegetation Index (NDVI) errors derived from Landsat data for a small portion of SW Oregon state. This raster was calculated by subtracting the best-fit polynomial plane from the orforest values. The best-fit polynomial plane was calculated using bestfitplane.

Usage

normforest

Format

A raster image with 371 x 371 pixels

range

-0.5854638 – 0.1585918

bounds

-123, -122.9, 43.0002, 43.1

resolution

30m x 30m (0.002694946 degrees)

projection

WGS84

scalar

1

...

Details

NDVI values are derived from Landsat scene path 45, row 30 summarized as the mean NDVI value between June and August 2000 at roughly 30m resolution. Clouds were removed from the Landsat scene before calculating the mean. The image was created using Google Earth Engine in August 2018.

SRTM elevation for a portion of southwestern Oregon, USA.

Description

A raster image of Shuttle Radar Topography Mission (SRTM) elevation for a portion of southwestern Oregon.

Usage

orelevation

Format

A raster image with 371 x 371 pixels

range

433 – 1390

bounds

-123.0001, -122.9002, 43.00015, 43.10013

resolution

30m x 30m (0.002694946 degrees)

projection

WGS84

scalar

1

...

Details

Elevation values are from the SRTM data for 2000 and are at roughly 30m resolution. The image was created using Google Earth Engine in October 2019.

NDVI for a portion of southwestern Oregon, USA.

Description

A raster image of Normalized Difference Vegetation Index (NDVI) derived from Landsat data for a small portion of SW Oregon state.

Usage

orforest

Format

A raster image with 371 x 371 pixels

range

0 – 1

bounds

-123, -122.9, 43.0002, 43.1

resolution

30m x 30m (0.002694946 degrees)

projection

WGS84

scalar

1

...

Details

NDVI values are derived from Landsat scene path 45, row 30 summarized as the mean NDVI value between June and August 2000 at roughly 30m resolution. Clouds were removed from the Landsat scene before calculating the mean. The image was created using Google Earth Engine in August 2018.

Extend edges of a matrix.

Description

Extends edge values of a raster or matrix by a specified number of pixels.

Usage

pad_edges(x, size, val = NULL)

Arguments

Value

A raster with edges padded size number of pixels on each edge.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# crop raster to much smaller area
x <- pad_edges(as.matrix(normforest), 3, val = NA)

Plots the Bearing Area Curve

Description

Calculates and plots the Bearing Area curve for a raster or matrix using the bearing_area() function (with correctly rotated results).

Usage

plot_ba_curve(x, divisions = FALSE)

Arguments

Details

If divisions = TRUE, the lines representing the best fit line to the flattest 40 percent of the curve will be shown, as well as both the x and y interception points of that line.

Value

Plots the Bearing Area curve.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# plot the bearing area curve
plot_ba_curve(normforest, divisions = TRUE)

Removes the Best Fit Polynomial Surface

Description

Finds the best fit polynomial surface for a raster or matrix and subtracts it from the actual values. The output image has positive values where the actual values are higher than the surface and negative values where the actual value are lower than the surface.

Usage

remove_plane(x)

Arguments

Value

A raster or matrix of the same size as the input with values equal to the difference between the original and bestfit plane.

Examples

# import raster image
data(orforest)
orforest <- terra::unwrap(orforest)

# remove the least squares polynomial surface
new_rast <- remove_plane(orforest)

# plot
terra::plot(new_rast)

Rotates a matrix 180 degrees.

Description

Rotates a matrix 180 degrees. Code is from https://stackoverflow.com/questions/16496210/rotate-a-matrix-in-r-by-90-degrees-clockwise.

Usage

rotate(x)

Arguments

Value

A matrix rotate 180 degrees.

Ten-Point Height

Description

Calculates the average height above the mean surface for the five highest local maxima plus the average height below the mean surface for the five lowest local minima.

Usage

s10z(x)

Arguments

Value

A numeric value representing the ten-point height.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate ten-point height.
S10z <- s10z(normforest)

Calculates the Average Roughness of a Surface

Description

Finds the average roughness of a surface (Sa) as the absolute deviation of surface heights from the mean surface height. Height is measured as the value of a raster and may not necessarily represent actual height.

Usage

sa(x)

Arguments

Value

A value of average roughness in the units of the original raster or matrix.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# find the surface roughness
roughness <- sa(normforest)

Surface Bearing Index

Description

Determines the surface bearing index (Sbi), calculated as the ratio of root mean square roughness (Sq) to height at 5% of bearing area (z05).

Usage

sbi(x)

Arguments

Value

A numeric value representing the surface bearing index.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# determine the surface bearing index
Sbi <- sbi(normforest)

Core Fluid Retention Index

Description

Determines the core fluid retention index (Sci). This value is the void volume (area under the bearing area curve) in the 'core' zone. See Figure 2a from Kedron et al. (2018) for more details.

Usage

sci(x)

Arguments

Value

A numeric value representing the core fluid retention index.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# determine the core fluid retention index
Sci <- sci(normforest)

Calculate Correlation Length

Description

Calculates the smallest and largest distances to specified autocorrelation values (e.g., 0.2) of the areal autocorrelation function (AACF). All 180 degrees from the origin of the AACF image are considered for the calculation.

Usage

scl(x, threshold = c(0.2, 1/exp(1)), create_plot = FALSE)

Arguments

Value

A list containing the minimum and maximum distances from an autocorrelation value of 1 to the specified autocorrelation values < 1. Distances are in the units of the x, y coordinates of the raster image. If more than one threshold value is specified, the order of this list will be [minval(t1), minval(t2), maxval(t1), maxval(t2)].

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate Scl20, the minimum distance to an autocorrelation value of 0.2 in the AACF
Scl20 <- scl(normforest)[1]

Height Intervals of the Bearing Area Curve

Description

Determines the height interval (height distance) for points along the bearing area curve as defined by their x values.

Usage

sdc(x, low, high)

Arguments

Value

A numeric value of the difference in height of the y values along the bearing area curve corresponding to the specified x values.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# determine the 10-40% height interval of the
# bearing area curve
val <- sdc(normforest, 0.1, 0.4)

Root Mean Square Slope of Surface

Description

Calculates the root mean square slope of a raster or matrix surface using the two-point method.

Usage

sdq(x)

Arguments

Value

A numeric value representing the two-point root mean square slope, Sdq. The units of the returned value are change in z per one unit (pixel).

References

This function is based on the equations found at https://www.ntmdt-si.ru/data/media/files/manuals/image_analisys_p9_nov12.e.pdf.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate root mean square slope
Sdq <- sdq(normforest)

Root Area Mean Square Slope of Surface

Description

Calculates the area root mean square slope of a raster or matrix surface using the seven-point method.

Usage

sdq6(x)

Arguments

Value

A numeric value representing the seven-point root mean square slope, Sdq6. The units of the returned value are change in z per one unit (pixel).

References

This function is based on the equations found at https://www.ntmdt-si.ru/data/media/files/manuals/image_analisys_p9_nov12.e.pdf.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate area root mean square slope
Sdq6 <- sdq6(normforest)

Surface Area Ratio

Description

Calculates the surface area ratio of a raster or matrix. This is the ratio of a flat surface to the actual surface.

Usage

sdr(x)

Arguments

Details

This function scales both x and y, as well as the surface value (z), to between 0 and 1 to best match their units. This is done because most satellite data have units where the x, y units do not equal the z units. Surface area is calculated over the sample area (N-1, M-1).

Value

A numeric value representing the surface area ratio.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate the surface area ratio
Sdr <- sdr(normforest)

Summit Density

Description

Calculates the summit density of a raster or matrix. Summit density is the number of local peaks per unit area.

Usage

sds(x)

Arguments

Value

A numeric value representing the summit density.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate summit density.
Sds <- sds(normforest)

Calculate the fractal dimension of a raster.

Description

Calculates the 3D fractal dimension of a raster using the triangular prism surface area method.

Usage

sfd(x, silent = FALSE)

Arguments

Value

A numeric value representing the fractal dimension of the image.

References

Clarke, K.C., 1986. Computation of the fractal dimension of topographic surfaces using the triangular prism surface area method. Computers & Geosciences, 12(5), pp.713-722.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate the fractal dimension
Sfd <- sfd(normforest)

Calculate the fractal dimension of a raster (C function).

Description

Calculates the 3D fractal dimension of a raster using the triangular prism surface area method.

Usage

sfd_(mat)

Arguments

Value

A numeric value representing the fractal dimension of the image.

References

Clarke, K.C., 1986. Computation of the fractal dimension of topographic surfaces using the triangular prism surface area method. Computers & Geosciences, 12(5), pp.713-722.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# convert to matrix
mat <- matrix(normforest[], ncol = ncol(normforest), nrow = nrow(normforest))

# calculate the fractal dimension
Sfd <- sfd_(mat)

Simpson's Rule Empirical Area Under a Curve

Description

Calculates the area below a curve from points a to b. This function is provided for general use.

Usage

simpsons(f, a, b, n = 100)

Arguments

Details

Note that if y-values are negative, this returns the area above the function line.

Value

A numeric value representing the area under the curve with x bounds a and b.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# basic values
z <- terra::values(normforest)

# calculate cumulative probability density function of surface 'height' (= ndvi)
mod <- ecdf((1 - z))

# calculate integral
int_area <- simpsons(f = mod, b = 1, a = 0.8, n = 500)

Core Roughness Depth

Description

Determines the core roughness depth (Sk), the height difference between y values of the intersection points of the least mean square line fit to the flattest 40% of the bearing area curve. See Figure 2a from Kedron et al. (2018) for more details.

Usage

sk(x)

Arguments

Value

A numeric value representing the core roughness depth of the image.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# determine the core roughness depth
Sk <- sk(normforest)

Calculates the Kurtosis of Raster Values

Description

Finds the kurtosis for a distribution of raster or matrix values (Sku). Kurtosis represents the peakedness of the raster surface height distribution. Height is measured as the value of a raster/matrix and may not necessarily represent actual height.

Usage

sku(x, excess = TRUE)

Arguments

Value

A numeric value representing kurtosis.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# find the excess kurtosis of the raster distribution
Sku <- sku(normforest, excess = TRUE)

Determines the Slopes Along the Bearing Area Curve

Description

Calculates the slopes along the bearing area curve of a raster or matrix. Slopes are determined at points x, from point x - h to x + h.

Usage

slopecalc(x, h, f)

Arguments

Value

A dataframe with the slope for each segment with centerpoint x.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# find the slopes along the bearing area curve
ba <- bearing_area(normforest)
x <- seq(0, 1, length.out = 100000)
slopes <- slopecalc(x = x, h = 0.01, f = ba)

Determines the Average Slope Along Larger Segments of the Bearing Area Curve

Description

Calculates the average slope over every segment of a specified percentage length of the total bearing area curve.

Usage

slopemeans(slopes, l = 0.4)

Arguments

Value

A dataframe with the average slope over segments beginning at specified x locations along the bearing area curve. 'slope' represents the mean slope over the segment, 'xstart' is the beginning x location of the segment, and 'xend' is the concluding x location of the segment.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# find the average slope of segments of the bearing area
# curve.
ba <- bearing_area(normforest)
x <- seq(0, 1, length.out = 10000)
slopes <- slopecalc(x = x, h = 0.01, f = ba)
slopes_forty <- slopemeans(slopes = slopes, l = 0.4)

Calculates the Mean Peak Height of a Surface Image

Description

Finds the mean height of positive values in the landscape (mean peak height; Smean) for a raster or matrix representing a surface.

Usage

smean(x)

Arguments

Value

A numeric value of mean peak height.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# find the maximum peak height
Smean <- smean(normforest)

Calculates the Maximum Peak Height of a Surface Image

Description

Finds the absolute value of the highest value in the landscape (maximum peak height; Sph) for a raster or matrix representing a surface.

Usage

sph(x)

Arguments

Value

A numeric value of maximum peak height.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# find the maximum peak height
Sph <- sph(normforest)

Reduced Peak Height

Description

Determines the reduced peak height (Spk), the height difference between the maximum y value of the bearing area curve and the y value of the highest intersection point of the least mean square line fit to the flattest 40% of the bearing area curve. See Figure 2a from Kedron et al. (2018) for more details.

Usage

spk(x)

Arguments

Value

A numeric value representing the reduced peak height.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# determine the reduced peak height
Spk <- spk(normforest)

Calculates the Root Mean Square Roughness of a Surface

Description

Finds the root mean square roughness of a surface (Sq) as the standard deviation of surface heights from the mean surface height. Height is measured as the value of a raster and may not necessarily represent actual height.

Usage

sq(x)

Arguments

Value

A value of root mean square roughness in the units of the original raster or matrix.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# find the surface roughness
roughness <- sq(normforest)

Radial Wavelength Metrics

Description

Calculates the dominant radial wavelength, radial wavelength index, and mean half wavelength of the radial Fourier spectrum. See Kedron et al. (2018) for more detailed description.

Usage

srw(x, create_plot = FALSE, option = c(1, 2, 3))

Arguments

Value

A vector containing numeric values for the dominant radial wavelength, radial wavelength index, and mean half wavelength.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate metrics
srwvals <- srw(normforest)

# extract each value
Srw <- srwvals[1]
Srwi <- srwvals[2]
Shw <- srwvals[3]

Mean Summit Curvature

Description

Calculates the mean summit curvature of a raster or matrix. Mean summit curvature is the average principle curvature of local maximas on the surface.

Usage

ssc(x)

Arguments

Value

A numeric value representing the average curvature of surface peaks.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate mean summit curvature
Ssc <- ssc(normforest)

Calculates the Skewness of Raster Values

Description

Finds the Fisher-Pearson coefficient of skewness for raster or matrix values (Ssk). Skewness represents the asymmetry of the surface height distribution. Height is measured as the value of a raster/matrix and may not necessarily represent actual height.

Usage

ssk(x, adj = TRUE)

Arguments

Value

A numeric value representing skewness. # import raster image data(normforest) normforest <- terra::unwrap(normforest)

# find the adjusted coefficient of skewness Ssk <- ssk(normforest, adj = TRUE)

Texture Direction Metrics

Description

Calculates the angle of dominating texture and the texture direction index of the Fourier spectrum image calculated from a raster image (see Kedron et al. 2018).

Usage

std(x, create_plot = FALSE, option = c(1, 2))

Arguments

Value

A vector containing numeric values for the angle of dominating texture and the texture direction index.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate Std and Stdi
stdvals <- std(normforest)

# extract each value
Std <- stdvals[1]
Stdi <- stdvals[2]

Estimate Texture Aspect Ratio

Description

Calculates the texture aspect ratio (Str) at defined autocorrelation values. The texture aspect ratio is the ratio of the fastest to the slowest decay lengths of the autocorrelation function to the defined autocorrelation values.

Usage

stxr(x, threshold = c(0.2, 1/exp(1)))

Arguments

Value

A vector with length equal to that of threshold containing the texture aspect ratio(s) for the input autocorrelation value(s).

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# estimate the texture aspect ratio for autocorrelation
# thresholds of 0.20 and 0.37 (1/e)
strvals <- stxr(normforest, threshold = c(0.20, 1 / exp(1)))

# calculate Str20, the texture aspect ratio for
# autocorrelation value of 0.2 in the AACF
Str20 <- strvals[1]

Surface Area

Description

Calculates the scaled surface area of a raster or matrix.

Usage

surface_area(x)

Arguments

Details

This function scales both x and y, as well as the surface value (z), to between 0 and 1 to best match their units. This is done because most satellite data have units where the x, y units do not equal the z units. The surface area represents the surface area of the sample area (N-1, M-1).

Note that the surface object may have NA values around the edges, but should not have any missing values within the main area.

Value

A numeric value representing the scaled surface area.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# calculate surface area
surface_area(normforest)

Calculates the Maximum Valley Depth of a Surface Image

Description

Finds the absolute value of the lowest value in the landscape (maximum valley depth; Sv) for a raster or matrix representing a surface.

Usage

sv(x)

Arguments

Value

A numeric value of maximum valley depth.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# find the maximum valley depth
Sv <- sv(normforest)

Valley Fluid Retention Index

Description

Determines the valley fluid retention index (Svi). This value is the void volume (area under the bearing area curve) in the 'valley' zone. See Figure 2a from Kedron et al. (2018) for more details.

Usage

svi(x)

Arguments

Value

A numeric value representing the valley fluid retention index.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# determine the valley fluid retention index
Svi <- svi(normforest)

Reduced Valley Depth

Description

Determines the reduced valley depth (Svk), the height difference between y value of the lowest intersection point of the least mean square line fit to the flattest 40% of the bearing area curve and the minimum y value of the bearing area curve. See Figure 2a from Kedron et al. (2018) for more details.

Usage

svk(x)

Arguments

Value

A numeric value representing the reduced valley depth.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# determine the reduced valley depth
Svk <- svk(normforest)

Calculate Texture Metrics per Pixel

Description

Calculates the various texture metrics over windows centered on individual pixels. This creates a continuous surface of the texture metric.

Usage

texture_image(
  x,
  window_type = "square",
  size = 5,
  in_meters = FALSE,
  metric,
  args = NULL,
  parallel = TRUE,
  ncores = NULL,
  nclumps = 100
)

Arguments

Details

Note that this function is meant to work on rasters with an equal area projection.

Metrics available from geodiv package:

1. 'sa': average surface roughness

2. 'sq': root mean square roughness

3. 's10z': ten-point height

4. 'sdq': root mean square slope of surface, 2-point method

5. 'sdq6': root mean square slope of surface, 7-point method

6. 'sdr': surface area ratio

7. 'sbi': surface bearing index

8. 'sci': core fluid retention index

9. 'ssk': skewness

10. 'sku': kurtosis

11. 'sds': summit density

12. 'sfd': 3d fractal dimension

13. 'srw': dominant radial wavelength, radial wavelength index, mean half wavelength

14. 'std': angle of dominating texture, texture direction index

15. 'svi': valley fluid retention index

16. 'stxr': texture aspect ratio

17. 'ssc': mean summit curvature

18. 'sv': maximum valley depth

19. 'sph': maximum peak height

20. 'sk': core roughness depth

21. 'smean': mean peak height

22. 'svk': reduced valley depth

23. 'spk': reduced peak height

24. 'scl': correlation length

25. 'sdc': bearing area curve height interval

Value

A raster or list of rasters (if function results in multiple outputs) with pixel values representative of the metric value for the window surrounding that pixel.

Note

The total window size for square windows will be (size * 2) + 1.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# crop raster to smaller area
x <- terra::crop(normforest, terra::ext(normforest[1:100, 1:100, drop = FALSE]))

# get a surface of root mean square roughness
sa_img <- texture_image(x = x, window = 'square',
size = 5, metric = 'sa',
parallel = TRUE, ncores = 1, nclumps = 20)

# plot the result
terra::plot(sa_img)

Calculate Texture Metric for Single Pixel

Description

Calculates the various texture metrics over a window centered on an individual pixel.

Usage

window_metric(
  x,
  coords,
  window_type = "square",
  size = 11,
  metric,
  args = NULL
)

Arguments

Details

Metrics from geodiv package:

1. 'sa': average surface roughness

2. 'sq': root mean square roughness

3. 's10z': ten-point height

4. 'sdq': root mean square slope of surface, 2-point method

5. 'sdq6': root mean square slope of surface, 7-point method

6. 'sdr': surface area ratio

7. 'sbi': surface bearing index

8. 'sci': core fluid retention index

9. 'ssk': skewness

10. 'sku': kurtosis

11. 'sds': summit density

12. 'sfd': 3d fractal dimension

13. 'srw': dominant radial wavelength, radial wavelength index, mean half wavelength

14. 'std': angle of dominating texture, texture direction index

15. 'svi': valley fluid retention index

16. 'stxr': texture aspect ratio

17. 'ssc': mean summit curvature

18. 'sv': maximum valley depth

19. 'sph': maximum peak height

20. 'sk': core roughness depth

21. 'smean': mean peak height

22. 'svk': reduced valley depth

23. 'spk': reduced peak height

24. 'scl': correlation length

25. 'sdc': bearing area curve height interval

Value

A raster with pixel values representative of the metric value for the window surrounding that pixel.

Note

Note that if calculating the metric at the edge of a raster or matrix, the input raster/matrix must be padded. This can be done using the pad_edges function.

Offset Raster or Matrix Values

Description

Calculates a matrix of values with a negative or positive, x or y, offset.

Usage

zshift(r, xdist = 0, ydist = 0, xrm, yrm, scale = FALSE)

Arguments

Value

A numeric vector of values created from a matrix of the values with the specified offset. The vector is created from a matrix with xrm fewer columns and yrm fewer rows than the original raster value matrix.

Examples

# import raster image
data(normforest)
normforest <- terra::unwrap(normforest)

# remove right and bottom borders 2 deep
noborder <- zshift(normforest, xdist = 2, ydist = 2)