aggregate: Metric derivation at different levels of regularization

Description

template_metrics() computes a series of user-defined descriptive statistics for a LiDAR dataset within each element of a template. Depending on the template it can be for each pixel of a raster (area-based approach), or each polygon, or each segmented tree, or on the whole point cloud. Other functions are convenient and simplified wrappers around template_metrics() and are expected to be the actual functions used. See Details and Examples.

Usage

cloud_metrics(las, func, ...)
crown_metrics(
  las,
  func,
  geom = "point",
  concaveman = c(3, 0),
  attribute = "treeID",
  ...
)
hexagon_metrics(las, func, area = 400, ...)
pixel_metrics(las, func, res = 20, start = c(0, 0), ...)
plot_metrics(las, func, geometry, ..., radius)
polygon_metrics(las, func, geometry, ...)
template_metrics(las, func, template, filter = NULL, by_echo = "all", ...)
voxel_metrics(las, func, res = 1, ..., all_voxels = FALSE)

Value

Depends on the function, the template and the number of metrics. Can be a RasterLayer, a RasterBrick, a stars, a SpatRaster a sf/sfc, a list, a SpatialPolygonDataFrame, or a data.table. Functions are supposed to return an object that is best suited for storing the level of regularization needed.

Arguments

las: An object of class LAS or LAScatalog.
func: formula or expression. An expression to be applied to each element of the template (see section "Parameter func").
...: propagated to template_metrics i.e. filter and by_echo. pixel_metrics() also supports pkg = "terra|raster|stars" to get an output in SpatRaster, Raster* or stars format. Default is getOption("lidR.raster.default").
geom: character. Geometry type of the output. Can be 'point', 'convex', 'concave' or 'bbox'.
concaveman: numeric. Only if type = "concave". Vector with the two parameters of the function concaveman.
attribute: character. The column name of the attribute containing tree IDs. Default is "treeID"
area: numeric. Area of the hexagons
res: numeric. The resolution of the output. Can optionally be a RasterLayer or a stars or a SpatRaster. In that case the raster is used as the template.
start: vector of x and y coordinates for the reference raster. Default is (0,0) meaning that the grid aligns on (0,0). Not consiered if res is a raster
geometry: A spatial vector object. sp and sf' objects are supported. plot_metrics() supports point and polygons but polygon_metrics() supports only polygons.
radius: numeric. If the geometry is spatial points a radius must be defined. Support one radius or a vector of radii for variable plot sizes.
template: can be of many types and corresponds to the different levels of regularization. RasterLayer/stars/SpatRaster, sf/sfc (polygons), numeric, bbox, NULL. The metrics are computed for each element of the template. See examples.
filter: formula of logical predicates. Enables the function to run only on points of interest in an optimized way. See examples.
by_echo: characters. The metrics are computed multiple times for different echo types. Can be one or more of "all", "first", "intermediate", "lastofmany", "single", and "multiple". See examples. Default is "all" meaning that it computes metrics with all points provided.
all_voxels: boolean. By default the function returns only voxels that contain 1 or more points. Empty voxels do not exist as the metrics are undefined. If all_voxels = TRUE all the voxels are returned and metrics are NA for voxels with 0 points.

Parameter <code>func</code>

The function to be applied to each cell is a classical function (see examples) that returns a labelled list of metrics. For example, the following function f is correctly formed.


f = function(x) {list(mean = mean(x), max = max(x))}

And could be applied either on the Z coordinates or on the intensities. These two statements are valid:


pixel_metrics(las, f(Z), res = 20)
voxel_metrics(las, f(Intensity), res = 2)

The following existing functions allow the user to compute some predefined metrics: stdmetrics entropy, VCI, LAD. But usually users must write their own functions to create metrics. template_metrics will dispatch the point cloud in the user's function.

Details

pixel_metrics: Area-based approach. Computes metrics in a square tessellation. The output is a raster.
hexagon_metrics: Computes metrics in an hexagon tessellation. The output is a sf/sfc_POLYGON
plot_metrics: Computes metrics for each plot of a ground inventory by 1. clipping the plot inventories with clip_roi, 2. computing the user's metrics for each plot with cloud_metrics, and 3. combining spatial data and metrics into one data.frame ready for statistical modelling with cbind. The output is of the class of the input.
cloud_metrics: Computes a series of user-defined descriptive statistics for an entire point cloud. The output is a list
crown_metrics: Once the trees are segmented, i.e. attributes exist in the point cloud that reference each tree, computes a set of user-defined descriptive statistics for each individual tree. The output can be spatial points or spatial polygons (sf/sfc_POINT or sf/sfc_POLYGON)
voxel_metrics: Is a 3D version of pixel_metrics. It creates a 3D matrix of voxels with a given resolution. It creates a voxel from the cloud of points if there is at least one point. The output is a data.frame
point_metrics: Is a bit more complex and is documented in point_metrics

Examples

Run this code

LASfile <- system.file("extdata", "Megaplot.laz", package="lidR")
las <- readLAS(LASfile, filter = "-keep_random_fraction 0.5")
col <- sf::sf.colors(15)
fun1 <- ~list(maxz = max(Z))
fun2 <- ~list(q85 = quantile(Z, probs = 0.85))

set_lidr_threads(1) ; data.table::setDTthreads(1) # for cran only

# ================
# CLOUD METRICS
# ================

cloud_metrics(las, .stdmetrics_z)

# ================
# PIXEL METRICS
# ================

m <- pixel_metrics(las, fun1, 20)
#plot(m, col = col)

# ================
# PLOT METRICS
# ================

shpfile <- system.file("extdata", "efi_plot.shp", package="lidR")
inventory <- sf::st_read(shpfile, quiet = TRUE)
inventory # contains an ID and a Value Of Interest (VOI) per plot

m <- plot_metrics(las, fun2, inventory, radius = 11.28)
#plot(header(las))
#plot(m["q85"], pch = 19, cex = 3, add = TRUE)

# \donttest{
# Works with polygons as well
inventory <- sf::st_buffer(inventory, 11.28)
#plot(header(las))
#plot(sf::st_geometry(inventory), add = TRUE)
m <- plot_metrics(las, .stdmetrics_z, inventory)
#plot(m["zq85"], pch = 19, cex = 3, add = TRUE)
# }

# ================
# VOXEL METRICS
# ================

m <- voxel_metrics(las, length(Z), 8)
m <- voxel_metrics(las, mean(Intensity), 8)
#plot(m, color = "V1", colorPalette = heat.colors(50), trim = 60)
#plot(m, color = "V1", colorPalette = heat.colors(50), trim = 60, voxel = TRUE)

# ================
# CROWN METRICS
# ================

# Already tree-segmented point cloud
LASfile <- system.file("extdata", "MixedConifer.laz", package="lidR")
trees <- readLAS(LASfile, filter = "-drop_z_below 0")

metrics <- crown_metrics(trees, .stdtreemetrics)
#plot(metrics["Z"], pch = 19)

metrics <- crown_metrics(trees, .stdtreemetrics, geom = "convex")
#plot(metrics["Z"])

metrics <- crown_metrics(trees, .stdtreemetrics, geom = "bbox")
#plot(metrics["Z"])

# \donttest{
metrics <- crown_metrics(trees, .stdtreemetrics, geom = "concave")
#plot(metrics["Z"])
# }
# ================
# ARGUMENT FILTER
# ================

# Compute using only some points: basic
first = filter_poi(las, ReturnNumber == 1)
metrics = pixel_metrics(first, mean(Z), 20)

# Compute using only some points: optimized
# faster and uses less memory. No intermediate object
metrics = pixel_metrics(las, mean(Z), 20, filter = ~ReturnNumber == 1)

# Compute using only some points: best
# ~50% faster and uses ~10x less memory
las = readLAS(LASfile, filter = "-keep_first")
metrics = pixel_metrics(las, mean(Z), 20)

# ================
# ARGUMENT BY_ECHO
# ================

func = ~list(avgI = mean(Intensity))
echo = c("all", "first","multiple")

# func defines one metric but 3 are computed respectively for: (1) all echo types,
# (2) for first returns only and (3) for multiple returns only
metrics <- pixel_metrics(las, func, 20, by_echo = echo)
#plot(metrics, col = heat.colors(25))

cloud_metrics(las, func, by_echo = echo)

if (FALSE) {
# ================
# TEMPLATE METRICS
# ================

# a raster as template
template <- raster::raster(extent(las), nrow = 15, ncol = 15)
raster::crs(template) <- crs(las)
m <- template_metrics(las, fun1, template)
#plot(m, col = col)

# a sfc_POLYGON as template
sfc <- sf::st_as_sfc(st_bbox(las))
template <- sf::st_make_grid(sfc, cellsize = 20, square = FALSE)
m <- template_metrics(las, fun1, template)
#plot(m)

# a bbox as template
template <- st_bbox(las) + c(50,30,-50,-70)
plot(sf::st_as_sfc(st_bbox(las)), col = "gray")
plot(sf::st_as_sfc(template), col = "darkgreen", add = TRUE)
m <- template_metrics(las, fun2, template)
print(m)

# ================
# CUSTOM METRICS
# ================

# Define a function that computes custom metrics
# in an R&D perspective.
myMetrics = function(z, i) {
  metrics = list(
     zwimean = sum(z*i)/sum(i), # Mean elevation weighted by intensities
     zimean  = mean(z*i),       # Mean products of z by intensity
     zsqmean = sqrt(mean(z^2))) # Quadratic mean

   return(metrics)
}

# example with a stars template
template <- stars::st_as_stars(st_bbox(las), dx = 10, dy = 10)
m <- template_metrics(las, myMetrics(Z, Intensity), template)
#plot(m, col = col)
}

Run the code above in your browser using DataLab