A lightweight Python wrapper for WhiteboxTools command-line interface
Project description
PyWBT: WhiteboxTools Wrapper for Python
Features
PyWBT is a lightweight Python wrapper for the command-line interface of WhiteboxTools (WBT), a powerful Rust library for geospatial analysis. Designed to simplify the use of WhiteboxTools, PyWBT provides a Pythonic interface that enables users to easily run tools and create custom workflows. Notably, PyWBT relies solely on Python's built-in modules, ensuring a minimal dependency footprint.
Try PyWBT in your browser by clicking on the Binder badge above.
Installation
You can install PyWBT using either pip
or micromamba
:
Using pip
:
pip install pywbt
Using micromamba
(or conda
/mamba
):
micromamba install -c conda-forge pywbt
Usage
PyWBT offers a streamlined interface to WhiteboxTools (WBT) through a single function
called whitebox_tools
. This function executes user-provided WBT workflows in a
temporary directory, saving only the specified output files rather than all intermediate
files. It handles downloading the WBT executable for the user's operating system, setting
up the environment, and running the tools.
The whitebox_tools
function has several arguments, with two being mandatory and the rest
optional. The two required arguments are:
src_dir
: This will be the working directory for the WhiteboxTools session. The input files should be in this directory. Thus, when using the files in this directory inarg_dict
, you must just use the filenames without the directory path.arg_dict
: A dictionary with tool names as keys and lists of each tool's arguments as values. Input and output filenames should be specified without directory paths.
For example workflows using arg_dict
to perform geospatial operations, refer to the
Workflows section of the documentation.
We encourage users to contribute to this section by providing sequences of geospatial
operations for performing specific tasks, helping to build a comprehensive resource for
the community.
Note that by default, all generated intermediate files will be stored in save_dir
(default is the current working directory). To save only the specified output files and
delete the rest of intermediate files, use the files_to_save
argument to specify the list
of target outputs. This list should contain the filenames only specified without directory
paths (as used in arg_dict
).
Also, there are two helper function that can be used to get the list of available tools,
their respective descriptions and parameters: list_tools
and tool_parameters
. For
better viewing and querying the outputs of these two functions, it is recommended to use
the pandas
library. For example, you can use:
tools = pd.Series(pywbt.list_tools())
tools[tools.str.contains("depression", case=False)]
to get a pandas.Series
of the tools containing the word "depression" in their
descriptions. Then, we can get the parameters for the BreachDepressions
tool using:
pd.DataFrame(pywbt.tool_parameters("BreachDepressions"))
Here's an example demonstrating how to use PyWBT to run a WBT workflow:
import pywbt
from pathlib import Path
fname = Path("path/to/input_files/dem.tif")
wbt_args = {
"BreachDepressions": [f"-i={fname.name}", "--fill_pits", "-o=dem_corr.tif"],
"D8Pointer": ["-i=dem_corr.tif", "-o=fdir.tif"],
"D8FlowAccumulation": ["-i=fdir.tif", "--pntr", "-o=d8accum.tif"],
"ExtractStreams": [
"--flow_accum=d8accum.tif",
"--threshold=600.0",
"-o=streams.tif",
],
"FindMainStem": ["--d8_pntr=fdir.tif", "--streams=d8accum.tif", "-o=mainstem.tif"],
"StrahlerStreamOrder": [
"--d8_pntr=fdir.tif",
"--streams=streams.tif",
"-o=strahler.tif",
],
"Basins": ["--d8_pntr=fdir.tif", "-o=basins.tif"],
}
pywbt.whitebox_tools(
fname.parent, wbt_args, ("strahler.tif", "mainstem.tif", "basins.tif")
)
For more examples, please visit PyWBT's documentation. For
detailed information about the whitebox_tools
function and its arguments, refer to the
API Reference.
Additionally, for comprehensive information on the various tools offered by WBT and their
arguments, consult its documentation.
Contributing
Contributions to PyWBT are welcome! For more information on how to contribute, please refer to the CONTRIBUTING.md and CODE_OF_CONDUCT.md files.
License
PyWBT is licensed under the MIT License. For more details, please see the LICENSE file.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.