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
: Path to the source directory containing input files. All user input files are copied from this directory to a temporary directory for processing. -
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
).
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.