A tutorial for the whitebox Python package

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.

This tutorial can be accessed in three ways:

Launch this tutorial as an interactive Jupyter Notebook on the cloud - MyBinder.org.

whitebox-gif

Installation

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.

About whitebox

import whitebox and call WhiteboxTools()

In [1]:
import whitebox
wbt = whitebox.WhiteboxTools()

Prints the whitebox-tools help...a listing of available commands

In [2]:
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.
--listtools      Lists all available tools. Keywords may also be used, --listtools slope.
-r, --run        Runs a tool; used in conjuction 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

In [3]:
print(wbt.license())
WhiteboxTools License
Copyright 2017-2019 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

In [4]:
print("Version information: {}".format(wbt.version()))
Version information: WhiteboxTools v1.0.0 by Dr. John B. Lindsay (c) 2017-2019

WhiteboxTools is an advanced geospatial data analysis platform developed at
the University of Guelph's Geomorphometry and Hydrogeomatics Research 
Group (GHRG). See https://jblindsay.github.io/ghrg/WhiteboxTools/index.html
for more details.

Print the help for a specific tool.

In [5]:
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.

In [6]:
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")
Out[6]:
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.

In [7]:
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 classify_overlap_points: Classifies or filters LAS points in regions o ...
002 clip_lidar_to_polygon: Clips a LiDAR point cloud to a vector polygon ...
003 erase_polygon_from_lidar: Erases (cuts out) a vector polygon or polygon ...
004 filter_lidar_classes: Removes points in a LAS file with certain spe ...
005 filter_lidar_scan_angles: Removes points in a LAS file with scan angles ...
006 find_flightline_edge_points: Identifies points along a flightline's edge i ...
007 find_patch_or_class_edge_cells: Finds all cells located on the edge of patch  ...
008 flightline_overlap: Reads a LiDAR (LAS) point file and outputs a  ...
009 las_to_ascii: Converts one or more LAS files into ASCII tex ...
010 las_to_multipoint_shapefile: Converts one or more LAS files into Multipoin ...
011 las_to_shapefile: Converts one or more LAS files into a vector  ...
012 lidar_block_maximum: Creates a block-maximum raster from an input  ...
013 lidar_block_minimum: Creates a block-minimum raster from an input  ...
014 lidar_classify_subset: Classifies the values in one LiDAR point clou ...
015 lidar_colourize: Adds the red-green-blue colour fields of a Li ...
016 lidar_construct_vector_tin: Creates a vector triangular irregular network ...
017 lidar_elevation_slice: Outputs all of the points within a LiDAR (LAS ...
018 lidar_ground_point_filter: Identifies ground points within LiDAR dataset ...
019 lidar_hex_binning: Hex-bins a set of LiDAR points. ...
020 lidar_hillshade: Calculates a hillshade value for points withi ...
021 lidar_histogram: Creates a histogram of LiDAR data. ...
022 lidar_idw_interpolation: Interpolates LAS files using an inverse-dista ...
023 lidar_info: Prints information about a LiDAR (LAS) datase ...
024 lidar_join: Joins multiple LiDAR (LAS) files into a singl ...
025 lidar_kappa_index: Performs a kappa index of agreement (KIA) ana ...
026 lidar_nearest_neighbour_gridding: Grids LAS files using nearest-neighbour schem ...
027 lidar_point_density: Calculates the spatial pattern of point densi ...
028 lidar_point_stats: Creates several rasters summarizing the distr ...
029 lidar_ransac_planes: Removes outliers (high and low points) in a L ...
030 lidar_remove_duplicates: Removes duplicate points from a LiDAR data se ...
031 lidar_remove_outliers: Removes outliers (high and low points) in a L ...
032 lidar_segmentation: Segments a LiDAR point cloud based on normal  ...
033 lidar_segmentation_based_filter: Identifies ground points within LiDAR point c ...
034 lidar_tin_gridding: Creates a raster grid based on a Delaunay tri ...
035 lidar_thin: Thins a LiDAR point cloud, reducing point den ...
036 lidar_thin_high_density: Thins points from high density areas within a ...
037 lidar_tile: Tiles a LiDAR LAS file into multiple LAS file ...
038 lidar_tile_footprint: Creates a vector polygon of the convex hull o ...
039 lidar_tophat_transform: Performs a white top-hat transform on a Lidar ...
040 normal_vectors: Calculates normal vectors for points within a ...
041 pennock_landform_class: Classifies hillslope zones based on slope, pr ...
042 raster_area: Calculates the area of polygons or classes wi ...
043 raster_cell_assignment: Assign row or column number to cells. ...
044 reclass: Reclassifies the values in a raster image. ...
045 reclass_equal_interval: Reclassifies the values in a raster image bas ...
046 reclass_from_file: Reclassifies the values in a raster image usi ...
047 select_tiles_by_polygon: Copies LiDAR tiles overlapping with a polygon ...
048 shape_complexity_index_raster: Calculates the complexity of raster polygons  ...
049 stream_link_class: Identifies the exterior/interior links and no ...

List all available tools in whitebox-tools. Currently, whitebox contains 372 tools. More tools will be added as they become available.

In [8]:
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 aspect: Calculates an aspect raster from an input DEM ...
012 atan2: Returns the 2-argument inverse tangent (atan2 ...
013 attribute_correlation: Performs a correlation analysis on attribute  ...
014 attribute_histogram: Creates a histogram for the field values of a ...
015 attribute_scattergram: Creates a scattergram for two field values of ...
016 average_flowpath_slope: Measures the average slope gradient from each ...
017 average_normal_vector_angular_deviation: Calculates the circular variance of aspect at ...
018 average_overlay: Calculates the average for each grid cell fro ...
019 average_upslope_flowpath_length: Measures the average length of all upslope fl ...
020 balance_contrast_enhancement: Performs a balance contrast enhancement on a  ...
021 basins: Identifies drainage basins that drain to the  ...
022 bilateral_filter: A bilateral filter is an edge-preserving smoo ...
023 block_maximum_gridding: Creates a raster grid based on a set of vecto ...
024 block_minimum_gridding: Creates a raster grid based on a set of vecto ...
025 boundary_shape_complexity: Calculates the complexity of the boundaries o ...
026 breach_depressions: Breaches all of the depressions in a DEM usin ...
027 breach_single_cell_pits: Removes single-cell pits from an input DEM by ...
028 buffer_raster: Maps a distance-based buffer around each non- ...
029 ceil: Returns the smallest (closest to negative inf ...
030 centroid: Calculates the centroid, or average location, ...
031 centroid_vector: Identifes the centroid point of a vector poly ...
032 change_vector_analysis: Performs a change vector analysis on a two-da ...
033 circular_variance_of_aspect: Calculates the circular variance of aspect at ...
034 classify_overlap_points: Classifies or filters LAS points in regions o ...
035 clean_vector: Removes null features and lines/polygons with ...
036 clip: Extract all the features, or parts of feature ...
037 clip_lidar_to_polygon: Clips a LiDAR point cloud to a vector polygon ...
038 clip_raster_to_polygon: Clips a raster to a vector polygon. ...
039 closing: A closing is a mathematical morphology operat ...
040 clump: Groups cells that form discrete areas, assign ...
041 compactness_ratio: Calculates the compactness ratio (A/P), a mea ...
042 conservative_smoothing_filter: Performs a conservative-smoothing filter on a ...
043 construct_vector_tin: Creates a vector triangular irregular network ...
044 convert_nodata_to_zero: Converts nodata values in a raster to zero. ...
045 convert_raster_format: Converts raster data from one format to anoth ...
046 corner_detection: Identifies corner patterns in boolean images  ...
047 correct_vignetting: Corrects the darkening of images towards corn ...
048 cos: Returns the cosine (cos) of each values in a  ...
049 cosh: Returns the hyperbolic cosine (cosh) of each  ...
050 cost_allocation: Identifies the source cell to which each grid ...
051 cost_distance: Performs cost-distance accumulation on a cost ...
052 cost_pathway: Performs cost-distance pathway analysis using ...
053 count_if: Counts the number of occurrences of a specifi ...
054 create_colour_composite: Creates a colour-composite image from three b ...
055 create_hexagonal_vector_grid: Creates a hexagonal vector grid. ...
056 create_plane: Creates a raster image based on the equation  ...
057 create_rectangular_vector_grid: Creates a rectangular vector grid. ...
058 crispness_index: Calculates the Crispness Index, which is used ...
059 cross_tabulation: Performs a cross-tabulation on two categorica ...
060 csv_points_to_vector: Converts a CSV text file to vector points. ...
061 cumulative_distribution: Converts a raster image to its cumulative dis ...
062 d8_flow_accumulation: Calculates a D8 flow accumulation raster from ...
063 d8_mass_flux: Performs a D8 mass flux calculation. ...
064 d8_pointer: Calculates a D8 flow pointer raster from an i ...
065 d_inf_flow_accumulation: Calculates a D-infinity flow accumulation ras ...
066 d_inf_mass_flux: Performs a D-infinity mass flux calculation. ...
067 d_inf_pointer: Calculates a D-infinity flow pointer (flow di ...
068 decrement: Decreases the values of each grid cell in an  ...
069 depth_in_sink: Measures the depth of sinks (depressions) in  ...
070 dev_from_mean_elev: Calculates deviation from mean elevation. ...
071 diff_from_mean_elev: Calculates difference from mean elevation (eq ...
072 diff_of_gaussian_filter: Performs a Difference of Gaussian (DoG) filte ...
073 difference: Outputs the features that occur in one of the ...
074 direct_decorrelation_stretch: Performs a direct decorrelation stretch enhan ...
075 directional_relief: Calculates relief for cells in an input DEM f ...
076 dissolve: Removes the interior, or shared, boundaries w ...
077 distance_to_outlet: Calculates the distance of stream grid cells  ...
078 diversity_filter: Assigns each cell in the output grid the numb ...
079 divide: Performs a division operation on two rasters  ...
080 downslope_distance_to_stream: Measures distance to the nearest downslope st ...
081 downslope_flowpath_length: Calculates the downslope flowpath length from ...
082 downslope_index: Calculates the Hjerdt et al. (2004) downslope ...
083 edge_density: Calculates the density of edges, or breaks-in ...
084 edge_preserving_mean_filter: Performs a simple edge-preserving mean filter ...
085 edge_proportion: Calculate the proportion of cells in a raster ...
086 elev_above_pit: Calculate the elevation of each grid cell abo ...
087 elev_percentile: Calculates the elevation percentile raster fr ...
088 elev_relative_to_min_max: Calculates the elevation of a location relati ...
089 elev_relative_to_watershed_min_max: Calculates the elevation of a location relati ...
090 elevation_above_stream: Calculates the elevation of cells above the n ...
091 elevation_above_stream_euclidean: Calculates the elevation of cells above the n ...
092 eliminate_coincident_points: Removes any coincident, or nearly coincident, ...
093 elongation_ratio: Calculates the elongation ratio for vector po ...
094 emboss_filter: Performs an emboss filter on an image, simila ...
095 equal_to: Performs a equal-to comparison operation on t ...
096 erase: Removes all the features, or parts of feature ...
097 erase_polygon_from_lidar: Erases (cuts out) a vector polygon or polygon ...
098 erase_polygon_from_raster: Erases (cuts out) a vector polygon from a ras ...
099 euclidean_allocation: Assigns grid cells in the output raster the v ...
100 euclidean_distance: Calculates the Shih and Wu (2004) Euclidean d ...
101 exp: Returns the exponential (base e) of values in ...
102 exp2: Returns the exponential (base 2) of values in ...
103 export_table_to_csv: Exports an attribute table to a CSV text file ...
104 extend_vector_lines: Extends vector lines by a specified distance. ...
105 extract_nodes: Converts vector lines or polygons into vertex ...
106 extract_raster_values_at_points: Extracts the values of raster(s) at vector po ...
107 extract_streams: Extracts stream grid cells from a flow accumu ...
108 extract_valleys: Identifies potential valley bottom grid cells ...
109 fd8_flow_accumulation: Calculates an FD8 flow accumulation raster fr ...
110 fd8_pointer: Calculates an FD8 flow pointer raster from an ...
111 farthest_channel_head: Calculates the distance to the furthest upstr ...
112 fast_almost_gaussian_filter: Performs a fast approximate Gaussian filter o ...
113 feature_preserving_smoothing: Reduces short-scale variation in an input DEM ...
114 fetch_analysis: Performs an analysis of fetch or upwind dista ...
115 fill_burn: Burns streams into a DEM using the FillBurn ( ...
116 fill_depressions: Fills all of the depressions in a DEM. Depres ...
117 fill_missing_data: Fills NoData holes in a DEM. ...
118 fill_single_cell_pits: Raises pit cells to the elevation of their lo ...
119 filter_lidar_classes: Removes points in a LAS file with certain spe ...
120 filter_lidar_scan_angles: Removes points in a LAS file with scan angles ...
121 find_flightline_edge_points: Identifies points along a flightline's edge i ...
122 find_lowest_or_highest_points: Locates the lowest and/or highest valued cell ...
123 find_main_stem: Finds the main stem, based on stream lengths, ...
124 find_no_flow_cells: Finds grid cells with no downslope neighbours ...
125 find_parallel_flow: Finds areas of parallel flow in D8 flow direc ...
126 find_patch_or_class_edge_cells: Finds all cells located on the edge of patch  ...
127 find_ridges: Identifies potential ridge and peak grid cell ...
128 flatten_lakes: Flattens lake polygons in a raster DEM. ...
129 flightline_overlap: Reads a LiDAR (LAS) point file and outputs a  ...
130 flip_image: Reflects an image in the vertical or horizont ...
131 flood_order: Assigns each DEM grid cell its order in the s ...
132 floor: Returns the largest (closest to positive infi ...
133 flow_accumulation_full_workflow: Resolves all of the depressions in a DEM, out ...
134 flow_length_diff: Calculates the local maximum absolute differe ...
135 gamma_correction: Performs a gamma correction on an input image ...
136 gaussian_contrast_stretch: Performs a Gaussian contrast stretch on input ...
137 gaussian_filter: Performs a Gaussian filter on an image. ...
138 greater_than: Performs a greater-than comparison operation  ...
139 hack_stream_order: Assigns the Hack stream order to each tributa ...
140 high_pass_filter: Performs a high-pass filter on an input image ...
141 high_pass_median_filter: Performs a high pass median filter on an inpu ...
142 highest_position: Identifies the stack position of the maximum  ...
143 hillshade: Calculates a hillshade raster from an input D ...
144 hillslopes: Identifies the individual hillslopes draining ...
145 histogram_equalization: Performs a histogram equalization contrast en ...
146 histogram_matching: Alters the statistical distribution of a rast ...
147 histogram_matching_two_images: This tool alters the cumulative distribution  ...
148 hole_proportion: Calculates the proportion of the total area o ...
149 horizon_angle: Calculates horizon angle (maximum upwind slop ...
150 horton_stream_order: Assigns the Horton stream order to each tribu ...
151 hypsometric_analysis: Calculates a hypsometric curve for one or mor ...
152 idw_interpolation: Interpolates vector points into a raster surf ...
153 ihs_to_rgb: Converts intensity, hue, and saturation (IHS) ...
154 image_autocorrelation: Performs Moran's I analysis on two or more in ...
155 image_correlation: Performs image correlation on two or more inp ...
156 image_regression: Performs image regression analysis on two inp ...
157 image_stack_profile: Plots an image stack profile (i.e. signature) ...
158 impoundment_size_index: Calculates the impoundment size resulting fro ...
159 in_place_add: Performs an in-place addition operation (inpu ...
160 in_place_divide: Performs an in-place division operation (inpu ...
161 in_place_multiply: Performs an in-place multiplication operation ...
162 in_place_subtract: Performs an in-place subtraction operation (i ...
163 increment: Increases the values of each grid cell in an  ...
164 integer_division: Performs an integer division operation on two ...
165 integral_image: Transforms an input image (summed area table) ...
166 intersect: Identifies the parts of features in common be ...
167 is_no_data: Identifies NoData valued pixels in an image. ...
168 isobasins: Divides a landscape into nearly equal sized d ...
169 jenson_snap_pour_points: Moves outlet points used to specify points of ...
170 join_tables: Merge a vector's attribute table with another ...
171 k_means_clustering: Performs a k-means clustering operation on a  ...
172 k_nearest_mean_filter: A k-nearest mean filter is a type of edge-pre ...
173 ks_test_for_normality: Evaluates whether the values in a raster are  ...
174 kappa_index: Performs a kappa index of agreement (KIA) ana ...
175 laplacian_filter: Performs a Laplacian filter on an image. ...
176 laplacian_of_gaussian_filter: Performs a Laplacian-of-Gaussian (LoG) filter ...
177 las_to_ascii: Converts one or more LAS files into ASCII tex ...
178 las_to_multipoint_shapefile: Converts one or more LAS files into Multipoin ...
179 las_to_shapefile: Converts one or more LAS files into a vector  ...
180 layer_footprint: Creates a vector polygon footprint of the are ...
181 lee_filter: Performs a Lee (Sigma) smoothing filter on an ...
182 length_of_upstream_channels: Calculates the total length of channels upstr ...
183 less_than: Performs a less-than comparison operation on  ...
184 lidar_block_maximum: Creates a block-maximum raster from an input  ...
185 lidar_block_minimum: Creates a block-minimum raster from an input  ...
186 lidar_classify_subset: Classifies the values in one LiDAR point clou ...
187 lidar_colourize: Adds the red-green-blue colour fields of a Li ...
188 lidar_construct_vector_tin: Creates a vector triangular irregular network ...
189 lidar_elevation_slice: Outputs all of the points within a LiDAR (LAS ...
190 lidar_ground_point_filter: Identifies ground points within LiDAR dataset ...
191 lidar_hex_binning: Hex-bins a set of LiDAR points. ...
192 lidar_hillshade: Calculates a hillshade value for points withi ...
193 lidar_histogram: Creates a histogram of LiDAR data. ...
194 lidar_idw_interpolation: Interpolates LAS files using an inverse-dista ...
195 lidar_info: Prints information about a LiDAR (LAS) datase ...
196 lidar_join: Joins multiple LiDAR (LAS) files into a singl ...
197 lidar_kappa_index: Performs a kappa index of agreement (KIA) ana ...
198 lidar_nearest_neighbour_gridding: Grids LAS files using nearest-neighbour schem ...
199 lidar_point_density: Calculates the spatial pattern of point densi ...
200 lidar_point_stats: Creates several rasters summarizing the distr ...
201 lidar_ransac_planes: Removes outliers (high and low points) in a L ...
202 lidar_remove_duplicates: Removes duplicate points from a LiDAR data se ...
203 lidar_remove_outliers: Removes outliers (high and low points) in a L ...
204 lidar_segmentation: Segments a LiDAR point cloud based on normal  ...
205 lidar_segmentation_based_filter: Identifies ground points within LiDAR point c ...
206 lidar_tin_gridding: Creates a raster grid based on a Delaunay tri ...
207 lidar_thin: Thins a LiDAR point cloud, reducing point den ...
208 lidar_thin_high_density: Thins points from high density areas within a ...
209 lidar_tile: Tiles a LiDAR LAS file into multiple LAS file ...
210 lidar_tile_footprint: Creates a vector polygon of the convex hull o ...
211 lidar_tophat_transform: Performs a white top-hat transform on a Lidar ...
212 line_detection_filter: Performs a line-detection filter on an image. ...
213 line_intersections: Identifies points where the features of two v ...
214 line_thinning: Performs line thinning a on Boolean raster im ...
215 linearity_index: Calculates the linearity index for vector pol ...
216 lines_to_polygons: Converts vector polylines to polygons. ...
217 list_unique_values: Lists the unique values contained in a field  ...
218 ln: Returns the natural logarithm of values in a  ...
219 log10: Returns the base-10 logarithm of values in a  ...
220 log2: Returns the base-2 logarithm of values in a r ...
221 long_profile: Plots the stream longitudinal profiles for on ...
222 long_profile_from_points: Plots the longitudinal profiles from flow-pat ...
223 longest_flowpath: Delineates the longest flowpaths for a group  ...
224 lowest_position: Identifies the stack position of the minimum  ...
225 majority_filter: Assigns each cell in the output grid the most ...
226 max: Performs a MAX operation on two rasters or a  ...
227 max_absolute_overlay: Evaluates the maximum absolute value for each ...
228 max_anisotropy_dev: Calculates the maximum anisotropy (directiona ...
229 max_anisotropy_dev_signature: Calculates the anisotropy in deviation from m ...
230 max_branch_length: Lindsay and Seibert's (2013) branch length in ...
231 max_difference_from_mean: Calculates the maximum difference from mean e ...
232 max_downslope_elev_change: Calculates the maximum downslope change in el ...
233 max_elev_dev_signature: Calculates the maximum elevation deviation ov ...
234 max_elevation_deviation: Calculates the maximum elevation deviation ov ...
235 max_overlay: Evaluates the maximum value for each grid cel ...
236 max_upslope_flowpath_length: Measures the maximum length of all upslope fl ...
237 maximum_filter: Assigns each cell in the output grid the maxi ...
238 mean_filter: Performs a mean filter (low-pass filter) on a ...
239 median_filter: Performs a median filter on an input image. ...
240 medoid: Calculates the medoid for a series of vector  ...
241 merge_line_segments: Merges vector line segments into larger featu ...
242 merge_table_with_csv: Merge a vector's attribute table with a table ...
243 merge_vectors: Combines two or more input vectors of the sam ...
244 min: Performs a MIN operation on two rasters or a  ...
245 min_absolute_overlay: Evaluates the minimum absolute value for each ...
246 min_downslope_elev_change: Calculates the minimum downslope change in el ...
247 min_max_contrast_stretch: Performs a min-max contrast stretch on an inp ...
248 min_overlay: Evaluates the minimum value for each grid cel ...
249 minimum_bounding_box: Creates a vector minimum bounding rectangle a ...
250 minimum_bounding_circle: Delineates the minimum bounding circle (i.e.  ...
251 minimum_bounding_envelope: Creates a vector axis-aligned minimum boundin ...
252 minimum_convex_hull: Creates a vector convex polygon around vector ...
253 minimum_filter: Assigns each cell in the output grid the mini ...
254 modified_k_means_clustering: Performs a modified k-means clustering operat ...
255 modify_no_data_value: Converts nodata values in a raster to zero. ...
256 modulo: Performs a modulo operation on two rasters or ...
257 mosaic: Mosaics two or more images together. ...
258 mosaic_with_feathering: Mosaics two images together using a featherin ...
259 multi_part_to_single_part: Converts a vector file containing multi-part  ...
260 multiply: Performs a multiplication operation on two ra ...
261 multiscale_roughness: Calculates surface roughness over a range of  ...
262 multiscale_roughness_signature: Calculates the surface roughness for points o ...
263 multiscale_std_dev_normals: Calculates surface roughness over a range of  ...
264 multiscale_std_dev_normals_signature: Calculates the surface roughness for points o ...
265 multiscale_topographic_position_image: Creates a multiscale topographic position ima ...
266 narrowness_index: Calculates the narrowness of raster polygons. ...
267 nearest_neighbour_gridding: Creates a raster grid based on a set of vecto ...
268 negate: Changes the sign of values in a raster or the ...
269 new_raster_from_base: Creates a new raster using a base image. ...
270 normal_vectors: Calculates normal vectors for points within a ...
271 normalized_difference_index: Calculate a normalized-difference index (NDI) ...
272 not: Performs a logical NOT operator on two Boolea ...
273 not_equal_to: Performs a not-equal-to comparison operation  ...
274 num_downslope_neighbours: Calculates the number of downslope neighbours ...
275 num_inflowing_neighbours: Computes the number of inflowing neighbours t ...
276 num_upslope_neighbours: Calculates the number of upslope neighbours t ...
277 olympic_filter: Performs an olympic smoothing filter on an im ...
278 opening: An opening is a mathematical morphology opera ...
279 or: Performs a logical OR operator on two Boolean ...
280 panchromatic_sharpening: Increases the spatial resolution of image dat ...
281 patch_orientation: Calculates the orientation of vector polygons ...
282 pennock_landform_class: Classifies hillslope zones based on slope, pr ...
283 percent_elev_range: Calculates percent of elevation range from a  ...
284 percent_equal_to: Calculates the percentage of a raster stack t ...
285 percent_greater_than: Calculates the percentage of a raster stack t ...
286 percent_less_than: Calculates the percentage of a raster stack t ...
287 percentage_contrast_stretch: Performs a percentage linear contrast stretch ...
288 percentile_filter: Performs a percentile filter on an input imag ...
289 perimeter_area_ratio: Calculates the perimeter-area ratio of vector ...
290 pick_from_list: Outputs the value from a raster stack specifi ...
291 plan_curvature: Calculates a plan (contour) curvature raster  ...
292 polygon_area: Calculates the area of vector polygons. ...
293 polygon_long_axis: This tool can be used to map the long axis of ...
294 polygon_perimeter: Calculates the perimeter of vector polygons. ...
295 polygon_short_axis: This tool can be used to map the short axis o ...
296 polygonize: Creates a polygon layer from two or more inte ...
297 polygons_to_lines: Converts vector polygons to polylines. ...
298 power: Raises the values in grid cells of one raster ...
299 prewitt_filter: Performs a Prewitt edge-detection filter on a ...
300 principal_component_analysis: Performs a principal component analysis (PCA) ...
301 print_geo_tiff_tags: Prints the tags within a GeoTIFF. ...
302 profile: Plots profiles from digital surface models. ...
303 profile_curvature: Calculates a profile curvature raster from an ...
304 quantiles: Transforms raster values into quantiles. ...
305 radius_of_gyration: Calculates the distance of cells from their p ...
306 raise_walls: Raises walls in a DEM along a line or around  ...
307 random_field: Creates an image containing random values. ...
308 random_sample: Creates an image containing randomly located  ...
309 range_filter: Assigns each cell in the output grid the rang ...
310 raster_area: Calculates the area of polygons or classes wi ...
311 raster_cell_assignment: Assign row or column number to cells. ...
312 raster_histogram: Creates a histogram from raster values. ...
313 raster_streams_to_vector: Converts a raster stream file into a vector f ...
314 raster_summary_stats: Measures a rasters min, max, average, standar ...
315 raster_to_vector_lines: Converts a raster lines features into a vecto ...
316 raster_to_vector_points: Converts a raster dataset to a vector of the  ...
317 rasterize_streams: Rasterizes vector streams based on Lindsay (2 ...
318 reciprocal: Returns the reciprocal (i.e. 1 / z) of values ...
319 reclass: Reclassifies the values in a raster image. ...
320 reclass_equal_interval: Reclassifies the values in a raster image bas ...
321 reclass_from_file: Reclassifies the values in a raster image usi ...
322 reinitialize_attribute_table: Reinitializes a vector's attribute table dele ...
323 related_circumscribing_circle: Calculates the related circumscribing circle  ...
324 relative_aspect: Calculates relative aspect (relative to a use ...
325 relative_stream_power_index: Calculates the relative stream power index. ...
326 relative_topographic_position: Calculates the relative topographic position  ...
327 remove_off_terrain_objects: Removes off-terrain objects from a raster dig ...
328 remove_polygon_holes: Removes holes within the features of a vector ...
329 remove_short_streams: Removes short first-order streams from a stre ...
330 remove_spurs: Removes the spurs (pruning operation) from a  ...
331 resample: Resamples one or more input images into a des ...
332 rescale_value_range: Performs a min-max contrast stretch on an inp ...
333 rgb_to_ihs: Converts red, green, and blue (RGB) images in ...
334 rho8_pointer: Calculates a stochastic Rho8 flow pointer ras ...
335 roberts_cross_filter: Performs a Robert's cross edge-detection filt ...
336 root_mean_square_error: Calculates the RMSE and other accuracy statis ...
337 round: Rounds the values in an input raster to the n ...
338 ruggedness_index: Calculates the Riley et al.'s (1999) terrain  ...
339 scharr_filter: Performs a Scharr edge-detection filter on an ...
340 sediment_transport_index: Calculates the sediment transport index. ...
341 select_tiles_by_polygon: Copies LiDAR tiles overlapping with a polygon ...
342 set_nodata_value: Assign a specified value in an input image to ...
343 shape_complexity_index: Calculates overall polygon shape complexity o ...
344 shape_complexity_index_raster: Calculates the complexity of raster polygons  ...
345 shreve_stream_magnitude: Assigns the Shreve stream magnitude to each l ...
346 sigmoidal_contrast_stretch: Performs a sigmoidal contrast stretch on inpu ...
347 sin: Returns the sine (sin) of each values in a ra ...
348 single_part_to_multi_part: Converts a vector file containing multi-part  ...
349 sinh: Returns the hyperbolic sine (sinh) of each va ...
350 sink: Identifies the depressions in a DEM, giving e ...
351 slope: Calculates a slope raster from an input DEM. ...
352 slope_vs_elevation_plot: Creates a slope vs. elevation plot for one or ...
353 smooth_vectors: Smooths a vector coverage of either a POLYLIN ...
354 snap_pour_points: Moves outlet points used to specify points of ...
355 sobel_filter: Performs a Sobel edge-detection filter on an  ...
356 spherical_std_dev_of_normals: Calculates the spherical standard deviation o ...
357 split_colour_composite: This tool splits an RGB colour composite imag ...
358 split_with_lines: Splits the lines or polygons in one layer usi ...
359 square: Squares the values in a raster. ...
360 square_root: Returns the square root of the values in a ra ...
361 standard_deviation_contrast_stretch: Performs a standard-deviation contrast stretc ...
362 standard_deviation_filter: Assigns each cell in the output grid the stan ...
363 standard_deviation_of_slope: Calculates the standard deviation of slope fr ...
364 stochastic_depression_analysis: Preforms a stochastic analysis of depressions ...
365 strahler_order_basins: Identifies Strahler-order basins from an inpu ...
366 strahler_stream_order: Assigns the Strahler stream order to each lin ...
367 stream_link_class: Identifies the exterior/interior links and no ...
368 stream_link_identifier: Assigns a unique identifier to each link in a ...
369 stream_link_length: Estimates the length of each link (or tributa ...
370 stream_link_slope: Estimates the average slope of each link (or  ...
371 stream_slope_continuous: Estimates the slope of each grid cell in a st ...
372 subbasins: Identifies the catchments, or sub-basin, drai ...
373 subtract: Performs a differencing operation on two rast ...
374 sum_overlay: Calculates the sum for each grid cell from a  ...
375 surface_area_ratio: Calculates a the surface area ratio of each g ...
376 symmetrical_difference: Outputs the features that occur in one of the ...
377 tin_gridding: Creates a raster grid based on a triangular i ...
378 tan: Returns the tangent (tan) of each values in a ...
379 tangential_curvature: Calculates a tangential curvature raster from ...
380 tanh: Returns the hyperbolic tangent (tanh) of each ...
381 thicken_raster_line: Thickens single-cell wide lines within a rast ...
382 to_degrees: Converts a raster from radians to degrees. ...
383 to_radians: Converts a raster from degrees to radians. ...
384 tophat_transform: Performs either a white or black top-hat tran ...
385 topological_stream_order: Assigns each link in a stream network its top ...
386 total_curvature: Calculates a total curvature raster from an i ...
387 total_filter: Performs a total filter on an input image. ...
388 trace_downslope_flowpaths: Traces downslope flowpaths from one or more t ...
389 trend_surface: Estimates the trend surface of an input raste ...
390 trend_surface_vector_points: Estimates a trend surface from vector points. ...
391 tributary_identifier: Assigns a unique identifier to each tributary ...
392 truncate: Truncates the values in a raster to the desir ...
393 turning_bands_simulation: Creates an image containing random values bas ...
394 union: Splits vector layers at their overlaps, creat ...
395 unnest_basins: Extract whole watersheds for a set of outlet  ...
396 unsharp_masking: An image sharpening technique that enhances e ...
397 user_defined_weights_filter: Performs a user-defined weights filter on an  ...
398 vector_hex_binning: Hex-bins a set of vector points. ...
399 vector_lines_to_raster: Converts a vector containing polylines into a ...
400 vector_points_to_raster: Converts a vector containing points into a ra ...
401 vector_polygons_to_raster: Converts a vector containing polygons into a  ...
402 viewshed: Identifies the viewshed for a point or set of ...
403 visibility_index: Estimates the relative visibility of sites in ...
404 voronoi_diagram: Creates a vector Voronoi diagram for a set of ...
405 watershed: Identifies the watershed, or drainage basin,  ...
406 weighted_overlay: Performs a weighted sum on multiple input ras ...
407 weighted_sum: Performs a weighted-sum overlay on multiple i ...
408 wetness_index: Calculates the topographic wetness index, Ln( ...
409 write_function_memory_insertion: Performs a write function memory insertion fo ...
410 xor: Performs a logical XOR operator on two Boolea ...
411 z_scores: Standardizes the values in an input raster by ...
412 zonal_statistics: Extracts descriptive statistics for a group o ...

Getting data

This section demonstrates two ways to get data into Binder so that you can test whitebox on the cloud using your own data.

Getting data from direct URLs

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.

In [9]:
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.

In [10]:
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.

In [11]:
url = "https://github.com/giswqs/whitebox/raw/master/examples/testdata.zip"

Download data the from the above URL and unzip the file if needed.

In [12]:
# 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.

Getting data from Google Drive

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.

In [13]:
gfile_url = 'https://drive.google.com/file/d/1xgxMLRh_jOLRNq-f3T_LXAaSuv9g_JnV'

Extract the file id from the above URL.

In [14]:
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.

In [15]:
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.

Using whitebox

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.

In [16]:
data_dir = './testdata/'
print(os.listdir(data_dir))
['breached_sink.tif', 'DEM.dep', 'smoothed.tif', 'DEM.tif.aux.xml', 'DEM.tif', 'breached_sink.tif.aux.xml']

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.

In [17]:
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")
Out[17]:
0

Displaying results

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

Import the libraries.

In [18]:
# 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.

In [19]:
raster = imageio.imread(os.path.join(data_dir, 'DEM.tif'))
plt.imshow(raster)
plt.show()

Read images as numpy arrays.

In [20]:
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.

In [21]:
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()

whitebox GUI

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()

Citing whitebox

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!

Credits

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!

Contact

If you have any questions regarding this tutorial or the whitebox Python package, you can contact me (Dr. Qiusheng Wu) at [email protected] or https://wetlands.io/#contact