R: Clip points in regions of interest

clip {lidR} | R Documentation

## Clip points in regions of interest

### Description

Clip points within a given region of interest (ROI) from a point cloud (`LAS` object) or a catalog (`LAScatalog` object). With a `LAS` object, the user first reads and loads a point cloud into memory and then can clip it to get a subset within a region of interest. With a `LAScatalog` object, the user can extract any arbitrary ROI for a set of `las/laz` files, loading only the points of interest. This is faster, easier and much more memory-efficient for extracting ROIs.

### Usage

    clip_roi(las, geometry, ...)

    clip_rectangle(las, xleft, ybottom, xright, ytop, ...)

    clip_polygon(las, xpoly, ypoly, ...)

    clip_circle(las, xcenter, ycenter, radius, ...)

    clip_transect(las, p1, p2, width, xz = FALSE, ...)

### Arguments

`las` | An object of class LAS or LAScatalog.
`geometry` | a geometric object. Many types are supported, see section 'supported geometries'.
`...` | in `clip_roi`: optional supplementary options (see supported geometries). Unused in other functions
`xleft` | numeric. left x coordinates of rectangles.
`ybottom` | numeric. bottom y coordinates of rectangles.
`xright` | numeric. right x coordinates of rectangles.
`ytop` | numeric. top y coordinates of rectangles.
`xpoly` | numeric. x coordinates of a polygon.
`ypoly` | numeric. y coordinates of a polygon.
`xcenter` | numeric. x coordinates of disc centers.
`ycenter` | numeric. y coordinates of disc centers.
`radius` | numeric. disc radius or radii.
`p1, p2` | numeric vectors of length 2 that gives the coordinates of two points that define a transect
`width` | numeric. width of the transect.
`xz` | bool. If `TRUE` the point cloud is reoriented to fit on XZ coordinates

### Value

If the input is a `LAS` object: an object of class `LAS`, or a `list` of `LAS` objects if the query implies several regions of interest will be returned.
If the input is a `LAScatalog` object: an object of class `LAS`, or a `list` of `LAS` objects if the query implies several regions of interest will be returned, or a `LAScatalog` if the queries are immediately written into files without loading anything in R.

### Supported geometries

- WKT string: describing a POINT, a POLYGON or a MULTIPOLYGON. If points, a parameter 'radius' must be passed in `...`

- Polygon, SpatialPolygons, SpatialPolygonsDataFrame, SpatialPoints or SpatialPointsDataFrame in that case a parameter 'radius' must be passed in `...`

- SimpleFeature from sf that consistently contains `POINT` or `POLYGON/MULTIPOLYGON`. In case of `POINT` a parameter 'radius' must be passed in `...`

- Extent from package `raster`

- bbox from package `sf`

- matrix 2 x 2 describing a bounding box following this order:

        min     max
      x 684816  684943
      y 5017823 5017957

### 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: Does not make sense here.

- buffer: Not supported yet.

- alignment: Does not makes sense here.

- progress: Displays a progress estimation.

- output_files: If 'output_files' is set in the catalog, the ROIs will not be returned in R. They will be written immediately in files. See LAScatalog-class and examples. The allowed templates in `clip_*` are `{XLEFT}, {XRIGHT}, {YBOTTOM}, {YTOP}, {ID}, {XCENTER}, {YCENTER}`. In addition `clip_roi` supports any names from the table of attributes of a spatial object given as input such as `{PLOTID}`, `{YEAR}`, `{SPECIES}`, for examples, if these attributes exist. If empty everything is returned into R.

- laz_compression: write `las` or `laz` files

- select: The function will write files equivalent to the originals. This option is not respected.

- filter: Read only the points of interest.

### Examples

    LASfile <- system.file("extdata", "Megaplot.laz", package="lidR")

    # Load the file and clip the region of interest
    las = readLAS(LASfile, select = "xyz", filter = "-keep_first")
    subset1 = clip_rectangle(las, 684850, 5017850, 684900, 5017900)

    # Do not load the file(s), extract only the region of interest
    # from a bigger dataset
    ctg = readLAScatalog(LASfile, progress = FALSE, filter = "-keep_first")
    subset2 = clip_rectangle(ctg, 684850, 5017850, 684900, 5017900)

    # Extract all the polygons from a shapefile
    f <- system.file("extdata", "lake_polygons_UTM17.shp", package = "lidR")
    lakes <- sf::st_read(f, quiet = TRUE)
    subset3 <- clip_roi(las, lakes)

    # Extract the polygons for a catalog, write them in files named
    # after the lake names, do not load anything in R
    opt_output_files(ctg) <- paste0(tempfile(), "_{LAKENAME_1}")
    new_ctg = clip_roi(ctg, lakes)
    plot(new_ctg)

    # Extract a transect
    p1 <- c(684800, y = 5017800)
    p2 <- c(684900, y = 5017900)
    tr1 <- clip_transect(las, p1, p2, width = 4)

    ## Not run:
    plot(subset1)
    plot(subset2)
    plot(subset3)

    plot(tr1, axis = TRUE, clear_artifacts = FALSE)

    ## End(Not run)

[Package lidR version 3.2.2 Index]