01_read.qmd

---
title: "Read/Plot/Query/Validate"
---

```{r, echo = FALSE, warnings = FALSE}
library(rgl)

r3dDefaults <- rgl::r3dDefaults
m <- structure(c(0.921, -0.146, 0.362, 0, 0.386, 0.482, -0.787, 0, 
                -0.06, 0.864, 0.5, 0, 0, 0, 0, 1), .Dim = c(4L, 4L))
r3dDefaults$FOV <- 50
r3dDefaults$userMatrix <- m
r3dDefaults$zoom <- 0.75

knitr::opts_chunk$set(
  comment =  "#>", 
  collapse = TRUE,
  fig.align = "center")

rgl::setupKnitr(autoprint = TRUE) 
options(lidR.progress = FALSE)
```

## Relevant Resources

[Code](https://github.com/tgoodbody/lidRtutorial/blob/main/code/tutorials/01_read.R)

[lidRbook section](https://r-lidar.github.io/lidRbook/index.htm)

## Overview

Welcome to this LiDAR data processing tutorial using R and the `lidR` library! In this tutorial, you will learn how to *read*, *visualize*, *query*, and *validate* LiDAR data.

We'll explore basic information like the *header* and *tabular data* and *visualize* point clouds using different color schemes based on attributes.

We'll use the `select` argument in `readLAS()` to load specific attributes and the `filter` argument to load only points of interest or apply transformations on-the-fly. We'll validate the LiDAR data using the `las_check` function on different LiDAR data files to ensure data integrity.

Let's get started with processing LiDAR data efficiently using `lidR` and R! Happy learning!

## Environment

We start by loading the necessary packages, clearing our current environment, and specifying that some warnings be turned off to make our outputs clearer. We will do this for each section in the tutorial.

```{r clear_warnings, warnings = FALSE, message = FALSE}
# Clear environment
rm(list = ls(globalenv()))

# Load packages
library(lidR)
library(sf)
```

## Basic Usage

### Load and Inspect LiDAR Data

Load the LiDAR point cloud data from a LAS file using the `readLAS()` function. The data is stored in the `las` object. We can inspect the header information and attributes of the `las` object.

```{r load_and_inspect_lidar_data}
las <- readLAS(files = "data/MixedEucaNat_normalized.laz")

# Inspect header information
las@header

# Inspect attributes of the point cloud
las@data

# Check the file size of the loaded LiDAR data
format(object.size(las), "Mb")
```

### Visualize LiDAR Data

We can visualize the LiDAR data using the `plot()` function. We have several options to control the colors in the plot, such as selecting specific attributes from the data to be used as colors.

::: callout-tip
## `lidR` plot background colour

Set the background of plots to white using `plot(las, bg = "white")`. To keep the code clean I've omitted it from examples.
:::

``` r
plot(las)
```

```{r visualize_lidar_data, echo = FALSE, rgl = TRUE, fig.width = 8, fig.height = 6}
# Visualize the LiDAR data with a default color palette
plot(las, bg = "white")
```

``` r
plot(las, color = "Intensity")
```

```{r visualize_lidar_data_int, echo = FALSE, rgl = TRUE, fig.width = 8, fig.height = 6}
# Visualize using intensity values as colors
plot(las, color = "Intensity", bg = "white")
```

``` r
plot(las, color = "Classification")
```

```{r visualize_lidar_data_class, echo = FALSE, rgl = TRUE, fig.width = 8, fig.height = 6}
# Visualize using the classification attribute as colors
plot(las, color = "Classification", bg = "white")
```

``` r
plot(las, color = "ScanAngleRank", axis = TRUE, legend = TRUE)
```

```{r visualize_lidar_data_scan, echo = FALSE, rgl = TRUE, fig.width = 8, fig.height = 6}
# Visualize using the scan angle rank as colors with an axis and legend
plot(las, color = "ScanAngleRank", axis = TRUE, legend = TRUE, bg = "white")
```

## Optimized Usage

### Selecting Attributes of Interest

The `readLAS()` function allows us to select specific attributes to be loaded into memory. This is useful to save memory when dealing with large LiDAR datasets.

```{r select_attributes}
# Load only the xyz coordinates (X, Y, Z) and ignore other attributes
las <- readLAS(files = "data/MixedEucaNat_normalized.laz", select = "xyz")

# Inspect the loaded attributes
las@data

# Check the memory size after loading only the selected attributes
format(object.size(las), "Mb")
```

### Filtering Points of Interest

We can also load only a subset of the LiDAR points based on certain criteria using the `filter` argument in `readLAS()`.

```{r filter_points}
# Load only the first return points
las <- readLAS(files = "data/MixedEucaNat_normalized.laz", filter = "-keep_first")

# Inspect the loaded points
las

# Check the memory size after loading only the filtered points
format(object.size(las), "Mb")
```

``` r
plot(las)
```

```{r visualize_lidar_data_filter, echo = FALSE, rgl = TRUE, fig.width = 8, fig.height = 6}
# Visualize the filtered points
plot(las, bg = "white")
```

### Applying Transformation on-the-fly

The `filter` argument in `readLAS()` can also be used to apply a transformation to the points on-the-fly during loading. This can be useful for tasks such as normalizing the point cloud heights.

```{r on_the_fly_transform}
# Load and visualize with an applied filter
las <- readLAS(files = "data/MixedEucaNat.laz", filter = "-keep_class 2")
```

``` r
plot(las)
```

```{r visualize_lidar_data_filter_class, echo = FALSE, rgl = TRUE, fig.width = 8, fig.height = 6}
plot(las, bg = "white")
```

### Filtering Points using `filter_poi()`

An alternative method for filtering points is using the `filter_poi()` function. This function allows filtering based on attributes of points.

```{r filter_poi_example}
# Filter points with Classification == 2
class_2 <- filter_poi(las = las, Classification == 2L)

# Combine queries to filter points with Classification == 1 and ReturnNumber == 1
first_ground <- filter_poi(las = las, Classification == 2L & ReturnNumber == 1L)
```

``` r
plot(class_2)
```

```{r class_2, echo = FALSE, rgl = TRUE, fig.width = 8, fig.height = 6}
plot(class_2, bg = "white")
```

``` r
plot(first_ground)
```

```{r first_ground, echo = FALSE, rgl = TRUE, fig.width = 8, fig.height = 6}
plot(first_ground, bg = "white")
```

### `LAS` Objects Validation

The `lidR` package provides a function `las_check()` to validate LAS objects for common issues.

```{r las_object_validation}
# Load and validate LAS data
las <- readLAS(files = "data/MixedEucaNat_normalized.laz")
las_check(las)

# Visualize corrupted LAS data
las <- readLAS(files = "data/example_corrupted.laz")
```

``` r
plot(las)
```

```{r corrupt, echo = FALSE, rgl = TRUE, fig.width = 8, fig.height = 6}
plot(las, bg = "white")
```

```{r validate_corrupted}
# Validate corrupted LAS data
las_check(las)
```

## Exercises and Questions

Using:

``` r
las <- readLAS(files = "data/MixedEucaNat_normalized.laz")
```

#### E1.

What are withheld points? Where are they in our point cloud?

#### E2.

Read the file dropping withheld points.

#### E3.

The withheld points seem to be legitimate points that we want to keep. Try to load the file including the withheld points but get rid of the warning (without using `suppressWarnings()`). Hint: Check available `-set_withheld` filters using `readLAS(filter = "-h")`.

#### E4.

Load only the ground points and plot the point cloud colored by the return number of the point. Do it loading the strict minimal amount of memory (4.7 Mb). Hint: use `?lidR::readLAS` and see what `select` options might help.

## Conclusion

This concludes our tutorial on the basic usage of the `lidR` package in R for processing and analyzing LiDAR data. We covered loading LiDAR data, inspecting and visualizing the data, selecting specific attributes, filtering points, and validating LAS objects for issues.