,
Nina Schiettekatte [aut, cre] | Title: | Tools and Metrics for 3D Surfaces and Objects |
|---|---|
| Description: | A collection of functions for sampling and simulating 3D surfaces and objects and estimating metrics like rugosity, fractal dimension, convexity, sphericity, circularity, second moments of area and volume, and more. |
| Authors: | Joshua Madin [aut] ,
Nina Schiettekatte [aut, cre] |
| Maintainer: | Nina Schiettekatte <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.7 |
| Built: | 2024-11-18 06:27:58 UTC |
| Source: | https://github.com/jmadinlab/habtools |
A helper function for segment, box and cube counting fractal methods.
The function divide the array into n pieces and counts how many are
occupied.
cell_count_1d(pts, xmin, xmax, n)cell_count_1d(pts, xmin, xmax, n)
pts |
Data frame with x coordinates |
xmin |
Minimum x-value |
xmax |
Maximum x-value |
n |
Multiplier |
Number of filled cells
pts <- data.frame(x = rnorm(200, 0, 5)) cell_count_1d(pts, xmin = min(pts$x), xmax = max(pts$x), n = 5)pts <- data.frame(x = rnorm(200, 0, 5)) cell_count_1d(pts, xmin = min(pts$x), xmax = max(pts$x), n = 5)
A helper function for segment, box and cube counting fractal methods.
The function divide the array into n pieces and counts how many are
occupied.
cell_count_2d(pts, xmin, xmax, ymin, ymax, n)cell_count_2d(pts, xmin, xmax, ymin, ymax, n)
pts |
Data frame with x and y coordinates |
xmin |
Minimum x-value |
xmax |
Maximum x-value |
ymin |
Minimum y-value |
ymax |
Maximum y-value |
n |
Multiplier |
Number of filled cells
A helper function for segment, box and cube counting fractal methods.
The function divide the array into n pieces and counts how many are
occupied.
cell_count_3d(pts, xmin, xmax, ymin, ymax, zmin, zmax, n)cell_count_3d(pts, xmin, xmax, ymin, ymax, zmin, zmax, n)
pts |
Data frame with x, y, and z coordinates |
xmin |
Minimum x-value |
xmax |
Maximum x-value |
ymin |
Minimum y-value |
ymax |
Maximum y-value |
zmin |
Minimum z-value |
zmax |
Maximum z-value |
n |
Multiplier |
Number of filled cells
Calculates the centroid for a given set of XYZ coordinates.
centroid(data)centroid(data)
data |
A data frame with x, y, and z coordinates. |
The coordinates of the centroid.
data <- mesh_to_points(mcap) centroid(data)data <- mesh_to_points(mcap) centroid(data)
The perimeter of the 2D shape is divided by the perimeter of a circle with the same area as the shape. The more irregular the shape is, the closer the output value is to zero. The closer the shape is to a circle, the closer the output value is to 1.
circularity(data)circularity(data)
data |
A data frame with the first two columns x and y coordinates, respectively. |
A value between 0 (infinitely irregular) and 1 (a perfect circle).
mcap_2d <- mesh_to_2d(mcap) plot(mcap_2d, asp=1) circularity(mcap_2d) circ <- sim_circle() # simulate xy coordinates for a circle plot(circ, asp=1) circularity(circ)mcap_2d <- mesh_to_2d(mcap) plot(mcap_2d, asp=1) circularity(mcap_2d) circ <- sim_circle() # simulate xy coordinates for a circle plot(circ, asp=1) circularity(circ)
The ratio of the volume of the object and the volume of the convex hull around the object. Objects with fewer concavities will be closer to 1.
convexity(mesh)convexity(mesh)
mesh |
A triangular mesh of class mesh3d. #' |
The convexity value.
convexity(mcap)convexity(mcap)
Calculates mechanical vulnerability of rigid, cantilever-type structural elements.
csf(mesh, z_min, res, keep_data = FALSE)csf(mesh, z_min, res, keep_data = FALSE)
mesh |
A triangular mesh of class mesh3d. |
z_min |
The z plane about which csf should be calculated. Defaults to min(z). |
res |
The resolution to be used for the calculation. Defaults to the resolution of the mesh. |
keep_data |
Logical. Return list with supplemental info? Defaults to FALSE. |
This function calculates the mechanical vulnerability of a structural element, like a hard coral colony, to fluid flow. While developed for corals, and originally called the Colony Shape Factor (CSF), the function is applicable to any attached, rigid cantilever type structure. CSF is dimensionless and can be used to compare the vulnerability among structures. Mechanistically, if the CSF of a structure becomes greater than the dislodgement mechanical threshold, breakage occurs. This threshold is a function of material tensile strength and inversely related to fluid velocity and density (Madin & Connolly 2006).
A value for csf or if keep_data = TRUE, a list containing the colony shape factor (csf), the parallel to flow (dy) and perpendicular (dx) diameters of the cantilever base, and the bending moment (mom).
The orientation of the 3D mesh is important for this function. The function assumes the fluid flow is parallel with the y-axis. The function also assumes the base of the cantilever over which the bending moment acts can be approximated as an ellipse with the diameter on the y-axis parallel with flow (dy). You can set a z_min if the base of your mesh is not flat at the base (i.e., shift the plane upon which the cantilever is attached upwards). The function output includes dy and dx for monitoring anticipated values.
Madin JS & Connolly SR (2006) Ecological consequences of major hydrodynamic disturbances on coral reefs. Nature. 444:477-480.
csf(mcap, z_min = -3.65) csf(mcap, z_min = -3.65, keep_data = TRUE)csf(mcap, z_min = -3.65) csf(mcap, z_min = -3.65, keep_data = TRUE)
A function for sampling a DEM by cropping squares of a given size around xy coordinates.
dem_crop(data, x0, y0, L, plot = FALSE)dem_crop(data, x0, y0, L, plot = FALSE)
data |
A DEM in RasterLayer format. |
x0 |
A value or vector of central x coordinate(s). |
y0 |
A value or vector of central y coordinate(s). |
L |
Size of squares to cropped from the DEM. |
plot |
Logical. Plot the DEM and the cropped sections? |
A cropped RasterLayer or list of RasterLayers.
# around one point dem_cropped <- dem_crop(horseshoe, -468, 1266, L = 2) raster::plot(dem_cropped) points(-468, 1266) # around multiple points points <- data.frame(x = c(-467, -465, -466), y = c(1270, 1265, 1268)) dem_list <- dem_crop(horseshoe, points$x, points$y, L = 1, plot = TRUE) # plot the first element raster::plot(dem_list[[1]])# around one point dem_cropped <- dem_crop(horseshoe, -468, 1266, L = 2) raster::plot(dem_cropped) points(-468, 1266) # around multiple points points <- data.frame(x = c(-467, -465, -466), y = c(1270, 1265, 1268)) dem_list <- dem_crop(horseshoe, points$x, points$y, L = 1, plot = TRUE) # plot the first element raster::plot(dem_list[[1]])
Sample a random DEM with specified size from a larger DEM
dem_sample(data, L, allow_NA = 0, plot = FALSE, max_iter = 100)dem_sample(data, L, allow_NA = 0, plot = FALSE, max_iter = 100)
data |
Digital elevation model of class RasterLayer. |
L |
Size of square to cut out of DEM. |
allow_NA |
Proportion of NA values allowed in the sample. Useful when DEM is not regular. |
plot |
Logical. Plot the DEM and the cropped section? |
max_iter |
Maximum number of random crops to try when allow_NA = FALSE before failing. |
Digital elevation model of class RasterLayer.
Not allowing NAs may increase sampling time for irregular DEMs that contain a lot of NAs; e.g., structure from motion transects.
dem <- dem_sample(horseshoe, L = 2, plot=TRUE)dem <- dem_sample(horseshoe, L = 2, plot=TRUE)
Split DEM into smaller tiles
dem_split(data, size, parallel = FALSE, ncores = (parallel::detectCores() - 1))dem_split(data, size, parallel = FALSE, ncores = (parallel::detectCores() - 1))
data |
Digital elevation model of class RasterLayer. |
size |
Size of tiles, in the same unit as the RasterLayer. |
parallel |
Logical. Use parallel processing? Note: parallel must be installed. |
ncores |
Number of cores to use when parallel = TRUE. |
List of RasterLayers.
L <- habtools::extent(horseshoe) # size of horseshoe = 8m size <- 2 # size of target tiles (L / size)^2 # number of target tiles = 16 dem_list <- dem_split(horseshoe, 2) length(dem_list)L <- habtools::extent(horseshoe) # size of horseshoe = 8m size <- 2 # size of target tiles (L / size)^2 # number of target tiles = 16 dem_list <- dem_split(horseshoe, 2) length(dem_list)
Transform DEM to 3D pointcloud of raster corners
dem_to_points(dem, bh = NULL, parallel = FALSE)dem_to_points(dem, bh = NULL, parallel = FALSE)
dem |
Digital elevation model of class RasterLayer. |
bh |
Border height from lowest point. |
parallel |
Logical. Use parallel computation? |
A 3D point cloud for raster cell corners.
dem <- sim_dem(20, 0.5) raster::plot(dem) pts <- dem_to_points(dem) rgl::plot3d(pts)dem <- sim_dem(20, 0.5) raster::plot(dem) pts <- dem_to_points(dem) rgl::plot3d(pts)
Detect a sudden drop, edge, or overhang in a DEM
detect_drop(data, d = 0.1)detect_drop(data, d = 0.1)
data |
DEM of class RasterLayer. |
d |
The threshold height difference to define a drop. |
A RasterLayer marking edges. Values indicate maximum height difference of surrounding cells.
edges <- detect_drop(horseshoe, d = 0.2) raster::plot(horseshoe) raster::plot(edges)edges <- detect_drop(horseshoe, d = 0.2) raster::plot(horseshoe) raster::plot(edges)
This function calculates the extent or largest length of the bounding box of a mesh or a DEM.
extent(data)extent(data)
data |
Digital elevation model of class RasterLayer or a triangular mesh of class mesh3d. |
A value, the extent of the mesh or DEM.
There are several extent function is other packages, including the raster package. Therefore it is recommended to use the package namespace, see examples below.
habtools::extent(mcap) habtools::extent(horseshoe)habtools::extent(mcap) habtools::extent(horseshoe)
Calculate fractal dimension
fd(data, method, lvec, keep_data = FALSE, diagnose = FALSE, ...)fd(data, method, lvec, keep_data = FALSE, diagnose = FALSE, ...)
data |
Digital elevation model of class RasterLayer or a triangular mesh of class mesh3d. |
method |
If data is a RasterLayer, possible methods are:"hvar", "area", "sd", and "cubes" (defaults to "hvar"). If data is a mesh3d, possible methods are "cubes" and "area" (defaults to "cubes"). |
lvec |
Vector of scales to use for calculation. |
keep_data |
Logical. Keep data? Default is FALSE. |
diagnose |
Logical. Show diagnostic plot and metrics? |
... |
Arguments from method-specific fd_ functions. |
Calculates fractal dimension using the specified method.
Note that methods are distinctly different and should not be mixed when comparing values for multiple objects.
See fd_hvar(), fd_area(), fd_cubes(), fd_sd() for details about each method.
If lvec is not specified, a default based on resolution, extent, and method will be used.
The cubes method is not recommended if the height range is much smaller than the extent of a 3d object or DEM, which is typically the case for DEMs.
Most objects and surfaces are not perfectly fractal. It is recommended to investigate scale transitions by setting diagnose to TRUE.
A value for fractal dimension, typically between 2 and 3 or a list if keep_data = TRUE.
dem <- dem_crop(horseshoe, x0 = -469, y0 = 1267, L = 2, plot = TRUE) fd(dem, method = "hvar", lvec = c(0.125, 0.25, 0.5, 1, 2)) fd(dem, method = "area", diagnose = TRUE) fd(dem, method = "sd") fd(mcap2, method = "cubes", plot = TRUE) fd(mcap2, method = "area", diagnose = TRUE)dem <- dem_crop(horseshoe, x0 = -469, y0 = 1267, L = 2, plot = TRUE) fd(dem, method = "hvar", lvec = c(0.125, 0.25, 0.5, 1, 2)) fd(dem, method = "area", diagnose = TRUE) fd(dem, method = "sd") fd(mcap2, method = "cubes", plot = TRUE) fd(mcap2, method = "area", diagnose = TRUE)
Calculate fractal dimension using the surface area method
fd_area(data, lvec = NULL, keep_data = FALSE, plot = FALSE, scale = FALSE)fd_area(data, lvec = NULL, keep_data = FALSE, plot = FALSE, scale = FALSE)
data |
DEM of class "RasterLayer" or mesh of class "mesh3d". |
lvec |
Vector of scales to use for calculation. |
keep_data |
Logical. Keep data? Default is FALSE. |
plot |
Logical. Plot surface with area resolutions superimposed? Defaults to FALSE. |
scale |
Logical. Rescale height values to fit the extent? Only relevant for DEMs. Defaults to FALSE. |
This function calculates fractal dimension using the area method.
Based on values in lvec, the DEM or mesh is reprojected to varying scales.
Fractal dimension is defined as 2 - s with s being the slope of the regression between the log-transformed surface areas across scales and the log-transformed scales.
Considerate bias is introduced if scales approach the extent of the object due to an edge effect.
Therefore, this approach is only appropriate when the object is large relative to the scales of interest to be used as lvec.
Diagnostic plots may help visualize whether bias is present for the scales chosen (i.e. points do not fall on a straight line).
A value for fractal dimension, typically between 2 and 3 or a list if keep_data = TRUE.
fd_area(horseshoe, lvec = c(0.125, 0.25, 0.5)) # Look at diagnostic plot fdata <- fd_area(horseshoe, lvec = c(0.05, 0.1, 0.2, 0.4), keep_data = TRUE) fd_diagnose(fdata) # points fall on straight line fdata <- fd_area(horseshoe, lvec = c(0.5, 1, 2, 4), keep_data = TRUE) fd_diagnose(fdata) # points fall on hollow curve, indicating that lvec includes values that # are too high.fd_area(horseshoe, lvec = c(0.125, 0.25, 0.5)) # Look at diagnostic plot fdata <- fd_area(horseshoe, lvec = c(0.05, 0.1, 0.2, 0.4), keep_data = TRUE) fd_diagnose(fdata) # points fall on straight line fdata <- fd_area(horseshoe, lvec = c(0.5, 1, 2, 4), keep_data = TRUE) fd_diagnose(fdata) # points fall on hollow curve, indicating that lvec includes values that # are too high.
Calculate fractal dimension using the box counting method
fd_boxes(data, lvec, keep_data = FALSE, plot = FALSE)fd_boxes(data, lvec, keep_data = FALSE, plot = FALSE)
data |
A data frame in which the first two columns are x and y coordinates, respectively. |
lvec |
The scales to use for calculation (i.e. box sizes). |
keep_data |
Logical. Keep calculation data? Default = TRUE. |
plot |
Logical. Plot the shape with box sizes superimposed? Defaults to FALSE. |
This function calculates fractal dimension using the box counting method.
If lvec is not specified, a default based on resolution and extent will be used.
Based on lvec, boxes of different sizes are defined and the function counts boxes that capture the outline of the shape.
It is recommended to specify the maximum value of lvec so that the largest
box encapsulates the entire object. The smallest scale included in lvec
should not be smaller than the resolution of your object.
A value for fractal dimension, typically between 1 and 2 or a list if keep_data = TRUE.
mcap_2d <- mesh_to_2d(mcap) fd_boxes(mcap_2d, plot = TRUE, keep_data = TRUE) fd_boxes(mcap_2d, lvec = c(0.05, 0.1, 0.2, 0.4), plot = TRUE)mcap_2d <- mesh_to_2d(mcap) fd_boxes(mcap_2d, plot = TRUE, keep_data = TRUE) fd_boxes(mcap_2d, lvec = c(0.05, 0.1, 0.2, 0.4), plot = TRUE)
Calculate fractal dimension using the cube counting method
fd_cubes(data, lvec = NULL, plot = FALSE, keep_data = FALSE, scale = FALSE)fd_cubes(data, lvec = NULL, plot = FALSE, keep_data = FALSE, scale = FALSE)
data |
An object of class RasterLayer or mesh3d. |
lvec |
Vector of scales to use for calculation (i.e. cube sizes). |
plot |
Planar representation of cubes superimposed on 3D mesh or DEM for visualizing |
keep_data |
Logical. Keep calculation data? Default = TRUE. |
scale |
Logical. Rescale height values to the extent? Only relevant for RasterLayer objects. (Defaults to FALSE). |
This function calculates fractal dimension using the cube counting method.
If lvec is not specified, a default based on resolution and extent will be used.
Based on lvec, cubes of different sizes are defined and the function counts mesh points that fall within each cube.
It is recommended to specify the maximum value of lvec so that the largest box encapsulates the entire object.
The smallest scale included in lvec should not be smaller than the resolution of your object.
A value for fractal dimension, typically between 2 and 3 or a list if keep_data = TRUE.
fd_cubes(mcap, keep_data = TRUE, plot = TRUE) fd_cubes(mcap, lvec = c(0.05, 0.1, 0.25, 0.5), plot = TRUE) dem <- dem_crop(horseshoe, x0 = -469, y0 = 1267, L = 2, plot = TRUE) fd_cubes(dem, plot = TRUE, keep_data = TRUE) fd_cubes(dem, plot = TRUE, keep_data = TRUE, scale = TRUE)fd_cubes(mcap, keep_data = TRUE, plot = TRUE) fd_cubes(mcap, lvec = c(0.05, 0.1, 0.25, 0.5), plot = TRUE) dem <- dem_crop(horseshoe, x0 = -469, y0 = 1267, L = 2, plot = TRUE) fd_cubes(dem, plot = TRUE, keep_data = TRUE) fd_cubes(dem, plot = TRUE, keep_data = TRUE, scale = TRUE)
Diagnoses fractal dimension variation across neighboring scales.
fd_diagnose(data, keep_data = TRUE)fd_diagnose(data, keep_data = TRUE)
data |
Output of |
keep_data |
Logical. Keep diagnostics data? |
A list with fractal dimension across scales, mean fractal dimension, and sd of fractal dimensions across scales.
fd_data <- fd(horseshoe, lvec = c(0.05, 0.1, 0.2, 0.4), method = "area", keep_data = TRUE) fd_diagnose(fd_data) fd_diagnose(fd_data, keep_data = FALSE)fd_data <- fd(horseshoe, lvec = c(0.05, 0.1, 0.2, 0.4), method = "area", keep_data = TRUE) fd_diagnose(fd_data) fd_diagnose(fd_data, keep_data = FALSE)
Calculate fractal Dimension using the height variation method
fd_hvar( data, lvec, regmethod = "mean", keep_data = FALSE, plot = FALSE, parallel = FALSE, ncores = (parallel::detectCores() - 1) )fd_hvar( data, lvec, regmethod = "mean", keep_data = FALSE, plot = FALSE, parallel = FALSE, ncores = (parallel::detectCores() - 1) )
data |
Digital elevation model of class RasterLayer or dataframe (output of hvar function) |
lvec |
Vector of scales to use for calculation. |
regmethod |
Method to use for linear regression between scale (lvec) and height range. One of |
keep_data |
Keep the data used for fd calculation? defaults to FALSE |
plot |
Logical. Show plot of scales relative to data? |
parallel |
Logical. Use parallel processing? Note: parallel must be installed. |
ncores |
Number of cores to use when parallel = TRUE. |
Calculates fractal dimension using the height variation regression.
If lvec is not specified, a default based on resolution and extent will be used.
data can be a DEM or a data.frame with columns labeled l and h for
grid cell length and height range of that cell, respectively (output of hvar()).
A rule of thumb is that l should range an order of magnitude.
However, large ranges also
average-out fractal dimension of a surface that might have
phase transitions, and therefore a thorough exploration of height ranges is suggested using the plot.
regmethod specifies whether data is summarized by taking the mean or median of height ranges across scales or all data is used.
regmethod "raw" is not recommended because the regression will give much more weight to the lower scales that include more points and likely underestimate D.
A value for fractal dimension, typically between 2 and 3 or a list if keep_data = TRUE.
dem <- habtools::dem_crop(horseshoe, x0 = -469, y0 = 1267, L = 2, plot = TRUE) fd_hvar(dem, lvec = c(0.125, 0.25, 0.5, 1, 2)) fd_hvar(dem, regmethod = "mean", plot = TRUE, keep_data = TRUE) fd_hvar(dem, regmethod = "median", plot = TRUE, keep_data = TRUE) fd_hvar(dem)dem <- habtools::dem_crop(horseshoe, x0 = -469, y0 = 1267, L = 2, plot = TRUE) fd_hvar(dem, lvec = c(0.125, 0.25, 0.5, 1, 2)) fd_hvar(dem, regmethod = "mean", plot = TRUE, keep_data = TRUE) fd_hvar(dem, regmethod = "median", plot = TRUE, keep_data = TRUE) fd_hvar(dem)
Calculate fractal Dimension using the standard deviation method
fd_sd( data, lvec, regmethod = "mean", keep_data = FALSE, plot = FALSE, parallel = FALSE, ncores = (parallel::detectCores() - 1) )fd_sd( data, lvec, regmethod = "mean", keep_data = FALSE, plot = FALSE, parallel = FALSE, ncores = (parallel::detectCores() - 1) )
data |
Digital elevation model of class RasterLayer. |
lvec |
Vector of scales to use for calculation. |
regmethod |
Method to use for linear regression between scale (lvec) and height range. One of |
keep_data |
Logical. Keep the data used for fd calculation? Defaults to FALSE. |
plot |
Logical. Show plot of scales relative to data? |
parallel |
Logical. Use parallel processing? Note: parallel must be installed. |
ncores |
Number of cores to use when parallel = TRUE. |
Calculates fractal dimension using the standard deviation method,
an analogue of the variation method, but using the standard deviation in height per grid cell instead of the full height range.
If lvec is not specified, a default based on resolution and extent will be used.
A rule of thumb is that lvec should range at least an order of magnitude.
However, large ranges also average-out fractal dimension of a surface that might have
phase transitions, and therefore a thorough exploration of height ranges is suggested using the plot.
regmethod specifies whether data is summarized by taking the mean or median of height ranges across scales or all data is used.
regmethod "raw" is not recommended because the regression will give much more weight to the lower scales that include more points and likely underestimate D.
A value for fractal dimension, typically between 2 and 3 or a list if keep_data = TRUE.
dem <- habtools::dem_crop(horseshoe, x0 = -469, y0 = 1267, L = 2, plot = TRUE) fd_sd(dem, lvec = c(0.125, 0.25, 0.5, 1, 2))dem <- habtools::dem_crop(horseshoe, x0 = -469, y0 = 1267, L = 2, plot = TRUE) fd_sd(dem, lvec = c(0.125, 0.25, 0.5, 1, 2))
A digital elevation model (DEM) of a reef patch in the Great Barrier Reef.
horseshoehorseshoe
A 800 by 800 digital elevation model (of class RasterLayer).
depth
0.01 m
8 m
...
raster::plot(habtools::horseshoe)raster::plot(habtools::horseshoe)
Calculates the distance between the lowest and highest point in a 3D object.
hr(data)hr(data)
data |
A RasterLayer or mesh3d object. |
Value of height range.
# for a DEM hr(horseshoe) # for a 3D mesh hr(mcap)# for a DEM hr(horseshoe) # for a 3D mesh hr(mcap)
This is a helper function used for calculating fractal dimension using the height variation and standard deviation methods.
hvar( data, lvec = NULL, parallel = FALSE, ncores = (parallel::detectCores() - 1) )hvar( data, lvec = NULL, parallel = FALSE, ncores = (parallel::detectCores() - 1) )
data |
Digital elevation model of class RasterLayer. |
lvec |
Scales to use for calculation. |
parallel |
Logical. Use parallel processing? Note: parallel must be installed. |
ncores |
Number of cores to use when parallel = TRUE. |
A data.frame containing height ranges of cells at different scales.
hvar(horseshoe, lvec = c(1, 2, 4, 8))hvar(horseshoe, lvec = c(1, 2, 4, 8))
A laser scan of a coral colony.
mcapmcap
mesh3d object with 5568 vertices, 10939 triangles.
library(rgl) plot3d(mcap)library(rgl) plot3d(mcap)
A remeshed version of mcap with resolution = 0.005.
mcap2mcap2
mesh3d object.
library(rgl) plot3d(mcap2)library(rgl) plot3d(mcap2)
Turns a 3D Mesh file into an xy data frame.
mesh_to_2d(mesh, L0 = NULL, plot = FALSE, silent = TRUE)mesh_to_2d(mesh, L0 = NULL, plot = FALSE, silent = TRUE)
mesh |
A mesh3d object. |
L0 |
(Optional) The desired DEM resolution in same units at the 3D mesh. |
plot |
logical. Plot the output? |
silent |
logical. Defaults to not showing warnings. |
The function uses the vertices of the mesh object and projects them on the XY plane. Then, only points that define the perimeter of the shape are maintained.
A data frame.
mcap_2d <- mesh_to_2d(mcap, plot = TRUE) geometry::polyarea(mcap_2d$x, mcap_2d$y) # area planar(mcap) perimeter(mcap_2d) # perimeter circularity(mcap_2d) # circularity fd_boxes(mcap_2d) # fractal dimensionmcap_2d <- mesh_to_2d(mcap, plot = TRUE) geometry::polyarea(mcap_2d$x, mcap_2d$y) # area planar(mcap) perimeter(mcap_2d) # perimeter circularity(mcap_2d) # circularity fd_boxes(mcap_2d) # fractal dimension
Turns a 3D mesh file into a Digital Elevation Model (DEM) of class RasterLayer format.
mesh_to_dem(mesh, res, fill = TRUE)mesh_to_dem(mesh, res, fill = TRUE)
mesh |
A mesh3d object. |
res |
(Optional) The desired DEM resolution in same units at the 3D mesh. |
fill |
Logical. Fill |
The function rasterizes uses the vertices of the mesh file.
If resolution is not
given, it is calculated by finding the maximum nearest neighbor
of vertices projected
on the xy plane. fill is used when irregular 3D meshes
result in NA values in
raster cells. The default is to fill these cells with the
minimum, non-NA raster value.
A dem of class RasterLayer.
dem <- mesh_to_dem(mcap) raster::plot(dem) dem <- mesh_to_dem(mcap, res = 0.05) raster::plot(dem) # Don't fill empty raster cells dem <- mesh_to_dem(mcap, res = 0.02, fill = FALSE) raster::plot(dem)dem <- mesh_to_dem(mcap) raster::plot(dem) dem <- mesh_to_dem(mcap, res = 0.05) raster::plot(dem) # Don't fill empty raster cells dem <- mesh_to_dem(mcap, res = 0.02, fill = FALSE) raster::plot(dem)
Transform mesh to 3D point cloud
mesh_to_points(mesh)mesh_to_points(mesh)
mesh |
A triangular mesh of class mesh3d. |
A data frame with XYZ coordinates.
Find midpoint of a DEM
mid_find(data)mid_find(data)
data |
A DEM in RasterLayer format. |
A data frame with x and y midpoints.
mid_find(horseshoe)mid_find(horseshoe)
The ratio of the surface area of the object and the surface area of the convex hull around the object.
packing(mesh)packing(mesh)
mesh |
A triangular mesh of class mesh3d. |
Value of packing.
packing(mcap)packing(mcap)
Calculates the perimeter of a 2D shape.
perimeter(data, keep_data = FALSE)perimeter(data, keep_data = FALSE)
data |
A data frame with the first two columns ordered x and y coordinates. |
keep_data |
Logical. Keep lengths of all segments of the perimeter? Defaults to FALSE. |
The perimeter.
mcap_2d <- mesh_to_2d(mcap) plot(mcap_2d) perimeter(mcap_2d) r <- 1 # radius circ <- sim_circle(r=r) # simulate xy coordinates for a circle of radius 1 plot(circ, asp=1) perimeter(circ) 2 * pi * r # Note xy resolution affects outputmcap_2d <- mesh_to_2d(mcap) plot(mcap_2d) perimeter(mcap_2d) r <- 1 # radius circ <- sim_circle(r=r) # simulate xy coordinates for a circle of radius 1 plot(circ, asp=1) perimeter(circ) 2 * pi * r # Note xy resolution affects output
Calculates planar area of a mesh
planar(mesh, L0, silent = FALSE)planar(mesh, L0, silent = FALSE)
mesh |
A triangular mesh of class mesh3d. |
L0 |
Resolution of the planar area. Is set to the resolution of the mesh when left empty. |
silent |
Logical. Suppress messages and warnings? |
A value for planar area.
planar(mcap)planar(mcap)
Calculate rugosity, fractal dimension, and height for a DEM
rdh( data, lvec, method_fd = "hvar", method_rg = "area", parallel = FALSE, ncores = (parallel::detectCores() - 1), ... )rdh( data, lvec, method_fd = "hvar", method_rg = "area", parallel = FALSE, ncores = (parallel::detectCores() - 1), ... )
data |
A dem of class RasterLayer. |
lvec |
Scales to use for calculation. |
method_fd |
method for the calculation of rugosity and fractal dimension. Can be "hvar", "sd", "cubes", or "area". Defaults to "hvar". |
method_rg |
Method to be used for the rugosity calculation. Defaults to "area". |
parallel |
Logical. Use parallel processing? Defaults to FALSE. |
ncores |
Number of cores to use if parallel = TRUE. |
... |
Additional arguments see |
Uses area method for rugosity and hvar method for fractal dimension calculations as default.
A dataframe with the three complexity metrics.
dem <- dem_sample(horseshoe, L = 1) rdh(dem, lvec = c(0.125, 0.25, 0.5, 1))dem <- dem_sample(horseshoe, L = 1) rdh(dem, lvec = c(0.125, 0.25, 0.5, 1))
Calculates either rugosity, fractal dimension or height range based on the other two variables.
rdh_theory(R, D, H, L, L0)rdh_theory(R, D, H, L, L0)
R, D, H
|
Two of the three variables to calculate the third. |
L |
Extent. |
L0 |
Resolution. |
This function uses the geometric plane equation from Torres-Pulliza et al. (2020) to calculate one of rugosity, fractal dimension or height range based on the other two variables.
A value corresponding one of the three variables not given to the function.
Torres-Pulliza D, Dornelas M, Pizarro O, Bewley M, Blowes SA, Boutros N, Brambilla V, Chase TJ, Frank G, Friedman A, Hoogenboom MO, Williams S, Zawada KJA, Madin JS (2020) A geometric basis for surface habitat complexity and biodiversity. Nature Ecology & Evolution 4:1495-1501. doi:10.1038/s41559-020-1281-8
rdh_theory(R=4, H=1, L=1, L0=0.01) rdh_theory(D=2.36928, H=1, L=1, L0=0.01) rdh_theory(D=2.36928, R=4, L=1, L0=0.01)rdh_theory(R=4, H=1, L=1, L0=0.01) rdh_theory(D=2.36928, H=1, L=1, L0=0.01) rdh_theory(D=2.36928, R=4, L=1, L0=0.01)
Rugosity is defined as the surface area divided by the planar area. For digital elevation models, there are two methods: "hvar" and "area".
The "hvar" method for calculating rugosity is described in Torres-Pulliza et al. (2004) and is based on height variations.
The "area" method uses the sp::surfaceArea() function and is detailed in Jenness (2004).
method is ignored if data is a mesh3D object.
In that case the function uses Rvcg::vcgArea() to calculate surface area of a triangular mesh of class mesh3d.
rg( data, L0, method = "area", parallel = FALSE, ncores = (parallel::detectCores() - 1) )rg( data, L0, method = "area", parallel = FALSE, ncores = (parallel::detectCores() - 1) )
data |
Digital elevation model of class RasterLayer or a triangular mesh of class mesh3d. |
L0 |
Grain or resolution of calculation. |
method |
If data is a RasterLayer methods "hvar" or "area" are allowed. Defaults to "hvar". |
parallel |
Logical. Use parallel processing? Defaults to FALSE. |
ncores |
Number of cores to use if parallel = TRUE. (Defaults to umber of available cores - 1) |
Rugosity value
Jenness, J.S. Calculating Landscape Surface Area from Digital Elevation Models. Wildlife Society Bulletin, Vol. 32, No. 3 (Autumn, 2004), pp. 829-839n
Torres-Pulliza, D., Dornelas, M.A., Pizarro, O. et al. A geometric basis for surface habitat complexity and biodiversity. Nat Ecol Evol 4, 1495–1501 (2020). https://doi.org/10.1038/s41559-020-1281-8
rg(horseshoe, L0 = 0.1) rg(mcap, L0 = 0.01)rg(horseshoe, L0 = 0.1) rg(mcap, L0 = 0.01)
Calculates the surface area of a triangle based on a set of XYZCoords.
sa_triangle(XYZcoords)sa_triangle(XYZcoords)
XYZcoords |
A data frame with XYZ coordinates of three points in following order: X1,X2,X3,Y1,Y2,Y3,Z1,Z2,Z3. |
The surface area of the triangle.
sa_triangle(c(X1 = 1, X2 = 2, X3 = 3 , Y1 = 1, Y2 = 2, Y3 = 1, Z1 = 1, Z2 = 1, Z3 = 1))sa_triangle(c(X1 = 1, X2 = 2, X3 = 3 , Y1 = 1, Y2 = 2, Y3 = 1, Z1 = 1, Z2 = 1, Z3 = 1))
Re-scale mesh based on a fixed area
scale_area(mesh, target_area = 1)scale_area(mesh, target_area = 1)
mesh |
A triangular mesh of class mesh3d. |
target_area |
The target area of the scaled 3D mesh. Defaults to 1. |
A mesh with area = target_area (1 as default).
Rvcg::vcgArea(mcap) mcap_scaled <- scale_area(mcap) Rvcg::vcgArea(mcap_scaled)Rvcg::vcgArea(mcap) mcap_scaled <- scale_area(mcap) Rvcg::vcgArea(mcap_scaled)
Re-scale mesh based on a fixed volume of 1
scale_volume(mesh)scale_volume(mesh)
mesh |
A triangular mesh of class mesh3d. |
A mesh with volume = 1.
Rvcg::vcgVolume(mcap) mcap_scaled <- scale_volume(mcap) Rvcg::vcgVolume(mcap_scaled)Rvcg::vcgVolume(mcap) mcap_scaled <- scale_volume(mcap) Rvcg::vcgVolume(mcap_scaled)
Transforms XYZ coordinates relative to a chosen origin
Transforms coordinates so that the origin lies at the reference vertex (defaults to the minimum of x, y, and z coordinates).
set_origin(mesh, reference = NULL)set_origin(mesh, reference = NULL)
mesh |
A triangular mesh of class mesh3d. |
reference |
Vector containing coordinates of the reference vertex. If left empty, this will default to the minimum of x, y, and z. |
mesh3d object
mesh <- set_origin(mcap)mesh <- set_origin(mcap)
Simulates xy coordinates for a circle of given radius. Created for package testing purposes, but might be useful for others.
sim_circle(r = 1, n = 100, mid = c(0, 0))sim_circle(r = 1, n = 100, mid = c(0, 0))
r |
Radius of the circle (default 1). |
n |
Number of xy coordinates defining the circle (default 100). |
mid |
Mid point of the circle (default 0, 0). |
A data frame of n xy-coordinates.
circ <- sim_circle() plot(circ) circularity(circ) perimeter(circ)circ <- sim_circle() plot(circ) circularity(circ) perimeter(circ)
Simulates z-values based on the Diamond-square algorithm.
sim_dem( L, smoothness, H, R, plot = FALSE, prop = 0.1, n = 100, method = "area", parallel = FALSE )sim_dem( L, smoothness, H, R, plot = FALSE, prop = 0.1, n = 100, method = "area", parallel = FALSE )
L |
The extent. |
smoothness |
A value between 0.0 and 1.0 (lower values produce rougher DEM). |
H |
Desired height range (optional). |
R |
Desired rugosity value (optional). |
plot |
Logical. Plot the simulated DEM during simulation? Only relevant if R is provided. |
prop |
Proportion of cells that undergo smoothing at each iteration when R is provided. |
n |
Number of iterations to try and reach desired R. Recommended to adapt R and H instead of increasing n if simulation fails. |
method |
The method to be used for rugosity calculation in case R is given. Can be "hvar" or "area" |
parallel |
Logical. Use parallel processing? Defaults to FALSE. Only relevant if method = "hvar". |
Warning: this function gets slow for n > 128.
If H is provided, the simulated DEM is rescaled based on the value for H.
If R is provided, a DEM is simulated using the same algorithm based on R, H, and the predicted D based on rdh_theory(), while smoothness is ignored.
From that first simulated DEM, R is calculated and the DEM undergoes smoothing at each iteration until the rugosity approximates the inputted R.
Argument prop defined the proportion of random cells of the DEM that are smoothed by averaging the z values of cell and neighboring cells at each iteration.
Caution: When R is provided, the DEM may become increasingly less fractal as it is modified at each iteration.
Digital elevation model of class RasterLayer.
library(raster) dem <- sim_dem(L = 32, smoothness = 0.5) plot(dem) dem <- sim_dem(L = 32, smoothness = 0.2, H = 20) plot(dem)library(raster) dem <- sim_dem(L = 32, smoothness = 0.5) plot(dem) dem <- sim_dem(L = 32, smoothness = 0.2, H = 20) plot(dem)
Calculates the 2nd moment of surface area about the origin by multiplying the surface area of each triangle in the mesh by its distance from the origin (should be set to the attachment point of the mesh). The sum of these values is the 2nd moment of area.#' This metric is size-dependent so to compare moments in terms of shape only, set scale = TRUE.
sma(mesh, axis = "z", scale = FALSE, origin = TRUE)sma(mesh, axis = "z", scale = FALSE, origin = TRUE)
mesh |
A triangular mesh of class mesh3d. |
axis |
The axis along which to calculate the second moment of area. z is the default. |
scale |
Logical. Scale the object to have a volume = 1? Default = FALSE |
origin |
Logical. Set the origin to the bottom left corner of bounding box? Default = TRUE. |
SMA value.
sma(mcap) sma(mcap, scale = TRUE)sma(mcap) sma(mcap, scale = TRUE)
Calculates the 2nd moment of volume (SMV) by multiplying the volume of each triangle in the mesh by its centroids' distance from the origin (should be set to the attachment point of the mesh). The sum of these values is the 2nd moment of volume. Axis is z by default, meaning it will calculate the vertical second moment, but this can be changed if needed. This metric is size-dependent so to compare moments in terms of shape only, set scale = TRUE.
smv(mesh, axis = "z", scale = FALSE, origin = TRUE)smv(mesh, axis = "z", scale = FALSE, origin = TRUE)
mesh |
A triangular mesh of class mesh3d. |
axis |
The axis along which to calculate the second moment of volume z is the default. |
scale |
Logical. Scale the object to have a volume = 1? Default = TRUE. |
origin |
Logical. Set the origin to the bottom left corner of bounding box? Default = FALSE |
SMV value.
smv(mcap)smv(mcap)
Calculates the ratio of the surface area of a sphere with the same volume as the object and the surface area of the object.
sphericity(mesh)sphericity(mesh)
mesh |
A triangular mesh of class mesh3d. |
Sphericity value.
sphericity(mcap)sphericity(mcap)
Calculates surface area of a 3D or 2D object.
surface_area(data)surface_area(data)
data |
DEM in RasterLayer format, mesh3d object or data frame with xy coordinates. |
Surface area value.
Jenness, J.S. Calculating Landscape Surface Area from Digital Elevation Models. Wildlife Society Bulletin, Vol. 32, No. 3 (Autumn, 2004), pp. 829-839n
surface_area(mcap) surface_area(horseshoe) surface_area(mesh_to_2d(mcap))surface_area(mcap) surface_area(horseshoe) surface_area(mesh_to_2d(mcap))
Calculates the signed volume of a triangle based on a set of XYZCoords. Signed volume means that volumes can take on a negative value depending on whether the surface normal of the triangle is facing towards or away from the origin. When all positive and negative volumes are integrated across the entire mesh, these values cancel out so that the final volume is an approximation of the total volume of the mesh.
svol_triangle(XYZCoords)svol_triangle(XYZCoords)
XYZCoords |
A dataframe with XYZ coordinates of three points in following order: X1,X2,X3,Y1,Y2,Y3,Z1,Z2,Z3 |
Value for the signed volume of a triangle.
svol_triangle(c(X1 = 1, X2 = 2, X3 = 3 , Y1 = 1, Y2 = 2, Y3 = 1, Z1 = 1, Z2 = 1, Z3 = 1))svol_triangle(c(X1 = 1, X2 = 2, X3 = 3 , Y1 = 1, Y2 = 2, Y3 = 1, Z1 = 1, Z2 = 1, Z3 = 1))
Extract mean depth or elevation of a DEM
z(data)z(data)
data |
A DEM in RasterLayer format. |
Value: mean depth or elevation of DEM.
z(horseshoe)z(horseshoe)