LiDAR Tools

• AsciiToLas
• ClassifyBuildingsInLidar
• ClassifyOverlapPoints
• ClipLidarToPolygon
• ErasePolygonFromLidar
• FilterLidarClasses
• FilterLidarScanAngles
• FindFlightlineEdgePoints
• FlightlineOverlap
• HeightAboveGround
• LasToAscii
• LasToMultipointShapefile
• LasToShapefile
• LasToZlidar
• LidarBlockMaximum
• LidarBlockMinimum
• LidarClassifySubset
• LidarColourize
• LidarDigitalSurfaceModel
• LidarElevationSlice
• LidarGroundPointFilter
• LidarHexBinning
• LidarHillshade
• LidarHistogram
• LidarIdwInterpolation
• LidarInfo
• LidarJoin
• LidarKappaIndex
• LidarNearestNeighbourGridding
• LidarPointDensity
• LidarPointStats
• LidarRansacPlanes
• LidarRbfInterpolation
• LidarRemoveDuplicates
• LidarRemoveOutliers
• LidarRooftopAnalysis
• LidarSegmentation
• LidarSegmentationBasedFilter
• LidarSibsonInterpolation
• LidarSortByTime
• LidarThin
• LidarThinHighDensity
• LidarTile
• LidarTileFootprint
• LidarTinGridding
• LidarTophatTransform
• NormalVectors
• SelectTilesByPolygon
• ZlidarToLas

AsciiToLas

This tool can be used to convert one or more ASCII files, containing LiDAR point data, into LAS files. The user must specify the name(s) of the input ASCII file(s) (--inputs). Each input file will have a correspondingly named output file with a .las file extension. The output point data, each on a separate line, will take the format:

x,y,z,intensity,class,return,num_returns"

The x, y, and z patterns must always be specified. If the rn pattern is used, the nr pattern must also be specified. Examples of valid pattern string include:

'x,y,z,i'
'x,y,z,i,rn,nr'
'x,y,z,i,c,rn,nr,sa'
'z,x,y,rn,nr'
'x,y,z,i,rn,nr,r,g,b'

Use the LasToAscii tool to convert a LAS file into a text file containing LiDAR point data.

See Also: LasToAscii

Parameters:

Python function:

wbt.ascii_to_las(
    inputs, 
    pattern, 
    proj=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AsciiToLas -v --wd="/path/to/data/" ^
-i="file1.las, file2.las, file3.las" -o=outfile.las" ^
--proj=2150 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/02/2019

Last Modified: 18/01/2020

ClassifyBuildingsInLidar

This tool can be used to assign the building class (classification value 6) to all points within an input LiDAR point cloud (--input) that are contained within the polygons of an input buildings footprint vector (--buildings). The tool performs a simple point-in-polygon operation to determine membership. The two inputs (i.e. the LAS file and vector) must share the same map projection. Furthermore, any error in the definition of the building footprints will result in misclassified points in the output LAS file (--output). In particular, if the footprints extend slightly beyond the actual building, ground points situated adjacent to the building will be incorrectly classified. Thus, care must be taken in digitizing building footprint polygons. Furthermore, where there are tall trees that overlap significantly with the building footprint, these vegetation points will also be incorrectly assigned the building class value.

See Also: FilterLidarClasses, LidarGroundPointFilter, ClipLidarToPolygon

Parameters:

Python function:

wbt.classify_buildings_in_lidar(
    i, 
    buildings, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ClassifyBuildingsInLidar -v ^
--wd="/path/to/data/" -i='data.las' --polygons='lakes.shp' ^
-o='output.las' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 17/11/2019

Last Modified: 17/11/2019

ClassifyOverlapPoints

Classifies or filters LAS points in regions of overlapping flight lines.

Parameters:

Python function:

wbt.classify_overlap_points(
    i, 
    output, 
    resolution=2.0, 
    filter=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ClassifyOverlapPoints -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.las ^
--resolution=2.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/04/2018

Last Modified: 18/10/2019

ClipLidarToPolygon

This tool can be used to isolate, or clip, all of the LiDAR points in a LAS file (--input) contained within one or more vector polygon features. The user must specify the name of the input clip file (--polygons), wich must be a vector of a Polygon base shape type. The clip file may contain multiple polygon features and polygon hole parts will be respected during clipping, i.e. LiDAR points within polygon holes will be removed from the output LAS file.

Use the ErasePolygonFromLidar tool to perform the complementary operation of removing points from a LAS file that are contained within a set of polygons.

See Also: ErasePolygonFromLidar, Clip, ClipRasterToPolygon

Parameters:

Python function:

wbt.clip_lidar_to_polygon(
    i, 
    polygons, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ClipLidarToPolygon -v ^
--wd="/path/to/data/" -i='data.las' --polygons='lakes.shp' ^
-o='output.las' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/04/2018

Last Modified: 26/07/2019

ErasePolygonFromLidar

This tool can be used to remove, or erase, all of the LiDAR points in a LAS file (--input) contained within one or more vector polygon features. The user must specify the name of the input clip file (--polygons), wich must be a vector of a Polygon base shape type. The clip file may contain multiple polygon features and polygon hole parts will be respected during clipping, i.e. LiDAR points within polygon holes will be remain in the output LAS file.

Use the ClipLidarToPolygon tool to perform the complementary operation of clipping (isolating) points from a LAS file that are contained within a set of polygons, while removing points that lie outside the input polygons.

See Also: ClipLidarToPolygon, Clip, ClipRasterToPolygon

Parameters:

Python function:

wbt.erase_polygon_from_lidar(
    i, 
    polygons, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ErasePolygonFromLidar -v ^
--wd="/path/to/data/" -i='data.las' --polygons='lakes.shp' ^
-o='output.las' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/04/2018

Last Modified: 12/10/2018

FilterLidarClasses

This tool can be used to remove points within a LAS LiDAR file that possess certain specified class values. The user must input the names of the input (--input) and output (--output) LAS files and the class values to be excluded (--exclude_cls). Class values are specified by their numerical values, such that:

Thus, to filter out low and high noise points from a point cloud, specify --exclude_cls='7,18'. Class ranges may also be specified, e.g. --exclude_cls='3-5,7,18'. Notice that usage of this tool assumes that the LAS file has underwent a comprehensive point classification, which not all point clouds have had. Use the LidarInfo tool determine the distribution of various class values in your file.

See Also: LidarInfo

Parameters:

Python function:

wbt.filter_lidar_classes(
    i, 
    output, 
    exclude_cls=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FilterLidarClasses -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--exclude_cls='7,18' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/07/2019

Last Modified: 16/01/2020

FilterLidarScanAngles

Removes points in a LAS file with scan angles greater than a threshold.

Parameters:

Python function:

wbt.filter_lidar_scan_angles(
    i, 
    output, 
    threshold, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FilterLidarScanAngles -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--threshold=10.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: September 17, 2017

Last Modified: 12/10/2018

FindFlightlineEdgePoints

Identifies points along a flightline's edge in a LAS file.

Parameters:

Python function:

wbt.find_flightline_edge_points(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FindFlightlineEdgePoints -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: June 14, 2017

Last Modified: 12/10/2018

FlightlineOverlap

Reads a LiDAR (LAS) point file and outputs a raster containing the number of overlapping flight lines in each grid cell.

Parameters:

Python function:

wbt.flightline_overlap(
    i=None, 
    output=None, 
    resolution=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FlightlineOverlap -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0"
./whitebox_tools -r=FlightlineOverlap -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=5.0 --palette=light_quant.plt 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/06/2017

Last Modified: 19/05/2020

HeightAboveGround

This tool normalizes an input LiDAR point cloud (--input) such that point z-values in the output LAS file (--output) are converted from elevations to heights above the ground, specifically the height above the nearest ground-classified point. The input LAS file must have ground-classified points, otherwise the tool will return an error. The LidarTophatTransform tool can be used to perform the normalization if a ground classification is lacking.

See Also: LidarTophatTransform

Parameters:

Python function:

wbt.height_above_ground(
    i=None, 
    output=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=HeightAboveGround -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/11/2019

Last Modified: 15/12/2019

LasToAscii

This tool can be used to convert one or more LAS file, containing LiDAR data, into ASCII files. The user must specify the name(s) of the input LAS file(s) (--inputs). Each input file will have a correspondingly named output file with a .csv file extension. CSV files are comma separated value files and contain tabular data with each column corresponding to a field in the table and each row a point value. Fields are separated by commas in the ASCII formated file. The output point data, each on a separate line, will take the format:

X,Y,Z,INTENSITY,CLASS,RETURN,NUM_RETURN,SCAN_ANGLE

If the LAS file has a point format that contains RGB data, the final three columns will contain the RED, GREEN, and BLUE values respectively. Use the AsciiToLas tool to convert a text file containing LiDAR point data into a LAS file.

See Also: AsciiToLas

Parameters:

Python function:

wbt.las_to_ascii(
    inputs, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LasToAscii -v --wd="/path/to/data/" ^
-i="file1.las, file2.las, file3.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/07/2017

Last Modified: 29/02/2020

LasToMultipointShapefile

Converts one or more LAS files into MultipointZ vector Shapefiles. When the input parameter is not specified, the tool grids all LAS files contained within the working directory.

This tool can be used in place of the LasToShapefile tool when the number of points are relatively high and when the desire is to represent the x,y,z position of points only. The z values of LAS points will be stored in the z-array of the output Shapefile. Notice that because the output file stores each point in a single multi-point record, this Shapefile representation, while unable to represent individual point classes, return numbers, etc, is an efficient means of converting LAS point positional information.

See Also: LasToShapefile

Parameters:

Python function:

wbt.las_to_multipoint_shapefile(
    i=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LasToMultipointShapefile -v ^
--wd="/path/to/data/" -i=input.las 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/09/2018

Last Modified: 19/05/2020

LasToShapefile

This tool converts one or more LAS files into a POINT vector. When the input parameter is not specified, the tool grids all LAS files contained within the working directory. The attribute table of the output Shapefile will contain fields for the z-value, intensity, point class, return number, and number of return.

This tool can be used in place of the LasToMultipointShapefile tool when the number of points are relatively low and when the desire is to represent more than simply the x,y,z position of points. Notice however that because each point in the input LAS file will be represented as a separate record in the output Shapefile, the output file will be many time larger than the equivalent output of the LasToMultipointShapefile tool. There is also a practical limit on the total number of records that can be held in a single Shapefile and large LAS files approach this limit. In these cases, the LasToMultipointShapefile tool should be preferred instead.

See Also: LasToMultipointShapefile

Parameters:

Python function:

wbt.las_to_shapefile(
    i=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LasToShapefile -v --wd="/path/to/data/" ^
-i=input.las 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/10/2018

Last Modified: 20/05/2020

LasToZlidar

This tool can be used to convert one or more LAS files into the zLidar compressed LiDAR data format. The tool takes a list of input LAS files (--inputs). If --inputs is unspecified, the tool will use all LAS files contained within the working directory as the tool inputs. The user may also specify an optional output directory --outdir. If this parameter is unspecified, each output zLidar file will be written to the same directory as the input files.

See Also: ZlidarToLas, LasToShapefile, LasToAscii

Parameters:

Python function:

wbt.las_to_zlidar(
    inputs=None, 
    outdir=None, 
    compress="brotli", 
    level=5, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LasToZlidar -v --wd="/path/to/data/" ^
-i="file1.las, file2.las, file3.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/05/2020

Last Modified: 15/05/2020

LidarBlockMaximum

Creates a block-maximum raster from an input LAS file. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory.

Parameters:

Python function:

wbt.lidar_block_maximum(
    i=None, 
    output=None, 
    resolution=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarBlockMaximum -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0"
./whitebox_tools -r=LidarBlockMaximum -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=5.0 --palette=light_quant.plt 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 19/05/2020

LidarBlockMinimum

Creates a block-minimum raster from an input LAS file. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory.

Parameters:

Python function:

wbt.lidar_block_minimum(
    i=None, 
    output=None, 
    resolution=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarBlockMinimum -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0"
./whitebox_tools -r=LidarBlockMinimum -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=5.0 --palette=light_quant.plt 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/07/2017

Last Modified: 19/05/2020

LidarClassifySubset

This tool classifies points within a user-specified LiDAR point cloud (--base) that correspond with points in a subset cloud (--subset). The subset point cloud may have been derived by filtering the original point cloud. The user must specify the names of the two input LAS files (i.e. the full and subset clouds) and the class value (--subset_class) to assign the matching points. This class value will be assigned to points in the base cloud, overwriting their input class values in the output LAS file (--output). Class values should be numerical (integer valued) and shoud follow the LAS specifications below:

The user may optionally specify a class value to be assigned to non-subset (i.e. non-matching) points (--nonsubset_class) in the base file. If this parameter is not specified, output non-sutset points will have the same class value as the base file.

Parameters:

Python function:

wbt.lidar_classify_subset(
    base, 
    subset, 
    output, 
    subset_class, 
    nonsubset_class=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarClassifySubset -v ^
--wd="/path/to/data/" --base="full_cloud.las" ^
--subset="filtered_cloud.las" -o="output.las" ^
--subset_class=2 

Source code on GitHub

Author: Dr. John Lindsay and Kevin Roberts

Created: 24/10/2018

Last Modified: 24/10/2018

LidarColourize

This tool can be used to add red-green-blue (RGB) colour values to the points contained within an input LAS file (--in_lidar), based on the pixel values of an input colour image (--in_image). Ideally, the image has been acquired at the same time as the LiDAR point cloud. If this is not the case, one may expect that transient objects (e.g. cars) in both input data sets will be incorrectly coloured. The input image should overlap in extent with the LiDAR data set. You may use the LidarTileFootprint tool to determine the spatial extent of the LAS file.

See Also: LidarTileFootprint

Parameters:

Python function:

wbt.lidar_colourize(
    in_lidar, 
    in_image, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarColourize -v --wd="/path/to/data/" ^
--in_lidar="input.las" --in_image="image.tif" ^
-o="output.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/02/2018

Last Modified: 12/10/2018

LidarDigitalSurfaceModel

This tool creates a digital surface model (DSM) from a LiDAR point cloud. A DSM reflects the elevation of the tops of all off-terrain objects (i.e. non-ground features) contained within the data set. For example, a DSM will model the canopy top as well as building roofs. This is in stark contrast to a bare-earth digital elevation model (DEM), which models the ground surface without off-terrain objects present. Bare-earth DEMs can be derived from LiDAR data by interpolating last-return points using one of the other LiDAR interpolators (e.g. LidarTINGridding). The algorithm used for interpolation in this tool is based on gridding a triangulation (TIN) fit to top-level points in the input LiDAR point cloud. All points in the input LiDAR data set that are below other neighbouring points, within a specified search radius (--radius), and that have a large inter-point slope, are filtered out. Thus, this tool will remove the ground surface beneath as well as any intermediate points within a forest canopy, leaving only the canopy top surface to be interpolated. Similarly, building wall points and any ground points beneath roof overhangs will also be remove prior to interpolation. Note that because the ground points beneath overhead wires and utility lines are filtered out by this operation, these features tend to be appear as 'walls' in the output DSM. If these points are classified in the input LiDAR file, you may wish to filter them out before using this tool (FilterLidarClasses).

The following images show the differences between creating a DSM using the LidarDigitalSurfaceModel and by interpolating first-return points only using the LidarTINGridding tool respectively. Note, the images show TimeInDaylight, which is a more effective way of hillshading DSMs than the traditional Hillshade method. Compare how the DSM created LidarDigitalSurfaceModel tool (above) has far less variability in areas of tree-cover, more effectively capturing the canopy top. As well, notice how building rooftops are more extensive and straighter in the LidarDigitalSurfaceModel DSM image. This is because this method eliminates ground returns beneath roof overhangs before the triangulation operation.

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, 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 interpolate a DSM for a large number of LiDAR files. Not only does this batch processing mode enable the tool to run in a more optimized parallel manner, but it will also allow the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file 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.

Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

Triangulation will generally completely fill the convex hull containing the input point data. This can sometimes result in very long and narrow triangles at the edges of the data or connecting vertices on either side of void areas. In LiDAR data, these void areas are often associated with larger waterbodies, and triangulation can result in very unnatural interpolated patterns within these areas. To avoid this problem, the user may specify a the maximum allowable triangle edge length (max_triangle_edge_length) and all grid cells within triangular facets with edges larger than this threshold are simply assigned the NoData values in the output DSM. These NoData areas can later be better dealt with using the FillMissingData tool after interpolation.

See Also: LidarTINGridding, FilterLidarClasses, FillMissingData, TimeInDaylight

Parameters:

Python function:

wbt.lidar_digital_surface_model(
    i=None, 
    output=None, 
    resolution=1.0, 
    radius=0.5, 
    minz=None, 
    maxz=None, 
    max_triangle_edge_length=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarDigitalSurfaceModel -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--returns=last --resolution=2.0 --exclude_cls='3,4,5,6,7,18' ^
--max_triangle_edge_length=5.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/08/2020

Last Modified: 16/08/2020

LidarElevationSlice

This tool can be used to either extract or classify the elevation values (z) of LiDAR points within a specified elevation range (slice). In addition to the names of the input and output LiDAR files (--input and --output), the user must specify the lower (--minz) and upper (--maxz) bounds of the elevation range. By default, the tool will only output points within the elevation slice, filtering out all points lying outside of this range. If the --class parameter is used, the tool will operate by assigning a class value (--inclassval) to the classification bit of points within the slice and another class value (--outclassval) to those points falling outside the range.

See Also: LidarRemoveOutliers, LidarClassifySubset

Parameters:

Python function:

wbt.lidar_elevation_slice(
    i, 
    output, 
    minz=None, 
    maxz=None, 
    cls=False, 
    inclassval=2, 
    outclassval=1, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarElevationSlice -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--minz=100.0 --maxz=250.0
>>./whitebox_tools ^
-r=LidarElevationSlice -v -i="/path/to/data/input.las" ^
-o="/path/to/data/output.las" --minz=100.0 --maxz=250.0 ^
--class
>>./whitebox_tools -r=LidarElevationSlice -v ^
-i="/path/to/data/input.las" -o="/path/to/data/output.las" ^
--minz=100.0 --maxz=250.0 --inclassval=1 --outclassval=0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/06/2017

Last Modified: 18/10/2019

LidarGroundPointFilter

This tool can be used to perform a slope-based classification, or filtering (i.e. removal), of non-ground points within a LiDAR point-cloud. The user must specify the name of the input and output LiDAR files (--input and --output). Inter-point slopes are compared between pair of points contained within local neighbourhoods of size --radius. Neighbourhoods with fewer than the user-specified minimum number of points (--min_neighbours) are extended until the minimum point number is equaled or exceeded. Points that are above neighbouring points by the minimum (--height_threshold) and have an inter-point slope greater than the user-specifed threshold (--slope_threshold) are considered non-ground points and are either optionally (--classify) excluded from the output point-cloud or assigned the unclassified (value 1) class value.

Slope-based ground-point classification methods suffer from the challenge of uses a constant slope threshold under varying terrain slopes. Some researchers have developed schemes for varying the slope threshold based on underlying terrain slopes. LidarGroundPointFilter instead allow the user to optionally (--slope_norm) normalize the underlying terrain (i.e. flatten the terrain) using a white top-hat transform. A constant slope threshold may then be used without contributing to poorer performance under steep topography. Note, that this option, while useful in rugged terrain, is computationally intensive. If the point-cloud is of a relatively flat terrain, this option may be excluded.

While this tool is appropriately applied to LiDAR point-clouds, the RemoveOffTerrainObjects tool can be used to remove off-terrain objects from rasterized LiDAR digital elevation models (DEMs).

Reference:

Vosselman, G. (2000). Slope based filtering of laser altimetry data. International Archives of Photogrammetry and Remote Sensing, 33(B3/2; PART 3), 935-942.

See Also: RemoveOffTerrainObjects

Parameters:

Python function:

wbt.lidar_ground_point_filter(
    i, 
    output, 
    radius=2.0, 
    min_neighbours=0, 
    slope_threshold=45.0, 
    height_threshold=1.0, 
    classify=True, 
    slope_norm=True, 
    height_above_ground=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarGroundPointFilter -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --min_neighbours=10 --slope_threshold=30.0 ^
--height_threshold=0.5 --classify --slope_norm 

Source code on GitHub

Author: Dr. John Lindsay

Created: 02/06/2017

Last Modified: 18/10/2019

LidarHexBinning

The practice of binning point data to form a type of 2D histogram, density plot, or what is sometimes called a heatmap, is quite useful as an alternative for the cartographic display of of very dense points sets. This is particularly the case when the points experience significant overlap at the displayed scale. The LidarPointDensity tool can be used to perform binning based on a regular grid (raster output). This tool, by comparison, bases the binning on a hexagonal grid.

The tool is similar to the CreateHexagonalVectorGrid tool, however instead will create an output hexagonal grid in which each hexagonal cell possesses a COUNT attribute which specifies the number of points from an input points file (LAS file) that are contained within the hexagonal cell. The tool will also calculate the minimum and maximum elevations and intensity values and outputs these data to the attribute table.

In addition to the names of the input points file and the output Shapefile, the user must also specify the desired hexagon width (w), which is the distance between opposing sides of each hexagon. The size (s) each side of the hexagon can then be calculated as, s = w / [2 x cos(PI / 6)]. The area of each hexagon (A) is, A = 3s(w / 2). The user must also specify the orientation of the grid with options of horizontal (pointy side up) and vertical (flat side up).

See Also: VectorHexBinning, LidarPointDensity, CreateHexagonalVectorGrid

Parameters:

Python function:

wbt.lidar_hex_binning(
    i, 
    output, 
    width, 
    orientation="horizontal", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarHexBinning -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.shp --width=10.0 ^
--orientation=vertical 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/09/2018

Last Modified: 12/10/2018

LidarHillshade

Calculates a hillshade value for points within a LAS file and stores these data in the RGB field.

Parameters:

Python function:

wbt.lidar_hillshade(
    i, 
    output, 
    azimuth=315.0, 
    altitude=30.0, 
    radius=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarHillshade -v --wd="/path/to/data/" ^
-i="input.las" -o="output.las" --radius=10.0
>>./whitebox_tools ^
-r=LidarHillshade -v --wd="/path/to/data/" -i="input.las" ^
-o="output.las" --azimuth=180.0 --altitude=20.0 --radius=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/06/2017

Last Modified: 22/10/2019

LidarHistogram

This tool can be used to plot a histogram of data derived from a LiDAR file. The user must specify the name of the input LAS file (--input), the name of the output HTML file (--output), the parameter (--parameter) to be plotted, and the amount (in percent) to clip the upper and lower tails of the f requency distribution (--clip). The LiDAR parameters that can be plotted using LidarHistogram include the point elevations, intensity values, scan angles, and class values.

Use the LidarPointStats tool instead to examine the spatial distribution of LiDAR points.

See Also: LidarPointStats

Parameters:

Python function:

wbt.lidar_histogram(
    i, 
    output, 
    parameter="elevation", 
    clip=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarHistogram -v --wd="/path/to/data/" ^
-i="file1.tif, file2.tif, file3.tif" -o=outfile.htm ^
--contiguity=Bishopsl 

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/12/2017

Last Modified: 12/10/2018

LidarIdwInterpolation

This tool interpolates LiDAR files using inverse-distance weighting (IDW) scheme. The user must specify the value of the IDW weight parameter (--weight). The output grid can be based on any of the stored LiDAR point parameters (--parameter), including elevation (in which case the output grid is a digital elevation model, DEM), intensity, class, return number, number of returns, scan angle, RGB (colour) values, and user data values. Similarly, the user may specify which point return values (--returns) to include in the interpolation, including all points, last returns (including single return points), and first returns (including single return points).

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, 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 interpolate a DEM for a large number of LiDAR files. Not only does this batch processing mode enable the tool to run in a more optimized parallel manner, but it will also allow the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file 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.

Users may excluded points from the interpolation based on point classification values, which follow the LAS classification scheme. Excluded classes are specified using the --exclude_cls parameter. For example, to exclude all vegetation and building classified points from the interpolation, use --exclude_cls='3,4,5,6'. Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

The tool will search for the nearest input LiDAR point to each grid cell centre, up to a maximum search distance (--radius). If a grid cell does not have a LiDAR point within this search distance, it will be assigned the NoData value in the output raster. In LiDAR data, these void areas are often associated with larger waterbodies. These NoData areas can later be better dealt with using the FillMissingData tool after interpolation.

See Also: LidarTINGridding, LidarNearestNeighbourGridding, LidarSibsonInterpolation

Parameters:

Python function:

wbt.lidar_idw_interpolation(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    weight=1.0, 
    radius=2.5, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarIdwInterpolation -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0 --radius=5.0"
./whitebox_tools ^
-r=LidarIdwInterpolation --wd="/path/to/data/" -i=file.las ^
-o=outfile.tif --resolution=5.0 --weight=2.0 --radius=2.0 ^
--exclude_cls='3,4,5,6,7,18' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 03/07/2017

Last Modified: 19/05/2020

LidarInfo

This tool can be used to print basic information about the data contained within a LAS file, used to store LiDAR data. The reported information will include including data on the header, point return frequency, and classification data and information about the variable length records (VLRs) and geokeys.

Parameters:

Python function:

wbt.lidar_info(
    i, 
    output=None, 
    vlr=True, 
    geokeys=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarInfo -v --wd="/path/to/data/" ^
-i=file.las --vlr --geokeys"
./whitebox_tools -r=LidarInfo ^
--wd="/path/to/data/" -i=file.las 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/06/2017

Last Modified: 18/10/2019

LidarJoin

This tool can be used to merge multiple LiDAR LAS files into a single output LAS file. Due to their large size, LiDAR data sets are often tiled into smaller, non-overlapping tiles. Sometimes it is more convenient to combine multiple tiles together for data processing and LidarJoin can be used for this purpose.

See Also: LidarTile

Parameters:

Python function:

wbt.lidar_join(
    inputs, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarJoin -v --wd="/path/to/data/" ^
-i="file1.las, file2.las, file3.las" -o=outfile.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/06/2017

Last Modified: 29/08/2018

LidarKappaIndex

This tool performs a kappa index of agreement (KIA) analysis on the classification values of two LiDAR (LAS) files. The output report HTML file should be displayed automatically but can also be displayed afterwards in any web browser. As a measure of overall classification accuracy, the KIA is more robust than the percent agreement calculation because it takes into account the agreement occurring by random chance. In addition to the KIA, the tool will output the producer's and user's accuracy, the overall accuracy, and the error matrix. The KIA is often used as a means of assessing the accuracy of an image classification analysis; however the LidarKappaIndex tool performs the analysis on a point-to-point basis, comparing the class values of the points in one input LAS file with the corresponding nearest points in the second input LAS file.

The user must also specify the name and resolution of an output raster file, which is used to show the spatial distribution of class accuracy. Each grid cell contains the overall accuracy, i.e. the points correctly classified divided by the total number of points contained within the cell, expressed as a percentage.

Parameters:

Python function:

wbt.lidar_kappa_index(
    input1, 
    input2, 
    output, 
    class_accuracy, 
    resolution=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarKappaIndex -v ^
--wd="/path/to/data/" --i1=class.las --i2=reference.las ^
-o=kia.html --class_accuracy=new_file.tif --resolution=0.5 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/09/2017

Last Modified: 04/01/2019

LidarNearestNeighbourGridding

This tool grids LiDAR files using nearest-neighbour (NN) scheme, that is, each grid cell in the output image will be assigned the parameter value of the point nearest the grid cell centre. This method should not be confused for the similarly named natural-neighbour interpolation (a.k.a Sibson's method). Nearest neighbour gridding is generally regarded as a poor way of interpolating surfaces from low-density point sets and results in the creation of a Voronoi diagram. However, this method has several advantages when applied to LiDAR data. NN gridding is one of the fastest methods for generating raster surfaces from large LiDAR data sets. NN gridding is one of the few interpolation methods, along with triangulation, that will preserve vertical breaks-in-slope, such as occur at the edges of building. This characteristic can be important when using some post-processing methods, such as the RemoveOffTerrainObjects tool. Furthermore, because most LiDAR data sets have remarkably high point densities compared with other types of geographic data, this approach does often produce a satisfactory result; this is particularly true when the point density is high enough that there are multiple points in the majority of grid cells.

The output grid can be based on any of the stored LiDAR point parameters (--parameter), including elevation (in which case the output grid is a digital elevation model, DEM), intensity, class, return number, number of returns, scan angle, RGB (colour) values, and user data values. Similarly, the user may specify which point return values (--returns) to include in the interpolation, including all points, last returns (including single return points), and first returns (including single return points).

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, 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 interpolate a DEM for a large number of LiDAR files. Not only does this batch processing mode enable the tool to run in a more optimized parallel manner, but it will also allow the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file 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.

Users may excluded points from the interpolation based on point classification values, which follow the LAS classification scheme. Excluded classes are specified using the --exclude_cls parameter. For example, to exclude all vegetation and building classified points from the interpolation, use --exclude_cls='3,4,5,6'. Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

The tool will search for the nearest input LiDAR point to each grid cell centre, up to a maximum search distance (--radius). If a grid cell does not have a LiDAR point within this search distance, it will be assigned the NoData value in the output raster. In LiDAR data, these void areas are often associated with larger waterbodies. These NoData areas can later be better dealt with using the FillMissingData tool after interpolation.

See Also: LidarTINGridding, LidarIdwInterpolation, LidarTINGridding, RemoveOffTerrainObjects, FillMissingData

Parameters:

Python function:

wbt.lidar_nearest_neighbour_gridding(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    radius=2.5, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarNearestNeighbourGridding -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--returns=last --resolution=2.0 --radius=5.0"
./whitebox_tools ^
-r=LidarNearestNeighbourGridding --wd="/path/to/data/" ^
-i=file.las -o=outfile.tif --resolution=5.0 --radius=2.0 ^
--exclude_cls='3,4,5,6,7,18' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/07/2017

Last Modified: 19/05/2020

LidarPointDensity

Calculates the spatial pattern of point density for a LiDAR data set. When the input/output parameters are not specified, the tool grids all LAS files contained within the working directory.

Parameters:

Python function:

wbt.lidar_point_density(
    i=None, 
    output=None, 
    returns="all", 
    resolution=1.0, 
    radius=2.5, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarPointDensity -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0 --radius=5.0"
./whitebox_tools ^
-r=LidarPointDensity -v --wd="/path/to/data/" -i=file.las ^
-o=outfile.tif --resolution=5.0 --radius=2.0 ^
--exclude_cls='3,4,5,6,7,18' --palette=light_quant.plt 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/07/2017

Last Modified: 19/05/2020

LidarPointStats

This tool creates several rasters summarizing the distribution of LiDAR points in a LAS data file. The user must specify the name of an input LAS file (--input) and the output raster grid resolution (--resolution). Additionally, the user must specify one or more of the possible output rasters to create using the various available flags, which include:

If no output raster flags are specified, all of the output rasters will be created. All output rasters will have the same base name as the input LAS file but will have a suffix that reflects the statistic type (e.g. _num_pnts, _num_pulses, _avg_points_per_pulse, etc.). Output files will be in the GeoTIFF (*.tif) file format.

When the input/output parameters are not specified, the tool works on all LAS files contained within the working directory.

Notes:

1. The num_pulses output is actually the number of pulses with at lease one return; specifically it is the sum of the early returns (first and only) in a grid cell. In areas of low reflectance, such as over water surfaces, the system may have emited a significantly higher pulse rate but far fewer returns are observed.
2. The memory requirement of this tool is high, particulalry if the grid resolution is fine and the spatial extent is large.

See Also: LidarBlockMinimum, LidarBlockMaximum

Parameters:

Python function:

wbt.lidar_point_stats(
    i=None, 
    resolution=1.0, 
    num_points=True, 
    num_pulses=False, 
    avg_points_per_pulse=True, 
    z_range=False, 
    intensity_range=False, 
    predom_class=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarPointStats -v ^
--wd="/path/to/data/" -i=file.las --resolution=1.0 ^
--num_points 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/02/2018

Last Modified: 20/05/2020

LidarRansacPlanes

This tool uses the random sample consensus (RANSAC) method to identify points within a LiDAR point cloud that belong to planar surfaces. RANSAC is a common method used in the field of computer vision to identify a subset of inlier points in a noisy data set containing abundant outlier points. Because LiDAR point clouds often contain vegetation points that do not form planar surfaces, this tool can be used to largely strip vegetation points from the point cloud, leaving behind the ground returns, buildings, and other points belonging to planar surfaces. If the --classify flag is used, non-planar points will not be removed but rather will be assigned a different class (1) than the planar points (0).

The algorithm selects a random sample, of a specified size (--num_samples) of the points from within the neighbourhood (--radius) surrounding each LiDAR point. The sample is then used to parameterize a planar best-fit model. The distance between each neighbouring point and the plane is then evaluated; inliers are those neighbouring points within a user-specified distance threshold (--threshold). Models with at least a minimum number of inlier points (--model_size) are then accepted. This process of selecting models is iterated a number of user-specified times (--num_iter).

One of the challenges with identifying planar surfaces in LiDAR point clouds is that these data are usually collected along scan lines. Therefore, each scan line can potentially yield a vertical planar surface, which is one reason that some vegetation points remain after applying the RANSAC plane-fitting method. To cope with this problem, the tool allows the user to specify a maximum planar slope (--max_slope) parameter. Planes that have slopes greater than this threshold are rejected by the algorithm. This has the side-effect of removing building walls however.

References:

Fischler MA and Bolles RC. 1981. Random sample consensus: a paradigm for model fitting with applications to image analysis and automated cartography. Commun. ACM, 24(6):381–395.

See Also: LidarSegmentation, LidarGroundPointFilter

Parameters:

Python function:

wbt.lidar_ransac_planes(
    i, 
    output, 
    radius=2.0, 
    num_iter=50, 
    num_samples=5, 
    threshold=0.35, 
    model_size=8, 
    max_slope=80.0, 
    classify=False, 
    last_returns=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarRansacPlanes -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --num_iter=10 --num_samples=5 --threshold=0.25 ^
--max_slope=70.0 --last_returns 

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/07/2019

Last Modified: 29/12/2019

LidarRbfInterpolation

Interpolates LAS files using a radial basis function (RBF) scheme. When the input/output parameters are not specified, the tool interpolates all LAS files contained within the working directory.

Parameters:

Python function:

wbt.lidar_rbf_interpolation(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    num_points=20, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    func_type="ThinPlateSpline", 
    poly_order="none", 
    weight=5, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarRbfInterpolation -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--resolution=2.0 --radius=5.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/11/2019

Last Modified: 19/05/2020

LidarRemoveDuplicates

This tool removes duplicate points from a LiDAR data set. Duplicates are determined by their x, y, and optionally (--include_z) z coordinates.

See Also: EliminateCoincidentPoints

Parameters:

Python function:

wbt.lidar_remove_duplicates(
    i, 
    output, 
    include_z=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarRemoveDuplicates -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/03/2018

Last Modified: 18/10/2019

LidarRemoveOutliers

This tool will filter out points from a LiDAR point cloud if the absolute elevation difference between a point and the averge elevation of its neighbourhood, calculated without the point, exceeds a threshold (elev_diff).

Parameters:

Python function:

wbt.lidar_remove_outliers(
    i, 
    output, 
    radius=2.0, 
    elev_diff=50.0, 
    use_median=False, 
    classify=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarRemoveOutliers -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --elev_diff=25.0 --use_median 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/02/2018

Last Modified: 18/10/2019

LidarRooftopAnalysis

This tool can be used to identify roof segments in a LiDAR point cloud.

See Also: ClassifyBuildingsInLidar, ClipLidarToPolygon

Parameters:

Python function:

wbt.lidar_rooftop_analysis(
    buildings, 
    output, 
    i=None, 
    radius=2.0, 
    num_iter=50, 
    num_samples=10, 
    threshold=0.15, 
    model_size=15, 
    max_slope=65.0, 
    norm_diff=10.0, 
    azimuth=180.0, 
    altitude=30.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarRooftopAnalysis -v ^
--wd="/path/to/data/" -i='data.las' --polygons='buildings.shp' ^
-o='rooftops.shp' --radius=10.0 --num_iter=10 --num_samples=5 ^
--threshold=0.25 --max_slope=70.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/06/2020

Last Modified: 10/06/2020

LidarSegmentation

This tool can be used to segment a LiDAR point cloud based on differences in the orientation of fitted planar surfaces and point proximity. The algorithm begins by attempting to fit planar surfaces to all of the points within a user-specified radius (--radius) of each point in the LiDAR data set. The planar equation is stored for each point for which a suitable planar model can be fit. A region-growing algorithm is then used to assign nearby points with similar planar models. Similarity is based on a maximum allowable angular difference (in degrees) between the two neighbouring points' plane normal vectors (--norm_diff). The --norm_diff parameter can therefore be thought of as a way of specifying the magnitude of edges mapped by the region-growing algorithm. By setting this value appropriately, it is possible to segment each facet of a building's roof. Segment edges for planar points may also be determined by a maximum allowable height difference (--maxzdiff) between neighbouring points on the same plane. Points for which no suitable planar model can be fit are assigned to 'volume' (non-planar) segments (e.g. vegetation points) using a region-growing method that connects neighbouring points based solely on proximity (i.e. all volume points within radius distance are considered to belong to the same segment).

The resulting point cloud will have both planar segments (largely ground surfaces and building roofs and walls) and volume segments (largely vegetation). Each segment is assigned a random red-green-blue (RGB) colour in the output LAS file. The largest segment in any airborne LiDAR dataset will usually belong to the ground surface. This largest segment will always be assigned a dark-green RGB of (25, 120, 0) by the tool.

This tool uses the random sample consensus (RANSAC) method to identify points within a LiDAR point cloud that belong to planar surfaces. RANSAC is a common method used in the field of computer vision to identify a subset of inlier points in a noisy data set containing abundant outlier points. Because LiDAR point clouds often contain vegetation points that do not form planar surfaces, this tool can be used to largely strip vegetation points from the point cloud, leaving behind the ground returns, buildings, and other points belonging to planar surfaces. If the --classify flag is used, non-planar points will not be removed but rather will be assigned a different class (1) than the planar points (0).

The algorithm selects a random sample, of a specified size (--num_samples) of the points from within the neighbourhood (--radius) surrounding each LiDAR point. The sample is then used to parameterize a planar best-fit model. The distance between each neighbouring point and the plane is then evaluated; inliers are those neighbouring points within a user-specified distance threshold (--threshold). Models with at least a minimum number of inlier points (--model_size) are then accepted. This process of selecting models is iterated a number of user-specified times (--num_iter).

One of the challenges with identifying planar surfaces in LiDAR point clouds is that these data are usually collected along scan lines. Therefore, each scan line can potentially yield a vertical planar surface, which is one reason that some vegetation points may be assigned to planes during the RANSAC plane-fitting method. To cope with this problem, the tool allows the user to specify a maximum planar slope (--max_slope) parameter. Planes that have slopes greater than this threshold are rejected by the algorithm. This has the side-effect of removing building walls however.

References:

Fischler MA and Bolles RC. 1981. Random sample consensus: a paradigm for model fitting with applications to image analysis and automated cartography. Commun. ACM, 24(6):381–395.

See Also: LidarRansacPlanes, LidarGroundPointFilter

Parameters:

Python function:

wbt.lidar_segmentation(
    i, 
    output, 
    radius=2.0, 
    num_iter=50, 
    num_samples=10, 
    threshold=0.15, 
    model_size=15, 
    max_slope=80.0, 
    norm_diff=10.0, 
    maxzdiff=1.0, 
    classes=False, 
    ground=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarSegmentation -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --num_iter=10 --num_samples=5 --threshold=0.25 ^
--max_slope=70.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/12/2017

Last Modified: 12/01/2020

LidarSegmentationBasedFilter

Identifies ground points within LiDAR point clouds using a segmentation based approach.

Parameters:

Python function:

wbt.lidar_segmentation_based_filter(
    i, 
    output, 
    radius=5.0, 
    norm_diff=2.0, 
    maxzdiff=1.0, 
    classify=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarSegmentationBasedFilter -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 --norm_diff=2.5 --maxzdiff=0.75 --classify 

Source code on GitHub

Author: Dr. John Lindsay

Created: 05/12/2017, 2017

Last Modified: 22/10/2019

LidarSibsonInterpolation

Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).

This tool interpolates LiDAR files using Sibson's interpolation method, sometimes referred to as natural-neighbour interpolation (not to be confused with nearest-neighbour interpolation, LidarNearestNeighbourGridding). Sibon's method is based on assigning weight to points for which inserting a grid point would result in captured areas of the Voronoi tessellation of the input point set. The larger the captured area, the higher the weight assigned to the associated point. One of the main advantages of this natural neighbour approach to interpolation over similar techniques, such as inverse-distance weighting (IDW LidarIdwInterpolation), is that there is no need to specify a search distance or other interpolation weighting parameters. Sibson's approach frequently provides a very suitable interpolation for LiDAR data. The method requires the calculation of a Delaunay triangulation, from which the Voronoi tessellation is calculated.

The user must specify the value of the IDW weight parameter (--weight). The output grid can be based on any of the stored LiDAR point parameters (--parameter), including elevation (in which case the output grid is a digital elevation model, DEM), intensity, class, return number, number of returns, scan angle values, and user data values. Similarly, the user may specify which point return values (--returns) to include in the interpolation, including all points, last returns (including single return points), and first returns (including single return points).

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, the tool will search for all valid LiDAR (*.las, *.laz, *.zlidar) files contained within the current working directory. This feature can be useful when you need to interpolate a DEM for a large number of LiDAR files. This batch processing mode enables the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file 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.

Users may excluded points from the interpolation based on point classification values, which follow the LAS classification scheme. Excluded classes are specified using the --exclude_cls parameter. For example, to exclude all vegetation and building classified points from the interpolation, use --exclude_cls='3,4,5,6'. Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

See Also: LidarTINGridding, LidarNearestNeighbourGridding, LidarIdwInterpolation

Parameters:

Python function:

wbt.lidar_sibson_interpolation(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    exclude_cls=None, 
    minz=None, 
    maxz=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LidarSibsonInterpolation -i=file.las ^
-o=outfile.tif -p='elevation' --returns='last' ^
--resolution=1.0 --exclude_cls='3,4,5,6,7,18' 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 12/04/2021

Last Modified: 12/04/2021

LidarSortByTime

Note this tool is part of a WhiteboxTools extension toolset. Please contact Whitebox Geospatial Inc. for information about purchasing a license activation key (https://www.whiteboxgeo.com).

This tool sorts the points in a LiDAR file by the GPS time. This can significantly improve LiDAR compression rates in the zLidar data format. Therefore, running LidarSortByTime can be a useful pre-cursor to running LasToZlidar when file size is the greatest concern.

See Also: LasToZlidar

Parameters:

Python function:

wbt.lidar_sort_by_time(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=LidarSortByTime -i=input.las ^
-o=output.las 

Source code is unavailable due to proprietary license.

Author: Whitebox Geospatial Inc. (c)

Created: 07/03/2021

Last Modified: 07/03/2021

LidarThin

Thins a LiDAR point cloud, reducing point density.

Parameters:

Python function:

wbt.lidar_thin(
    i, 
    output, 
    resolution=2.0, 
    method="lowest", 
    save_filtered=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarThin -v --wd="/path/to/data/" ^
-i=file.las -o=outfile.las --resolution=2.0, --method=first ^
--save_filtered 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/05/2018

Last Modified: 18/10/2019

LidarThinHighDensity

Thins points from high density areas within a LiDAR point cloud.

Parameters:

Python function:

wbt.lidar_thin_high_density(
    i, 
    output, 
    density, 
    resolution=1.0, 
    save_filtered=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarThinHighDensity -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--resolution=1.0 --density=100.0 --save_filtered 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/02/2018

Last Modified: 18/10/2019

LidarTile

This tool can be used to break a LiDAR LAS file into multiple, non-overlapping tiles, each saved as a single LAS file. The user must specify the parameter of the tile grid, including its origin (--origin_x and --origin_y) and the tile width and height (--width and --height). Tiles containing fewer points than specified in the --min_points parameter will not be output. This can be useful when tiling terrestrial LiDAR datasets because the low point density at the edges of the point cloud (i.e. most distant from the scan station) can result in poorly populated tiles containing relatively few points.

See Also: LidarJoin, LidarTileFootprint

Parameters:

Python function:

wbt.lidar_tile(
    i, 
    width=1000.0, 
    height=1000.0, 
    origin_x=0.0, 
    origin_y=0.0, 
    min_points=2, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarTile -v -i=/path/to/data/input.las ^
--width=1000.0 --height=2500.0 -=min_points=100 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 05/02/2019

LidarTileFootprint

This tool can be used to create a vector polygon of the bounding box or convex hull of a LiDAR point cloud (i.e. LAS file). If the user specified an input file (--input) and output file (--output), the tool will calculate the footprint, containing all of the data points, and output this feature to a vector polygon file. If the input and output parameters are left unspecified, the tool will calculate the footprint of every LAS file contained within the working directory and output these features to a single vector polygon file. If this is the desired mode of operation, it is important to specify the working directory (--wd) containing the group of LAS files; do not specify the optional --input and --output parameters in this case. Each polygon in the output vector will contain a LAS_NM field, specifying the source LAS file name, a NUM_PNTS field, containing the number of points within the source file, and Z_MIN and Z_MAX fields, containing the minimum and maximum elevations. This output can therefore be useful to create an index map of a large tiled LiDAR dataset.

By default, this tool identifies the axis-aligned minimum rectangular hull, or bounding box, containing the points in each of the input tiles. If the user specifies the --hull flag, the tool will identify the minimum convex hull instead of the bounding box. This option is considerably more computationally intensive and will be a far longer running operation if many tiles are specified as inputs.

A note on LAZ file inputs: While WhiteboxTools does not currently support the reading and writing of the compressed LiDAR format LAZ, it is able to read LAZ file headers. This tool, when run in in the bounding box mode (rather than the convex hull mode), is able to take LAZ input files.

LidarTile, LayerFootprint, MinimumBoundingBox, MinimumConvexHull

Parameters:

Python function:

wbt.lidar_tile_footprint(
    output, 
    i=None, 
    hull=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarTileFootprint -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 31/08/2018

Last Modified: 19/05/2020

LidarTinGridding

This tool creates a raster grid based on a Delaunay triangular irregular network (TIN) fitted to LiDAR points. The output grid can be based on any of the stored LiDAR point parameters (--parameter), including elevation (in which case the output grid is a digital elevation model, DEM), intensity, class, return number, number of returns, scan angle, RGB (colour) values, and user data values. Similarly, the user may specify which point return values (--returns) to include in the interpolation, including all points, last returns (including single return points), and first returns (including single return points).

The user must specify the grid resolution of the output raster (--resolution), and optionally, the name of the input LiDAR file (--input) and output raster (--output). Note that if an input LiDAR file (--input) is not specified by the user, 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 interpolate a DEM for a large number of LiDAR files. Not only does this batch processing mode enable the tool to run in a more optimized parallel manner, but it will also allow the tool to include a small buffer of points extending into adjacent tiles when interpolating an individual file. This can significantly reduce edge-effects when the output tiles are later mosaicked together. When run in this batch mode, the output file (--output) also need not be specified; the tool will instead create an output file 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.

Users may excluded points from the interpolation based on point classification values, which follow the LAS classification scheme. Excluded classes are specified using the --exclude_cls parameter. For example, to exclude all vegetation and building classified points from the interpolation, use --exclude_cls='3,4,5,6'. Users may also exclude points from the interpolation if they fall below or above the minimum (--minz) or maximum (--maxz) thresholds respectively. This can be a useful means of excluding anomalously high or low points. Note that points that are classified as low points (LAS class 7) or high noise (LAS class 18) are automatically excluded from the interpolation operation.

Triangulation will generally completely fill the convex hull containing the input point data. This can sometimes result in very long and narrow triangles at the edges of the data or connecting vertices on either side of void areas. In LiDAR data, these void areas are often associated with larger waterbodies, and triangulation can result in very unnatural interpolated patterns within these areas. To avoid this problem, the user may specify a the maximum allowable triangle edge length (max_triangle_edge_length) and all grid cells within triangular facets with edges larger than this threshold are simply assigned the NoData values in the output DSM. These NoData areas can later be better dealt with using the FillMissingData tool after interpolation.

See Also: LidarIdwInterpolation, LidarNearestNeighbourGridding, LidarTINGridding, FilterLidarClasses, FillMissingData

Parameters:

Python function:

wbt.lidar_tin_gridding(
    i=None, 
    output=None, 
    parameter="elevation", 
    returns="all", 
    resolution=1.0, 
    exclude_cls="7,18", 
    minz=None, 
    maxz=None, 
    max_triangle_edge_length=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarTINGridding -v ^
--wd="/path/to/data/" -i=file.las -o=outfile.tif ^
--returns=last --resolution=2.0 --exclude_cls='3,4,5,6,7,18' ^
--max_triangle_edge_length=5.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/09/2018

Last Modified: 25/05/2020

LidarTophatTransform

This tool performs a white top-hat transform on a LiDAR point cloud. A top-hat transform is a common digital image processing operation used for various tasks, such as feature extraction, background equalization, and image enhancement. When applied to a LiDAR point cloud, the white top-hat transform provides an estimate of height above ground, which is useful for modelling the vegetation canopy.

The white top-hat transform is defined as the difference between a point's original elevation and its opening. The opening operation can be thought of as the local neighbourhood maximum of a previous local minimum surface. The user must specify the size of the neighbourhood using the --radius parameter.

See Also: TophatTransform, Closing, Opening

Parameters:

Python function:

wbt.lidar_tophat_transform(
    i, 
    output, 
    radius=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LidarTophatTransform -v ^
--wd="/path/to/data/" -i="input.las" -o="output.las" ^
--radius=10.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/09/2017

Last Modified: 24/04/2019

NormalVectors

Calculates normal vectors for points within a LAS file and stores these data (XYZ vector components) in the RGB field.

Parameters:

Python function:

wbt.normal_vectors(
    i, 
    output, 
    radius=1.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NormalVectors -v --wd="/path/to/data/" ^
-i="input.las" -o="output.las" --radius=10.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/06/2017

Last Modified: 22/10/2019

SelectTilesByPolygon

This tool copies LiDAR tiles overlapping with a polygon into an output directory. In actuality, the tool performs point-in-polygon operations, using the four corner points, the center point, and the four mid-edge points of each LiDAR tile bounding box and the polygons. This representation of overlapping geometry aids with performance. This approach generally works well when the polygon size is large relative to the LiDAR tiles. If, however, the input polygon is small relative to the tile size, this approach may miss some copying some tiles. It is advisable to buffer the polygon if this occurs.

A note on LAZ file inputs: While WhiteboxTools does not currently support the reading and writing of the compressed LiDAR format LAZ, it is able to read LAZ file headers. Because this tool only requires information contained in the input file's header (i.e. the bounding box of the data), it is able to take LAZ input files.

See Also: LidarTileFootprint

Parameters:

Python function:

wbt.select_tiles_by_polygon(
    indir, 
    outdir, 
    polygons, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SelectTilesByPolygon -v ^
--indir='/path/to/lidar/' --outdir='/output/path/' ^
--polygons='watershed.shp' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/08/2018

Last Modified: 19/05/2020

ZlidarToLas

This tool can be used to convert one or more zLidar files ('*.zlidar') files into the LAS LiDAR data format. zLidar files are a compressed form of the LAS data format. The tool takes a list of input LAS files (--inputs). If --inputs is unspecified, the tool will use all ZLidar files contained within the working directory as the tool inputs. The user may also specify an optional output directory --outdir. If this parameter is unspecified, each output LAS file will be written to the same directory as the input files.

See Also: LasToZlidar, AsciiToLas

Parameters:

Python function:

wbt.zlidar_to_las(
    inputs=None, 
    outdir=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ZlidarToLas -v --wd="/path/to/data/" ^
-i="file1.zlidar, file2.zlidar, file3.zlidar" 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/05/2020

Last Modified: 13/05/2020