% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/metrics_stdmetrics.R
\docType{data}
\name{stdmetrics}
\alias{stdmetrics}
\alias{stdmetrics_z}
\alias{stdmetrics_i}
\alias{stdmetrics_rn}
\alias{stdmetrics_pulse}
\alias{stdmetrics_ctrl}
\alias{stdtreemetrics}
\alias{stdshapemetrics}
\alias{.stdmetrics}
\alias{.stdmetrics_z}
\alias{.stdmetrics_i}
\alias{.stdmetrics_rn}
\alias{.stdmetrics_pulse}
\alias{.stdmetrics_ctrl}
\alias{.stdtreemetrics}
\alias{.stdshapemetrics}
\title{Predefined standard metrics functions}
\format{
An object of class \code{formula} of length 2.

An object of class \code{formula} of length 2.

An object of class \code{formula} of length 2.

An object of class \code{formula} of length 2.

An object of class \code{formula} of length 2.

An object of class \code{formula} of length 2.

An object of class \code{formula} of length 2.

An object of class \code{formula} of length 2.
}
\usage{
stdmetrics(x, y, z, i, rn, class, dz = 1, th = 2, zmin = 0)

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

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{
\item{x, y, z, i}{Coordinates of the points, Intensity}

\item{rn, class}{ReturnNumber, Classification}

\item{dz}{numeric. Layer thickness  metric \link[=entropy]{entropy}}

\item{th}{numeric. Threshold for metrics pzabovex. Can be a vector to compute with several thresholds.}

\item{zmin}{numeric. Lower bound of the integral for zpcumx metrics.
See \href{https://github.com/r-lidar/lidR/wiki/stdmetrics}{wiki page} and Wood et al.
(2008) reference.}

\item{pulseID}{The number referencing each pulse}
}
\description{
Predefined metrics functions intended to me used in \verb{*_metrics} function such as
\link{pixel_metrics}, \link{cloud_metrics}, \link{crown_metrics}, \link{voxel_metrics} and
so on. Each function comes with a convenient shortcuts for lazy coding. The \code{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, sets of standard metrics have been predefined (see details). Every
function can be computed by every \verb{*_metrics} functions however \verb{stdmetrics*} are
more pixel-based metrics, \code{stdtreemetrics} are more tree-based metrics and \code{stdshapemetrics} are
more point-based metrics. For example the metric \code{zmean} computed by \code{stdmetrics_z} makes sense
when computed at the pixel level but brings no information at the voxel level.
}
\details{
The function names, their parameters and the output names of the metrics rely on a nomenclature
chosen for brevity:
\itemize{
\item{\code{z}: refers to the elevation}
\item{\code{i}: refers to the intensity}
\item{\code{rn}: refers to the return number}
\item{\code{q}: refers to quantile}
\item{\code{a}: refers to the ScanAngleRank or ScanAngle}
\item{\code{n}: refers to a number (a count)}
\item{\code{p}: refers to a percentage}
}
For example the metric named \code{zq60} refers to the elevation, quantile, 60 i.e. the 60th percentile
of elevations. The metric \code{pground} refers to a percentage. It is the percentage of points
classified as ground. The function \code{stdmetric_i} refers to metrics of intensity. A description of
each existing metric can be found on the \href{https://github.com/r-lidar/lidR/wiki/stdmetrics}{lidR wiki page}.\cr\cr
Some functions have optional parameters. If these parameters are not provided the function
computes only a subset of existing metrics. For example, \code{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.\cr\cr
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 behaviour (see examples)\cr
\describe{
\item{\code{stdmetrics}}{is a combination of \code{stdmetrics_ctrl} + \code{stdmetrics_z} +
\code{stdmetrics_i} +  \code{stdmetrics_rn}}
\item{\code{stdtreemetrics}}{is a special function that works with \link{crown_metrics}. Actually,
it won't fail with other functions but the output makes more sense if computed at the
individual tree level.}
\item{\code{stdshapemetrics}}{is a set of eigenvalue based feature described in Lucas et al, 2019
(see references).}
}
}
\examples{
LASfile <- system.file("extdata", "Megaplot.laz", package="lidR")
las <- readLAS(LASfile, select = "*", filter = "-keep_random_fraction 0.5")

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

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

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

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

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

# 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 <- pixel_metrics(las, ~myMetrics(Z, Intensity, ReturnNumber), res = 40)

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

}
\references{
M. Woods, K. Lim, and P. Treitz. Predicting forest stand variables from LiDAR data in
the Great Lakes – St. Lawrence forest of Ontario. The Forestry Chronicle. 84(6): 827-839.
https://doi.org/10.5558/tfc84827-6

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.
}
\keyword{datasets}
