API Reference

Python wrapper for WhiteboxTools command-line utility.

prepare_wbt

prepare_wbt(
    wbt_root,
    zip_path=None,
    refresh_download=False,
    max_attempts=3,
    verbose=False,
)

Download the WhiteboxTools executable for the current platform.

Parameters:

• wbt_root (str or Path) –

  Root directory to extract WhiteboxTools to.

• zip_path (str or Path, default: None ) –

  Path to the zip file containing the WhiteboxTools executables, defaults to None. If None, the zip file will be downloaded to a temporary directory that gets deleted after the function finishes. Otherwise, the zip file will be saved to the specified path.

• refresh_download (bool, default: False ) –

  Whether to refresh the download even if WhiteboxTools is found. Defaults to False.

• max_attempts (int, default: 3 ) –

  Maximum number of attempts to prepare WhiteboxTools, defaults to 3.

• verbose (bool, default: False ) –

  Whether to enable verbose logging, defaults to False.

Returns:

• str –

  Version of WhiteboxTools.

whitebox_tools

whitebox_tools(
    src_dir,
    arg_dict,
    files_to_save=None,
    save_dir=".",
    wbt_root="WBT",
    compress_rasters=False,
    zip_path=None,
    refresh_download=False,
    max_procs=-1,
    verbose=False,
)

Run a WhiteboxTools (not Whitebox Runner) tool with specified arguments.

Parameters:

• src_dir (str or Path) –

  Path to the source directory containing input files. 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 in arg_dict, you must just use the filenames without the directory path. Refer to the example in arg_dict.

• arg_dict (dict) –

  A dictionary containing the tool names as keys and list of each tool's arguments as values. For example:

  {
      "BreachDepressions": ["-i=dem.tif", "--fill_pits", "-o=dem_corr.tif"],
      "D8Pointer": ["-i=dem_corr.tif", "-o=fdir.tif"],
      "D8FlowAccumulation": ["-i=fdir.tif", "--pntr", "-o=d8accum.tif"],
  }
  

  Note that the input and output file names should not contain the directory path, only the filenames.

• files_to_save (list, default: None ) –

  List of output files to save to save_dir. Note that these should be the filenames without the directory path, just as they are used in the arg_dict, i.e. the values that are passed by -o or --output. Defaults to None, which means all intermediate files will be saved to save_dir.

• save_dir (str or Path, default: '.' ) –

  Path to the directory where the output files given in files_to_save will be saved (default is ".", i.e., current working directory).

• wbt_root (str or Path, default: 'WBT' ) –

  Path to the directory the Whitebox executables will be extracted to (default is "WBT").

• zip_path (str or Path, default: None ) –

  Path to the zip file containing the WhiteboxTools executables (default is None). If None, the zip file will be downloaded to a temporary directory that gets deleted after the function finishes. Otherwise, the zip file will be saved to the specified path.

• refresh_download (bool, default: False ) –

  Whether to refresh the download if WhiteboxTools is found (default is False).

• compress_rasters (bool, default: False ) –

  Whether to compress output rasters (default is False).

• max_procs (int, default: -1 ) –

  The maximum number of processes to use (default is -1).

• verbose (bool, default: False ) –

  Whether to print verbose output (default is False).

Raises:

• CalledProcessError –

  If the tool execution fails.

• Exception –

  For any other unexpected errors.

list_tools

list_tools(wbt_root='WBT', zip_path=None)

List the available WhiteboxTools commands.

Parameters:

• wbt_root (str or Path, default: 'WBT' ) –

  Path to the directory containing the WhiteboxTools executables (default is WBT).

• zip_path (str or Path, default: None ) –

  Path to the zip file containing the WhiteboxTools executables (default is None).

Returns:

• dict –

  A dictionary of WhiteboxTools commands and their descriptions. Can be converted to a pandas.Series for easier viewing using pd.Series(pywbt.list_tools()).

tool_parameters

tool_parameters(tool_name, wbt_root='WBT', zip_path=None)

List the parameters for a WhiteboxTools command.

Parameters:

• tool_name (str) –

  Name of the WhiteboxTools command.

• wbt_root (str or Path, default: 'WBT' ) –

  Path to the directory containing the WhiteboxTools executables (default is "WBT").

• zip_path (str or Path, default: None ) –

  Path to the zip file containing the WhiteboxTools executables (default is None).

Returns:

• list –

  A list of WhiteboxTools command parameters and their descriptions. Can be converted to a pandas.DataFrame for easier viewing. For example, to get parameters of Aspect tool, use pd.DataFrame(pywbt.tool_parameters("Aspect")).

Utility functions for getting and processing Digital Elevation Models (DEMs).

DependencyError

DependencyError()

Bases: ImportError

Raised when a required dependency is not found.

get_nasadem

get_nasadem(bbox, tif_path, to_utm=False)

Get DEM for a given bounding box from NASADEM.

Parameters:

• bbox (tuple) –

  Bounding box coordinates in the order (west, south, east, north) in decimal degrees.

• tif_path (str or Path) –

  Path to save the obtained data as a GeoTIFF file.

• to_utm (bool, default: False ) –

  Reproject the DEM to UTM, by default False.

get_3dep

get_3dep(bbox, tif_path, resolution=10, to_5070=False)

Get DEM from USGS's 3D Hydrography Elevation Data Program (3DEP).

Parameters:

• bbox (tuple) –

  Bounding box coordinates in the order (west, south, east, north) in decimal degrees.

• tif_path (str or Path) –

  Path to save the obtained data as a GeoTIFF file.

• resolution (int, default: 10 ) –

  Resolution of the DEM in meters, by default 10.

• to_5070 (bool, default: False ) –

  Reproject the DEM to EPGS:5070, by default False.

tif_to_da

tif_to_da(
    tif_path,
    dtype=None,
    name=None,
    long_name=None,
    nodata=None,
)

Read a GeoTIFF file with a single band into an xarray DataArray.

Parameters:

• tif_path (str or Path) –

  Path to the GeoTIFF file with a single band.

• dtype (str, default: None ) –

  Data type to cast the data to, e.g. int32, by default None, i.e. use the data type from the GeoTIFF.

• name (str, default: None ) –

  Name to assign to the xarray.DataArray, by default None.

• long_name (str, default: None ) –

  Long name to assign to the xarray.DataArray, by default None.

• nodata (int or float, default: None ) –

  Value to use as da.rio.nodata, by default None, i.e. use the da.rio.nodata value from the GeoTIFF.

Returns:

• DataArray –

  DataArray containing the GeoTIFF data.

tif_to_gdf

tif_to_gdf(tif_path, dtype, feat_name, connectivity=8)

Convert a GeoTIFF to a GeoDataFrame.

Parameters:

• tif_path (str or Path) –

  Path to the GeoTIFF file. The file must contain a single band.

• dtype (str) –

  String representation of the data type to use for the feature values, e.g. int32.

• feat_name (str) –

  Name to assign to the feature values column.

• connectivity (int, default: 8 ) –

  Use 4 or 8 pixel connectivity for grouping pixels into features, by default 8.

Returns:

• GeoDataFrame –

  GeoDataFrame containing the features.