This notebook demonstrates the usage of the whitebox Python package for geospatial analysis, which is built on a stand-alone executable command-line program called WhiteboxTools.
Launch this tutorial as an interactive Jupyter Notebook on the cloud - MyBinder.org.
whitebox supports a variety of platforms, including Microsoft Windows, macOS, and Linux operating systems. Note that you will need to have Python 3.x installed. Python 2.x is not supported. The whitebox Python package can be installed using the following command:
pip install whitebox
If you have installed whitebox Python package before and want to upgrade to the latest version, you can use the following command:
pip install whitebox -U
If you encounter any installation issues, please check Troubleshooting on the whitebox GitHub page and Report Bugs.
!pip install whitebox
import whitebox and call WhiteboxTools()
import whitebox
wbt = whitebox.WhiteboxTools()
Prints the whitebox-tools help...a listing of available commands
print(wbt.help())
WhiteboxTools Help The following commands are recognized: --cd, --wd Changes the working directory; used in conjunction with --run flag. -h, --help Prints help information. -l, --license Prints the whitebox-tools license. Tool names may also be used, --license="Slope" --listtools Lists all available tools. Keywords may also be used, --listtools slope. -r, --run Runs a tool; used in conjunction with --wd flag; -r="LidarInfo". --toolbox Prints the toolbox associated with a tool; --toolbox=Slope. --toolhelp Prints the help associated with a tool; --toolhelp="LidarInfo". --toolparameters Prints the parameters (in json form) for a specific tool; --toolparameters="LidarInfo". -v Verbose mode. Without this flag, tool outputs will not be printed. --viewcode Opens the source code of a tool in a web browser; --viewcode="LidarInfo". --version Prints the version information. Example Usage: >> ./whitebox_tools -r=lidar_info --cd="/path/to/data/" -i=input.las --vlr --geokeys
Prints the whitebox-tools license
print(wbt.license())
WhiteboxTools License Copyright 2017-2020 John Lindsay Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Prints the whitebox-tools version
print("Version information: {}".format(wbt.version()))
Version information: WhiteboxTools v2.0.0 by Dr. John B. Lindsay (c) 2017-2021 WhiteboxTools is an advanced geospatial data analysis platform developed at the University of Guelph's Geomorphometry and Hydrogeomatics Research Group (GHRG). See www.whiteboxgeo.com for more details.
Print the help for a specific tool.
print(wbt.tool_help("ElevPercentile"))
ElevPercentile Description: Calculates the elevation percentile raster from a DEM. Toolbox: Geomorphometric Analysis Parameters: Flag Description ----------------- ----------- -i, --input, --dem Input raster DEM file. -o, --output Output raster file. --filterx Size of the filter kernel in the x-direction. --filtery Size of the filter kernel in the y-direction. --sig_digits Number of significant digits. Example usage: >>./whitebox_tools -r=ElevPercentile -v --wd="/path/to/data/" --dem=DEM.tif -o=output.tif --filter=25
Tool names in the whitebox Python package can be called either using the snake_case or CamelCase convention (e.g. lidar_info or LidarInfo). The example below uses snake_case.
import os, pkg_resources
# identify the sample data directory of the package
data_dir = os.path.dirname(pkg_resources.resource_filename("whitebox", 'testdata/'))
# set whitebox working directory
wbt.set_working_dir(data_dir)
wbt.verbose = False
# call whiteboxtools
wbt.feature_preserving_smoothing("DEM.tif", "smoothed.tif", filter=9)
wbt.breach_depressions("smoothed.tif", "breached.tif")
wbt.d_inf_flow_accumulation("breached.tif", "flow_accum.tif")
0
You can search tools using keywords. For example, the script below searches and lists tools with 'lidar' or 'LAS' in tool name or description.
lidar_tools = wbt.list_tools(['lidar', 'LAS'])
for index, tool in enumerate(lidar_tools):
print("{} {}: {} ...".format(str(index+1).zfill(3), tool, lidar_tools[tool][:45]))
001 ascii_to_las: Converts one or more ASCII files containing L ... 002 classify_buildings_in_lidar: Reclassifies a LiDAR points that lie within v ... 003 classify_overlap_points: Classifies or filters LAS points in regions o ... 004 clip_lidar_to_polygon: Clips a LiDAR point cloud to a vector polygon ... 005 erase_polygon_from_lidar: Erases (cuts out) a vector polygon or polygon ... 006 filter_lidar_classes: Removes points in a LAS file with certain spe ... 007 filter_lidar_scan_angles: Removes points in a LAS file with scan angles ... 008 find_flightline_edge_points: Identifies points along a flightline's edge i ... 009 find_patch_or_class_edge_cells: Finds all cells located on the edge of patch ... 010 flightline_overlap: Reads a LiDAR (LAS) point file and outputs a ... 011 height_above_ground: Normalizes a LiDAR point cloud, providing the ... 012 k_means_clustering: Performs a k-means clustering operation on a ... 013 las_to_ascii: Converts one or more LAS files into ASCII tex ... 014 las_to_multipoint_shapefile: Converts one or more LAS files into Multipoin ... 015 las_to_shapefile: Converts one or more LAS files into a vector ... 016 las_to_zlidar: Converts one or more LAS files into the zlida ... 017 lidar_block_maximum: Creates a block-maximum raster from an input ... 018 lidar_block_minimum: Creates a block-minimum raster from an input ... 019 lidar_classify_subset: Classifies the values in one LiDAR point clou ... 020 lidar_colourize: Adds the red-green-blue colour fields of a Li ... 021 lidar_digital_surface_model: Creates a top-surface digital surface model ( ... 022 lidar_elevation_slice: Outputs all of the points within a LiDAR (LAS ... 023 lidar_ground_point_filter: Identifies ground points within LiDAR dataset ... 024 lidar_hex_binning: Hex-bins a set of LiDAR points. ... 025 lidar_hillshade: Calculates a hillshade value for points withi ... 026 lidar_histogram: Creates a histogram of LiDAR data. ... 027 lidar_idw_interpolation: Interpolates LAS files using an inverse-dista ... 028 lidar_info: Prints information about a LiDAR (LAS) datase ... 029 lidar_join: Joins multiple LiDAR (LAS) files into a singl ... 030 lidar_kappa_index: Performs a kappa index of agreement (KIA) ana ... 031 lidar_nearest_neighbour_gridding: Grids LiDAR files using nearest-neighbour sch ... 032 lidar_point_density: Calculates the spatial pattern of point densi ... 033 lidar_point_stats: Creates several rasters summarizing the distr ... 034 lidar_ransac_planes: Performs a RANSAC analysis to identify points ... 035 lidar_rbf_interpolation: Interpolates LAS files using a radial basis f ... 036 lidar_remove_duplicates: Removes duplicate points from a LiDAR data se ... 037 lidar_remove_outliers: Removes outliers (high and low points) in a L ... 038 lidar_rooftop_analysis: Identifies roof segments in a LiDAR point clo ... 039 lidar_segmentation: Segments a LiDAR point cloud based on differe ... 040 lidar_segmentation_based_filter: Identifies ground points within LiDAR point c ... 041 lidar_tin_gridding: Creates a raster grid based on a Delaunay tri ... 042 lidar_thin: Thins a LiDAR point cloud, reducing point den ... 043 lidar_thin_high_density: Thins points from high density areas within a ... 044 lidar_tile: Tiles a LiDAR LAS file into multiple LAS file ... 045 lidar_tile_footprint: Creates a vector polygon of the convex hull o ... 046 lidar_tophat_transform: Performs a white top-hat transform on a Lidar ... 047 modified_k_means_clustering: Performs a modified k-means clustering operat ... 048 normal_vectors: Calculates normal vectors for points within a ... 049 pennock_landform_class: Classifies hillslope zones based on slope, pr ... 050 raster_area: Calculates the area of polygons or classes wi ... 051 raster_cell_assignment: Assign row or column number to cells. ... 052 raster_perimeter: Calculates the perimeters of polygons or clas ... 053 reclass: Reclassifies the values in a raster image. ... 054 reclass_equal_interval: Reclassifies the values in a raster image bas ... 055 reclass_from_file: Reclassifies the values in a raster image usi ... 056 select_tiles_by_polygon: Copies LiDAR tiles overlapping with a polygon ... 057 shape_complexity_index_raster: Calculates the complexity of raster polygons ... 058 stream_link_class: Identifies the exterior/interior links and no ... 059 zlidar_to_las: Converts one or more zlidar files into the LA ...
List all available tools in whitebox-tools. Currently, whitebox contains 372 tools. More tools will be added as they become available.
all_tools = wbt.list_tools()
for index, tool in enumerate(all_tools):
print("{} {}: {} ...".format(str(index+1).zfill(3), tool, all_tools[tool][:45]))
001 absolute_value: Calculates the absolute value of every cell i ... 002 adaptive_filter: Performs an adaptive filter on an image. ... 003 add: Performs an addition operation on two rasters ... 004 add_point_coordinates_to_table: Modifies the attribute table of a point vecto ... 005 aggregate_raster: Aggregates a raster to a lower resolution. ... 006 and: Performs a logical AND operator on two Boolea ... 007 anova: Performs an analysis of variance (ANOVA) test ... 008 arc_cos: Returns the inverse cosine (arccos) of each v ... 009 arc_sin: Returns the inverse sine (arcsin) of each val ... 010 arc_tan: Returns the inverse tangent (arctan) of each ... 011 arcosh: Returns the inverse hyperbolic cosine (arcosh ... 012 arsinh: Returns the inverse hyperbolic sine (arsinh) ... 013 artanh: Returns the inverse hyperbolic tangent (arcta ... 014 ascii_to_las: Converts one or more ASCII files containing L ... 015 aspect: Calculates an aspect raster from an input DEM ... 016 atan2: Returns the 2-argument inverse tangent (atan2 ... 017 attribute_correlation: Performs a correlation analysis on attribute ... 018 attribute_correlation_neighbourhood_analysis: Performs a correlation on two input vector at ... 019 attribute_histogram: Creates a histogram for the field values of a ... 020 attribute_scattergram: Creates a scattergram for two field values of ... 021 average_flowpath_slope: Measures the average slope gradient from each ... 022 average_normal_vector_angular_deviation: Calculates the circular variance of aspect at ... 023 average_overlay: Calculates the average for each grid cell fro ... 024 average_upslope_flowpath_length: Measures the average length of all upslope fl ... 025 balance_contrast_enhancement: Performs a balance contrast enhancement on a ... 026 basins: Identifies drainage basins that drain to the ... 027 bilateral_filter: A bilateral filter is an edge-preserving smoo ... 028 block_maximum_gridding: Creates a raster grid based on a set of vecto ... 029 block_minimum_gridding: Creates a raster grid based on a set of vecto ... 030 boundary_shape_complexity: Calculates the complexity of the boundaries o ... 031 breach_depressions: Breaches all of the depressions in a DEM usin ... 032 breach_depressions_least_cost: Breaches the depressions in a DEM using a lea ... 033 breach_single_cell_pits: Removes single-cell pits from an input DEM by ... 034 buffer_raster: Maps a distance-based buffer around each non- ... 035 burn_streams_at_roads: Burns-in streams at the sites of road embankm ... 036 ceil: Returns the smallest (closest to negative inf ... 037 centroid: Calculates the centroid, or average location, ... 038 centroid_vector: Identifes the centroid point of a vector poly ... 039 change_vector_analysis: Performs a change vector analysis on a two-da ... 040 circular_variance_of_aspect: Calculates the circular variance of aspect at ... 041 classify_buildings_in_lidar: Reclassifies a LiDAR points that lie within v ... 042 classify_overlap_points: Classifies or filters LAS points in regions o ... 043 clean_vector: Removes null features and lines/polygons with ... 044 clip: Extract all the features, or parts of feature ... 045 clip_lidar_to_polygon: Clips a LiDAR point cloud to a vector polygon ... 046 clip_raster_to_polygon: Clips a raster to a vector polygon. ... 047 closing: A closing is a mathematical morphology operat ... 048 clump: Groups cells that form discrete areas, assign ... 049 compactness_ratio: Calculates the compactness ratio (A/P), a mea ... 050 conditional_evaluation: This tool performs a conditional evaluaton (i ... 051 conservative_smoothing_filter: Performs a conservative-smoothing filter on a ... 052 construct_vector_tin: Creates a vector triangular irregular network ... 053 contours_from_points: Creates a contour coverage from a set of inpu ... 054 contours_from_raster: Derives a vector contour coverage from a rast ... 055 convert_nodata_to_zero: Converts nodata values in a raster to zero. ... 056 convert_raster_format: Converts raster data from one format to anoth ... 057 corner_detection: Identifies corner patterns in boolean images ... 058 correct_vignetting: Corrects the darkening of images towards corn ... 059 cos: Returns the cosine (cos) of each values in a ... 060 cosh: Returns the hyperbolic cosine (cosh) of each ... 061 cost_allocation: Identifies the source cell to which each grid ... 062 cost_distance: Performs cost-distance accumulation on a cost ... 063 cost_pathway: Performs cost-distance pathway analysis using ... 064 count_if: Counts the number of occurrences of a specifi ... 065 create_colour_composite: Creates a colour-composite image from three b ... 066 create_hexagonal_vector_grid: Creates a hexagonal vector grid. ... 067 create_plane: Creates a raster image based on the equation ... 068 create_rectangular_vector_grid: Creates a rectangular vector grid. ... 069 crispness_index: Calculates the Crispness Index, which is used ... 070 cross_tabulation: Performs a cross-tabulation on two categorica ... 071 csv_points_to_vector: Converts a CSV text file to vector points. ... 072 cumulative_distribution: Converts a raster image to its cumulative dis ... 073 d8_flow_accumulation: Calculates a D8 flow accumulation raster from ... 074 d8_mass_flux: Performs a D8 mass flux calculation. ... 075 d8_pointer: Calculates a D8 flow pointer raster from an i ... 076 d_inf_flow_accumulation: Calculates a D-infinity flow accumulation ras ... 077 d_inf_mass_flux: Performs a D-infinity mass flux calculation. ... 078 d_inf_pointer: Calculates a D-infinity flow pointer (flow di ... 079 decrement: Decreases the values of each grid cell in an ... 080 depth_in_sink: Measures the depth of sinks (depressions) in ... 081 dev_from_mean_elev: Calculates deviation from mean elevation. ... 082 diff_from_mean_elev: Calculates difference from mean elevation (eq ... 083 diff_of_gaussian_filter: Performs a Difference of Gaussian (DoG) filte ... 084 difference: Outputs the features that occur in one of the ... 085 direct_decorrelation_stretch: Performs a direct decorrelation stretch enhan ... 086 directional_relief: Calculates relief for cells in an input DEM f ... 087 dissolve: Removes the interior, or shared, boundaries w ... 088 distance_to_outlet: Calculates the distance of stream grid cells ... 089 diversity_filter: Assigns each cell in the output grid the numb ... 090 divide: Performs a division operation on two rasters ... 091 downslope_distance_to_stream: Measures distance to the nearest downslope st ... 092 downslope_flowpath_length: Calculates the downslope flowpath length from ... 093 downslope_index: Calculates the Hjerdt et al. (2004) downslope ... 094 edge_contamination: This tool identifies grid cells within an inp ... 095 edge_density: Calculates the density of edges, or breaks-in ... 096 edge_preserving_mean_filter: Performs a simple edge-preserving mean filter ... 097 edge_proportion: Calculate the proportion of cells in a raster ... 098 elev_above_pit: Calculate the elevation of each grid cell abo ... 099 elev_percentile: Calculates the elevation percentile raster fr ... 100 elev_relative_to_min_max: Calculates the elevation of a location relati ... 101 elev_relative_to_watershed_min_max: Calculates the elevation of a location relati ... 102 elevation_above_stream: Calculates the elevation of cells above the n ... 103 elevation_above_stream_euclidean: Calculates the elevation of cells above the n ... 104 eliminate_coincident_points: Removes any coincident, or nearly coincident, ... 105 elongation_ratio: Calculates the elongation ratio for vector po ... 106 embankment_mapping: Maps and/or removes road embankments from an ... 107 emboss_filter: Performs an emboss filter on an image, simila ... 108 equal_to: Performs a equal-to comparison operation on t ... 109 erase: Removes all the features, or parts of feature ... 110 erase_polygon_from_lidar: Erases (cuts out) a vector polygon or polygon ... 111 erase_polygon_from_raster: Erases (cuts out) a vector polygon from a ras ... 112 euclidean_allocation: Assigns grid cells in the output raster the v ... 113 euclidean_distance: Calculates the Shih and Wu (2004) Euclidean d ... 114 exp: Returns the exponential (base e) of values in ... 115 exp2: Returns the exponential (base 2) of values in ... 116 export_table_to_csv: Exports an attribute table to a CSV text file ... 117 exposure_towards_wind_flux: This tool evaluates hydrologic connectivity w ... 118 extend_vector_lines: Extends vector lines by a specified distance. ... 119 extract_nodes: Converts vector lines or polygons into vertex ... 120 extract_raster_values_at_points: Extracts the values of raster(s) at vector po ... 121 extract_streams: Extracts stream grid cells from a flow accumu ... 122 extract_valleys: Identifies potential valley bottom grid cells ... 123 fd8_flow_accumulation: Calculates an FD8 flow accumulation raster fr ... 124 fd8_pointer: Calculates an FD8 flow pointer raster from an ... 125 farthest_channel_head: Calculates the distance to the furthest upstr ... 126 fast_almost_gaussian_filter: Performs a fast approximate Gaussian filter o ... 127 feature_preserving_smoothing: Reduces short-scale variation in an input DEM ... 128 fetch_analysis: Performs an analysis of fetch or upwind dista ... 129 fill_burn: Burns streams into a DEM using the FillBurn ( ... 130 fill_depressions: Fills all of the depressions in a DEM. Depres ... 131 fill_depressions_planchon_and_darboux: Fills all of the depressions in a DEM using t ... 132 fill_depressions_wang_and_liu: Fills all of the depressions in a DEM using t ... 133 fill_missing_data: Fills NoData holes in a DEM. ... 134 fill_single_cell_pits: Raises pit cells to the elevation of their lo ... 135 filter_lidar_classes: Removes points in a LAS file with certain spe ... 136 filter_lidar_scan_angles: Removes points in a LAS file with scan angles ... 137 filter_raster_features_by_area: Removes small-area features from a raster. ... 138 find_flightline_edge_points: Identifies points along a flightline's edge i ... 139 find_lowest_or_highest_points: Locates the lowest and/or highest valued cell ... 140 find_main_stem: Finds the main stem, based on stream lengths, ... 141 find_no_flow_cells: Finds grid cells with no downslope neighbours ... 142 find_parallel_flow: Finds areas of parallel flow in D8 flow direc ... 143 find_patch_or_class_edge_cells: Finds all cells located on the edge of patch ... 144 find_ridges: Identifies potential ridge and peak grid cell ... 145 flatten_lakes: Flattens lake polygons in a raster DEM. ... 146 flightline_overlap: Reads a LiDAR (LAS) point file and outputs a ... 147 flip_image: Reflects an image in the vertical or horizont ... 148 flood_order: Assigns each DEM grid cell its order in the s ... 149 floor: Returns the largest (closest to positive infi ... 150 flow_accumulation_full_workflow: Resolves all of the depressions in a DEM, out ... 151 flow_length_diff: Calculates the local maximum absolute differe ... 152 gamma_correction: Performs a gamma correction on an input image ... 153 gaussian_contrast_stretch: Performs a Gaussian contrast stretch on input ... 154 gaussian_filter: Performs a Gaussian filter on an image. ... 155 greater_than: Performs a greater-than comparison operation ... 156 hack_stream_order: Assigns the Hack stream order to each tributa ... 157 height_above_ground: Normalizes a LiDAR point cloud, providing the ... 158 high_pass_filter: Performs a high-pass filter on an input image ... 159 high_pass_median_filter: Performs a high pass median filter on an inpu ... 160 highest_position: Identifies the stack position of the maximum ... 161 hillshade: Calculates a hillshade raster from an input D ... 162 hillslopes: Identifies the individual hillslopes draining ... 163 histogram_equalization: Performs a histogram equalization contrast en ... 164 histogram_matching: Alters the statistical distribution of a rast ... 165 histogram_matching_two_images: This tool alters the cumulative distribution ... 166 hole_proportion: Calculates the proportion of the total area o ... 167 horizon_angle: Calculates horizon angle (maximum upwind slop ... 168 horton_stream_order: Assigns the Horton stream order to each tribu ... 169 hypsometric_analysis: Calculates a hypsometric curve for one or mor ... 170 hypsometrically_tinted_hillshade: Creates an colour shaded relief image from an ... 171 idw_interpolation: Interpolates vector points into a raster surf ... 172 ihs_to_rgb: Converts intensity, hue, and saturation (IHS) ... 173 image_autocorrelation: Performs Moran's I analysis on two or more in ... 174 image_correlation: Performs image correlation on two or more inp ... 175 image_correlation_neighbourhood_analysis: Performs image correlation on two input image ... 176 image_regression: Performs image regression analysis on two inp ... 177 image_stack_profile: Plots an image stack profile (i.e. signature) ... 178 impoundment_size_index: Calculates the impoundment size resulting fro ... 179 in_place_add: Performs an in-place addition operation (inpu ... 180 in_place_divide: Performs an in-place division operation (inpu ... 181 in_place_multiply: Performs an in-place multiplication operation ... 182 in_place_subtract: Performs an in-place subtraction operation (i ... 183 increment: Increases the values of each grid cell in an ... 184 insert_dams: Calculates the impoundment size resulting fro ... 185 integer_division: Performs an integer division operation on two ... 186 integral_image: Transforms an input image (summed area table) ... 187 intersect: Identifies the parts of features in common be ... 188 is_no_data: Identifies NoData valued pixels in an image. ... 189 isobasins: Divides a landscape into nearly equal sized d ... 190 jenson_snap_pour_points: Moves outlet points used to specify points of ... 191 join_tables: Merge a vector's attribute table with another ... 192 k_means_clustering: Performs a k-means clustering operation on a ... 193 k_nearest_mean_filter: A k-nearest mean filter is a type of edge-pre ... 194 kappa_index: Performs a kappa index of agreement (KIA) ana ... 195 ks_test_for_normality: Evaluates whether the values in a raster are ... 196 laplacian_filter: Performs a Laplacian filter on an image. ... 197 laplacian_of_gaussian_filter: Performs a Laplacian-of-Gaussian (LoG) filter ... 198 las_to_ascii: Converts one or more LAS files into ASCII tex ... 199 las_to_multipoint_shapefile: Converts one or more LAS files into Multipoin ... 200 las_to_shapefile: Converts one or more LAS files into a vector ... 201 las_to_zlidar: Converts one or more LAS files into the zlida ... 202 layer_footprint: Creates a vector polygon footprint of the are ... 203 lee_sigma_filter: Performs a Lee (Sigma) smoothing filter on an ... 204 length_of_upstream_channels: Calculates the total length of channels upstr ... 205 less_than: Performs a less-than comparison operation on ... 206 lidar_block_maximum: Creates a block-maximum raster from an input ... 207 lidar_block_minimum: Creates a block-minimum raster from an input ... 208 lidar_classify_subset: Classifies the values in one LiDAR point clou ... 209 lidar_colourize: Adds the red-green-blue colour fields of a Li ... 210 lidar_digital_surface_model: Creates a top-surface digital surface model ( ... 211 lidar_elevation_slice: Outputs all of the points within a LiDAR (LAS ... 212 lidar_ground_point_filter: Identifies ground points within LiDAR dataset ... 213 lidar_hex_binning: Hex-bins a set of LiDAR points. ... 214 lidar_hillshade: Calculates a hillshade value for points withi ... 215 lidar_histogram: Creates a histogram of LiDAR data. ... 216 lidar_idw_interpolation: Interpolates LAS files using an inverse-dista ... 217 lidar_info: Prints information about a LiDAR (LAS) datase ... 218 lidar_join: Joins multiple LiDAR (LAS) files into a singl ... 219 lidar_kappa_index: Performs a kappa index of agreement (KIA) ana ... 220 lidar_nearest_neighbour_gridding: Grids LiDAR files using nearest-neighbour sch ... 221 lidar_point_density: Calculates the spatial pattern of point densi ... 222 lidar_point_stats: Creates several rasters summarizing the distr ... 223 lidar_ransac_planes: Performs a RANSAC analysis to identify points ... 224 lidar_rbf_interpolation: Interpolates LAS files using a radial basis f ... 225 lidar_remove_duplicates: Removes duplicate points from a LiDAR data se ... 226 lidar_remove_outliers: Removes outliers (high and low points) in a L ... 227 lidar_rooftop_analysis: Identifies roof segments in a LiDAR point clo ... 228 lidar_segmentation: Segments a LiDAR point cloud based on differe ... 229 lidar_segmentation_based_filter: Identifies ground points within LiDAR point c ... 230 lidar_tin_gridding: Creates a raster grid based on a Delaunay tri ... 231 lidar_thin: Thins a LiDAR point cloud, reducing point den ... 232 lidar_thin_high_density: Thins points from high density areas within a ... 233 lidar_tile: Tiles a LiDAR LAS file into multiple LAS file ... 234 lidar_tile_footprint: Creates a vector polygon of the convex hull o ... 235 lidar_tophat_transform: Performs a white top-hat transform on a Lidar ... 236 line_detection_filter: Performs a line-detection filter on an image. ... 237 line_intersections: Identifies points where the features of two v ... 238 line_thinning: Performs line thinning a on Boolean raster im ... 239 linearity_index: Calculates the linearity index for vector pol ... 240 lines_to_polygons: Converts vector polylines to polygons. ... 241 list_unique_values: Lists the unique values contained in a field ... 242 ln: Returns the natural logarithm of values in a ... 243 log10: Returns the base-10 logarithm of values in a ... 244 log2: Returns the base-2 logarithm of values in a r ... 245 long_profile: Plots the stream longitudinal profiles for on ... 246 long_profile_from_points: Plots the longitudinal profiles from flow-pat ... 247 longest_flowpath: Delineates the longest flowpaths for a group ... 248 lowest_position: Identifies the stack position of the minimum ... 249 md_inf_flow_accumulation: Calculates an FD8 flow accumulation raster fr ... 250 majority_filter: Assigns each cell in the output grid the most ... 251 map_off_terrain_objects: Maps off-terrain objects in a digital elevati ... 252 max: Performs a MAX operation on two rasters or a ... 253 max_absolute_overlay: Evaluates the maximum absolute value for each ... 254 max_anisotropy_dev: Calculates the maximum anisotropy (directiona ... 255 max_anisotropy_dev_signature: Calculates the anisotropy in deviation from m ... 256 max_branch_length: Lindsay and Seibert's (2013) branch length in ... 257 max_difference_from_mean: Calculates the maximum difference from mean e ... 258 max_downslope_elev_change: Calculates the maximum downslope change in el ... 259 max_elev_dev_signature: Calculates the maximum elevation deviation ov ... 260 max_elevation_deviation: Calculates the maximum elevation deviation ov ... 261 max_overlay: Evaluates the maximum value for each grid cel ... 262 max_upslope_flowpath_length: Measures the maximum length of all upslope fl ... 263 maximum_filter: Assigns each cell in the output grid the maxi ... 264 mean_filter: Performs a mean filter (low-pass filter) on a ... 265 median_filter: Performs a median filter on an input image. ... 266 medoid: Calculates the medoid for a series of vector ... 267 merge_line_segments: Merges vector line segments into larger featu ... 268 merge_table_with_csv: Merge a vector's attribute table with a table ... 269 merge_vectors: Combines two or more input vectors of the sam ... 270 min: Performs a MIN operation on two rasters or a ... 271 min_absolute_overlay: Evaluates the minimum absolute value for each ... 272 min_downslope_elev_change: Calculates the minimum downslope change in el ... 273 min_max_contrast_stretch: Performs a min-max contrast stretch on an inp ... 274 min_overlay: Evaluates the minimum value for each grid cel ... 275 minimum_bounding_box: Creates a vector minimum bounding rectangle a ... 276 minimum_bounding_circle: Delineates the minimum bounding circle (i.e. ... 277 minimum_bounding_envelope: Creates a vector axis-aligned minimum boundin ... 278 minimum_convex_hull: Creates a vector convex polygon around vector ... 279 minimum_filter: Assigns each cell in the output grid the mini ... 280 modified_k_means_clustering: Performs a modified k-means clustering operat ... 281 modify_no_data_value: Converts nodata values in a raster to zero. ... 282 modulo: Performs a modulo operation on two rasters or ... 283 mosaic: Mosaics two or more images together. ... 284 mosaic_with_feathering: Mosaics two images together using a featherin ... 285 multi_part_to_single_part: Converts a vector file containing multi-part ... 286 multidirectional_hillshade: Calculates a multi-direction hillshade raster ... 287 multiply: Performs a multiplication operation on two ra ... 288 multiscale_elevation_percentile: Calculates surface roughness over a range of ... 289 multiscale_roughness: Calculates surface roughness over a range of ... 290 multiscale_roughness_signature: Calculates the surface roughness for points o ... 291 multiscale_std_dev_normals: Calculates surface roughness over a range of ... 292 multiscale_std_dev_normals_signature: Calculates the surface roughness for points o ... 293 multiscale_topographic_position_image: Creates a multiscale topographic position ima ... 294 narrowness_index: Calculates the narrowness of raster polygons. ... 295 natural_neighbour_interpolation: Creates a raster grid based on Sibson's natur ... 296 nearest_neighbour_gridding: Creates a raster grid based on a set of vecto ... 297 negate: Changes the sign of values in a raster or the ... 298 new_raster_from_base: Creates a new raster using a base image. ... 299 normal_vectors: Calculates normal vectors for points within a ... 300 normalized_difference_index: Calculate a normalized-difference index (NDI) ... 301 not: Performs a logical NOT operator on two Boolea ... 302 not_equal_to: Performs a not-equal-to comparison operation ... 303 num_downslope_neighbours: Calculates the number of downslope neighbours ... 304 num_inflowing_neighbours: Computes the number of inflowing neighbours t ... 305 num_upslope_neighbours: Calculates the number of upslope neighbours t ... 306 olympic_filter: Performs an olympic smoothing filter on an im ... 307 opening: An opening is a mathematical morphology opera ... 308 or: Performs a logical OR operator on two Boolean ... 309 paired_sample_t_test: Performs a 2-sample K-S test for significant ... 310 panchromatic_sharpening: Increases the spatial resolution of image dat ... 311 patch_orientation: Calculates the orientation of vector polygons ... 312 pennock_landform_class: Classifies hillslope zones based on slope, pr ... 313 percent_elev_range: Calculates percent of elevation range from a ... 314 percent_equal_to: Calculates the percentage of a raster stack t ... 315 percent_greater_than: Calculates the percentage of a raster stack t ... 316 percent_less_than: Calculates the percentage of a raster stack t ... 317 percentage_contrast_stretch: Performs a percentage linear contrast stretch ... 318 percentile_filter: Performs a percentile filter on an input imag ... 319 perimeter_area_ratio: Calculates the perimeter-area ratio of vector ... 320 pick_from_list: Outputs the value from a raster stack specifi ... 321 plan_curvature: Calculates a plan (contour) curvature raster ... 322 polygon_area: Calculates the area of vector polygons. ... 323 polygon_long_axis: This tool can be used to map the long axis of ... 324 polygon_perimeter: Calculates the perimeter of vector polygons. ... 325 polygon_short_axis: This tool can be used to map the short axis o ... 326 polygonize: Creates a polygon layer from two or more inte ... 327 polygons_to_lines: Converts vector polygons to polylines. ... 328 power: Raises the values in grid cells of one raster ... 329 prewitt_filter: Performs a Prewitt edge-detection filter on a ... 330 principal_component_analysis: Performs a principal component analysis (PCA) ... 331 print_geo_tiff_tags: Prints the tags within a GeoTIFF. ... 332 profile: Plots profiles from digital surface models. ... 333 profile_curvature: Calculates a profile curvature raster from an ... 334 qin_flow_accumulation: This tool calculates Qin et al. (2007) flow a ... 335 quantiles: Transforms raster values into quantiles. ... 336 quinn_flow_accumulation: This tool calculates Quinn et al. (1995) flow ... 337 radial_basis_function_interpolation: Interpolates vector points into a raster surf ... 338 radius_of_gyration: Calculates the distance of cells from their p ... 339 raise_walls: Raises walls in a DEM along a line or around ... 340 random_field: Creates an image containing random values. ... 341 random_sample: Creates an image containing randomly located ... 342 range_filter: Assigns each cell in the output grid the rang ... 343 raster_area: Calculates the area of polygons or classes wi ... 344 raster_calculator: This tool performs a conditional evaluaton (i ... 345 raster_cell_assignment: Assign row or column number to cells. ... 346 raster_histogram: Creates a histogram from raster values. ... 347 raster_perimeter: Calculates the perimeters of polygons or clas ... 348 raster_streams_to_vector: Converts a raster stream file into a vector f ... 349 raster_summary_stats: Measures a rasters min, max, average, standar ... 350 raster_to_vector_lines: Converts a raster lines features into a vecto ... 351 raster_to_vector_points: Converts a raster dataset to a vector of the ... 352 raster_to_vector_polygons: Converts a raster dataset to a vector of the ... 353 rasterize_streams: Rasterizes vector streams based on Lindsay (2 ... 354 reciprocal: Returns the reciprocal (i.e. 1 / z) of values ... 355 reclass: Reclassifies the values in a raster image. ... 356 reclass_equal_interval: Reclassifies the values in a raster image bas ... 357 reclass_from_file: Reclassifies the values in a raster image usi ... 358 reinitialize_attribute_table: Reinitializes a vector's attribute table dele ... 359 related_circumscribing_circle: Calculates the related circumscribing circle ... 360 relative_aspect: Calculates relative aspect (relative to a use ... 361 relative_topographic_position: Calculates the relative topographic position ... 362 remove_off_terrain_objects: Removes off-terrain objects from a raster dig ... 363 remove_polygon_holes: Removes holes within the features of a vector ... 364 remove_short_streams: Removes short first-order streams from a stre ... 365 remove_spurs: Removes the spurs (pruning operation) from a ... 366 resample: Resamples one or more input images into a des ... 367 rescale_value_range: Performs a min-max contrast stretch on an inp ... 368 rgb_to_ihs: Converts red, green, and blue (RGB) images in ... 369 rho8_flow_accumulation: This tool calculates Fairfield and Leymarie ( ... 370 rho8_pointer: Calculates a stochastic Rho8 flow pointer ras ... 371 roberts_cross_filter: Performs a Robert's cross edge-detection filt ... 372 root_mean_square_error: Calculates the RMSE and other accuracy statis ... 373 round: Rounds the values in an input raster to the n ... 374 ruggedness_index: Calculates the Riley et al.'s (1999) terrain ... 375 scharr_filter: Performs a Scharr edge-detection filter on an ... 376 sediment_transport_index: Calculates the sediment transport index. ... 377 select_tiles_by_polygon: Copies LiDAR tiles overlapping with a polygon ... 378 set_nodata_value: Assign a specified value in an input image to ... 379 shape_complexity_index: Calculates overall polygon shape complexity o ... 380 shape_complexity_index_raster: Calculates the complexity of raster polygons ... 381 shreve_stream_magnitude: Assigns the Shreve stream magnitude to each l ... 382 sigmoidal_contrast_stretch: Performs a sigmoidal contrast stretch on inpu ... 383 sin: Returns the sine (sin) of each values in a ra ... 384 single_part_to_multi_part: Converts a vector file containing multi-part ... 385 sinh: Returns the hyperbolic sine (sinh) of each va ... 386 sink: Identifies the depressions in a DEM, giving e ... 387 slope: Calculates a slope raster from an input DEM. ... 388 slope_vs_elevation_plot: Creates a slope vs. elevation plot for one or ... 389 smooth_vectors: Smooths a vector coverage of either a POLYLIN ... 390 snap_pour_points: Moves outlet points used to specify points of ... 391 sobel_filter: Performs a Sobel edge-detection filter on an ... 392 spherical_std_dev_of_normals: Calculates the spherical standard deviation o ... 393 split_colour_composite: This tool splits an RGB colour composite imag ... 394 split_vector_lines: This tool can be used to split a vector line ... 395 split_with_lines: Splits the lines or polygons in one layer usi ... 396 square: Squares the values in a raster. ... 397 square_root: Returns the square root of the values in a ra ... 398 standard_deviation_contrast_stretch: Performs a standard-deviation contrast stretc ... 399 standard_deviation_filter: Assigns each cell in the output grid the stan ... 400 standard_deviation_of_slope: Calculates the standard deviation of slope fr ... 401 stochastic_depression_analysis: Performs a stochastic analysis of depressions ... 402 strahler_order_basins: Identifies Strahler-order basins from an inpu ... 403 strahler_stream_order: Assigns the Strahler stream order to each lin ... 404 stream_link_class: Identifies the exterior/interior links and no ... 405 stream_link_identifier: Assigns a unique identifier to each link in a ... 406 stream_link_length: Estimates the length of each link (or tributa ... 407 stream_link_slope: Estimates the average slope of each link (or ... 408 stream_power_index: Calculates the relative stream power index. ... 409 stream_slope_continuous: Estimates the slope of each grid cell in a st ... 410 subbasins: Identifies the catchments, or sub-basin, drai ... 411 subtract: Performs a differencing operation on two rast ... 412 sum_overlay: Calculates the sum for each grid cell from a ... 413 surface_area_ratio: Calculates a the surface area ratio of each g ... 414 symmetrical_difference: Outputs the features that occur in one of the ... 415 tin_gridding: Creates a raster grid based on a triangular i ... 416 tan: Returns the tangent (tan) of each values in a ... 417 tangential_curvature: Calculates a tangential curvature raster from ... 418 tanh: Returns the hyperbolic tangent (tanh) of each ... 419 thicken_raster_line: Thickens single-cell wide lines within a rast ... 420 time_in_daylight: Calculates the proportion of time a location ... 421 to_degrees: Converts a raster from radians to degrees. ... 422 to_radians: Converts a raster from degrees to radians. ... 423 tophat_transform: Performs either a white or black top-hat tran ... 424 topological_stream_order: Assigns each link in a stream network its top ... 425 total_curvature: Calculates a total curvature raster from an i ... 426 total_filter: Performs a total filter on an input image. ... 427 trace_downslope_flowpaths: Traces downslope flowpaths from one or more t ... 428 trend_surface: Estimates the trend surface of an input raste ... 429 trend_surface_vector_points: Estimates a trend surface from vector points. ... 430 tributary_identifier: Assigns a unique identifier to each tributary ... 431 truncate: Truncates the values in a raster to the desir ... 432 turning_bands_simulation: Creates an image containing random values bas ... 433 two_sample_ks_test: Performs a 2-sample K-S test for significant ... 434 union: Splits vector layers at their overlaps, creat ... 435 unnest_basins: Extract whole watersheds for a set of outlet ... 436 unsharp_masking: An image sharpening technique that enhances e ... 437 update_nodata_cells: Replaces the NoData values in an input raster ... 438 upslope_depression_storage: Estimates the average upslope depression stor ... 439 user_defined_weights_filter: Performs a user-defined weights filter on an ... 440 vector_hex_binning: Hex-bins a set of vector points. ... 441 vector_lines_to_raster: Converts a vector containing polylines into a ... 442 vector_points_to_raster: Converts a vector containing points into a ra ... 518 vector_polygons_to_raster: Converts a vector containing polygons into a ... 444 viewshed: Identifies the viewshed for a point or set of ... 445 visibility_index: Estimates the relative visibility of sites in ... 446 voronoi_diagram: Creates a vector Voronoi diagram for a set of ... 447 watershed: Identifies the watershed, or drainage basin, ... 448 weighted_overlay: Performs a weighted sum on multiple input ras ... 449 weighted_sum: Performs a weighted-sum overlay on multiple i ... 450 wetness_index: Calculates the topographic wetness index, Ln( ... 451 wilcoxon_signed_rank_test: Performs a 2-sample K-S test for significant ... 452 write_function_memory_insertion: Performs a write function memory insertion fo ... 453 xor: Performs a logical XOR operator on two Boolea ... 454 z_scores: Standardizes the values in an input raster by ... 455 zlidar_to_las: Converts one or more zlidar files into the LA ... 456 zonal_statistics: Extracts descriptive statistics for a group o ...
This section demonstrates two ways to get data into Binder so that you can test whitebox on the cloud using your own data.
If you have data hosted on your own HTTP server or GitHub, you should be able to get direct URLs. With a direct URL, users can automatically download the data when the URL is clicked. For example https://github.com/giswqs/whitebox/raw/master/examples/testdata.zip
Import the following Python libraries and start getting data from direct URLs.
import os
import zipfile
import tarfile
import shutil
import urllib.request
Create a folder named whitebox under the user home folder and set it as the working directory.
work_dir = os.path.join(os.path.expanduser("~"), 'whitebox')
if not os.path.exists(work_dir):
os.mkdir(work_dir)
os.chdir(work_dir)
print("Working directory: {}".format(work_dir))
Working directory: /home/qiusheng/whitebox
Replace the following URL with your own direct URL hosting your data.
url = "https://github.com/giswqs/whitebox/raw/master/examples/testdata.zip"
Download data the from the above URL and unzip the file if needed.
# download the file
zip_name = os.path.basename(url)
zip_path = os.path.join(work_dir, zip_name)
print('Downloading {} ...'.format(zip_name))
urllib.request.urlretrieve(url, zip_path)
print('Downloading done.'.format(zip_name))
# if it is a zip file
if '.zip' in zip_name:
print("Decompressing {} ...".format(zip_name))
with zipfile.ZipFile(zip_name, "r") as zip_ref:
zip_ref.extractall(work_dir)
print('Decompressing done.')
# if it is a tar file
if '.tar' in zip_name:
print("Decompressing {} ...".format(zip_name))
with tarfile.open(zip_name, "r") as tar_ref:
tar_ref.extractall(work_dir)
print('Decompressing done.')
print('Data directory: {}'.format(os.path.splitext(zip_path)[0]))
Downloading testdata.zip ... Downloading done. Decompressing testdata.zip ... Decompressing done. Data directory: /home/qiusheng/whitebox/testdata
You have successfully downloaded data to Binder. Therefore, you can skip to Using whitebox and start testing whitebox with your own data.
Alternatively, you can upload data to Google Drive and then share files publicly from Google Drive. Once the file is shared publicly, you should be able to get a shareable URL. For example, https://drive.google.com/file/d/1xgxMLRh_jOLRNq-f3T_LXAaSuv9g_JnV.
To download files from Google Drive to Binder, you can use the Python package called google-drive-downloader, which can be installed using the following command:
pip install googledrivedownloader requests
Replace the following URL with your own shareable URL from Google Drive.
gfile_url = 'https://drive.google.com/file/d/1xgxMLRh_jOLRNq-f3T_LXAaSuv9g_JnV'
Extract the file id from the above URL.
file_id = gfile_url.split('/')[5] #'1xgxMLRh_jOLRNq-f3T_LXAaSuv9g_JnV'
print('Google Drive file id: {}'.format(file_id))
Google Drive file id: 1xgxMLRh_jOLRNq-f3T_LXAaSuv9g_JnV
Download the shared file from Google Drive.
from google_drive_downloader import GoogleDriveDownloader as gdd
dest_path = './testdata.zip' # choose a name for the downloaded file
gdd.download_file_from_google_drive(file_id, dest_path, unzip=True)
You have successfully downloaded data from Google Drive to Binder. You can now continue to Using whitebox and start testing whitebox with your own data.
Here you can specify where your data are located. In this example, we will use DEM.tif, which has been downloaded to the testdata folder.
List data under the data folder.
data_dir = './testdata/'
print(os.listdir(data_dir))
['DEM.tif', 'DEM.dep']
In this simple example, we smooth DEM.tif using a feature preserving denoising algorithm. Then, we fill depressions in the DEM using a depression breaching algorithm. Finally, we calculate flow accumulation based on the depressionless DEM.
import whitebox
wbt = whitebox.WhiteboxTools()
# set whitebox working directory
wbt.set_working_dir(data_dir)
wbt.verbose = False
# call whiteboxtool
wbt.feature_preserving_smoothing("DEM.tif", "smoothed.tif", filter=9)
wbt.breach_depressions("smoothed.tif", "breached.tif")
wbt.d_inf_flow_accumulation("breached.tif", "flow_accum.tif")
0
This section demonstrates how to display images on Jupyter Notebook. Three Python packages are used here, including matplotlib, imageio, and tifffile. These three packages can be installed using the following command:
pip install matplotlib imageio tifffile
!pip install matplotlib imageio tifffile
Import the libraries.
# comment out the third line (%matplotlib inline) if you run the tutorial in other IDEs other than Jupyter Notebook
import matplotlib.pyplot as plt
import imageio
%matplotlib inline
Display one single image.
raster = imageio.imread(os.path.join(data_dir, 'DEM.tif'))
plt.imshow(raster)
plt.show()
Read images as numpy arrays.
original = imageio.imread(os.path.join(data_dir, 'DEM.tif'))
smoothed = imageio.imread(os.path.join(data_dir, 'smoothed.tif'))
breached = imageio.imread(os.path.join(data_dir, 'breached.tif'))
flow_accum = imageio.imread(os.path.join(data_dir, 'flow_accum.tif'))
Display multiple images in one plot.
fig=plt.figure(figsize=(16,11))
ax1 = fig.add_subplot(2, 2, 1)
ax1.set_title('Original DEM')
plt.imshow(original)
ax2 = fig.add_subplot(2, 2, 2)
ax2.set_title('Smoothed DEM')
plt.imshow(smoothed)
ax3 = fig.add_subplot(2, 2, 3)
ax3.set_title('Breached DEM')
plt.imshow(breached)
ax4 = fig.add_subplot(2, 2, 4)
ax4.set_title('Flow Accumulation')
plt.imshow(flow_accum)
plt.show()
WhiteboxTools also provides a Graphical User Interface (GUI) - WhiteboxTools Runner, which can be invoked using the following Python script. Note that the GUI might not work in Jupyter notebooks deployed on the cloud (e.g., MyBinder.org), but it should work on Jupyter notebooks on local computers.
import whitebox
whitebox.Runner()
If you use the whitebox Python package for your research and publications, please consider citing the following papers to give Prof. John Lindsay credits for his tremendous efforts in developing Whitebox GAT and WhiteboxTools. Without his work, this whitebox Python package would not exist!
This interactive notebook is made possible by MyBinder.org. Big thanks to MyBinder.org for developing the amazing binder platform, which is extremely valuable for reproducible research!
This tutorial made use a number of open-source Python packages, including Cookiecutter, numpy, matplotlib, imageio, tifffile, and google-drive-downloader. Thanks to all developers of these wonderful Python packages!
If you have any questions regarding this tutorial or the whitebox Python package, you can contact me (Qiusheng Wu) at qwu18@utk.edu or https://wetlands.io/#contact