--- title: "Voxelization" output: rmarkdown::html_vignette #output: rmarkdown::pdf_document vignette: > %\VignetteIndexEntry{Voxelization} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ![](rsc/amapvox-logo.png){width=256px} ```{r setup} library(AMAPVox) ``` In the *voxelization* process, AMAPvox tracks every laser pulse through a 3D grid (voxelized space) to the last recorded hit. Several estimators are implemented in order to calculate local transmittance, local attenuation and several other variables of interest. For details about the vozelization theoretical framework please refer to [A note on PAD/LAD estimators implemented in AMAPVox](https://doi.org/10.23708/1AJNMP) This vignette goes through all the parameters of the voxelization configuration. ## Semantics Every field has its own jargon, LiDAR is no exception. Throughout the documents we will use different terms: - a shot or a pulse refers to a single light pulse going out from the laser. A shot is defined by an origin, a direction, a time and zero, one or more hits. - a hit or and echo occurs when the light beam hits and obstacle and returns some light that is recorded by the laser. It is associated to a pulse and there may be no hit, a single hit or multiple hits. Be aware that absence of hit does not mean that there were no obstacle on the way: the light might have been diffracted or the laser failed to record the signal. We will refer to that situation as a "false empty shot". Conversely a hit may not always indicate that the light beam hit some vegetation (see section Butterfly remover for instance). - free path is the path from the shot origin to the hit. In a voxel, the free path refers to the path from the voxel entering point to the hit. - free path length is the length in meter of the free path - path length refers to the length of the path from the voxel entering point to the voxel exiting point, whether or not the pulse has been intercepted. ## LiDAR scans ### LAS/LAZ point cloud - [LAS](https://en.wikipedia.org/wiki/LAS_file_format) file format; - LAZ file format (compressed LAS); *LAS/LAZ* files can be manipulated by the [LAStools](http://lastools.org/) software or the [LidR](https://CRAN.R-project.org/package=lidR) R package. AMAPVox rebuilds shots geometry from LAS/LAZ point clouds. *Consistency checks*: AMAPVox can perform preliminary checks on the LAS/LAZ data, prior to the voxelization. First, it suggests to discard shots with inconsistent number of echoes or ranks. It check whether a subset of LAS points with same GPS time is consistent in terms of echo rank and number of echoes. Every LAS point of the subset should have a unique echo rank and the same number of echoes. Secondly, it may discard shots whose echoes are not collinear. The maximal deviation, user defined, is a tolerance in degree to strict collinearity. Theses checks are not mandatory but inconsistent shots will most likely lead to errors in the voxelization process. It is advised to enable them both in a first run just to make sure the point cloud is "clean" and then disable them since it is time consuming and pointless to perform the checks every time. ### Text SHOT format *SHT or SHOT format* is a text based format, one shot per line, a shot being defined by an origin, a direction, the number of echoes and the echo ranges. First row is header, columns are separated by space character. ``` xOrigin yOrigin zOrigin xDirection yDirection zDirection nbEchoes r1 r2 r3 r4 r5 r6 r7 c1 c2 c3 c4 c5 c6 c7 x0 y0 z0 xd yd zd 1 10 etc. ``` ### RIEGL scans - RiSCAN single scan, RXP file format. A proprietary binary file format owned by RIEGL. Can be edited with RiSCAN Pro software. - RiSCAN project, RSP file format. An aggregation of RXP scans in the same folder with an XML file project.xml that lists the file paths of the single scans, the SOP and POP matrix (see section Transformation for details on the transformation matrix) ### LEICA formats - PTX / PTG file formats from LEICA Geosystems. ### FARO formats - XYB from FARO ## Trajectory file (LAS/LAZ) For LAS and LAZ file, you need to provide either a fixed scanner position or a *trajectory file*. A trajectory file is a text based format that contains GPS positions of the scanner at a given time. Four columns are expected: - easting (x coordinate), - northing (y coordinate), - elevation (z-coordinate) - and time. Time of the trajectory file must be consistent with time of the LAS/LAZ file. Scanner positions must be expressed in the same coordinate system as the point cloud prior to any transformation (refer to section Transformation). AMAPVox will isolate points from the the LAS/LAZ point cloud with same GPS time (the hits from the same laser pulse), and calculates the scanner position with a linear interpolation of the trajectory points. Then AMAPVox can reconstruct the geometry of the pulse. The text based format is flexible: AMAPVox GUI provides a user interface to identify the columns, the separator, number of lines to skip, etc. Example: ``` "X" "Y" "Z" "T" 289109.129 586268.068 504.85 308500.003528 289108.973 586267.861 504.846 308500.008528 289108.816 586267.654 504.842 308500.013527 289108.659 586267.447 504.838 308500.018526 etc. ``` ## Digital Terrain Model input Digital Terrain Model is optional. If provided it will be used to compute distance to ground. Required if DTM filter (section Filter > DTM filter) or Ground energy output (section Output > Post-processing) are enabled. Expected format: [AAIGrid – Arc/Info ASCII Grid](https://gdal.org/drivers/raster/aaigrid.html#raster-aaigrid) No data values must be a numeric. ## Output parameters Set output folder, output format and output variables to be recorded. ## Transformation matrix A transformation matrix in AMAPVox is a 4x4 matrix that combines translation and rotation movements applied to 3D points (x, y, z). ### SOP matrix System Orientation and Position, TLS only. Each scan from Riscan Project has its own SOP matrix which is included in Riscan Pro project file. If a single scan (*.rxp) is selected, by clicking on the « Open file » button next to POP matrix you can choose the Riscan Pro project file and it will automatically configure the POP matrix and the SOP matrix of that scan. ### POP matrix Project Orientation and Position, TLS only Projection matrix of a Riscan Pro project, this is defined in the project file (*.rsp). That matrix is automatically filled when a Riscan Pro project file is open, being read in the file. Using single scan (*.rxp) voxelization, it is possible to defined POP matrix, either by opening a matrix file (see file formats in annexe), or by choosing a Riscan Pro project file. ### VOP matrix Voxel Orientation and Position. Optional transformation matrix. The final transformation matrix is the product of the three matrix. `transformation matrix = (VOP.POP).SOP` ## Voxel space Defines geographical extent and spatial resolution of the voxelized space. The geographical extent is a 3-dimensional rectangular cuboid, defined by (x, y, z) min and max coordinates. Spatial resolution is a (x, y, z) unitary vector giving the dimensions of a single voxel. A voxel is a rectangular cuboid and most commonly a cube. Voxel size is a critical parameter for estimating plant area density. It must be small enough so that the hypothesis of the vegetation being homogeneously distributed within the voxel holds true. But it must be large enough to include enough points to ensure reliable attenuation/PAD estimations. ## Filtering ### Digital Terrain Model filter Digital Terrain Model filter discards every point that are below a given distance to the ground (the Offset parameter in meter). Enabling this filter implies that a Digital Terrain Model has been provided in the Input section. ### Shot decimation Randomly downsample the scan by a float factor M ranging inside [0, 1[, the decimation factor. M = 0 means no shot discarded, M = 0.1 means 10% of the shots discarded, etc. ### Shot angle filter Filter shots based on shot Zenith angle (also called polar angle) in degrees, i.e angle between zenith (origin at the ground) and shot direction. ### False empty shot Riegl TLS scanners may include artifical empty shots for objects too close to the sensor (around 1m). This option allows to remove those "false" empty shots. ### Point cloud filter Discard or retain subset of points from the input point cloud for the voxelization. For instance it allows to extract a tree from a forest patch or remove the wood of a tree to estimate leaf area density instead of plant area density. The point cloud is provided as a text file with 3 columns x, y, z the coordinates of the points. ### Echo attribute filter For RIEGL scans only, filter echoes based on reflectance, amplitude or deviation values. ### Classification filter For LAS/LAZ only, filter echoes based on LAS classification. By default discard class "2 - Ground". ## Weighting For multi-echoes sans, the weighting table defines energy attenuation for every hit of a pulse. AMAPVox calculates the amount of light entering, intercepted and exiting the voxels to derive attenuation and plant area density estimators. A partial hit implies that some light is intercepted and some light carries on. This information is sometimes provided in the scans as the returned intensity, but we have not find yet an approach that works in every situation (work in progress). Providing a statistical model of energy attenuation as a function of the return rank is an other option, not straightforward though. [Vincent et al., 2017](https://doi.org/10.1016/j.rse.2017.05.034) and [Vincent et al., 2022](https://doi.org/10.1016/j.rse.2022.113442) discuss pros and cons of both approaches. As for now (2022), we consider that the best default option is to assume that the energy is evenly distributed among every hit of a pulse. Hence the suggested default weighting table with equal weights summing up to one for every pulse. The table remains editable for advanced users who would rather apply custom statistical model that fits better their data. No weighting table means that AMAPVox will only take into account the first return of a pulse. Exploratory approach "most intense return" has been implemented but not released. Fee free to request binaries for testing purpose. ## Scanner Either user predefined laser specifications or define custom specifications. Please contact us to include permanently your scanner specifications.