Metric derivation at different levels of regularization
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.
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)
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.
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.
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_POLYGONplot_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 listcrown_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.framepoint_metrics: Is a bit more complex and is documented in point_metricsfuncThe 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.
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) # 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"]) 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) ## Not run: # ================ # 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) ## End(Not run)