R: Compute metrics for each tree

tree_metrics {lidR} | R Documentation

## Compute metrics for each tree

### Description

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. This is the "tree version" of grid_metrics.

### Usage

    tree_metrics(las, func = ~max(Z), attribute = "treeID")

### Arguments

`las` | An object of class LAS or LAScatalog.
`func` | formula. An expression to be applied to each tree. It works like in grid_metrics voxel_metrics or delineate_crowns and computes, in addition to tree locations a set of metrics for each tree.
`attribute` | character. The column name of the attribute containing tree IDs. Default is `"treeID"`

### Details

By default the function computes the xyz-coordinates of the highest point of each tree and uses xy as tree coordinates in `SpatialPoinsDataFrame`. z is stored in the table of attributes along with the id of each tree. All the other attributes are user-defined attributes:
The following existing functions contain a small set of pre-defined metrics:

- stdmetrics_tree

Users must write their own functions to create their own metrics. `tree_metrics` will dispatch the LiDAR data for each segmented tree in the user-defined function. Functions are defined without the need to consider each segmented tree i.e. only the point cloud (see examples).

### Value

A `SpatialPoinsDataFrame` that references the xy-position with a table of attributes that associates the z-elevation (highest points) of the trees and the id of the trees, plus the metrics defined by the user.

### Working with a `LAScatalog`

This section appears in each function that supports a LAScatalog as input.

In `lidR` when the input of a function is a LAScatalog the function uses the LAScatalog processing engine. The user can modify the engine options using the available options. A careful reading of the engine documentation is recommended before processing `LAScatalogs`. Each `lidR` function should come with a section that documents the supported engine options.

The `LAScatalog` engine supports `.lax` files that significantly improve the computation speed of spatial queries using a spatial index. Users should really take advantage a `.lax` files, but this is not mandatory.

### Supported processing options

Supported processing options for a `LAScatalog` (in bold). For more details see the LAScatalog engine documentation:

- chunk size: How much data is loaded at once.

- chunk buffer*: Mandatory to get a continuous output without edge effects. The buffer is always removed once processed and will never be returned either in R or in files.

- chunk alignment: Align the processed chunks.

- progress: Displays a progression estimation.

- output files: Supported templates are `{XLEFT}`, `{XRIGHT}`, `{YBOTTOM}`, `{YTOP}`, `{XCENTER}`, `{YCENTER}` `{ID}` and, if chunk size is equal to 0 (processing by file), `{ORIGINALFILENAME}`.

- select: Load only attributes of interest.

- filter: Read only points of interest.

### See Also

Other metrics: `cloud_metrics()`, `grid_metrics()`, `plot_metrics()`, `point_metrics()`, `voxel_metrics()`

### Examples

    LASfile <- system.file("extdata", "MixedConifer.laz", package="lidR")
    las = readLAS(LASfile, filter = "-drop_z_below 0")

    # NOTE: This dataset is already segmented
    # plot(las, color = "treeID", colorPalette = pastel.colors(200))

    # Default computes only Z max
    metrics = tree_metrics(las)

    # User-defined metrics - mean height and mean intensity for each tree
    metrics = tree_metrics(las, ~list(Zmean = mean(Z), Imean = mean(Intensity)))

    # Define your own new metrics function
    myMetrics = function(z, i)
    {
      metrics = list(
         imean = mean(i),
         imax  = max(i),
         npoint = length(z)
       )

       return(metrics)
    }

    metrics = tree_metrics(las, ~myMetrics(Z, Intensity))

    # predefined metrics (see ?stdmetrics)
    metrics = tree_metrics(las, .stdtreemetrics)

[Package lidR version 3.2.2 Index]