R: Area-Based Approach

grid_metrics {lidR} | R Documentation

## Area-Based Approach

### Description

Computes a series of user-defined descriptive statistics for a LiDAR dataset within each pixel of a raster (area-based approach). The grid cell coordinates are pre-determined for a given resolution, so the algorithm will always provide the same coordinates independently of the dataset. When start = (0,0) and res = 20 grid_metrics will produce the following cell centers: (10,10), (10,30), (30,10) etc. aligning the corner of a cell on (0,0). When start = (-10, -10) and res = 20 grid_metrics will produce the following cell centers: (0,0), (0,20), (20,0) etc. aligning the corner of a cell on (-10, -10).

### Usage

    grid_metrics(
      las,
      func,
      res = 20,
      start = c(0, 0),
      filter = NULL,
      by_echo = "all"
    )

### Arguments

`las` | An object of class LAS or LAScatalog.
`func` | formula. An expression to be applied to each cell (see section "Parameter func").
`res` | numeric. The resolution of the output `Raster`. Can optionally be a `RasterLayer`. In that case the `RasterLayer` is used as the layout.
`start` | vector of x and y coordinates for the reference raster. Default is (0,0) meaning that the grid aligns on (0,0).
`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 multiples times for different echo types. Can be one or more of "all", "first", "intermediate", "lastofmany", "single", "multiple". See examples. Default is "all" meaning that it computes metrics with all points provided.

### Value

A `RasterLayer` or a `RasterBrick` containing a numeric value in each cell. If the `RasterLayer`s are written on disk when running the function with a `LAScatalog`, a virtual raster mosaic is returned (see gdalbuildvrt)

### Parameter `func`

The function to be applied to each cell is a classical function (see examples) that returns a labeled 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:

    grid_metrics(las, ~f(Z), res = 20)
    grid_metrics(las, ~f(Intensity), res = 20)

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. `grid_metrics` will dispatch the point cloud in the user's function.

### 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 `grid_*` functions (in bold). For more details see the LAScatalog engine documentation:

- chunk size: How much data is loaded at once. The chunk size may be slightly modified internally to ensure a strict continuous wall-to-wall output even when chunk size is equal to 0 (processing by file).

- chunk buffer: This function guarantees a strict continuous wall-to-wall output. The `buffer` option is not considered.

- chunk alignment: Align the processed chunks. The alignment may be slightly modified internally to ensure a strict continuous wall-to-wall output.

- progress: Displays a progress estimate.

- output files: Return the output in R or write each cluster's output in a file. Supported templates are `{XLEFT}`, `{XRIGHT}`, `{YBOTTOM}`, `{YTOP}`, `{XCENTER}`, `{YCENTER}` `{ID}` and, if chunk size is equal to 0 (processing by file), `{ORIGINALFILENAME}`.

- select: The `grid_*` functions usually 'know' what should be loaded and this option is not considered. In grid_metrics this option is respected.

- filter: Read only the points of interest.

### See Also

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

### Examples

    LASfile <- system.file("extdata", "Megaplot.laz", package="lidR")
    las = readLAS(LASfile)
    col = height.colors(50)

    # === Using all points ===

    # Mean height with 400 m^2 cells
    metrics = grid_metrics(las, ~mean(Z), 20)
    plot(metrics, col = col)

    # Define your own new metrics
    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)
    }

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

    plot(metrics, col = col)
    #plot(metrics, "zwimean", col = col)
    #plot(metrics, "zimean", col = col)

    # === With point filters ===

    # Compute using only some points: basic
    first = filter_poi(las, ReturnNumber == 1)
    metrics = grid_metrics(first, ~mean(Z), 20)

    # Compute using only some points: optimized
    # faster and uses less memory. No intermediate object
    metrics = grid_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 = grid_metrics(las, ~mean(Z), 20)

    # === Split by echo type ===
    func = ~list(avgI = mean(Intensity))
    echo = c("all", "first","multiple")
    metrics <- grid_metrics(las, func , 20, by_echo = echo)
    plot(metrics, col = heat.colors(25))

[Package lidR version 3.2.2 Index]