Environment and Discovery

This chapter covers environment lifecycle and tool discovery patterns.

Environment setup is where workflow reliability begins. By explicitly creating and configuring a runtime environment, you make script behavior predictable across machines and sessions. Discovery APIs then let you verify capability before execution, which avoids long-running failures caused by missing tools, unexpected categories, or version mismatches.

Create and Configure Environment

This example establishes an explicit runtime configuration. In production scripts, this is where you set working directory and verbosity policy.

import whitebox_workflows as wb

wbe = wb.WbEnvironment()
wbe.working_directory = '/path/to/data'
wbe.verbose = True

print(wbe.version())
print(wbe.license_type())

Namespace Discovery

Use discovery to understand available capability before writing long workflows or generating dynamic tooling UIs.

import whitebox_workflows as wb

wbe = wb.WbEnvironment()

print('categories:', wbe.categories())
print('domains:', wbe.domain_namespaces())
print('terrain tools sample:', wbe.terrain.list_tools()[:15])

Search and Describe Tools

This pattern is useful when you know a task but not the exact tool identifier.

import whitebox_workflows as wb

wbe = wb.WbEnvironment()

matches = wbe.search_tools('slope')
for m in matches[:5]:
	print(m.get('tool_id', m))

desc = wbe.describe_tool('slope')
print(desc)

Discovering Parameter Values with describe_tool

describe_tool returns a dictionary containing structured parameter metadata. Each entry in the params list includes:

Use this to enumerate valid values before calling a tool:

import whitebox_workflows as wb

wbe = wb.WbEnvironment()

desc = wbe.describe_tool('lidar_tin_gridding')
for p in desc['params']:
    name = p['name']
    choices = p.get('choices')
    default = p.get('default_value')
    if choices:
        print(f"{name}: choices={choices}, default={default!r}")
    else:
        print(f"{name}: type={p.get('type', 'any')}, default={default!r}")

Example output (selected parameters):

interpolation_parameter: choices=['elevation', 'intensity', 'class', 'return_number', 'number_of_returns', 'scan_angle', 'time', 'rgb', 'user_data'], default='elevation'
returns_included: choices=['all', 'first', 'last'], default='all'
triangulation_backend: choices=['auto', 'delaunator', 'wbtopology'], default='auto'
triangulation_thin_method: choices=['nearest_center', 'min_value', 'max_value'], default='nearest_center'
triangulation_thin_cell_size: type=float, default='0.0'

This is especially useful for building dynamic UIs, generating documentation, or writing validation helpers that do not hard-code allowed values.

Validate Tool Availability

Use hard checks like this in batch scripts so failures occur immediately, before expensive processing begins.

import whitebox_workflows as wb

wbe = wb.WbEnvironment()
available = set(wbe.list_tools())

required = {'fill_depressions', 'd8_flow_accum'}
missing = sorted(required - available)
if missing:
	raise RuntimeError(f'Missing required tools: {missing}')

Category Access Patterns

Prefer direct properties when available:

• wbe.hydrology
• wbe.terrain
• wbe.raster
• wbe.vector
• wbe.lidar
• wbe.remote_sensing
• wbe.conversion
• wbe.streams
• wbe.precision_agriculture
• wbe.other

Use generic accessors for dynamic workflows:

• wbe.category(name)
• wbe.domain(name)

Projection/georeferencing tools are cataloged under the canonical category key projection_georeferencing and can be queried with:

proj_tools = wbe.category('projection_georeferencing').list_tools()
print(proj_tools[:10])

WbEnvironment Method Reference

This reference lists callable WbEnvironment methods with brief descriptions. Special Python dunder methods are intentionally omitted.

Constructors

Runtime and Licensing

Discovery and Introspection

Core Data Readers

Sensor Bundle Readers and Composites

Reprojection Helpers

Writers and Raster-Memory Management

Key Environment Properties