## License Information

Use of this function requires a license for Whitebox Workflows for Python Professional (WbW-Pro). Please visit www.whiteboxgeo.com to purchase a license.

## Description

This performs a quality control check on the return values of points in a LiDAR file. In particular, the tool will search for missing point returns, duplicate point returns, and points for which the return number (r) is larger than the encoded number of returns (n), all of which may be indicative of processing or encoding errors in the input file.

The user must specify the name of the input LiDAR file (`input`), and may optionally specify an output LiDAR file (`output`). If no output file is specified, only the text report is generated by the tool. If an output is specified, the tool will create an output LiDAR file for which missing returns are assigned class 13, duplicate returns are assigned class 14, points that are both, part of a missing series and are duplicate returns, are classed 15, and all other non-problemmatic points are assigned class 1. Note, those points designated as missing in the output image are clearly not so much missing as they are part of a sequence of points that contain missing returns. Missing points are apparent when the first point in a series does not have r = 1, when the last point does not have r = n, or the series is non-sequential (e.g. 1/3, 3/3, but no 2/3). This condition may occur because returns are split between tiles. However, when sequences with missing points are not located near the edges of tiles, it is usually an indication that either point filtering has taken place during pre-processing or that there is been some kind of processing or encoding error.

Duplicate points are defined as points that share the same time, scanner channel, r, and n. Note that these points may have different x, y, z coordinates. Duplicate points are always an indication of a processing or encoding error. For example, it may indicate that the scanner channel information from a multi-channel LiDAR sensor has not been encoded when creating the file or has been lost.

No point should have r > n. This always indicates some kind of processing or encoding error when it occurs.

The following is a sample output report generated by this tool:

`********* * Welcome to LidarPointReturnAnalysis *`

The Global Encoding for this file indicates that the point returns are not synthetic.

Missing Returns: 2441636 (16.336 percent) points are missing

| r | n | Missing Pts
1 | 2 | 1127770
2 | 2 | 817
1 | 3 | 823240
2 | 3 | 569
3 | 3 | 718
1 | 4 | 285695
2 | 4 | 142890
3 | 4 | 142
4 | 4 | 213
1 | 5 | 29772
2 | 5 | 19848
3 | 5 | 9928
4 | 5 | 18
5 | 5 | 16

Duplicate Returns: 4311021 (28.844 percent) points are duplicates

| r | n | Duplicates
1 | 1 | 2707083
1 | 2 | 332028
2 | 2 | 663717
1 | 3 | 70619
2 | 3 | 211834
3 | 3 | 282348
1 | 4 | 2856
2 | 4 | 8568
3 | 4 | 14280
4 | 4 | 17136
1 | 5 | 23
2 | 5 | 69
3 | 5 | 115
4 | 5 | 161
5 | 5 | 184

Return Greater Than Num. Returns: 0 (0.000 percent) points have r > n

Writing output LAS file... Complete! Elapsed Time (including I/O): 1.959s

## Function Signature

`def lidar_point_return_analysis(self, input: Lidar, create_output: bool = False) -> Optional[Lidar]: ...`

## Project Links

WbW Homepage User Manual Support WbW