CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-whiteboxgui

An interactive GUI for WhiteboxTools in a Jupyter-based environment

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

whiteboxgui

An interactive Graphical User Interface (GUI) for WhiteboxTools in a Jupyter-based environment. This package serves as a Python frontend that enables users to access WhiteboxTools' extensive suite of 518+ geospatial analysis tools through an intuitive interface, providing widgets and controls for parameter input, tool selection through a hierarchical tree structure, and seamless integration with Jupyter notebooks and JupyterLab environments.

Package Information

  • Package Name: whiteboxgui
  • Language: Python
  • Installation: pip install whiteboxgui or conda install whiteboxgui -c conda-forge

Core Imports

import whiteboxgui

Basic Usage

import whiteboxgui

# Show the main WhiteboxTools GUI interface
gui = whiteboxgui.show()

# Show with custom parameters
gui = whiteboxgui.show(
    verbose=True,    # Show progress info when tools run
    tree=False,     # Use list-based interface (True for tree-based)
    reset=False,    # Regenerate tool dictionary
    sandbox_path=None  # Path to sandbox directory for file operations
)

# Update the package from GitHub
whiteboxgui.update_package()

Architecture

whiteboxgui provides a Jupyter-based GUI wrapper around WhiteboxTools with the following key components:

  • Main GUI Interface: Interactive toolbox with tool selection, parameter input, and execution
  • Tool Dictionary System: Comprehensive database of all 518+ WhiteboxTools with metadata
  • File Management: Integration with Jupyter file chooser for input/output file selection
  • Code Generation: Export tool configurations as executable Python code
  • Tool Search: Keyword-based search across tool names and descriptions
  • Documentation Links: Direct access to tool documentation and source code

The package integrates with ipywidgets for UI components, ipytree for hierarchical tool browsing, and ipyfilechooser for file selection, providing a complete geospatial analysis environment within Jupyter.

Capabilities

Main GUI Interface

Display the interactive WhiteboxTools GUI with customizable options for tool browsing and execution.

def show(verbose=True, tree=False, reset=False, sandbox_path=None):
    """
    Show the toolbox GUI.

    Parameters:
    - verbose (bool): Whether to show progress info when tools run. Defaults to True.
    - tree (bool): Whether to use tree mode toolbox built using ipytree rather than ipywidgets. Defaults to False.
    - reset (bool): Whether to regenerate the json file with tool dictionary. Defaults to False.  
    - sandbox_path (str): The path to the sandbox directory. Defaults to None.

    Returns:
    A toolbox GUI widget (ipywidget object)
    """

Package Management

Update the whiteboxgui package directly from the GitHub repository without using pip or conda.

def update_package():
    """
    Updates the whiteboxgui package from the GitHub repository without the need to use pip or conda.
    In this way, I don't have to keep updating pypi and conda-forge with every minor update of the package.
    """

String Formatting Utilities

Convert between different string case formats used by WhiteboxTools.

def to_camelcase(name):
    """
    Convert snake_case name to CamelCase name.

    Parameters:
    - name (str): The name of the tool.

    Returns:
    str: The CamelCase name of the tool.
    """

def to_label(name):
    """
    Convert snake_case name to Title case label.

    Parameters:
    - name (str): The name of the tool.

    Returns:
    str: The Title case name of the tool.
    """

def to_snakecase(name):
    """
    Convert CamelCase name to snake_case name.

    Parameters:
    - name (str): The name of the tool.

    Returns:
    str: The snakecase name of the tool.
    """

Jupyter Integration

Create and manipulate code cells within Jupyter notebooks.

def create_code_cell(code="", where="below"):
    """
    Creates a code cell in the IPython Notebook.

    Parameters:
    - code (str): Code to fill the new code cell with. Defaults to ''.
    - where (str): Where to add the new code cell. Can be 'above', 'below', or 'at_bottom'. Defaults to 'below'.
    """

File Operations

Download and extract files from URLs with support for various archive formats.

def download_from_url(url, out_file_name=None, out_dir=".", unzip=True, verbose=False):
    """
    Download a file from a URL (e.g., https://github.com/giswqs/whitebox/raw/master/examples/testdata.zip)

    Parameters:
    - url (str): The HTTP URL to download.
    - out_file_name (str): The output file name to use. Defaults to None.
    - out_dir (str): The output directory to use. Defaults to '.'.
    - unzip (bool): Whether to unzip the downloaded file if it is a zip file. Defaults to True.
    - verbose (bool): Whether to display or not the output of the function. Defaults to False.
    """

def clone_repo(out_dir=".", unzip=True):
    """
    Clones the whiteboxgui GitHub repository.

    Parameters:
    - out_dir (str): Output folder for the repo. Defaults to '.'.
    - unzip (bool): Whether to unzip the repository. Defaults to True.
    """

Tool Information and Discovery

Access metadata and documentation for WhiteboxTools.

def get_github_url(tool_name):
    """
    Get the link to the source code of the tool on GitHub.

    Parameters:
    - tool_name (str): The name of the tool.

    Returns:
    str: The URL to source code.
    """

def get_book_url(tool_name, category):
    """
    Get the link to the help documentation of the tool.

    Parameters:
    - tool_name (str): The name of the tool.
    - category (str): The category of the tool.

    Returns:
    str: The URL to help documentation.
    """

def search_api_tree(keywords, api_tree, tools_dict):
    """
    Search the WhiteboxTools API and return functions containing the specified keywords

    Parameters:
    - keywords (str): The keywords to search for.
    - api_tree (dict): The dictionary containing the WhiteboxTools API tree.
    - tools_dict (dict): The dictionary containing the dict of all tools.

    Returns:
    An ipytree object/widget.
    """

def tool_categories():
    """
    Generate a dictionary containing the toolbox corresponds to each tool.

    Returns:
    dict: a dictionary containing the toolbox corresponds to each tool.
    """

Tool Configuration and Analysis

Retrieve detailed tool information and parameters for GUI generation.

def get_tool_params(tool_name):
    """
    Get parameters for a tool.

    Parameters:
    - tool_name (str): The name of the tool.

    Returns:
    dict: The tool parameters as a dictionary.
    """

def get_ext_dict(verbose=True, reset=False):
    """
    Generate a dictionary containing information for the general extension tools.

    Parameters:
    - verbose (bool): Whether to print out description info. Defaults to True.
    - reset (bool): Whether to recreate the json file containing the dictionary. Defaults to False.

    Returns:
    dict: The dictionary containing information for general extension tools.
    """

def get_wbt_dict(reset=False):
    """
    Generate a dictionary containing information for all tools.

    Parameters:
    - reset (bool): Whether to recreate the json file containing the dictionary. Defaults to False.

    Returns:
    dict: The dictionary containing information for all tools.
    """

GUI Widget Construction

Build interactive GUI components for tool selection and parameter input.

def tool_gui(tool_dict, max_width="420px", max_height="600px", sandbox_path=None):
    """
    Create a GUI for a tool based on the tool dictionary.

    Parameters:
    - tool_dict (dict): The dictionary containing the tool info.
    - max_width (str): The max width of the tool dialog.
    - max_height (str): The max height of the tool dialog.
    - sandbox_path (str): The path to the sandbox directory. Defaults to None.

    Returns:
    An ipywidget object representing the tool interface.
    """

def build_toolbox_tree(tools_dict, folder_icon="folder", tool_icon="wrench", sandbox_path=None):
    """
    Build the toolbox for WhiteboxTools using tree-based interface.

    Parameters:
    - tools_dict (dict): A dictionary containing information for all tools.
    - folder_icon (str): The font-awesome icon for tool categories. Defaults to "folder".
    - tool_icon (str): The font-awesome icon for tools. Defaults to "wrench".
    - sandbox_path (str): The path to the sandbox folder. Defaults to None.

    Returns:
    An ipywidget representing the toolbox.
    """

def build_toolbox(tools_dict, max_width="1080px", max_height="600px", sandbox_path=None):
    """
    Build the toolbox for WhiteboxTools using list-based interface.

    Parameters:
    - tools_dict (dict): A dictionary containing information for all tools.
    - max_width (str): The maximum width of the widget.
    - max_height (str): The maximum height of the widget.
    - sandbox_path (str): The path to the sandbox folder. Defaults to None.

    Returns:
    An ipywidget representing the toolbox.
    """

Environment Detection

Detect execution environment for platform-specific functionality.

def in_colab_shell():
    """
    Tests if the code is being executed within Google Colab.

    Returns:
    bool: True if in Google Colab, False otherwise.
    """

Module-level Variables

# WhiteboxTools instance for tool execution
wbt = whitebox.WhiteboxTools()

# Package metadata constants
__author__ = "Qiusheng Wu"
__email__ = "giswqs@gmail.com"
__version__ = "2.3.0"

Usage Examples

Creating a Custom Tool Interface

import whiteboxgui

# Get the complete tool dictionary
tools_dict = whiteboxgui.get_wbt_dict()

# Create GUI for a specific tool
tool_name = "Slope"  # Example tool
if tool_name in tools_dict:
    tool_interface = whiteboxgui.tool_gui(
        tools_dict[tool_name],
        max_width="500px",
        max_height="700px"
    )
    # Display the interface in Jupyter
    display(tool_interface)

Searching and Filtering Tools

import whiteboxgui

# Get all tools
tools_dict = whiteboxgui.get_wbt_dict()

# Search for hydrology-related tools
hydrology_tools = {}
for tool_name, tool_info in tools_dict.items():
    if "hydro" in tool_info["description"].lower():
        hydrology_tools[tool_name] = tool_info

print(f"Found {len(hydrology_tools)} hydrology tools")

Custom Toolbox with Specific Tools

import whiteboxgui

# Get full tool dictionary
all_tools = whiteboxgui.get_wbt_dict()

# Filter to specific category
terrain_tools = {
    name: info for name, info in all_tools.items()
    if info["category"] == "Terrain Analysis"
}

# Build custom toolbox
custom_toolbox = whiteboxgui.build_toolbox(
    terrain_tools,
    max_width="800px",
    max_height="500px"
)

display(custom_toolbox)

Error Handling

The package handles various error conditions:

  • Network errors: URL downloads may fail with connection issues
  • File system errors: File operations may fail due to permissions or disk space
  • Tool execution errors: WhiteboxTools may fail due to invalid parameters or data issues
  • Environment errors: Some features may not work outside Jupyter environments

Common error patterns:

try:
    gui = whiteboxgui.show()
except Exception as e:
    print(f"Failed to initialize GUI: {e}")
    # Fallback to updating package or checking dependencies

docs

index.md

tile.json