This function calculates distances between connected cells in a raster, given (a) the planar distances between connected cells and (b) differences in elevation.
lcp_costs(surface, verbose = TRUE)A raster for which to calculate distances. The surface must be planar (i.e., Universal Transverse Mercator projection) with units of metres in the x, y and z directions. The surface's resolution is taken to define the distance between connected cells in the x and y directions and must be the same in both cases (for surface's with unequal horizontal resolution, resample can be used to equalise resolution).
A logical function that defines whether or not to print messages to the console to relay function progress.
The function returns a named list of sparse dsCMatrix-class matrices that define the distances (m) between connected cells under a rook's or bishop's movement (`dist_rook' and `dist_bishop'), the planar and vertical distances between connected cells (`dist_planar' and `dist_vertical') and the total distance between connected cells (`dist_total').
This function was motivated by the need to determine the shortest paths between locations over the seabed for benthic animals (see lcp_over_surface). An animal's movement can be conceptualised as that of a queen on a chessboard, which can move, in eight directions around its current position, across a surface. Movements in the x and y direction are termed `rook's movement' and movements in the diagonal direction are termed `bishop's movement'.
Under this framework, the distance that an entity must travel between connected cells depends on the planar distances between cells and their differences in elevation. Planar distances (\(d_p\), m) depend on the movement type: under a rook's movement (i.e., horizontally or vertically), the distance (\(d_{p,r}\)) between connected cells is extracted from the raster's resolution (which is assumed to be identical in the x and y directions); under a bishop's movement (i.e., diagonally), the distance between connected cells \(d_{p,b}\) is given by Pythagoras' Theorem: \(d_{p,b} = \sqrt{(d_{p, r}^2 + d_{p, r}^2)}\). Vertical distances (\(d_v\), m) are simply the differences in height between cells. The total distance (\(d_t\)) between any two connected cells is a combination of these distances given by Pythagoras' Theorem: \(d_t = \sqrt{(d_p^2 + d_v^2)}\).
The function returns a warning produced by transition which is implemented to facilitate the definition of distances before shortest paths/distances are computed by either method: `In .TfromR(x, transitionFunction, directions, symm) : transition function gives negative values'. This warning arises because the height differences between connecting cells can be negative. It can be safely ignored.
This routine is implemented by the lcp_over_surface function to calculate the shortest path(s) and/or the distance(s) of the shortest paths(s) between origin and destination coordinates, and by the lcp_from_point function to calculate the shortest distances from a point on a raster to surrounding cells.
# In this example, consider the distances between connected cells in the example
# ... 'dat_gebco' raster. For speed, we will focus on a subset of the area.
# ... Within this area, we need to regularise the resolution:
boundaries <- raster::extent(707884.6, 709884.6, 6253404, 6255404)
blank <- raster::raster(boundaries, res = c(5, 5))
r <- raster::resample(dat_gebco, blank)
#> Warning: aggregation factor is larger than the number of columns
#> Warning: aggregation factor is larger than the number of rows
#> Error in .intersectExtent(x, y, validate = TRUE): Objects do not intersect
# Implement algorithm
costs <- lcp_costs(r)
#> flapper::lcp_costs() called (@ 2023-08-29 15:43:31)...
#> Error in h(simpleError(msg, call)): error in evaluating the argument 'x' in selecting a method for function 'res': object 'r' not found
# Examine outputs
utils::str(costs)
#> Error in utils::str(costs): object 'costs' not found