GIS Analysis

• AggregateRaster
• BlockMaximumGridding
• BlockMinimumGridding
• Centroid
• CentroidVector
• Clump
• ConstructVectorTin
• CreateHexagonalVectorGrid
• CreatePlane
• CreateRectangularVectorGrid
• Dissolve
• EliminateCoincidentPoints
• ExtendVectorLines
• ExtractNodes
• ExtractRasterValuesAtPoints
• FilterRasterFeaturesByArea
• FindLowestOrHighestPoints
• IdwInterpolation
• LayerFootprint
• Medoid
• MinimumBoundingBox
• MinimumBoundingCircle
• MinimumBoundingEnvelope
• MinimumConvexHull
• NaturalNeighbourInterpolation
• NearestNeighbourGridding
• PolygonArea
• PolygonLongAxis
• PolygonPerimeter
• PolygonShortAxis
• RadialBasisFunctionInterpolation
• RasterArea
• RasterCellAssignment
• RasterPerimeter
• Reclass
• ReclassEqualInterval
• ReclassFromFile
• SmoothVectors
• SplitVectorLines
• TinGridding
• VectorHexBinning
• VoronoiDiagram

AggregateRaster

This tool can be used to reduce the grid resolution of a raster by a user specified amount. For example, using an aggregation factor (--agg_factor) of 2 would result in a raster with half the number of rows and columns. The grid cell values (--type) in the output image will consist of the mean, sum, maximum, minimum, or range of the overlapping grid cells in the input raster (four cells in the case of an aggregation factor of 2).

See Also: Resample

Parameters:

Python function:

wbt.aggregate_raster(
    i, 
    output, 
    agg_factor=2, 
    type="mean", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AggregateRaster -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif ^
--output_text 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/12/2017

Last Modified: 20/01/2019

BlockMaximumGridding

Creates a raster grid based on a set of vector points and assigns grid values using a block maximum scheme.

Parameters:

Python function:

wbt.block_maximum_gridding(
    i, 
    field, 
    output, 
    use_z=False, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BlockMaximumGridding -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--cell_size=1.0
>>./whitebox_tools -r=BlockMaximumGridding -v ^
--wd="/path/to/data/" -i=points.shp --use_z -o=output.tif ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/10/2018

Last Modified: 09/12/2019

BlockMinimumGridding

Creates a raster grid based on a set of vector points and assigns grid values using a block minimum scheme.

Parameters:

Python function:

wbt.block_minimum_gridding(
    i, 
    field, 
    output, 
    use_z=False, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=BlockMinimumGridding -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--cell_size=1.0
>>./whitebox_tools -r=BlockMinimumGridding -v ^
--wd="/path/to/data/" -i=points.shp --use_z -o=output.tif ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/10/2018

Last Modified: 09/12/2019

Centroid

This tool calculates the centroid, or average location, of raster polygon objects. For vector features, use the CentroidVector tool instead.

See Also: CentroidVector

Parameters:

Python function:

wbt.centroid(
    i, 
    output, 
    text_output=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Centroid -v --wd="/path/to/data/" ^
-i=polygons.tif -o=output.tif
>>./whitebox_tools -r=Centroid ^
-v --wd="/path/to/data/" -i=polygons.tif -o=output.tif ^
--text_output 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/07/2017

Last Modified: 18/10/2019

CentroidVector

This can be used to identify the centroid point of a vector polyline or polygon feature or a group of vector points. The output is a vector shapefile of points. For multi-part polyline or polygon features, the user can optionally specify whether to identify the centroid of each part. The default is to treat multi-part features a single entity.

For raster features, use the Centroid tool instead.

See Also: Centroid, Medoid

Parameters:

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=CentroidVector -v --wd="/path/to/data/" ^
-i=in_file.shp -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 20/09/2018

Last Modified: 24/07/2020

Clump

This tool re-categorizes data in a raster image by grouping cells that form discrete, contiguous areas into unique categories. Essentially this will produce a patch map from an input categorical raster, assigning each feature unique identifiers. The input raster should either be Boolean (1's and 0's) or categorical. The input raster could be created using the Reclass tool or one of the comparison operators (GreaterThan, LessThan, EqualTo, NotEqualTo). Use the treat zeros as background cells options (--zero_back) if you would like to only assigned contiguous groups of non-zero values in the raster unique identifiers. Additionally, inter-cell connectivity can optionally include diagonally neighbouring cells if the --diag flag is specified.

See Also: Reclass, GreaterThan, LessThan, EqualTo, NotEqualTo

Parameters:

Python function:

wbt.clump(
    i, 
    output, 
    diag=True, 
    zero_back=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Clump -v --wd="/path/to/data/" ^
-i=input.tif -o=output.tif --diag 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 18/10/2019

ConstructVectorTin

This tool creates a vector triangular irregular network (TIN) for a set of vector points (--input) using a 2D Delaunay triangulation algorithm. TIN vertex heights can be assigned based on either a field in the vector's attribute table (--field), or alternatively, if the vector is of a z-dimension ShapeTypeDimension, the point z-values may be used for vertex heights (--use_z). For LiDAR points, use the LidarConstructVectorTIN tool instead.

Triangulation often creates very long, narrow triangles near the edges of the data coverage, particularly in convex regions along the data boundary. To avoid these spurious triangles, the user may optionally specify the maximum allowable edge length of a triangular facet (--max_triangle_edge_length).

See Also: LidarConstructVectorTIN

Parameters:

Python function:

wbt.construct_vector_tin(
    i, 
    output, 
    field=None, 
    use_z=False, 
    max_triangle_edge_length=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ConstructVectorTIN -v ^
--wd="/path/to/data/" -i=points.shp --field=HEIGHT ^
-o=tin.shp
>>./whitebox_tools -r=ConstructVectorTIN -v ^
--wd="/path/to/data/" -i=points.shp --use_z -o=tin.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 21/09/2018

Last Modified: 07/12/2019

CreateHexagonalVectorGrid

This tool can be used to create a hexagonal vector grid. The extent of the hexagonal grid is based on the extent of a user-specified base file (any supported raster format, shapefiles, or LAS files). The user must also specify the hexagonal cell width (--width) and whether the hexagonal orientation (--orientation) is horizontal or vertical.

See Also: CreateRectangularVectorGrid

Parameters:

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/09/2018

Last Modified: 19/05/2020

CreatePlane

This tool can be used to create a new raster with values that are determined by the equation of a simple plane. The user must specify the name of a base raster (--base) from which the output raster coordinate and dimensional information will be taken. In addition the user must specify the values of the planar slope gradient (S; --gradient; --aspect) in degrees, the planar slope direction or aspect (A; 0 to 360 degrees), and an constant value (k; --constant). The equation of the plane is as follows:

Z = tan(S) × sin(A - 180) × X + tan(S) × cos(A - 180) × Y + k

where X and Y are the X and Y coordinates of each grid cell in the grid. Notice that A is the direction, or azimuth, that the plane is facing

Parameters:

Python function:

wbt.create_plane(
    base, 
    output, 
    gradient=15.0, 
    aspect=90.0, 
    constant=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CreatePlane -v --wd="/path/to/data/" ^
--base=base.tif -o=NewRaster.tif --gradient=15.0 ^
--aspect=315.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 30/01/2020

CreateRectangularVectorGrid

This tool can be used to create a rectangular vector grid. The extent of the rectangular grid is based on the extent of a user-specified base file (any supported raster format, shapefiles, or LAS files). The user must also specify the origin of the grid (--xorig and --yorig) and the grid cell width and height (--width and --height).

See Also: CreateHexagonalVectorGrid

Parameters:

Python function:

wbt.create_rectangular_vector_grid(
    i, 
    output, 
    width, 
    height, 
    xorig=0, 
    yorig=0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CreateRectangularVectorGrid -v ^
--wd="/path/to/data/" -i=file.shp -o=outfile.shp --width=10.0 ^
--height=10.0 --xorig=0.0 --yorig=0.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/09/2018

Last Modified: 19/05/2020

Dissolve

This tool can be used to remove the interior, or shared, boundaries within a vector polygon coverage. You can either dissolve all interior boundaries or dissolve those boundaries along polygons with the same value of a user-specified attribute within the vector's attribute table. It may be desirable to use the VectorCleaning tool to correct any topological errors resulting from the slight misalignment of nodes along shared boundaries in the vector coverage before performing the Dissolve operation.

See Also: Clip, Erase, Polygonize

Parameters:

Python function:

wbt.dissolve(
    i, 
    output, 
    field=None, 
    snap=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Dissolve -v --wd="/path/to/data/" ^
-input=layer1.shp --field=SIZE -o=out_file.shp ^
--snap=0.0000001 

Source code on GitHub

Author: Dr. John Lindsay

Created: 13/11/2018

Last Modified: 22/11/2018

EliminateCoincidentPoints

This tool can be used to remove any coincident, or nearly coincident, points from a vector points file. The user must specify the name of the input file, which must be of a POINTS ShapeType, the output file name, and the tolerance distance. All points that are within the specified tolerance distance will be eliminated from the output file. A tolerance distance of 0.0 indicates that points must be exactly coincident to be removed.

See Also: LidarRemoveDuplicates

Parameters:

Python function:

wbt.eliminate_coincident_points(
    i, 
    output, 
    tolerance, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=EliminateCoincidentPoints -v ^
--wd="/path/to/data/" -i=input_file.shp -o=out_file.shp ^
--tolerance=0.01 

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/09/2018

Last Modified: 13/10/2018

ExtendVectorLines

This tool can be used to extend vector lines by a specified distance. The user must input the names of the input and output shapefiles, the distance to extend features by, and whether to extend both ends, line starts, or line ends. The input shapefile must be of a POLYLINE base shape type and should be in a projected coordinate system.

Parameters:

Python function:

wbt.extend_vector_lines(
    i, 
    output, 
    dist, 
    extend="both ends", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ExtendVectorLines -v ^
--wd="/path/to/data/" -i=in_file.shp -o=out_file.shp ^
--dist=10.0 --extend='both ends' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 20/09/2018

Last Modified: 13/10/2018

ExtractNodes

This tool converts vector lines or polygons into vertex points. The user must specify the name of the input vector, which must be of a polyline or polygon base shape type, and the name of the output point-type vector.

Parameters:

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/09/2018

Last Modified: 13/10/2018

ExtractRasterValuesAtPoints

This tool can be used to extract the values of one or more rasters (--inputs) at the sites of a set of vector points. By default, the data is output to the attribute table of the input points (--points) vector; however, if the --out_text parameter is specified, the tool will additionally output point values as text data to standard output (stdout). Attribute fields will be added to the table of the points file, with field names, VALUE1, VALUE2, VALUE3, etc. each corresponding to the order of input rasters.

If you need to plot a chart of values from a raster stack at a set of points, the ImageStackProfile may be more suitable for this application.

See Also: ImageStackProfile, FindLowestOrHighestPoints

Parameters:

Python function:

wbt.extract_raster_values_at_points(
    inputs, 
    points, 
    out_text=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ExtractRasterValuesAtPoints -v ^
--wd="/path/to/data/" -i='image1.tif;image2.tif;image3.tif' ^
-points=points.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 17/06/2018

Last Modified: 18/10/2019

FilterRasterFeaturesByArea

This tool takes an input raster (--input) containing integer-labelled features, such as the output of the Clump tool, and removes all features that are smaller than a user-specified size (--threshold), measured in grid cells. The user must specify the replacement value for removed features using the --background parameter, which can be either zero or nodata.

See Also: Clump

Parameters:

Python function:

wbt.filter_raster_features_by_area(
    i, 
    output, 
    threshold, 
    background="zero", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FilterRasterFeaturesByArea -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif ^
--background=zero 

Source code on GitHub

Author: Dr. John Lindsay

Created: 22/06/2017

Last Modified: 18/10/2019

FindLowestOrHighestPoints

This tool locates the lowest and/or highest cells in a raster and outputs these locations to a vector points file. The user must specify the name of the input raster (--input) and the name of the output vector file (--output). The user also has the option (--out_type) to locate either the lowest value, highest value, or both values. The output vector's attribute table will contain fields for the points XY coordinates and their values.

See Also: ExtractRasterValuesAtPoints

Parameters:

Python function:

wbt.find_lowest_or_highest_points(
    i, 
    output, 
    out_type="lowest", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=FindLowestOrHighestPoints -v ^
--wd="/path/to/data/" --input=DEM.tif -o=out.shp ^
--out_type=highest 

Source code on GitHub

Author: Dr. John Lindsay

Created: 12/06/2018

Last Modified: 13/10/2018

IdwInterpolation

points or a fixed neighbourhood size. This tool is currently configured to perform the later only, using a FixedRadiusSearch structure. Using a fixed number of neighbours will require use of a KD-tree structure. I've been testing one Rust KD-tree library but its performance does not appear to be satisfactory compared to the FixedRadiusSearch. I will need to explore other options here.

Another change that will need to be implemented is the use of a nodal function. The original Whitebox GAT tool allows for use of a constant or a quadratic. This tool only allows the former. This tool interpolates vector points into a raster surface using an inverse-distance weighted scheme.

Parameters:

Python function:

wbt.idw_interpolation(
    i, 
    field, 
    output, 
    use_z=False, 
    weight=2.0, 
    radius=None, 
    min_points=None, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=IdwInterpolation -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--weight=2.0 --radius=4.0 --min_points=3 ^
--cell_size=1.0
>>./whitebox_tools -r=IdwInterpolation -v ^
--wd="/path/to/data/" -i=points.shp --use_z -o=output.tif ^
--weight=2.0 --radius=4.0 --min_points=3 ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/05/2018

Last Modified: 9/12/2019

LayerFootprint

This tool creates a vector polygon footprint of the area covered by a raster grid or vector layer. It will create a vector rectangle corresponding to the bounding box. The user must specify the name of the input file, which may be either a Whitebox raster or a vector, and the name of the output file.

If an input raster grid is specified which has an irregular shape, i.e. it contains NoData values at the edges, the resulting vector will still correspond to the full grid extent, ignoring the irregular boundary. If this is not the desired effect, you should reclass the grid such that all cells containing valid values are assigned some positive, non-zero value, and then use the RasterToVectorPolygons tool to vectorize the irregular-shaped extent boundary.

See Also: MinimumBoundingEnvelope, RasterToVectorPolygons

Parameters:

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 31/09/2018

Last Modified: 13/10/2018

Medoid

This tool calculates the medoid for a series of vector features contained in a shapefile. The medoid of a two-dimensional feature is conceptually similar its centroid, or mean position, but the medoid is always a members of the input feature data set. Thus, the medoid is a measure of central tendency that is robust in the presence of outliers. If the input vector is of a POLYLINE or POLYGON ShapeType, the nodes of each feature will be used to estimate the feature medoid. If the input vector is of a POINT base ShapeType, the medoid will be calculated for the collection of points. While there are more than one competing method of calculating the medoid, this tool uses an algorithm that works as follows:

1. The x-coordinate and y-coordinate of each point/node are placed into two arrays.
2. The x- and y-coordinate arrays are then sorted and the median x-coordinate (Med X) and median y-coordinate (Med Y) are calculated.
3. The point/node in the dataset that is nearest the point (Med X, Med Y) is identified as the medoid.

See Also: CentroidVector

Parameters:

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=Medoid -v --wd="/path/to/data/" ^
-i=in_file.shp -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 20/09/2018

Last Modified: 24/07/2020

MinimumBoundingBox

This tool delineates the minimum bounding box (MBB) for a group of vectors. The MBB is the smallest box to completely enclose a feature. The algorithm works by rotating the feature, calculating the axis-aligned bounding box for each rotation, and finding the box with the smallest area, length, width, or perimeter. The MBB is needed to compute several shape indices, such as the Elongation Ratio. The MinimumBoundingEnvelop tool can be used to calculate the axis-aligned bounding rectangle around each feature in a vector file.

See Also: MinimumBoundingCircle, MinimumBoundingEnvelope, MinimumConvexHull

Parameters:

Python function:

wbt.minimum_bounding_box(
    i, 
    output, 
    criterion="area", 
    features=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MinimumBoundingBox -v ^
--wd="/path/to/data/" -i=file.shp -o=outfile.shp ^
--criterion=length --features 

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/09/2018

Last Modified: 18/10/2019

MinimumBoundingCircle

This tool delineates the minimum bounding circle (MBC) for a group of vectors. The MBC is the smallest enclosing circle to completely enclose a feature.

See Also: MinimumBoundingBox, MinimumBoundingEnvelope, MinimumConvexHull

Parameters:

Python function:

wbt.minimum_bounding_circle(
    i, 
    output, 
    features=True, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/09/2018

Last Modified: 18/10/2019

MinimumBoundingEnvelope

This tool delineates the minimum bounding axis-aligned box for a group of vector features. The is the smallest rectangle to completely enclose a feature, in which the sides of the envelope are aligned with the x and y axis of the coordinate system. The MinimumBoundingBox can be used instead to find the smallest possible non-axis aligned rectangular envelope.

See Also: MinimumBoundingBox, MinimumBoundingCircle, MinimumConvexHull

Parameters:

Python function:

wbt.minimum_bounding_envelope(
    i, 
    output, 
    features=True, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 31/09/2018

Last Modified: 18/10/2019

MinimumConvexHull

This tool creates a vector convex polygon around vector features. The convex hull is a convex closure of a set of points or polygon verticies and can be may be conceptualized as the shape enclosed by a rubber band stretched around the point set. The convex hull has many applications and is most notably used in various shape indices. The Delaunay triangulation of a point set and its dual, the Voronoi diagram, are mathematically related to convex hulls.

See Also: MinimumBoundingBox, MinimumBoundingCircle, MinimumBoundingEnvelope

Parameters:

Python function:

wbt.minimum_convex_hull(
    i, 
    output, 
    features=True, 
    callback=default_callback
)

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 03/09/2018

Last Modified: 18/10/2019

NaturalNeighbourInterpolation

This tool can be used to interpolate a set of input vector points (--input) onto a raster grid using Sibson's (1981) natural neighbour method. Similar to inverse-distance-weight interpolation (IdwInterpolation), the natural neighbour method performs a weighted averaging of nearby point values to estimate the attribute (--field) value at grid cell intersections in the output raster (--output). However, the two methods differ quite significantly in the way that neighbours are identified and in the weighting scheme. First, natural neigbhour identifies neighbours to be used in the interpolation of a point by finding the points connected to the estimated value location in a Delaunay triangulation, that is, the so-called natural neighbours. This approach has the main advantage of not having to specify an arbitrary search distance or minimum number of nearest neighbours like many other interpolators do. Weights in the natural neighbour scheme are determined using an area-stealing approach, whereby the weight assigned to a neighbour's value is determined by the proportion of its Voronoi polygon that would be lost by inserting the interpolation point into the Voronoi diagram. That is, inserting the interpolation point into the Voronoi diagram results in the creation of a new polygon and shrinking the sizes of the Voronoi polygons associated with each of the natural neighbours. The larger the area by which a neighbours polygon is reduced through the insertion, relative to the polygon of the interpolation point, the greater the weight given to the neighbour point's value in the interpolation. Interpolation weights sum to one because the sum of the reduced polygon areas must account for the entire area of the interpolation points polygon.

The user must specify the attribute field containing point values (--field). Alternatively, if the input Shapefile contains z-values, the interpolation may be based on these values (--use_z). Either an output grid resolution (--cell_size) must be specified or alternatively an existing base file (--base) can be used to determine the output raster's (--output) resolution and spatial extent. Natural neighbour interpolation generally produces a satisfactorily smooth surface within the region of data points but can produce spurious breaks in the surface outside of this region. Thus, it is recommended that the output surface be clipped to the convex hull of the input points (--clip).

Reference:

Sibson, R. (1981). "A brief description of natural neighbor interpolation (Chapter 2)". In V. Barnett (ed.). Interpolating Multivariate Data. Chichester: John Wiley. pp. 21–36.

See Also: IdwInterpolation, NearestNeighbourGridding

Parameters:

Python function:

wbt.natural_neighbour_interpolation(
    i, 
    output, 
    field=None, 
    use_z=False, 
    cell_size=None, 
    base=None, 
    clip=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NaturalNeighbourInterpolation -v ^
--wd="/path/to/data/" -i=points.shp --field=HEIGHT ^
-o=surface.tif --resolution=10.0 --clip 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/12/2019

Last Modified: 10/12/2019

NearestNeighbourGridding

Creates a raster grid based on a set of vector points and assigns grid values using the nearest neighbour.

Parameters:

Python function:

wbt.nearest_neighbour_gridding(
    i, 
    field, 
    output, 
    use_z=False, 
    cell_size=None, 
    base=None, 
    max_dist=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NearestNeighbourGridding -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--cell_size=1.0
>>./whitebox_tools -r=NearestNeighbourGridding ^
-v --wd="/path/to/data/" -i=points.shp --use_z -o=output.tif ^
--base=existing_raster.tif --max_dist=5.5 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/10/2018

Last Modified: 09/12/2019

PolygonArea

This tool calculates the area of vector polygons, adding the result to the vector's attribute table (AREA field). The area calculation will account for any holes contained within polygons. The vector should be in a projected coordinate system.

To calculate the area of raster polygons, use the RasterArea tool instead.

See Also: RasterArea

Parameters:

Python function:

wbt.polygon_area(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PolygonArea -v --wd="/path/to/data/" ^
--input=polygons.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/09/2018

Last Modified: 13/10/2018

PolygonLongAxis

This tool can be used to map the long axis of polygon features. The long axis is the longer of the two primary axes of the minimum bounding box (MBB), i.e. the smallest box to completely enclose a feature. The long axis is drawn for each polygon in the input vector file such that it passes through the centre point of the MBB. The output file is therefore a vector of simple two-point polylines forming a vector field.

Parameters:

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 14/09/2018

Last Modified: 03/03/2020

PolygonPerimeter

This tool calculates the perimeter of vector polygons, adding the result to the vector's attribute table (PERIMETER field). The area calculation will account for any holes contained within polygons. The vector should be in a a projected coordinate system.

Parameters:

Python function:

wbt.polygon_perimeter(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PolygonPerimeter -v ^
--wd="/path/to/data/" --input=polygons.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/09/2018

Last Modified: 13/10/2018

PolygonShortAxis

This tool can be used to map the short axis of polygon features. The short axis is the shorter of the two primary axes of the minimum bounding box (MBB), i.e. the smallest box to completely enclose a feature. The short axis is drawn for each polygon in the input vector file such that it passes through the centre point of the MBB. The output file is therefore a vector of simple two-point polylines forming a vector field.

Parameters:

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 15/09/2018

Last Modified: 03/03/2020

RadialBasisFunctionInterpolation

This tool interpolates vector points into a raster surface using a radial basis function (RBF) scheme.

Parameters:

Python function:

wbt.radial_basis_function_interpolation(
    i, 
    field, 
    output, 
    use_z=False, 
    radius=None, 
    min_points=None, 
    func_type="ThinPlateSpline", 
    poly_order="none", 
    weight=0.1, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RadialBasisFunctionInterpolation -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--weight=2.0 --radius=4.0 --min_points=3 --cell_size=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/12/2019

Last Modified: 10/12/2019

RasterArea

This tools estimates the area of each category, polygon, or patch in an input raster. The input raster must be categorical in data scale. Rasters with floating-point cell values are not good candidates for an area analysis. The user must specify whether the output is given in grid cells or map units (--units). Map Units are physical units, e.g. if the rasters's scale is in metres, areas will report in square-metres. Notice that square-metres can be converted into hectares by dividing by 10,000 and into square-kilometres by dividing by 1,000,000. If the input raster is in geographic coordinates (i.e. latitude and longitude) a warning will be issued and areas will be estimated based on per-row calculated degree lengths.

The tool can be run with a raster output (--output), a text output (--out_text), or both. If niether outputs are specified, the tool will automatically output a raster named area.tif.

Zero values in the input raster may be excluded from the area analysis if the --zero_back flag is used.

To calculate the area of vector polygons, use the PolygonArea tool instead.

See Also: PolygonArea, RasterHistogram

Parameters:

Python function:

wbt.raster_area(
    i, 
    output=None, 
    out_text=False, 
    units="grid cells", 
    zero_back=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterArea -v --wd="/path/to/data/" ^
-i=input.tif -o=output.tif --out_text --units='grid cells' ^
--zero_back 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/02/2019

Last Modified: 04/12/2019

RasterCellAssignment

This tool can be used to create a new raster with the same coordinates and dimensions (i.e. rows and columns) as an existing base image. Grid cells in the new raster will be assigned either the row or column number or the x- or y-coordinate, depending on the selected option (--assign flag). The user must also specify the name of the base image (--input).

See Also: NewRasterFromBase

Parameters:

Python function:

wbt.raster_cell_assignment(
    i, 
    output, 
    assign="column", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterCellAssignment -v ^
--wd="/path/to/data/" -i='input.tif' -o=output.tif ^
--assign='column' 

Source code on GitHub

Author: Daniel Newman

Created: August 10, 2017

Last Modified: 13/10/2018

RasterPerimeter

This tool can be used to measure the length of the perimeter of polygon features in a raster layer. The user must specify the name of the input raster file (--input) and optionally an output raster (--output), which is the raster layer containing the input features assigned the perimeter length. The user may also optionally choose to output text data (--out_text). Raster-based perimeter estimation uses the accurate, anti-aliasing algorithm of Prashker (2009).

The input file must be of a categorical data type, containing discrete polygon features that have been assigned unique identifiers. Such rasters are often created by region-grouping (Clump) a classified raster.

Reference:

Prashker, S. (2009) An anti-aliasing algorithm for calculating the perimeter of raster polygons. Geotec, Ottawa and Geomtics Atlantic, Wolfville, NS.

See Also: RasterArea, Clump

Parameters:

Python function:

wbt.raster_perimeter(
    i, 
    output=None, 
    out_text=False, 
    units="grid cells", 
    zero_back=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterPerimeter -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --out_text ^
--units='grid cells' --zero_back 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/12/2019

Last Modified: 18/12/2019

Reclass

This tool creates a new raster in which the value of each grid cell is determined by an input raster (--input) and a collection of user-defined classes. The user must specify the New value, the From value, and the To Just Less Than value of each class triplet of the reclass string. Classes must be mutually exclusive, i.e. non-overlapping. For example:

--reclass_vals='0.0;0.0;1.0;1.0;1.0;2.0'

The above reclass string assigns 0.0 to all grid cells in the input image with values from 0.0-1.0 and an output value of 1.0 from to inputs from 1.0-2.0. Alternatively, if the --assign_mode flag is specified, Reclass will operate in assign mode, using a reclass string composed of paired values:

--reclass_vals='0.0;1.0;1.0;2.0'

Here, 0.0 is assigned to input grid cell values of 1.0 and 1.0 is output for all input cells with a value of 2.0. Users may add the text strings min and max in the class definitions to stand in for the raster's minimum and maximum values. For example:

--reclass_vals='0.0;min;1.0;1.0;1.0;max'

Any values in the input raster that do not fall within one of the classes will be assigned its original value in the output raster. NoData values in the input raster will be assigned NoData values in the output raster, unless NoData is used in one of the user-defined reclass ranges (notice that it is valid to enter 'NoData' in these ranges).

See Also: ReclassEqualInterval, ReclassFromFile

Parameters:

Python function:

wbt.reclass(
    i, 
    output, 
    reclass_vals, 
    assign_mode=False, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=Reclass -v --wd="/path/to/data/" ^
-i='input.tif' -o=output.tif ^
--reclass_vals='0.0;0.0;1.0;1.0;1.0;2.0'
>>./whitebox_tools ^
-r=Reclass -v --wd="/path/to/data/" -i='input.tif' ^
-o=output.tif --reclass_vals='10;1;20;2;30;3;40;4' ^
--assign_mode 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/09/2017

Last Modified: 13/02/2020

ReclassEqualInterval

This tool reclassifies the values in an input raster (--input) file based on an equal-interval scheme, where the user must specify the reclass interval value (--interval), the starting value (--start_val), and optionally, the ending value (--end_val). Grid cells containing values that fall outside of the range defined by the starting and ending values, will be assigned their original values in the output grid. If the user does not specify an ending value, the tool will assign a very large positive value.

See Also: Reclass, ReclassFromFile

Parameters:

Python function:

wbt.reclass_equal_interval(
    i, 
    output, 
    interval=10.0, 
    start_val=None, 
    end_val=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ReclassEqualInterval -v ^
--wd="/path/to/data/" -i='input.tif' -o=output.tif ^
--interval=10.0 --start_val=0.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 06/07/2017

Last Modified: 30/01/2020

ReclassFromFile

This tool creates a new raster image in which the value of each grid cell is determined by the values in an input raster image (--input) and a reclass file (--reclass_file). The reclass file is a text file containing two or three columns, delimited (i.e. separated) by either a space, tab, or comma. The columns describe respectively the New value, the From value, and the To Just Less Than value. Classes must be mutually exclusive, i.e. non-overlapping. Users may add the text strings min and max in the class definitions to stand in for the raster's minimum and maximum values.

If only two columns are present in the reclass file, i.e. the From column is left blank, the tool will operate in assign mode. That is, any cell in the input image that is equal to the From value (contained in the second column) will be assigned the New value (contained in the first column) in the output image.

Any values in the input raster that do not fall within one of the classes will be assigned its original value in the output raster. NoData values in the input raster will be assigned NoData values in the output raster.

See Also: Reclass, ReclassEqualInterval

Parameters:

Python function:

wbt.reclass_from_file(
    i, 
    reclass_file, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ReclassFromFile -v ^
--wd="/path/to/data/" -i='input.tif' ^
--reclass_file='reclass.txt' -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/09/2017

Last Modified: 13/02/2020

SmoothVectors

This tool smooths a vector coverage of either a POLYLINE or POLYGON base ShapeType. The algorithm uses a simple moving average method for smoothing, where the size of the averaging window is specified by the user. The default filter size is 3 and can be any odd integer larger than or equal to 3. The larger the averaging window, the greater the degree of line smoothing.

Parameters:

Python function:

wbt.smooth_vectors(
    i, 
    output, 
    filter=3, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SmoothVectors -v --wd="/path/to/data/" ^
-i=in_file.shp -o=out_file.shp --filter=9 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/10/2018

Last Modified: 13/10/2018

SplitVectorLines

This tool can be used to divide longer vector lines (--input) into segments of a maximum specified length (--length).

See Also: AssessRoute

Parameters:

Python function:

wbt.split_vector_lines(
    i, 
    output, 
    length=None, 
    callback=default_callback
)

Command-line Interface:

>> ./whitebox_tools -r=SplitVectorLines -i=input.shp ^
-o=line_segments.shp --length=100.0 

[Source code on GitHub](https://github.com/jblindsay/whitebox-tools/blob/master/Splitvectorlines thread 'main' panicked at 'Unrecognized tool name Splitvectorlines.', whitebox-tools-app/src/main.rs:72:21 note: run with RUST_BACKTRACE=1 environment variable to display a backtrace )

Author: Prof. John Lindsay

Created: 23/04/2021

Last Modified: 23/04/2021

TinGridding

Creates a raster grid based on a triangular irregular network (TIN) fitted to vector points and linear interpolation within each triangular-shaped plane. The TIN creation algorithm is based on Delaunay triangulation.

The user must specify the attribute field containing point values (--field). Alternatively, if the input Shapefile contains z-values, the interpolation may be based on these values (--use_z). Either an output grid resolution (--cell_size) must be specified or alternatively an existing base file (--base) can be used to determine the output raster's (--output) resolution and spatial extent. Natural neighbour interpolation generally produces a satisfactorily smooth surface within the region of data points but can produce spurious breaks in the surface outside of this region. Thus, it is recommended that the output surface be clipped to the convex hull of the input points (--clip).

See Also: LidarTINGridding, ConstructVectorTIN, NaturalNeighbourInterpolation

Parameters:

Python function:

wbt.tin_gridding(
    i, 
    output, 
    field=None, 
    use_z=False, 
    resolution=None, 
    base=None, 
    max_triangle_edge_length=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=TINGridding -v --wd="/path/to/data/" ^
-i=points.shp --field=HEIGHT -o=tin.shp ^
--resolution=10.0
>>./whitebox_tools -r=TINGridding -v ^
--wd="/path/to/data/" -i=points.shp --use_z -o=tin.shp ^
--resolution=5.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 23/09/2018

Last Modified: 18/10/2019

VectorHexBinning

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 PointDensity 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 (Shapefile vector) that are contained within the hexagonal cell.

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: LidarHexBinning, PointDensity, CreateHexagonalVectorGrid

Parameters:

Python function:

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

Command-line Interface:

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

Source code on GitHub

Author: Dr. John Lindsay

Created: 16/09/2018

Last Modified: 13/10/2018

VoronoiDiagram

This tool creates a vector Voronoi diagram for a set of vector points. The Voronoi diagram is the dual graph of the Delaunay triangulation. The tool operates by first constructing the Delaunay triangulation and then connecting the circumcenters of each triangle. Each Voronoi cell contains one point of the input vector points. All locations within the cell are nearer to the contained point than any other input point.

A dense frame of 'ghost' (hidden) points is inserted around the input point set to limit the spatial extent of the diagram. The frame is set back from the bounding box of the input points by 2 x the average point spacing. The polygons of these ghost points are not output, however, points that are situated along the edges of the data will have somewhat rounded (paraboloic) exterior boundaries as a result of this edge condition. If this property is unacceptable for application, clipping the Voronoi diagram to the convex hull may be a better alternative.

This tool works on vector input data only. If a Voronoi diagram is needed to tesselate regions associated with a set of raster points, use the EuclideanAllocation tool instead. To use Voronoi diagrams for gridding data (i.e. raster interpolation), use the NearestNeighbourGridding tool.

See Also: ConstructVectorTIN, EuclideanAllocation, NearestNeighbourGridding

Parameters:

Python function:

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

Command-line Interface:

>>./whitebox_tools -r=VoronoiDiagram -v --wd="/path/to/data/" ^
-i=points.shp -o=tin.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 03/10/2018

Last Modified: 16/06/2020