Interacting with WhiteboxTools through the command line prompt
At its base, WhiteboxTools is a stand-alone executable command-line program. The Python scripting interface is effectively just interacting with this executable file through a series of process calls and reading the standard output. You can also interact directly with the WhiteboxTools executable file.
The following material has been extracted from the WhiteboxTools User Manual, which can be found in pdf form along with the download.
WhiteboxTools is a command-line program and can be run either by calling it from a terminal application with appropriate commands and arguments, or, more conveniently, by calling it from a script. The following commands are recognized by the WhiteboxTools library:
| Command | Description |
|---|---|
| --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, with tool descriptions. Keywords may also be used, --listtools slope. |
| -r, --run | Runs a tool; used in conjunction with --cd 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; e.g. --toolparameters="FeaturePreservingDenoise". |
| -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. |
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 hyphens (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).
The following is an example of calling the WhiteboxTools binary executable file directly from the command prompt:
>>./whitebox_tools --wd='/Users/johnlindsay/Documents/data/' ^
--run=DevFromMeanElev --input='DEM clipped.tif' ^
--output='DEV raster.tif' -v
Notice the quotation marks (single or double) used around
directories and filenames, and string tool arguments in general. After the
--run flag, used to call a tool, a series of tool-specific
flags are provided to indicate the values of various input parameters. Note
that the order of these flags is unimportant. Use the
-v flag (run in verbose mode) to force any tool to 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.
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. Also, it is sometimes necessary to break
(^) commands across multiple lines, as above, in order to better fit with the
documents format. Actual command prompts should be contained to a single line.
