## 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 tool can be used to extract a subset of points from an input LiDAR point cloud (`input_lidar`) that correspond to a user-specified `percentile` of the points within the local neighbourhood. The algorithm works by overlaying a grid of a specified size (`block_size`). The group of LiDAR points contained within each block in the superimposed grid are identified and are sorted by elevation. The point with the elevation that corresponds most closely to the specified percentile is then inserted into the output LiDAR point cloud. For example, if `percentile = 0.0`, the lowest point within each block will be output, if `percentile = 100.0` the highest point will be output, and if `percentile = 50.0` the point that is nearest the median elevation will be output. Notice that the lower the number of points contained within a block, the more approximate the calculation will be. For example, if a block only contains three points, no single point occupies the 25th percentile. The equation that is used to identify the closest corresponding point (zero-based) from a list of `n` sorted by elevation values is:

`point_num = ⌊percentile / 100.0 * (n - 1)⌉`

Increasing the block size (default is 1.0 xy-units) will increase the average number of points within blocks, allowing for a more accurate percentile calculation.

Like many of the LiDAR functions, the input LiDAR point cloud (`input_lidar`) is optional. If an input LiDAR file is not specified, the tool will search for all valid LiDAR (.las, .laz, *.zlidar) files contained within the current working directory. This feature can be very useful when you need to process a large number of LiDAR files contained within a directory. This batch processing mode enables the function to run in a more optimized parallel manner. When run in this batch mode, no output LiDAR object will be created. Instead the function will create an output file (saved to disc) with the same name as each input LiDAR file, but with the .tif extension. This can provide a very efficient means for processing extremely large LiDAR data sets.

## See Also

filter_lidar, lidar_block_minimum, lidar_block_maximum

## Function Signature

`def filter_lidar_by_percentile(self, input_lidar: Optional[Lidar], percentile: float = 0.0, block_size: float = 1.0) -> Optional[Lidar]: ...`

## Project Links

WbW Homepage User Manual Support WbW