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