lidR: stdmetrics – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

stdmetrics

Predefined standard metrics functions

Description

Predefined functions computable at pixel level (grid_metrics), hexagonal cell level (hexbin_metrics), point cloud level (cloud_metrics), tree level (tree_metrics) voxel level (voxel_metrics) and point level (point_metrics). Each function comes with a convenient shortcuts for lazy coding. The lidR package aims to provide an easy way to compute user-defined metrics rather than to provide them. However, for efficiency and to save time, a set of standard metrics has been predefined (see details).

Usage

stdmetrics(x, y, z, i, rn, class, dz = 1, th = 2)

stdmetrics_z(z, dz = 1, th = 2)

stdmetrics_i(i, z = NULL, class = NULL, rn = NULL)

stdmetrics_rn(rn, class = NULL)

stdmetrics_pulse(pulseID, rn)

stdmetrics_ctrl(x, y, z)

stdtreemetrics(x, y, z)

stdshapemetrics(x, y, z)

.stdmetrics

.stdmetrics_z

.stdmetrics_i

.stdmetrics_rn

.stdmetrics_pulse

.stdmetrics_ctrl

.stdtreemetrics

.stdshapemetrics

Arguments

`x, y, z, i`	Coordinates of the points, Intensity
`rn, class`	ReturnNumber, Classification
`dz`	numeric. Layer thickness metric entropy
`th`	numeric. Threshold for metrics pzabovex. Can be a vector to compute with several thresholds.
`pulseID`	The number referencing each pulse

Format

An object of class formula of length 2.

Details

The function names, their parameters and the output names of the metrics rely on a nomenclature chosen for brevity:

z: refers to the elevation
i: refers to the intensity
rn: refers to the return number
q: refers to quantile
a: refers to the ScanAngleRank or ScanAngle
n: refers to a number (a count)
p: refers to a percentage

For example the metric named zq60 refers to the elevation, quantile, 60 i.e. the 60th percentile of elevations. The metric pground refers to a percentage. It is the percentage of points classified as ground. The function stdmetric_i refers to metrics of intensity. A description of each existing metric can be found on the lidR wiki page.

Some functions have optional parameters. If these parameters are not provided the function computes only a subset of existing metrics. For example, stdmetrics_i requires the intensity values, but if the elevation values are also provided it can compute additional metrics such as cumulative intensity at a given percentile of height.

Each function has a convenient associated variable. It is the name of the function, with a dot before the name. This enables the function to be used without writing parameters. The cost of such a feature is inflexibility. It corresponds to a predefined behavior (see examples)

stdmetrics: is a combination of stdmetrics_ctrl + stdmetrics_z + stdmetrics_i + stdmetrics_rn
stdtreemetrics: is a special function that works with tree_metrics. Actually, it won't fail with other functions but the output makes more sense if computed at the individual tree level.
stdshapemetrics: is a set of eigenvalue based feature described in Lucas et al, 2019 (see references).

References

Lucas, C., Bouten, W., Koma, Z., Kissling, W. D., & Seijmonsbergen, A. C. (2019). Identification of Linear Vegetation Elements in a Rural Landscape Using LiDAR Point Clouds. Remote Sensing, 11(3), 292.

Examples

LASfile <- system.file("extdata", "Megaplot.laz", package="lidR")
las <- readLAS(LASfile, select = "*", filter = "-keep_random_fraction 0.5")

# All the predefined metrics
m1 <- grid_metrics(las, ~stdmetrics(X,Y,Z,Intensity,ReturnNumber,Classification,dz=1), res = 40)

# Convenient shortcut
m2 <- grid_metrics(las, .stdmetrics, res = 40)

# Basic metrics from intensities
m3 <- grid_metrics(las, ~stdmetrics_i(Intensity), res = 40)

# All the metrics from intensities
m4 <- grid_metrics(las, ~stdmetrics_i(Intensity, Z, Classification, ReturnNumber), res = 40)

# Convenient shortcut for the previous example
m5 <- grid_metrics(las, .stdmetrics_i, res = 40)

# Works also with cloud_metrics and hexbin_metrics
m6 <- cloud_metrics(las, .stdmetrics)
m7 <- hexbin_metrics(las, .stdmetrics)

# Combine some predefined function with your own new metrics
# Here convenient shortcuts are no longer usable.
myMetrics = function(z, i, rn)
{
  first  <- rn == 1L
  zfirst <- z[first]
  nfirst <- length(zfirst)
  above2 <- sum(z > 2)

  x <- above2/nfirst*100

  # User's metrics
  metrics <- list(
     above2aboven1st = x,       # Num of returns above 2 divided by num of 1st returns
     zimean  = mean(z*i),       # Mean products of z by intensity
     zsqmean = sqrt(mean(z^2))  # Quadratic mean of z
   )

  # Combined with standard metrics
  return( c(metrics, stdmetrics_z(z)) )
}

m10 <- grid_metrics(las, ~myMetrics(Z, Intensity, ReturnNumber), res = 40)

# Users can write their own convenient shorcuts like this:
.myMetrics = ~myMetrics(Z, Intensity, ReturnNumber)
m11 <- grid_metrics(las, .myMetrics, res = 40)

lidR

Airborne LiDAR Data Manipulation and Visualization for Forestry Applications

v3.1.2

GPL-3

Authors

Jean-Romain Roussel [aut, cre, cph], David Auty [aut, ctb] (Reviews the documentation), Florian De Boissieu [ctb] (Fixed bugs and improved catalog features), Andrew Sánchez Meador [ctb] (Implemented wing2015() for segment_snags()), Bourdon Jean-François [ctb] (Contributed to Roussel2020() for track_sensor()), Gatziolis Demetrios [ctb] (Implemented Gatziolis2019() for track_sensor())

Initial release

2021-03-11