dist_over_surface: Calculate the total distance of a path over a...

In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

Calculate the total distance of a path over a three-dimensional surface

Description

This function calculates the total distance of a path, whose horizontal coordinates are known, over a three-dimensional surface. To implement the function, the path should be supplied as a matrix or dataframe of coordinates or a SpatialLines object and the surface should be supplied as a raster. The function takes the horizontal coordinates of the path and extracts the values of the surface at these points, and then calculates the total distance of the path as the sum of the paired distances between each pair of points.

Usage

dist_over_surface(path, surface)

Arguments

path	A matrix or dataframe of horizontal coordinates (x, y) or a SpatialLines object which defines the path over a surface. The coordinate reference system (projection) of path should be the same as that for the surface.
surface	A raster over which the movement that generated the path occurred. The coordinate reference system (projection) of path should be the same as that for the surface and the values of the surface should also be expressed in the same units (e.g., metres).

Details

The total distance of a path over a three-dimensional surface is equal to the sum of the pairwise distances between each point (i) and its successor (i + 1) according to the equation:

\Sigma_{i = 1}^n \sqrt{(x_{i+1} - x_i)^2 + (y_{i + 1} - y_i)^2 + (z_{i + 1} - z_i)^2)}

where x, y and z are the x, y and z coordinates of each point in three-dimensional space and n is the total number of points minus 1. Pairwise distances are calculated via dist_btw_points_3d. Note that for realistic distances, some interpolation (e.g., via least-cost paths) between points may be required to generate localisations at sufficiently high resolution to effectively capture the shape of the landscape.

This function does not currently support non-planar coordinates (path or surface).

Value

The function returns a number equal to the total distance along the path.

Author(s)

Edward Lavender

See Also

If the coordinates of the points are known in three dimensions already, dist_btw_points_3d can be used directly.

Examples

#### Simulate a hypothetical landscape
# Define a miniature, blank landscape with known dimensions
proj_utm <- sp::CRS(SRS_string = "EPSG:32629")
r <- raster::raster(
  nrows = 3, ncols = 3,
  crs = proj_utm,
  resolution = c(5, 5),
  ext = raster::extent(0, 15, 0, 15)
)
# Define a matrix of hypothetical values for the landscape
mat <- matrix(c(
  5, 10, 3,
  2, 1, 4,
  5, 6, 6
), ncol = 3, nrow = 3, byrow = TRUE)
r[] <- mat
# Visualise simulated landscape
raster::plot(r)
raster::text(r)

#### Example (1): Total distance between two example adjacent points
path_cells <- c(1, 2)
path_matrix <- sp::coordinates(r)[path_cells, ]
dist_over_surface(path_matrix, r)
sqrt(5^2 + (10 - 5)^2)

#### Example (2): Total distance between two example diagonal points
path_cells <- c(1, 5)
path_matrix <- sp::coordinates(r)[path_cells, ]
dist_over_surface(path_matrix, r)
sqrt(sqrt(5^2 + 5^2)^2 + (5 - 1)^2)

#### Example (3): Total distance along a longer path
path_cells <- c(1, 2, 3)
path_matrix <- sp::coordinates(r)[path_cells, ]
dist_over_surface(path_matrix, r)
sqrt(5^2 + (10 - 5)^2) + sqrt(5^2 + (10 - 3)^2)

#### Example (4): Total distance along an even longer path
path_cells <- c(1, 2, 3, 6, 8)
path_matrix <- sp::coordinates(r)[path_cells, ]
dist_over_surface(path_matrix, r)

#### Example (5): A SpatialLines object can be used for the path
path_line <- Orcs::coords2Lines(path_matrix, ID = 1, proj4string = proj_utm)
raster::lines(path_line)
dist_over_surface(path_line, r)

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.