lidR (version 3.2.3)

grid_metrics: 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 RasterLayers are written on disk when running the function with a LAScatalog, a virtual raster mosaic is returned (see gdalbuildvrt)

Parameter <code>func</code>

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 <code>LAScatalog</code>

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

# NOT RUN {
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))
# }