0
# whiteboxgui
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: whiteboxgui
7
- **Language**: Python
8
- **Installation**: `pip install whiteboxgui` or `conda install whiteboxgui -c conda-forge`
9

10
## Core Imports
11

12
```python
13
import whiteboxgui
14
```
15

16
## Basic Usage
17

18
```python
19
import whiteboxgui
20

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

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

32
# Update the package from GitHub
33
whiteboxgui.update_package()
34
```
35

36
## Architecture
37

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

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

47
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.
48

49
## Capabilities
50

51
### Main GUI Interface
52

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

55
```python { .api }
56
def show(verbose=True, tree=False, reset=False, sandbox_path=None):
57
    """
58
    Show the toolbox GUI.
59

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

66
    Returns:
67
    A toolbox GUI widget (ipywidget object)
68
    """
69
```
70

71
### Package Management
72

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

75
```python { .api }
76
def update_package():
77
    """
78
    Updates the whiteboxgui package from the GitHub repository without the need to use pip or conda.
79
    In this way, I don't have to keep updating pypi and conda-forge with every minor update of the package.
80
    """
81
```
82

83
### String Formatting Utilities
84

85
Convert between different string case formats used by WhiteboxTools.
86

87
```python { .api }
88
def to_camelcase(name):
89
    """
90
    Convert snake_case name to CamelCase name.
91

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

95
    Returns:
96
    str: The CamelCase name of the tool.
97
    """
98

99
def to_label(name):
100
    """
101
    Convert snake_case name to Title case label.
102

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

106
    Returns:
107
    str: The Title case name of the tool.
108
    """
109

110
def to_snakecase(name):
111
    """
112
    Convert CamelCase name to snake_case name.
113

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

117
    Returns:
118
    str: The snakecase name of the tool.
119
    """
120
```
121

122
### Jupyter Integration
123

124
Create and manipulate code cells within Jupyter notebooks.
125

126
```python { .api }
127
def create_code_cell(code="", where="below"):
128
    """
129
    Creates a code cell in the IPython Notebook.
130

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

137
### File Operations
138

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

141
```python { .api }
142
def download_from_url(url, out_file_name=None, out_dir=".", unzip=True, verbose=False):
143
    """
144
    Download a file from a URL (e.g., https://github.com/giswqs/whitebox/raw/master/examples/testdata.zip)
145

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

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

158
    Parameters:
159
    - out_dir (str): Output folder for the repo. Defaults to '.'.
160
    - unzip (bool): Whether to unzip the repository. Defaults to True.
161
    """
162
```
163

164
### Tool Information and Discovery
165

166
Access metadata and documentation for WhiteboxTools.
167

168
```python { .api }
169
def get_github_url(tool_name):
170
    """
171
    Get the link to the source code of the tool on GitHub.
172

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

176
    Returns:
177
    str: The URL to source code.
178
    """
179

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

184
    Parameters:
185
    - tool_name (str): The name of the tool.
186
    - category (str): The category of the tool.
187

188
    Returns:
189
    str: The URL to help documentation.
190
    """
191

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

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

201
    Returns:
202
    An ipytree object/widget.
203
    """
204

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

209
    Returns:
210
    dict: a dictionary containing the toolbox corresponds to each tool.
211
    """
212
```
213

214
### Tool Configuration and Analysis
215

216
Retrieve detailed tool information and parameters for GUI generation.
217

218
```python { .api }
219
def get_tool_params(tool_name):
220
    """
221
    Get parameters for a tool.
222

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

226
    Returns:
227
    dict: The tool parameters as a dictionary.
228
    """
229

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

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

238
    Returns:
239
    dict: The dictionary containing information for general extension tools.
240
    """
241

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

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

249
    Returns:
250
    dict: The dictionary containing information for all tools.
251
    """
252
```
253

254
### GUI Widget Construction
255

256
Build interactive GUI components for tool selection and parameter input.
257

258
```python { .api }
259
def tool_gui(tool_dict, max_width="420px", max_height="600px", sandbox_path=None):
260
    """
261
    Create a GUI for a tool based on the tool dictionary.
262

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

269
    Returns:
270
    An ipywidget object representing the tool interface.
271
    """
272

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

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

283
    Returns:
284
    An ipywidget representing the toolbox.
285
    """
286

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

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

297
    Returns:
298
    An ipywidget representing the toolbox.
299
    """
300
```
301

302
### Environment Detection
303

304
Detect execution environment for platform-specific functionality.
305

306
```python { .api }
307
def in_colab_shell():
308
    """
309
    Tests if the code is being executed within Google Colab.
310

311
    Returns:
312
    bool: True if in Google Colab, False otherwise.
313
    """
314
```
315

316
## Module-level Variables
317

318
```python { .api }
319
# WhiteboxTools instance for tool execution
320
wbt = whitebox.WhiteboxTools()
321

322
# Package metadata constants
323
__author__ = "Qiusheng Wu"
324
__email__ = "giswqs@gmail.com"
325
__version__ = "2.3.0"
326
```
327

328
## Usage Examples
329

330
### Creating a Custom Tool Interface
331

332
```python
333
import whiteboxgui
334

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

338
# Create GUI for a specific tool
339
tool_name = "Slope"  # Example tool
340
if tool_name in tools_dict:
341
    tool_interface = whiteboxgui.tool_gui(
342
        tools_dict[tool_name],
343
        max_width="500px",
344
        max_height="700px"
345
    )
346
    # Display the interface in Jupyter
347
    display(tool_interface)
348
```
349

350
### Searching and Filtering Tools
351

352
```python
353
import whiteboxgui
354

355
# Get all tools
356
tools_dict = whiteboxgui.get_wbt_dict()
357

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

364
print(f"Found {len(hydrology_tools)} hydrology tools")
365
```
366

367
### Custom Toolbox with Specific Tools
368

369
```python
370
import whiteboxgui
371

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

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

381
# Build custom toolbox
382
custom_toolbox = whiteboxgui.build_toolbox(
383
    terrain_tools,
384
    max_width="800px",
385
    max_height="500px"
386
)
387

388
display(custom_toolbox)
389
```
390

391
## Error Handling
392

393
The package handles various error conditions:
394

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

400
Common error patterns:
401

402
```python
403
try:
404
    gui = whiteboxgui.show()
405
except Exception as e:
406
    print(f"Failed to initialize GUI: {e}")
407
    # Fallback to updating package or checking dependencies
408
```