LAScatalog-class {lidR}

An S4 class to represent a collection of .las or .laz files

Description

A LAScatalog object is a representation of a collection of las/laz files. A LAScatalog is a way to manage and batch process a lidar coverage. It allows the user to process a large area, or to selectively clip data from a large area without loading all the data into computer memory. A LAScatalog can be built with the function readLAScatalog.

Details

A LAScatalog contains an sf object to store the geometry and metadata. It is extended with slots that contain processing options. In lidR, each function that supports a LAScatalog as input will respect these processing options. Internally, processing a catalog is almost always the same and relies on a few steps:

1. Define chunks. A chunk is an arbitrarily-defined region of interest (ROI) of the collection. Altogether, the chunks are a wall-to-wall set of ROIs that encompass the whole dataset.

2. Loop over each chunk (in parallel or not).

3. For each chunk, load the points inside the ROI into R, run some R functions, return the expected output.

4. Merge the outputs of the different chunks once they are all processed to build a continuous (wall-to-wall) output.

So basically, a LAScatalog is an object that allows for batch processing but with the specificity that lidR does not loop through LAS or LAZ files, but loops seamlessly through chunks that do not necessarily match with the file pattern. This way lidR can sequentially process tiny ROIs even if each file may be individually too big to fit in memory. This is also why point cloud indexation with lax files may significantly speed-up the processing.

It is important to note that catalogs with files that overlap each other are not natively supported by lidR. When encountering such datasets the user should always filter any overlaps if possible. This is possible if the overlapping points are flagged, for example in the 'withheld' attribute. Otherwise lidR will not be able to process the dataset correctly.

Slots

data

sf. An sf data.frame with the bounding box of each file as well as all the information read from the header of each LAS/LAZ file.

processing_options

list. A list that contains some settings describing how the collection will be processed (see dedicated section).

chunk_options

list. A list that contains some settings describing how the collection will be sub-divided into chunks to be processed (see dedicated section).

output_options

list. A list that contains some settings describing how the collection will return the outputs (see dedicated section).

input_options

list. A list of parameters to pass to readLAS (see dedicated section).

index

list. See spatial indexing.

Processing options

The slot ⁠@processing_options⁠ contains a list of options that determine how chunks (the sub-areas that are sequentially processed) are processed.

• progress: boolean. Display a progress bar and a chart of progress. Default is TRUE. Progress estimation can be enhanced by installing the package progress. See opt_progress.

• stop_early: boolean. Stop the processing if an error occurs in a chunk. If FALSE the process can run until the end, removing chunks that failed. Default is TRUE and the user should have no reason to change this. See opt_stop_early.

• wall.to.wall logical. The catalog processing engine always guarantees to return a continuous output without edge effects, assuming that the catalog is a wall-to-wall catalog. To do so, some options are checked internally to guard against bad settings, such as buffer = 0 for an algorithm that requires a buffer. In rare cases it might be useful to disable these controls. If wall.to.wall = FALSE controls are disabled and wall-to-wall outputs cannot be guaranteed. See opt_wall_to_wall

Chunk options

The slot ⁠@chunk_options⁠ contains a list of options that determine how chunks (the sub-areas that are sequentially processed) are made.

• chunk_size: numeric. The size of the chunks that will be sequentially processed. A small size allows small amounts of data to be loaded at once, saving computer memory. With big chunks the computation is usually faster but uses much more memory. If chunk_size = 0 the chunk pattern is build using the file pattern. The chunks are expecting to be wall-to-wall coverage, which means that chunk_size = 0 has meaning only if the files are not overlapping. Default is 0 i.e. by default the processing engine respects the existing tiling pattern. See opt_chunk_size.

• buffer: numeric. Each chunk can be read with an extra buffer around it to ensure there are no edge effects between two independent chunks and that the output is continuous. This is mandatory for some algorithms. Default is 30. See opt_chunk_buffer.

• alignment: numeric. A vector of size 2 (x and y coordinates, respectively) to align the chunk pattern. By default the alignment is made along (0,0), meaning that the edge of the first chunk will belong on x = 0 and y = 0 and all the the other chunks will be multiples of the chunk size. Not relevant if chunk_size = 0. See opt_chunk_alignment.

• drop: integers. A vector of integers that specify the IDs of the chunks that should not be created. This is designed to enable users to restart a computation that failed without reprocessing everything. See opt_restart<-. Technically, this option may be used for partial processing of a collection, but it generally should not be. Partial processing is already a feature of the engine. See this vignette

Output options

The slot ⁠@output_options⁠ contains a list of options that determine how chunks (the sub-areas that are sequentially processed) are written. By "written" we mean written to files or written in R memory.

• output_files: string. If output_files = "" outputs are returned in R. Otherwise, if output_files is a string the outputs will be written to files. This is useful if the output is too big to be returned in R. A path to a filename template without a file extension (the engine guesses it for you) is expected. When several files are going to be written a single string is provided with a template that is automatically filled. For example, the following file names are possible:

  "/home/user/als/normalized/file_{ID}_segmented"
  "C:/user/document/als/zone52_{XLEFT}_{YBOTTOM}_confidential"
  "C:/user/document/als/{ORIGINALFILNAME}_normalized"
  

  This option will generate as many filenames as needed with custom names for each file. The allowed templates are {XLEFT}, {XRIGHT}, {YBOTTOM}, {YTOP}, {ID}, {XCENTER}, {YCENTER}, {ORIGNALFILENAME}. See opt_output_files.

• drivers: list. This contains all the drivers required to seamlessly write ⁠Raster*⁠, SpatRaster, stars, ⁠Spatial*⁠, sf, and LAS objects. It is recommended that only advanced users change this option. A dedicated page describes the drivers in lidR-LAScatalog-drivers.

• merge: boolean. Multiple objects are merged into a single object at the end of the processing. See opt_merge.

Input options

The slot ⁠@input_options⁠ contains a list of options that are passed to the function readLAS. Indeed, the readLAS function is not called directly by the user but by the internal processing engine. Users can propagate these options through the LAScatalog settings.

• select: string. The option select. Usually this option is not respected because each function knows which data must be loaded or not. This is documented in each function. See opt_select.

• filter: string. The option filter. See opt_filter.

Examples

## Not run: 
# Build a catalog
ctg <- readLAScatalog("filder/to/las/files/", filter =  "-keep_first")


# Summary gives a summary of how the catalog will be processed
summary(ctg)

# We can seamlessly use lidR functions
hmean <- pixel_metrics(ctg, ~~mean(Z), 20)
ttops <- tree_detection(ctg, lmf(5))

# For low memory config it is probably advisable not to load entire files
# and process chunks instead
opt_chunk_size(ctg) <- 500

# Sometimes the output is likely to be very large
# e.g. large coverage and small resolution
dtm <- rasterize_terrain(ctg, 1, tin())

# In that case it is advisable to write the output(s) to files
opt_output_files(ctg) <- "path/to/folder/DTM_chunk_{XLEFT}_{YBOTTOM}"

# Raster will be written to disk. The list of written files is returned
# or, in this specific case, a virtual raster mosaic.
dtm <- rasterize_terrain(ctg, 1, tin())

# When chunks are files the original names of the las files can be preserved
opt_chunk_size(ctg) <- 0
opt_output_files(ctg) <- "path/to/folder/DTM_{ORIGINALFILENAME}"
dtm <- rasterize_terrain(ctg, 1, tin())

# For some functions, files MUST be written to disk. Indeed, it is certain that R cannot
# handle the entire output.
opt_chunk_size(ctg) <- 0
opt_output_files(ctg) <- "path/to/folder/{ORIGINALFILENAME}_norm"
opt_laz_compression(ctg) <- TRUE
new_ctg <- normalize_height(ctg, tin())

# The user has access to the catalog engine through the functions catalog_apply
# and catalog_map
output <- catalog_apply(ctg, FUN, ...)

## End(Not run)