aggregate: Metric derivation at different levels of regularization

In Jean-Romain/lidR: Airborne LiDAR Data Manipulation and Visualization for Forestry Applications

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)

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.

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

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.

Parameter func

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.

Examples

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)

Jean-Romain/lidR documentation built on April 6, 2024, 9:41 p.m.