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

numeric. Layer thickness metric entropy

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

Run this code

# NOT RUN {
LASfile <- system.file("extdata", "Megaplot.laz", package="lidR")
las = readLAS(LASfile, select = "*")

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

# Convenient shortcut
m2 = grid_metrics(las, .stdmetrics)

# Basic metrics from intensities
m3 = grid_metrics(las, ~stdmetrics_i(Intensity))

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

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

# Compute the metrics only on first return
first = lasfilterfirst(las)
m6 = grid_metrics(first, .stdmetrics_z)

# Compute the metrics with a threshold at 2 meters
over2 = lasfilter(las, Z > 2)
m7 = grid_metrics(over2, .stdmetrics_z)

# Works also with cloud_metrics and hexbin_metrics
m8 = cloud_metrics(las, .stdmetrics)
m9 = 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))

# Users can write their own convenient shorcuts like this:
.myMetrics = ~myMetrics(Z, Intensity, ReturnNumber)

m11 = grid_metrics(las, .myMetrics)
# }

Run the code above in your browser using DataLab