├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Qiusheng Wu 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # WhiteboxTools Frontends 2 | 3 | [![docs](https://img.shields.io/badge/whitebox-Docs-brightgreen.svg)](https://jblindsay.github.io/wbt_book) 4 | [![frontends](https://img.shields.io/badge/whitebox-Frontends-yellowgreen.svg)](https://github.com/giswqs/whitebox-frontends) 5 | [![Rust](https://img.shields.io/badge/whitebox-Rust-yellow.svg)](https://github.com/jblindsay/whitebox-tools) 6 | [![python](https://img.shields.io/badge/whitebox-Python-blue.svg)](https://github.com/giswqs/whitebox-python) 7 | [![R](https://img.shields.io/badge/whitebox-R-green.svg)](https://github.com/giswqs/whiteboxR) 8 | [![ArcGIS](https://img.shields.io/badge/whitebox-ArcGIS-brightgreen.svg)](https://github.com/giswqs/WhiteboxTools-ArcGIS) 9 | [![QGIS](https://img.shields.io/badge/whitebox-QGIS-orange.svg)](https://jblindsay.github.io/wbt_book/qgis_plugin.html) 10 | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 11 | [![image](https://img.shields.io/twitter/follow/giswqs?style=social%20%20%20%20..%20image::%20https://readthedocs.org/projects/geemap/badge/?version=latest)](https://twitter.com/giswqs) 12 | 13 | **WhiteboxTools** is an advanced geospatial data analysis platform developed by Prof. [John Lindsay](https://github.com/jblindsay) at the University of Guelph's [Geomorphometry and Hydrogeomatics Research Group](https://jblindsay.github.io/ghrg/index.html). The **[WhiteboxTools](https://github.com/jblindsay/whitebox-tools)** library currently contains **440** tools, which are each grouped based on their main function into one of the following categories: Data Tools, GIS Analysis, Hydrological Analysis, Image Analysis, LiDAR Analysis, Mathematical and Statistical Analysis, Stream Network Analysis, and Terrain Analysis. For a listing of available tools, complete with documentation and usage details, please see the [WhiteboxTools User Manual](https://jblindsay.github.io/wbt_book/available_tools/index.html). 14 | 15 | **WhiteboxTools** can be accessed either from a [command prompt](#cmd) (i.e. terminal) or through one of the following front-ends: 16 | 17 | - [Python Package](#python) 18 | - [R Package](#r) 19 | - [ArcGIS Python Toolbox](#arcgis) 20 | - [QGIS Plugin](#qgis) 21 | - [Command-line Interface](#cmd) 22 | 23 | ## Python Package 24 | 25 | ### Links 26 | 27 | - GitHub repo: 28 | - PyPI: 29 | - conda-forge: 30 | - Documentation: 31 | - Maintainer: [Qiusheng Wu](https://wetlands.io) 32 | 33 | ### Installation 34 | 35 | The **whitebox** Python package can be installed using the following command: 36 | 37 | ```python 38 | pip install whitebox 39 | ``` 40 | 41 | The **whitebox** Python package is also available on [conda-forge](https://anaconda.org/conda-forge/whitebox), which can be installed using the following command: 42 | 43 | ```python 44 | conda install -c conda-forge whitebox 45 | ``` 46 | 47 | ### Usage 48 | 49 | Tool names in the whitebox Python package can be called using the snake_case convention (e.g. lidar_info). See below for an example Python script. 50 | 51 | ```python 52 | import os 53 | import pkg_resources 54 | import whitebox 55 | 56 | wbt = whitebox.WhiteboxTools() 57 | print(wbt.version()) 58 | print(wbt.help()) 59 | 60 | # identify the sample data directory of the package 61 | data_dir = os.path.dirname(pkg_resources.resource_filename("whitebox", 'testdata/')) 62 | 63 | wbt.set_working_dir(data_dir) 64 | wbt.verbose = False 65 | wbt.feature_preserving_smoothing("DEM.tif", "smoothed.tif", filter=9) 66 | wbt.breach_depressions("smoothed.tif", "breached.tif") 67 | wbt.d_inf_flow_accumulation("breached.tif", "flow_accum.tif") 68 | ``` 69 | 70 | **WhiteboxTools** also provides a Graphical User Interface (GUI) - **WhiteboxTools Runner**, which can be invoked using the following Python script: 71 | 72 | ```python 73 | import whitebox 74 | whitebox.Runner() 75 | ``` 76 | 77 | ![whitebox-runner](https://wetlands.io/file/images/whitebox.png) 78 | 79 | ## R Package 80 | 81 | ### Links 82 | 83 | - GitHub repo: 84 | - R-Forge: 85 | - Documentation: 86 | - Maintainer: [Qiusheng Wu](https://wetlands.io) 87 | 88 | ### Installation 89 | 90 | The **whitebox** R package is available on [R-Forge](https://r-forge.r-project.org/R/?group_id=2337), which can be installed using the following command: 91 | 92 | ```R 93 | install.packages("whitebox", repos="http://R-Forge.R-project.org") 94 | ``` 95 | 96 | You can alternatively install the development version of whitebox from [GitHub](https://github.com/giswqs/whiteboxR) as follows: 97 | 98 | ```R 99 | if (!require(devtools)) install.packages('devtools') 100 | devtools::install_github("giswqs/whiteboxR") 101 | ``` 102 | 103 | ### RStudio Screenshot 104 | 105 | ![whiteboxR](https://wetlands.io/file/images/whiteboxR.png) 106 | 107 | ### Usage 108 | 109 | Tool names in the **whitebox** R package can be called using the snake_case (e.g. wbt_lidar_info). See below for an example. 110 | 111 | ```R 112 | library(whitebox) 113 | 114 | # Set input raster DEM file 115 | dem <- system.file("extdata", "DEM.tif", package="whitebox") 116 | 117 | # Run tools 118 | wbt_feature_preserving_smoothing(dem, "./smoothed.tif", filter=9, verbose_mode = TRUE) 119 | wbt_breach_depressions("./smoothed.tif", "./breached.tif") 120 | wbt_d_inf_flow_accumulation(dem, "./flow_accum.tif") 121 | ``` 122 | 123 | ## ArcGIS Python Toolbox 124 | 125 | ### Links 126 | 127 | - GitHub repo: 128 | - Maintainer: [Qiusheng Wu](https://wetlands.io) 129 | 130 | ### Installation 131 | 132 | #### Step 1: Download the toolbox 133 | 134 | 1. Go to the [WhiteboxTools-ArcGIS GitHub repo](https://github.com/giswqs/WhiteboxTools-ArcGIS) and click the green button (**[Clone or download](https://gishub.org/whitebox-arcgis-download)**) on the upper-right corner of the page to download the toolbox as a zip file. 135 | 136 | ![](https://i.imgur.com/2xQkxCY.png) 137 | 138 | 2. Depcompress the downloaded zip file. 139 | 140 | #### Step 2: Connect to the toolbox 141 | 142 | 1. Navigate to the **Folder Connections** node in the catalog window tree. 143 | 144 | 2. Right-click the node and choose **Connect To Folder**. 145 | 146 | ![](https://i.imgur.com/uKK1Yel.png) 147 | 148 | 3. Type the path or navigate to the **WhiteboxTools-ArcGIS** folder and click **OK**. 149 | 150 | 4. Browse into the toolbox and start using its tools. 151 | 152 | ![](https://i.imgur.com/JcdNBnt.png) 153 | 154 | ### Usage 155 | 156 | Open any tool within the toolbox and start using it. Check out the [WhiteboxTools User Mannual](https://jblindsay.github.io/wbt_book/) for more detailed help documentation of each tool. 157 | 158 | ![](https://i.imgur.com/4c9RLZY.png) 159 | 160 | ### ArcGIS Pro Screenshot 161 | 162 | ![ArcGISPro](https://wetlands.io/file/images/whitebox-ArcGISPro.png) 163 | 164 | ### ArcMap Screenshots 165 | 166 | ![Toolbox-1](https://raw.githubusercontent.com/giswqs/WhiteboxTools-ArcGIS/master/screenshots/Toolbox-1.png) 167 | ![Toolbox-2](https://raw.githubusercontent.com/giswqs/WhiteboxTools-ArcGIS/master/screenshots/Toolbox-2.png) 168 | ![Toolbox-3](https://raw.githubusercontent.com/giswqs/WhiteboxTools-ArcGIS/master/screenshots/Toolbox-3.png) 169 | 170 | ## QGIS Plugin 171 | 172 | ### Links 173 | 174 | - Documentation: 175 | - GitHub repo: https://github.com/alexbruy/processing-wbt 176 | - Maintainer: [Alexander Bruy](https://wiki.osgeo.org/wiki/User:Alexbruy) 177 | 178 | ### Installation 179 | 180 | Please follow the installation guide [here](https://jblindsay.github.io/wbt_book/qgis_plugin.html). 181 | 182 | ### Screenshot 183 | 184 | ![QGIS](https://wetlands.io/file/images/whitebox-QGIS.png) 185 | 186 | ## Command-line Interface 187 | 188 | ### Links 189 | 190 | - GitHub repo: 191 | - User Manual: 192 | - Maintainer: [John Lindsay](https://jblindsay.github.io/ghrg/index.html) 193 | 194 | ### Installation 195 | 196 | You can download a copy of the **WhiteboxTools** executable for your operating system from the [Geomorphometry and Hydrogeomatics Research Group website](https://jblindsay.github.io/ghrg/WhiteboxTools/download.html). Once you've downloaded WhiteboxTools and decompressed (unzipped) the folder, you can open a command prompt and start using it. 197 | 198 | ### Usage 199 | 200 | **WhiteboxTools** is a command-line program and can be run by calling it with appropriate commands and arguments, from a terminal application. The following commands are recognized by the **WhiteboxTools** library: 201 | 202 | | Command | Description | 203 | | ---------------- | ------------------------------------------------------------------------------------------------ | 204 | | --cd, --wd | Changes the working directory; used in conjunction with --run flag. | 205 | | -h, --help | Prints help information. | 206 | | -l, --license | Prints the whitebox-tools license. | 207 | | --listtools | Lists all available tools, with tool descriptions. Keywords may also be used, --listtools slope. | 208 | | -r, --run | Runs a tool; used in conjunction with --cd flag; -r="LidarInfo". | 209 | | --toolbox | Prints the toolbox associated with a tool; --toolbox=Slope. | 210 | | --toolhelp | Prints the help associated with a tool; --toolhelp="LidarInfo". | 211 | | --toolparameters | Prints the parameters (in json form) for a specific tool; --toolparameters=\"LidarInfo\". | 212 | | -v | Verbose mode. Without this flag, tool outputs will not be printed. | 213 | | --viewcode | Opens the source code of a tool in a web browser; --viewcode=\"LidarInfo\". | 214 | | --version | Prints the version information. | 215 | 216 | Generally, the Unix convention is that single-letter arguments (options) use a single hyphen (e.g. -h) while word-arguments (longer, more descriptive argument names) use double hyphen (e.g. --help). The same rule is used for passing arguments to tools as well. Use the _--toolhelp_ argument to print information about a specific tool (e.g. --toolhelp=Clump). Tool names can be specified either using the snake_case or CamelCase convention (e.g. _lidar_info_ or _LidarInfo_). 217 | 218 | For examples of how to call functions and run tools from _WhiteboxTools_, see the _whitebox_example.py_ Python script, which itself uses the _whitebox_tools.py_ script as an interface for interacting with the executable file. 219 | 220 | In addition to direct command-line and script-based interaction, a very basic user-interface called _WB Runner_ can be used to call the tools within the _WhiteboxTools_ executable file, providing the required tool arguments. 221 | 222 | **Example command prompt:** 223 | 224 | ``` 225 | >>./whitebox_tools --wd='/Users/johnlindsay/Documents/data/' --run=DevFromMeanElev 226 | --input='DEM clipped.dep' --output='DEV raster.dep' -v 227 | ``` 228 | 229 | Notice the quotation marks (single or double) used around directories and filenames, and string tool arguments in general. Use the '-v' flag (run in verbose mode) to force the tool print output to the command prompt. Please note that the whitebox_tools executable file must have permission to be executed; on some systems, this may require setting special permissions. The '>>' is shorthand for the command prompt and is not intended to be typed. Also, the above example uses the forward slash character (/), the directory path separator used on unix based systems. On Windows, users should use the back slash character (\\) instead. 230 | --------------------------------------------------------------------------------