GIS Analysis → Patch Shape Tools
- BoundaryShapeComplexity
- CompactnessRatio
- DeviationFromRegionalDirection
- EdgeProportion
- ElongationRatio
- FindPatchOrClassEdgeCells
- HoleProportion
- LinearityIndex
- NarrownessIndex
- PatchOrientation
- PerimeterAreaRatio
- RadiusOfGyration
- RelatedCircumscribingCircle
- ShapeComplexityIndex
- ShapeComplexityIndexRaster
BoundaryShapeComplexity
This tools calculates a type of shape complexity index for raster objects, focused on the complexity of the boundary of polygons. The index uses the LineThinning tool to estimate a skeletonized network for each input raster polygon. The Boundary Shape Complexity (BSC) index is then calculated as the percentage of the skeletonized network belonging to exterior links. Polygons with more complex boundaries will possess more branching skeletonized networks, with each spur in the boundary possessing a short exterior branch. The two longest exterior links in the network are considered to be part of the main network. Therefore, polygons of complex shaped boundaries will have a higher percentage of their skeleton networks consisting of exterior links. It is expected that simple convex hulls should have relatively low BSC index values.
Objects in the input raster (--input
) are designated by their unique identifiers. Identifier values should be
positive, non-zero whole numbers.
See Also: ShapeComplexityIndexRaster, LineThinning
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
Python function:
wbt.boundary_shape_complexity(
i,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=BoundaryShapeComplexity -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --zero_back
Author: Dr. John Lindsay
Created: 17/02/2019
Last Modified: 17/02/2019
CompactnessRatio
The compactness ratio is an indicator of polygon shape complexity. The compactness ratio is defined as the polygon area divided by its perimeter. Unlike some other shape parameters (e.g. ShapeComplexityIndex), compactness ratio does not standardize to a simple Euclidean shape. Although widely used for landscape analysis, compactness ratio, like its inverse, the PerimeterAreaRatio, exhibits the undesirable property of polygon size dependence (Mcgarigal et al. 2002). That is, holding shape constant, an increase in polygon size will cause a change in the compactness ratio.
The output data will be contained in the input vector's attribute table as a new field (COMPACT).
See Also: PerimeterAreaRatio, ShapeComplexityIndex, RelatedCircumscribingCircle
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
Python function:
wbt.compactness_ratio(
i,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=CompactnessRatio -v ^
--wd="/path/to/data/" --input=polygons.shp
Author: Dr. John Lindsay
Created: 27/09/2018
Last Modified: 13/10/2018
DeviationFromRegionalDirection
This tool calculates the degree to which each polygon in an input shapefile (--input
) deviates from the average,
or regional, direction. The input file will have a new attribute inserted in the attribute table, DEV_DIR
, which
will contain the calculated values. The deviation values are in degrees. The orientation of each polygon is determined
based on the long-axis of the minimum bounding box fitted to the polygon. The regional direction is based on the
mean direciton of the polygons, weighted by long-axis length (longer polygons contribute more weight) and elongation,
i.e., a function of the long and short axis lengths (greater elongation contributes more weight). Polygons with
elongation values lower than the elongation threshold value (--elong_threshold
), which has values between 0 and 1,
will be excluded from the calculation of the regional direction.
See Also: PatchOrientation, ElongationRatio
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
--elong_threshold | Elongation threshold used in determining which polygons are used to estimate the regional direction (0.05-0.95) |
Python function:
wbt.deviation_from_regional_direction(
i,
elong_threshold=0.75,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=DeviationFromRegionalDirection -v ^
--wd="/path/to/data/" --input=polygons.shp
Author: Dr. John Lindsay
Created: 24/05/2023
Last Modified: 24/05/2023
EdgeProportion
This tool will measure the edge proportion, i.e. the proportion of grid cells in a patch that are located along the
patch's boundary, for an input raster image (--input
). Edge proportion is an indicator of polygon shape complexity
and elongation. The user must specify the name of the output raster file (--output
), which will be raster layer
containing the input features assigned the edge proportion. The user may also optionally choose to output text data
for easy input to a spreadsheet or database.
Objects in the input raster are designated by their unique identifiers. Identifier values must be positive, non-zero whole numbers.
See Also: ShapeComplexityIndexRaster, LinearityIndex, ElongationRatio
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--output_text | flag indicating whether a text report should also be output |
Python function:
wbt.edge_proportion(
i,
output,
output_text=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=EdgeProportion -v --wd="/path/to/data/" ^
-i=input.tif -o=output.tif --output_text
Author: Dr. John Lindsay
Created: 13/07/2017
Last Modified: 18/10/2019
ElongationRatio
This tool can be used to calculate the elongation ratio for vector polygons. The elongation ratio values calculated for each vector polygon feature will be placed in the accompanying database file (.dbf) as an elongation field (ELONGATION).
The elongation ratio (E
) is:
E = 1 - S / L
Where S
is the short-axis length, and L
is the long-axis length. Axes
lengths are determined by estimating the minimum bounding box.
The elongation ratio provides similar information as the Linearity Index. The ratio is not an adequate measure of overall polygon narrowness, because a highly sinuous but narrow polygon will have a low linearity (elongation) owing to the compact nature of these polygon.
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
Python function:
wbt.elongation_ratio(
i,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ElongationRatio -v ^
--wd="/path/to/data/" --input=polygons.shp
Author: Dr. John Lindsay
Created: 25/09/2018
Last Modified: 13/10/2018
FindPatchOrClassEdgeCells
This tool will identify all grid cells situated along the edges of patches or class features within an
input raster (--input
). Edge cells in the output raster (--output
) will have the patch identifier value
assigned in the corresponding grid cell. All non-edge cells will be assigned zero in the output raster.
Patches (or classes) are designated by positive, non-zero values in the input image. Zero-valued
and NoData-valued grid cells are interpreted as background cells by the tool.
See Also: EdgeProportion
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
Python function:
wbt.find_patch_or_class_edge_cells(
i,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=FindPatchOrClassEdgeCells -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif
Author: Dr. John Lindsay
Created: 14/07/2017
Last Modified: 13/10/2018
HoleProportion
This calculates the proportion of the total area of a polygon's holes (i.e. islands) relative to the area of the polygon's hull. It can be a useful measure of shape complexity, or how discontinuous a patch is. The user must specify the name of the input vector file and the output data will be contained within the input vector's database file as a new field (HOLE_PROP).
See Also: ShapeComplexityIndex, ElongationRatio, PerimeterAreaRatio
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
Python function:
wbt.hole_proportion(
i,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=HoleProportion -v --wd="/path/to/data/" ^
--input=polygons.shp
Author: Dr. John Lindsay
Created: 26/09/2018
Last Modified: 26/09/2018
LinearityIndex
This tool calculates the linearity index of polygon features based on a regression analysis. The index is simply the coefficient of determination (r-squared) calculated from a regression analysis of the x and y coordinates of the exterior hull nodes of a vector polygon. Linearity index is a measure of how well a polygon can be described by a straight line. It is a related index to the ElongationRatio, but is more efficient to calculate as it does not require finding the minimum bounding box. The Pearson correlation coefficient between linearity index and the elongation ratio for a large data set of lake polygons in northern Canada was found to be 0.656, suggesting a moderate level of association between the two measures of polygon linearity. Note that this index is not useful for identifying narrow yet sinuous polygons, such as meandering rivers.
The only required input is the name of the file. The linearity values calculated for each vector polygon feature will be placed in the accompanying attribute table as a new field (LINEARITY).
See Also: ElongationRatio, PatchOrientation
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
Python function:
wbt.linearity_index(
i,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=LinearityIndex -v --wd="/path/to/data/" ^
--input=polygons.shp
Author: Dr. John Lindsay
Created: 01/10/2018
Last Modified: 13/10/2018
NarrownessIndex
This tools calculates a type of shape narrowness index (NI) for raster objects. The index is equal to:
NI = A / (πMD2)
where A is the patch area and MD is the maximum distance-to-edge of the patch. Circular-shaped patches will have a narrowness index near 1.0, while more narrow patch shapes will have higher index values. The index may be conceptualized as the ratio of the patch area to the area of the largest contained circle, although in practice the circle defined by the radius of the maximum distance-to-edge will often fall outside the patch boundaries.
Objects in the input raster (--input
) are designated by their unique identifiers. Identifier values must
be positive, non-zero whole numbers. It is quite common for identifiers to be set using the Clump tool
applied to some kind of thresholded raster.
See Also: LinearityIndex, ElongationRatio, Clump
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
Python function:
wbt.narrowness_index(
i,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=NarrownessIndex -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --zero_back
Author: Dr. John Lindsay
Created: 17/02/2019
Last Modified: 17/02/2019
PatchOrientation
This tool calculates the orientation of polygon features based on the slope of a reduced major axis (RMA) regression line. The regression analysis use the vertices of the exterior hull nodes of a vector polygon. The only required input is the name of the vector polygon file. The orientation values, measured in degrees from north, will be placed in the accompanying attribute table as a new field (ORIENT). The value of the orientation measure for any polygon will depend on how elongated the feature is.
Note that the output values are polygon orientations and not true directions. While directions may take values ranging from 0-360, orientation is expressed as an angle between 0 and 180 degrees clockwise from north. Lastly, the orientation measure may become unstable when polygons are oriented nearly vertical or horizontal.
See Also: LinearityIndex, ElongationRatio
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
Python function:
wbt.patch_orientation(
i,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=PatchOrientation -v ^
--wd="/path/to/data/" --input=polygons.shp
Author: Dr. John Lindsay
Created: 16/10/2018
Last Modified: 16/10/2018
PerimeterAreaRatio
The perimeter-area ratio is an indicator of polygon shape complexity. Unlike some other shape parameters (e.g. shape complexity index), perimeter-area ratio does not standardize to a simple Euclidean shape. Although widely used for landscape analysis, perimeter-area ratio exhibits the undesirable property of polygon size dependence (Mcgarigal et al. 2002). That is, holding shape constant, an increase in polygon size will cause a decrease in the perimeter-area ratio. The perimeter-area ratio is the inverse of the compactness ratio.
The output data will be displayed as a new field (P_A_RATIO) in the input vector's database file.
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
Python function:
wbt.perimeter_area_ratio(
i,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=PerimeterAreaRatio -v ^
--wd="/path/to/data/" --input=polygons.shp
Author: Dr. John Lindsay
Created: 26/09/2018
Last Modified: 03/03/2020
RadiusOfGyration
This can be used to calculate the radius of gyration (RoG) for the polygon features within a raster image. RoG measures how far across the landscape a polygon extends its reach on average, given by the mean distance between cells in a patch (Mcgarigal et al. 2002). The radius of gyration can be considered a measure of the average distance an organism can move within a patch before encountering the patch boundary from a random starting point (Mcgarigal et al. 2002). The input raster grid should contain polygons with unique identifiers greater than zero. The user must also specify the name of the output raster file (where the radius of gyration will be assigned to each feature in the input file) and the specified option of outputting text data.
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
--text_output | Optional text output |
Python function:
wbt.radius_of_gyration(
i,
output,
text_output=False,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RadiusOfGyration -v ^
--wd="/path/to/data/" -i=polygons.tif -o=output.tif ^
--text_output
Author: Dr. John Lindsay
Created: 31/12/2017
Last Modified: 18/10/2019
RelatedCircumscribingCircle
This tool can be used to calculate the related circumscribing circle (Mcgarigal et al. 2002) for vector polygon features. The related circumscribing circle values calculated for each vector polygon feature will be placed in the accompanying attribute table as a new field (RC_CIRCLE).
Related circumscribing circle (RCC) is defined as:
RCC = 1 - A / Ac
Where A
is the polygon's area and Ac
the area of the smallest circumscribing circle.
Theoretically, RelatedCircumscribingCircle ranges from 0 to 1, where a value of 0 indicates a circular polygon and a value of 1 indicates a highly elongated shape. The circumscribing circle provides a measure of polygon elongation. Unlike the ElongationRatio, however, it does not provide a measure of polygon direction in addition to overall elongation. Like the ElongationRatio and LinearityIndex, RelatedCircumscribingCircle is not an adequate measure of overall polygon narrowness, because a highly sinuous but narrow patch will have a low related circumscribing circle index owing to the compact nature of these polygon.
Note: Holes are excluded from the area calculation of polygons.
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
Python function:
wbt.related_circumscribing_circle(
i,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=RelatedCircumscribingCircle -v ^
--wd="/path/to/data/" --input=polygons.shp
Author: Dr. John Lindsay
Created: 27/09/2018
Last Modified: 13/10/2018
ShapeComplexityIndex
This tool provides a measure of overall polygon shape complexity, or irregularity, for vector polygons. Several shape indices have been created to compare a polygon's shape to simple Euclidean shapes (e.g. circles, squares, etc.). One of the problems with this approach is that it inherently convolves the characteristics of polygon complexity and elongation. The Shape Complexity Index (SCI) was developed as a parameter for assessing the complexity of a polygon that is independent of its elongation.
SCI relates a polygon's shape to that of an encompassing convex hull. It is defined as:
SCI = 1 - A / Ah
Where A
is the polygon's area and Ah
is the area of the convex hull containing
the polygon. Convex polygons, i.e. those that do not contain concavities or holes,
have a value of 0. As the shape of the polygon becomes more complex, the SCI
approaches 1. Note that polygon shape complexity also increases with the greater
number of holes (i.e. islands), since holes have the effect of reducing the lake
area.
The SCI values calculated for each vector polygon feature will be placed in the accompanying database file (.dbf) as a complexity field (COMPLEXITY).
See Also: ShapeComplexityIndexRaster
Parameters:
Flag | Description |
---|---|
-i, --input | Input vector polygon file |
Python function:
wbt.shape_complexity_index(
i,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ShapeComplexityIndex -v ^
--wd="/path/to/data/" --input=polygons.shp
Author: Dr. John Lindsay
Created: 25/09/2018
Last Modified: 13/10/2018
ShapeComplexityIndexRaster
This tools calculates a type of shape complexity index for raster objects. The index is equal to the average
number of intersections of the group of vertical and horizontal transects passing through an object. Simple
objects will have a shape complexity index of 1.0 and more complex shapes, including those containing numerous
holes or are winding in shape, will have higher index values. Objects in the input raster (--input
) are
designated by their unique identifiers. Identifier values should be positive, non-zero whole numbers.
See Also: ShapeComplexityIndex, BoundaryShapeComplexity
Parameters:
Flag | Description |
---|---|
-i, --input | Input raster file |
-o, --output | Output raster file |
Python function:
wbt.shape_complexity_index_raster(
i,
output,
callback=default_callback
)
Command-line Interface:
>>./whitebox_tools -r=ShapeComplexityIndexRaster -v ^
--wd="/path/to/data/" -i=input.tif -o=output.tif --zero_back
Author: Dr. John Lindsay
Created: 16/02/2019
Last Modified: 16/02/2019