Overview

This manual is the long-form user guide for WbW-QGIS.

WbW-QGIS (Whitebox Workflows for QGIS) is the QGIS frontend for Whitebox Next Gen. It provides a QGIS-native way to discover, configure, and run Whitebox tools through the Processing framework and plugin UI.

Whitebox Next Gen uses a layered architecture:

backend geospatial engines and tools in Rust,
frontend runtimes for Python, R, and QGIS,
shared tool taxonomy and capability metadata.

Whitebox Next Gen is intentionally full-stack: core geospatial capabilities that are often delegated to external C/C++ dependencies in other GIS platforms (for example raster I/O, projections, geometry/topology operations, and lidar handling) are implemented in the Whitebox codebase itself. This architecture is unusual in GIS and provides practical benefits for users: consistent behavior across platforms, tighter control over correctness and performance, fewer system-level dependency issues during installation, and faster iteration when fixing bugs or introducing new capabilities.

Within this model, WbW-QGIS is intentionally a thin integration layer. It handles QGIS presentation and orchestration while computation remains in the Whitebox backend runtime.

What This Manual Covers

This guide focuses on practical use of WbW-QGIS:

setting up the plugin and runtime correctly,
understanding discovery and provider refresh,
running tools through QGIS Processing,
handling output and troubleshooting common issues.

The manual is written for both analysts and developers who use QGIS as the primary working environment.

Goals

Provide a stable onboarding path for local installation.
Document the operational behavior of plugin discovery and execution.
Clarify tier and licensing behavior in QGIS.
Reduce setup friction and runtime ambiguity.

How to Use This Manual

For first-time setup, read chapters in order:

Installation and Setup
Build and Preview
Quick Start
Runtime and Discovery

After setup is stable, use the remaining chapters as reference material.

Installation and Setup

This chapter covers installing the Whitebox Workflows QGIS plugin and its Python backend.

System Requirements

QGIS 4.0 or later (3.28+ may work but is not officially supported)
Internet connection (required for backend installation via pip)
macOS, Linux, or Windows

Install the QGIS Plugin

From QGIS Plugin Repository (Recommended)

Open QGIS
Go to Plugins → Manage and Install Plugins
Search for "Whitebox Workflows"
Click Install Plugin
Restart QGIS

From File (Manual Installation)

If you have a plugin .zip file:

Download or obtain the whitebox_workflows_for_qgis-*.zip file
Extract the zip to your QGIS plugins directory:
- macOS: ~/Library/Application Support/QGIS/QGIS4/profiles/default/python/plugins/
- Linux: ~/.local/share/QGIS/QGIS4/profiles/default/python/plugins/
- Windows: %APPDATA%\QGIS\QGIS4\profiles\default\python\plugins\
Ensure the directory structure is plugins/whitebox_workflows_qgis/ with __init__.py and metadata.txt directly inside
Restart QGIS

Install the Whitebox Workflows Backend

After installing the plugin, restart QGIS. The plugin will check for the whitebox-workflows Python package.

Option A: Install via Plugin Dialog (Easiest)

Open QGIS
If the backend is not installed, a dialog appears: "⚠️ Action Required — Install Whitebox Workflows Backend"
Read the installation instructions (or copy the command to clipboard)

exec("import runpy,sys\nsys.argv=['pip','install','--user','whitebox-workflows']\ntry:\n    runpy.run_module('pip',run_name='__main__',alter_sys=True)\nexcept SystemExit:\n    pass\nimport qgis.utils\nqgis.utils.unloadPlugin('whitebox_workflows_qgis')\nqgis.utils.loadPlugin('whitebox_workflows_qgis')\nqgis.utils.startPlugin('whitebox_workflows_qgis')\nprint('Whitebox Workflows backend installed and plugin reloaded.')")

Click Install to automatically download and install the backend using QGIS's bundled Python and pip
Wait for the installation to complete
The plugin automatically reloads with full access to all tools

Option B: Install via Command Line

If you prefer manual installation, run:

pip install whitebox-workflows

Or, if you have the QGIS Python environment:

# macOS/Linux (find the QGIS Python executable)
$(which python3) -m pip install whitebox-workflows

# Or explicitly use QGIS's Python if installed locally:
/Applications/QGIS.app/Contents/MacOS/Python/bin/python3 -m pip install whitebox-workflows

After installation, restart QGIS.

Verify Installation

Once the backend is installed, you should see:

The Processing Toolbox populates with 700+ Whitebox tools
No error messages in the QGIS message log
Whitebox tools appear in Processing → Toolbox → Whitebox Workflows

For Development and Local Testing

If you are a developer working with the source repository:

Checkout the whitebox_next_gen repository

Install the plugin locally by symlinking it into your QGIS plugins folder:

export QGIS_PLUGIN_DIR="<QGIS settings dir>/python/plugins"
mkdir -p "$QGIS_PLUGIN_DIR"
ln -snf "$PWD/crates/wbw_qgis/plugin/whitebox_workflows_qgis" \
  "$QGIS_PLUGIN_DIR/whitebox_workflows_qgis"

Install the backend using the automated installer or pip install whitebox-workflows
Changes to the plugin source are reflected immediately on QGIS restart

Troubleshooting

"Cannot find init.py or metadata.txt"

This error means the plugin zip was extracted incorrectly. Ensure your plugins directory contains:

plugins/
  whitebox_workflows_qgis/
    __init__.py
    metadata.txt
    bootstrap.py
    plugin.py
    ... (other files)

Not:

plugins/
  whitebox_workflows_qgis/
    whitebox_workflows_qgis/     ← Extra nesting
      __init__.py

Backend Installation Fails

"pip: command not found" — Use python3 -m pip instead
"Permission denied" — Try pip install --user whitebox-workflows
Network issues — Check your internet connection and try again
For help — See Troubleshooting or contact support@whiteboxgeo.com

Build and Preview

The WbW-QGIS manual uses mdBook, matching the WbW-Python and WbW-R manuals.

Build the Manual

From the manual directory:

cd crates/wbw_qgis/manual
mdbook build

Generated output will be written to:

crates/wbw_qgis/manual/book

Live Preview

For a local preview server:

cd crates/wbw_qgis/manual
mdbook serve --open

This starts a local server and opens the manual in your browser.

Writing Conventions

Keep examples task-oriented and reproducible.
Prefer short, complete QGIS workflows over abstract API descriptions.
Document expected outputs and validation checks where possible.

Quick Start

This walkthrough verifies that WbW-QGIS is running and can execute tools.

1. Enable Plugin

Start QGIS.
Open Plugin Manager.
Enable Whitebox Workflows.

2. Confirm Provider Availability

Open the Processing Toolbox.
Confirm Whitebox provider entries appear.
If tools are missing, trigger a discovery refresh from the plugin panel.

3. Run a First Tool

A common smoke test is a simple raster analysis tool with a small input file.

Recommended pattern:

Choose a small test raster.
Run a lightweight tool from the Whitebox provider.
Write output to a temporary file.
Load and inspect the output layer in QGIS.

4. Validate Results

Confirm the output file exists.
Confirm layer metadata and CRS are as expected.
Confirm visual result is plausible for the input.

If any step fails, continue to the Troubleshooting chapter.

Runtime and Discovery

WbW-QGIS discovers tool availability at runtime using the active whitebox_workflows environment.

Discovery Flow

At a high level:

Import whitebox_workflows in the QGIS Python environment.
Create a runtime session.
Read runtime capability metadata.
Read tool catalog metadata.
Partition available vs locked tools.
Refresh Processing provider algorithms.

When to Refresh

Refresh discovery when:

plugin settings change,
runtime tier/entitlement changes,
whitebox_workflows is rebuilt or reinstalled,
tool taxonomy updates are introduced.

Common Discovery Symptoms

Provider missing entirely: plugin import/runtime bootstrap failure.
Provider appears but tools are absent: catalog read failure or stale cache.
Tools show as locked unexpectedly: runtime capability/tier mismatch.

In all cases, validate environment alignment first.

Tool Execution in QGIS

WbW-QGIS executes tools through the QGIS Processing framework.

Typical Execution Path

Select a Whitebox algorithm in Processing Toolbox.
Fill parameters in the algorithm dialog.
Execute and monitor progress/messages.
Load or inspect output artifacts.

Recommended Execution Practices

Use explicit output paths for reproducibility.
Start with small representative datasets before full runs.
Validate intermediate outputs for CRS, schema, and metadata.
Keep task logs for long workflows and batch operations.

Output Handling

Whitebox tools may produce:

raster outputs,
vector outputs,
lidar outputs,
text/report sidecar artifacts.

Confirm output type and format before chaining into downstream steps.

Progress and Messaging

Execution status and warnings should be treated as part of result validation. If a tool completes with warnings, inspect outputs before continuing.

Recipes

Recipes in WbW-QGIS are guided workflow entries that help users launch common multi-tool patterns faster.

A recipe is not a new backend algorithm. It is a curated sequence of existing tools with summary guidance, launch defaults, and tier-aware visibility.

What Recipes Provide

Recipes provide:

A short purpose statement.
A launch tool (the first tool dialog opened when you run the recipe).
A step list (ordered tool IDs for the workflow).
Optional input and output hints.
Tier gating (Open, Pro, or Enterprise).

Where Recipes Appear in QGIS

Recipes are available in the Whitebox Workflows dock panel under Workflow Recipes.

The panel includes:

Open Recipe
Copy Recipe Steps
Why Is This Locked?
Open Recipe File
Reload Recipe File
Validate Recipe File
Include locked recipes toggle

Built-in and User Recipes

WbW-QGIS merges two sources:

Built-in recipes shipped with the plugin.
User-defined recipes loaded from a local JSON file.

If a user recipe has the same id as a built-in recipe, the user recipe overrides the built-in entry.

User Recipe File Location

Default file path:

~/.whitebox_workflows_qgis/recipes.json

Override path with environment variable:

WBW_QGIS_USER_RECIPES

When you press Open Recipe File, the plugin creates the file from a template if it does not exist.

User Recipe File Format

The file may be either:

An object with a recipes array.
A direct array of recipes.

Each recipe should include:

id (required)
tools array (required)

Optional fields:

title
summary
tier (open, pro, enterprise)
launch_tool
input_hint
output_hint

Example:

{
  "recipes": [
    {
      "id": "my_custom_terrain_recipe",
      "title": "My Custom Terrain Recipe",
      "summary": "User-defined recipe example.",
      "tier": "open",
      "launch_tool": "slope",
      "tools": ["slope", "aspect", "hillshade"],
      "input_hint": "Set a DEM raster as the primary input.",
      "output_hint": "Write outputs to a dedicated project output folder."
    }
  ]
}

Validation and Error Reporting

Use Validate Recipe File in the panel to run validation and see a full report.

Validation checks include:

Entry structure is a JSON object.
id exists and is non-empty.
tools exists and is a non-empty array.
tier value is valid when supplied.

Invalid entries are skipped, while valid entries continue to load.

Warnings include recipe index and, when available, recipe id to speed up fixes.

Recipe Visibility and Tier Behavior

Recipes are filtered by:

Runtime tier entitlement.
Tool availability in the current runtime catalog.
Include locked recipes panel setting.

When Include locked recipes is enabled, recipes that are not runnable in the current runtime remain visible with lock messaging for discovery.

Discovery and Sorting

Recipes are shown alphabetically in the panel for easier scanning.

Sorting applies to both built-in and user-defined recipes.

Recommended Team Practice

For teams, keep a shared recipe JSON under version control and point WBW_QGIS_USER_RECIPES to that path in your local environment setup.

This gives you repeatable, reviewable workflow definitions without modifying plugin source files.

Licensing and Tiers

Whitebox NG is available in two licensing tiers with different capabilities and licensing models.

License Tiers

Open Tier (free): Governed by MIT/Apache 2.0 dual licensing. All Open-tier tools are free and open-source with no entitlement or activation required. Use this tier for learning, research, and open development.
Pro Tier (commercial): Proprietary software governed by EULA. Pro-tier tools provide advanced capabilities and require activation with a valid license key. Once activated, the license persists locally so you do not need to re-authenticate on each QGIS session.

How QGIS Reflects Licensing

The Whitebox Workflows QGIS plugin is a frontend layer. Licensing authority and rules are enforced in the backend runtime.

Core Principle

The plugin reflects backend capabilities; it does not define licensing rules. Runtime mode (open vs. pro) determines which tools are available and functional.

Practical Behavior

Open-tier tools are expected to run in all standard public QGIS environments.
Pro-tier tools may be visible in the plugin but locked without an active Pro license.
You can request a specific tier, but the effective tier depends on your entitlement state.

Why This Matters

One plugin surface adapts to both open and pro capability tiers.
Tool discovery remains consistent across Python, R, and QGIS frontends.
Licensing decisions and enforcement remain centralized in backend logic.

Interactive License Management

The plugin provides convenient menu actions for license management without requiring external tools or command lines.

Activating a Pro License

In QGIS, navigate to Plugins > Whitebox Workflows > Activate License.
Enter your license information when prompted:
- License key (required)
- First name (required)
- Last name (required)
- Email (required)
- Provider URL (optional; defaults to production)
Accept the EULA terms.
Click OK. The plugin will activate and persist your license locally.
The tool catalog automatically refreshes to show Pro-tier tools.

Important: License activation is tied to your machine. See Transferring a License to move to another machine.

Checking License Status

Navigate to Plugins > Whitebox Workflows > Plugin Settings (or look for diagnostics output) to see:

License validity (active or expired)
Effective tier (open or pro)
License expiration time

Transferring a License

If you need to use your Pro license on a different machine, you must first deactivate it on the current machine and then activate on the destination.

On the current machine, navigate to Plugins > Whitebox Workflows > Transfer License. This generates a portable activation payload and clears your local license state.
Share the activation payload with the destination machine (or keep it for your own use on the other machine).
On the destination machine, navigate to Plugins > Whitebox Workflows > Activate License and enter your license key using the same process as above. The destination will obtain its own local license state.

Deactivating a License

If you no longer plan to use Pro tools on this machine, navigate to Plugins > Whitebox Workflows > Deactivate License. This clears your local license state. Future sessions will fall back to Open-tier tools only.

Local License State

Once activated, your license information is stored locally at ~/.whitebox/wbw_ng_license_state.json (or override via the WBW_LICENSE_STATE_PATH environment variable). On each QGIS startup:

If valid local state exists, it is automatically loaded.
If local state is expired or missing, the plugin falls back to Open-tier mode.
You do not need to re-authenticate in QGIS on every session.

Expected Local-Dev Outcome

For most source-based setups, assume open-tier behavior unless your runtime environment is explicitly configured for Pro-enabled integration testing or you have an active Pro license activated on your machine.

Supported Data Formats

This chapter documents format support exposed through WbW-QGIS.

Authoritative backend support comes from Whitebox core crates:

Raster I/O: wbraster
Vector I/O: wbvector
LiDAR I/O: wblidar

The format tables below are aligned with those backend crates' README "Supported Formats" sections.

Raster Formats

Raster support in Whitebox is provided by wbraster.

Format	Extension(s)	Read	Write	Notes
DTED	`.dt0`, `.dt1`, `.dt2`	Yes	Yes	DTED 0/1/2 elevation; WGS-84 geographic only
ENVI HDR Labelled	`.hdr` + sidecar data	Yes	Yes	Multi-band (`BSQ` / `BIL` / `BIP`)
ER Mapper	`.ers` + data	Yes	Yes	Hierarchical header
ERDAS IMAGINE (HFA)	`.img`	Yes	No	Read-only MVP; RLC compression supported
Esri ASCII Grid	`.asc`, `.grd`	Yes	Yes	Handles `xllcorner` and `xllcenter`
Esri Binary Grid	workspace dir / `.adf`	Yes	Yes	Single-band float32, big-endian
Esri Float Grid	`.flt`, `.hdr`	Yes	Yes	Single-band float grid with header
JPEG + World File	`.jpg`, `.jpeg` + `.jgw`/`.wld`	Yes	Yes	Non-rotated georeferencing
PNG + World File	`.png` + `.pgw`/`.wld`	Yes	Yes	Non-rotated georeferencing
GeoTIFF / BigTIFF / COG	`.tif`, `.tiff`	Yes	Yes	Stripped/tiled GeoTIFF, BigTIFF, COG
GeoPackage Raster (Phase 4)	`.gpkg`	Yes	Yes	Multi-band tiled raster
GRASS ASCII Raster	`.asc`, `.txt`	Yes	Yes	`north/south/east/west`, `rows/cols` headers
Idrisi/TerrSet Raster	`.rdc`, `.rst`	Yes	Yes	`byte`, `integer`, `real`, `RGB24`
JPEG2000 / GeoJP2	`.jp2`	Yes	Yes	Pure-Rust reader and writer
PCRaster	`.map`	Yes	Yes	Value-scale aware writer
SAGA GIS Binary	`.sgrd`, `.sdat`	Yes	Yes	SAGA data types supported
Surfer GRD	`.grd`	Yes	Yes	DSAA and DSRB
Zarr v2/v3	`.zarr`	Yes	Yes	2D and 3D (`band,y,x`) chunked arrays
XYZ ASCII Grid	`.xyz`	Yes	Yes	Whitespace or comma-delimited X Y Z points

Notes:

Whitebox avoids runtime dependence on GDAL.
In QGIS workflows, GeoTIFF remains the safest default interchange raster.

Vector Formats

Vector support in Whitebox is provided by wbvector.

Format	Read	Write	Notes
FlatGeobuf (`.fgb`)	Yes	Yes	High-performance binary interchange
GeoJSON (`.geojson`)	Yes	Yes	Web-friendly text format
TopoJSON (`.topojson`)	Yes	Yes	Topology-preserving JSON format
GeoPackage (`.gpkg`)	Yes	Yes	SQLite container; multi-layer workflows
GML (`.gml`)	Yes	Yes	Standards-based XML exchange
GPX (`.gpx`)	Yes	Yes	GPS tracks/routes/waypoints
KML (`.kml`)	Yes	Yes	Google Earth-style visualization
MapInfo Interchange (`.mif` + `.mid`)	Yes	Yes	Legacy MapInfo interoperability
ESRI Shapefile (`.shp` + sidecars)	Yes	Yes	Broad legacy compatibility
GeoParquet (`.parquet`)	Yes	Yes	Optional `geoparquet` feature
KMZ (`.kmz`)	Yes	Yes	Optional `kmz` feature
OSM PBF (`.osm.pbf`)	Yes	No	Read-only; optional `osmpbf` feature

Feature-gated formats in wbvector:

geoparquet for GeoParquet support
kmz for KMZ support
osmpbf for OSM PBF read support

In QGIS workflows, GeoPackage and FlatGeobuf are good modern interchange choices; Shapefile remains a compatibility fallback.

LiDAR / Point Cloud Formats

LiDAR support in Whitebox is provided by wblidar.

Format	Read	Write	Notes
LAS	Yes	Yes	LAS 1.1-1.5, PDRF 0-15
LAZ	Yes	Yes	Standards-compliant LASzip v2/v3 Point10/Point14 codecs
COPC	Yes	Yes	COPC 1.0 hierarchy with Point14-family payloads
PLY	Yes	Yes	ASCII, binary little-endian, binary big-endian
E57	Yes	Yes	ASTM E2807 with CRC-32 page validation

Optional features in wblidar:

copc-http for HTTP range fetching of remote COPC
copc-parallel for parallel COPC writing paths
laz-parallel for optional parallel LAZ decode paths
parallel umbrella feature (enables both parallel paths)

In QGIS workflows, .copc.laz is a strong default for large point-cloud delivery and archive.

QGIS Practical Defaults

For most WbW-QGIS production workflows:

Raster default: GeoTIFF (.tif)
Vector default: GeoPackage (.gpkg) or FlatGeobuf (.fgb)
LiDAR default: COPC LAZ (.copc.laz) or LAZ (.laz)

These defaults balance compatibility, file size, and performance.

Important Distinction

Backend format support means the Whitebox runtime can read/write those formats. Specific QGIS tool dialogs may still constrain certain outputs or defaults depending on parameter wiring and the tool category.

When in doubt:

Use the tool's default output extension in QGIS.
Re-open output and validate metadata.
Use QGIS conversion tools only when you need a different interchange format.

Common Format Problems

Problem	Likely cause	Fix
Output opens but schema is unexpected	Format-specific field/type constraints	Use GeoPackage or FlatGeobuf for richer schema
Shapefile field names truncated	10-character DBF limit	Switch output to GeoPackage
Large cloud is slow to browse	Non-indexed point-cloud format	Use COPC LAZ for tiled access
Optional format not available	Feature not enabled in build	Use a non-optional format (for example GeoPackage/GeoJSON/Shapefile)
CRS appears missing in output	Sidecar or metadata issue	Confirm CRS in layer properties and re-export if needed

Reprojection and CRS

A Coordinate Reference System (CRS) defines how coordinates in a dataset map to real-world locations. CRS mismatches are one of the most common sources of silent errors in GIS workflows: two layers may display correctly on screen (because QGIS reprojects them on-the-fly for display) while producing wrong results when passed to an analysis tool that expects matching CRS inputs.

This chapter explains how to identify, verify, and correct CRS issues in WbW-QGIS workflows.

Key Concepts

Geographic CRS (GCS): Coordinates in angular units (degrees of latitude and longitude). Common examples: WGS84 (EPSG:4326), NAD83 (EPSG:4269). Not suitable as a working CRS for distance/area calculations.
Projected CRS (PCS): Coordinates in linear units (metres or feet) on a flat map projection. Examples: UTM zones, Lambert Conformal Conic, Albers Equal Area.
EPSG code: A numeric registry identifier for a CRS. EPSG:4326 = WGS84; EPSG:32617 = UTM Zone 17N (WGS84); EPSG:3978 = Canada Atlas Lambert.
On-the-fly reprojection: QGIS displays all layers in the project CRS regardless of their native CRS. This is for display only — it does not change the file on disk.
Reproject (warp): Permanently transform raster or vector data to a new CRS, writing a new file. Required before passing data to analysis tools.
Z factor: A unit-conversion factor applied when DEM horizontal units (metres) differ from vertical units (feet), or vice versa.

Choosing a Working CRS

Scenario	Recommended CRS type
Global or continental analysis	Geographic (WGS84 / EPSG:4326) for data exchange; Equal-Area projection for area measurements
Regional / national analysis	National projected CRS (e.g. Canada Atlas Lambert / EPSG:3978)
Local analysis (< 500 km extent)	UTM zone covering the study area
Terrain analysis, hydrology, LiDAR	Projected CRS in metres (UTM recommended)
Slope / distance calculations	Always use a projected CRS

Finding your UTM zone: The UTM zone number equals ⌊(longitude + 180) / 6⌋ + 1. For Ottawa, Canada (longitude ≈ –75.7°): zone 18, northern hemisphere → EPSG:32618.

Checking the CRS of a Layer

Right-click a layer in the Layers panel → Properties.
Select the Information tab.
Read the CRS field. Confirm:
- Authority and code (e.g. EPSG:32618)
- Unit (metres vs degrees)
- Datum (WGS84, NAD83, etc.)

Or in the Python Console:

from qgis.core import QgsProject

layer = QgsProject.instance().mapLayersByName('dem')[0]
crs = layer.crs()
print(crs.authid())        # e.g. "EPSG:32618"
print(crs.mapUnits())      # 0 = metres, 6 = degrees
print(crs.isGeographic())  # True if GCS

Setting the Project CRS

The project CRS controls the display and the default output CRS for tools that do not inherit CRS from their inputs.

Project → Properties → CRS tab → search by EPSG code or name → click OK.

Or use View → Panels → CRS Status at the bottom-right of the QGIS window to set the project CRS from any loaded layer.

Reprojecting a Raster

Use Reproject Raster to permanently transform a raster to a new CRS. This is required before any terrain analysis on a DEM stored in geographic (degree) coordinates.

Processing Toolbox → Whitebox Workflows → Raster → Reproject Raster

Parameter	Recommended value
Input layer	`dem_wgs84.tif`
Target EPSG code	`32618`
Resampling method	`bilinear` (elevation surfaces)
Output	`dem_utm18n.tif`

The Resampling method parameter accepts any of the methods supported by WbW's raster engine:

Method	Best for
`nearest`	Categorical / integer rasters (classification maps, stream grids)
`bilinear`	Continuous surfaces (DEMs, slope, TWI, reflectance)
`cubic`	High-quality continuous-surface resampling
`lanczos`	High-quality sinc-window resampling
`average`	3×3 mean statistic
`min` / `max`	3×3 extremum statistics
`mode`	3×3 majority-class (smoothed categorical)
`median`	3×3 median statistic
`stddev`	3×3 standard deviation

import processing

processing.run('whitebox_workflows:reproject_raster', {
    'input': '/data/dem_wgs84.tif',
    'epsg': 32618,
    'resample': 'bilinear',
    'output': '/data/dem_utm18n.tif',
})

After running, load the output and confirm in Layer Properties → Information: CRS shows EPSG:32618 and the extent is in metres.

Reprojecting a Vector Layer

Use Reproject Vector to transform a vector dataset to a new CRS.

Processing Toolbox → Whitebox Workflows → Vector → Reproject Vector

Parameter	Recommended value
Input layer	`roads_wgs84.shp`
Target EPSG code	`32618`
Output	`roads_utm18n.shp`

import processing

processing.run('whitebox_workflows:reproject_vector', {
    'input': '/data/roads_wgs84.shp',
    'epsg': 32618,
    'output': '/data/roads_utm18n.shp',
})

Reprojecting a LiDAR Dataset

Use Reproject LiDAR to transform a point cloud to a new CRS.

Processing Toolbox → Whitebox Workflows → LiDAR → Reproject LiDAR

Parameter	Recommended value
Input LiDAR file	`cloud_wgs84.laz`
Target EPSG code	`32618`
Output	`cloud_utm18n.laz`

import processing

processing.run('whitebox_workflows:reproject_lidar', {
    'input': '/data/cloud_wgs84.laz',
    'epsg': 32618,
    'output': '/data/cloud_utm18n.laz',
})

Epoch-Aware Reprojection (Dynamic Datums)

For dynamic datums and realization-to-realization transformations, the reprojection tools support optional epoch-routing controls:

coordinate_epoch
source_reference_epoch
target_reference_epoch
operation_code
prefer_official_operation
epoch_policy (strict or allow_static_fallback)

These parameters are optional. Use them when you need deterministic routing for time-dependent CRS transformations.

CSRS operational status (current)

For NAD83(CSRS) realization-routing in current WbW builds:

Active preferred-operation corridors (zone-matched UTM, zones 7-24):
- all matched-zone CSRS realization pairs v2..v8 -> v2..v8 (excluding same-realization no-op pairs), operation 10715

For CRS pairs without a registered preferred operation mapping, standard reprojection remains available via the baseline transform path.

There is no reverse-corridor pending gate in this policy.

Expected active examples in current builds:

Source	Target	Status	Operation	Zones
v3	v8	active	10715	7-24
v4	v6	active	10715	7-24
v5	v8	active	10715	7-24
v8	v5	active	10715	7-24

Inspect CSRS support in QGIS diagnostics

The plugin diagnostics report now includes a csrs_preferred_operation_support summary with:

zone range (zone_min, zone_max)
active realization pairs and operation codes
pending pair count (expected to be zero for non-identical realization pairs)

Open diagnostics from the Whitebox Workflows plugin menu, then inspect the capabilities block in the report text or JSON section for projection_csrs_preferred_operation_support.

Epoch-aware raster example

import processing

processing.run('whitebox_workflows:reproject_raster', {
  'input': '/data/dem_csrs_v3.tif',
  'epsg': 22818,
  'resample': 'bilinear',
  'coordinate_epoch': 2020.0,
  'source_reference_epoch': 2010.0,
  'target_reference_epoch': 2020.0,
  'prefer_official_operation': True,
  'epoch_policy': 'strict',
  'output': '/data/dem_csrs_v8_epoch2020.tif',
})

Epoch-aware vector example

import processing

processing.run('whitebox_workflows:reproject_vector', {
  'input': '/data/stations_csrs_v3.gpkg',
  'epsg': 22818,
  'coordinate_epoch': 2020.0,
  'prefer_official_operation': True,
  'epoch_policy': 'strict',
  'output': '/data/stations_csrs_v8_epoch2020.gpkg',
})

Epoch-aware LiDAR example

import processing

processing.run('whitebox_workflows:reproject_lidar', {
  'input': '/data/survey_csrs_v3.laz',
  'epsg': 22818,
  'coordinate_epoch': 2020.0,
  'prefer_official_operation': True,
  'epoch_policy': 'strict',
  'output': '/data/survey_csrs_v8_epoch2020.laz',
})

Assigning a Missing CRS

If a file has correct coordinates but missing or wrong CRS metadata (shown as "Unknown CRS" in Layer Properties), use one of the three Assign Projection tools to write the correct EPSG code into the file without moving any coordinates.

Assign vs. Reproject: Assigning a CRS only updates the metadata label. Use it when coordinates are already in the target system but the file has no CRS tag. If the coordinate values themselves need to change, use the Reproject tools above instead.

Assign Projection to a Raster

Processing Toolbox → Whitebox Workflows → Raster → Assign Projection Raster

Parameter	Value
Input layer	`dem_no_crs.tif`
EPSG code to assign	`32618`

import processing

processing.run('whitebox_workflows:assign_projection_raster', {
    'input': '/data/dem_no_crs.tif',
    'epsg': 32618,
})

Assign Projection to a Vector

Processing Toolbox → Whitebox Workflows → Vector → Assign Projection Vector

Parameter	Value
Input layer	`roads_no_crs.shp`
EPSG code to assign	`32618`

import processing

processing.run('whitebox_workflows:assign_projection_vector', {
    'input': '/data/roads_no_crs.shp',
    'epsg': 32618,
})

Assign Projection to a LiDAR File

Processing Toolbox -> Whitebox Workflows -> LiDAR -> Assign Projection LiDAR

Parameter	Value
Input LiDAR file	`cloud_no_crs.laz`
EPSG code to assign	`32618`

import processing

processing.run('whitebox_workflows:assign_projection_lidar', {
  'input': '/data/cloud_no_crs.laz',
  'epsg': 32618,
})

Georeferencing from Control Points

Use Georeference Raster From Control Points when the raster has no valid georeferencing and you have control points that relate pixel coordinates to map coordinates.

Processing Toolbox -> Whitebox Workflows -> Raster -> Georeference Raster From Control Points

Parameter	Recommended value
Input raster	`historical_scan.tif`
Control points CSV	`historical_scan_gcps.csv`
Destination EPSG code	`32618`
Resampling method	`bilinear` (continuous) or `nearest` (categorical)
Georeferenced raster output	`historical_scan_georef.tif`
Diagnostics report output	`historical_scan_georef_report.json` (optional)

Control-points CSV fields must include source image coordinates and target map coordinates:

source_col
source_row
target_x
target_y

import processing

processing.run('whitebox_workflows:georeference_raster_from_control_points', {
  'input': '/data/historical_scan.tif',
  'control_points': '/data/historical_scan_gcps.csv',
  'epsg': 32618,
  'resample': 'bilinear',
  'output': '/data/historical_scan_georef.tif',
  'report': '/data/historical_scan_georef_report.json',
})

Assign Projection to a LiDAR Dataset

Processing Toolbox → Whitebox Workflows → LiDAR → Assign Projection LiDAR

Parameter	Value
Input LiDAR file	`cloud_no_crs.laz`
EPSG code to assign	`32618`

import processing

processing.run('whitebox_workflows:assign_projection_lidar', {
    'input': '/data/cloud_no_crs.laz',
    'epsg': 32618,
})

The Z Factor for Terrain Tools

When a DEM's horizontal units differ from its vertical units, slope and curvature calculations are incorrect unless a Z factor is applied.

Horizontal unit	Vertical unit	Z factor
Metres	Metres	`1.0` (no conversion needed)
Metres	Feet	`0.3048`
Feet	Feet	`1.0`
Degrees (geographic)	Metres	Do not use — reproject first

All WbW terrain tools that accept a Z factor parameter apply the conversion as: slope = atan(rise × z_factor / run).

Best practice: Reproject the DEM to a projected CRS in metres before running any terrain analysis. Set Z factor to 1.0 after reprojection if vertical units are also metres.

Batch Reprojection via Python Console

Reproject all GeoPackages in a folder to EPSG:32618 using the Whitebox vector reprojection tool:

import processing
from pathlib import Path

src_dir = Path('/data/raw_vectors')
out_dir = Path('/data/projected')
out_dir.mkdir(exist_ok=True)

for gpkg in src_dir.glob('*.gpkg'):
    out = out_dir / gpkg.name
    processing.run('whitebox_workflows:reproject_vector', {
        'input': str(gpkg),
        'epsg': 32618,
        'output': str(out),
    })
    print(f"Reprojected: {gpkg.name}")

print("Batch reprojection complete.")

Reproject a folder of LiDAR files in the same pattern:

import processing
from pathlib import Path

src_dir = Path('/data/raw_lidar')
out_dir = Path('/data/projected_lidar')
out_dir.mkdir(exist_ok=True)

for las in src_dir.glob('*.laz'):
    out = out_dir / las.name
    processing.run('whitebox_workflows:reproject_lidar', {
        'input': str(las),
        'epsg': 32618,
        'output': str(out),
    })
    print(f"Reprojected: {las.name}")

print("Batch LiDAR reprojection complete.")

Common CRS Problems

Problem	Likely cause	Fix
Layers display in wrong location	Layer has incorrect assigned CRS	Assign correct CRS (do not reproject)
Slope values in hundreds of degrees	DEM in geographic CRS (degrees) — cell size << 1°	Reproject DEM to metres before running slope
Area calculations wildly wrong	Layer CRS is geographic (degrees)	Reproject to equal-area projected CRS
Watershed does not close properly	Raster and vector inputs in different CRS	Reproject all inputs to same CRS before processing
WbW tool silently returns NoData everywhere	CRS mismatch causes spatial extents not to overlap	Verify all inputs share the same CRS and extent
"Datum transform not found" warning in QGIS	Datum shift grid file not installed	Install `proj-data` package, or accept approximate transform

Validation Checklist

Project CRS is set to the intended working CRS before analysis.
All raster inputs share the same CRS, extent, and cell size.
All vector inputs share the same CRS as the raster grid.
DEM CRS is projected (linear units — metres or feet), not geographic.
Z factor is set to 1.0 when both horizontal and vertical units are metres.
Reprojected outputs have been inspected (extent in metres, CRS code confirmed).
No layers show "Unknown CRS" in the Layers panel.

Terrain Analysis and Geomorphometry

Terrain analysis — or geomorphometry — is the quantitative characterisation of land-surface form from digital elevation models (DEMs). It is one of the original strengths of the Whitebox platform and covers first-order derivatives (slope, aspect), curvature families, terrain position, roughness, multiscale analysis, and visibility.

This chapter walks through a complete primary-derivative workflow in the QGIS Processing Toolbox, followed by a Python console version for batch scripting.

Key Concepts

DEM: Raster where each cell stores surface elevation. All terrain derivatives begin here. Common sources: LiDAR bare-earth, drone photogrammetry, SRTM, Copernicus DEM.
Slope: Maximum rate of elevation change per unit distance (degrees or percent). Core input for erosion, landslide, and routing models.
Aspect: Compass direction a slope faces (0–360°, clockwise from north). Flat cells are assigned –1. Controls solar insolation and moisture.
Curvature: Rate of change of slope. Profile curvature describes flow acceleration/deceleration; plan curvature describes flow convergence/divergence.
TPI / geomorphons: Terrain position indices and landform classification assign cells to ridge, slope, valley, etc., without manual thresholds.
TWI: Topographic Wetness Index — ln(upslope area / tan(slope)) — predicts persistent soil moisture and runoff zones.

End-to-End Workflow: Primary Terrain Derivatives

This workflow takes a raw DEM through sink filling, then derives the most commonly used terrain surfaces.

Inputs

Layer	Format	Notes
`dem.tif`	GeoTIFF raster	Projected CRS (e.g. UTM) strongly recommended

Step 1 — Fill Depressions

Sinks (isolated low cells) in a DEM cause flow-routing artifacts in all downstream terrain derivatives. Fill them first.

Processing Toolbox → Whitebox Workflows → Spatial Hydrology → Fill Depressions

Parameter	Recommended value
Input DEM	`dem.tif`
Fix flats	✓ enabled
Flat increment	`0.001` (one thousandth of the DEM z unit)
Output	`dem_filled.tif`

Why fix flats? Perfectly flat areas produce ambiguous flow directions. Adding a tiny gradient across flats ensures a routable surface.

Step 2 — Slope

Processing Toolbox → Whitebox Workflows → Terrain Analysis → Slope

Parameter	Recommended value
Input DEM	`dem_filled.tif`
Output units	`Degrees`
Z conversion factor	`1.0` (set to `0.3048` if DEM z is in feet but CRS is metres)
Output	`slope.tif`

Expected output range: 0° (flat) to ~85° (near-vertical cliff). Values above 70° often indicate interpolation artefacts — inspect those cells.

Step 3 — Aspect

Processing Toolbox → Whitebox Workflows → Terrain Analysis → Aspect

Parameter	Recommended value
Input DEM	`dem_filled.tif`
Output	`aspect.tif`

Flat cells receive –1. Apply a pseudocolor ramp (circular HSV) to aspect for intuitive visualisation of slope direction.

Step 4 — Hillshade

Processing Toolbox → Whitebox Workflows → Terrain Analysis → Hillshade

Parameter	Recommended value
Input DEM	`dem_filled.tif`
Azimuth (°)	`315` (NW sun — standard cartographic convention)
Altitude (°)	`45`
Z factor	`1.0`
Output	`hillshade.tif`

Set the hillshade layer to Multiply blend mode in QGIS and overlay it on a coloured DEM for a publication-quality relief map.

Step 5 — Profile and Plan Curvature

Processing Toolbox → Whitebox Workflows → Terrain Analysis → Profile Curvature

Parameter	Recommended value
Input DEM	`dem_filled.tif`
Output	`profile_curv.tif`

Repeat for Plan Curvature → plan_curv.tif.

Style both outputs with a diverging colour ramp centred on 0. Negative profile curvature (blue) marks deceleration zones (valley bottoms); positive (red) marks acceleration zones (ridge crests). Plan curvature negatives mark convergent hollows; positives mark divergent noses.

Step 6 — Topographic Wetness Index

Processing Toolbox → Whitebox Workflows → Terrain Analysis → Wetness Index

Parameter	Recommended value
Slope raster	`slope.tif`
Specific contributing area raster	(run `D8 Flow Accumulation` first — see Spatial Hydrology chapter)
Output	`twi.tif`

High TWI values (> 8–10) indicate persistent moisture zones. Use as a predictor variable in soil, flood, and habitat models.

Python Console Equivalent

Paste the following into the QGIS Python Console (Plugins → Python Console) or save as a Processing script to batch multiple DEMs.

import processing

dem = '/data/dem.tif'

# Step 1: fill depressions
processing.run('whitebox_workflows:fill_depressions', {
    'dem': dem,
    'fix_flats': True,
    'flat_increment': 0.001,
    'output': '/data/dem_filled.tif',
})

# Step 2: slope
processing.run('whitebox_workflows:slope', {
    'dem': '/data/dem_filled.tif',
    'units': 'Degrees',
    'zfactor': 1.0,
    'output': '/data/slope.tif',
})

# Step 3: aspect
processing.run('whitebox_workflows:aspect', {
    'dem': '/data/dem_filled.tif',
    'output': '/data/aspect.tif',
})

# Step 4: hillshade
processing.run('whitebox_workflows:hillshade', {
    'dem': '/data/dem_filled.tif',
    'azimuth': 315.0,
    'altitude': 45.0,
    'zfactor': 1.0,
    'output': '/data/hillshade.tif',
})

# Step 5: curvature
processing.run('whitebox_workflows:profile_curvature', {
    'dem': '/data/dem_filled.tif',
    'output': '/data/profile_curv.tif',
})
processing.run('whitebox_workflows:plan_curvature', {
    'dem': '/data/dem_filled.tif',
    'output': '/data/plan_curv.tif',
})

print("Terrain derivatives complete.")

Advanced: Geomorphons Landform Classification

Geomorphons classify each cell into one of ten landform elements (peak, ridge, shoulder, spur, slope, hollow, footslope, valley, pit, flat) by analysing horizon profiles in eight compass directions.

Processing Toolbox → Whitebox Workflows → Terrain Analysis → Geomorphons

Parameter	Recommended value
Input DEM	`dem_filled.tif`
Search distance (cells)	`50` (adjust to DEM resolution and landscape scale)
Skip radius (cells)	`0`
Flatness threshold (°)	`1.0`
Output	`geomorphons.tif`

The output is a categorical raster (1–10). Apply a predefined categorical colour map — the Geomorphons palette is available in many QGIS style repositories.

processing.run('whitebox_workflows:geomorphons', {
    'dem': '/data/dem_filled.tif',
    'search': 50,
    'skip': 0,
    'threshold': 1.0,
    'output': '/data/geomorphons.tif',
})

Pro Siting Sweep Diagnostics

For Pro terrain siting workflows (wind_turbine_siting and solar_site_suitability_analysis), providing a sweep specification executes a multi-run grid and emits extra diagnostics:

run_matrix_summary (CSV)
sensitivity_report (JSON)
sensitivity_report_html (HTML)
stability_map (GeoTIFF; 3=high, 2=medium, 1=low)

Inside sensitivity_report, use these fields for quick robustness checks:

metrics.primary_metric
metrics.primary_relative_span
metrics.stability_class (high, medium, low)

These outputs are intended for scenario comparison and shortlist stability review before field validation.

Common Pitfalls

Problem	Likely cause	Fix
Slope values are unrealistically high (> 85°)	DEM has interpolation artefacts or NoData spikes	Run `Remove Off-terrain Objects` or inspect raw DEM
Flat areas produce zero slope everywhere	Depressions not filled before slope derivation	Run `Fill Depressions` first
Aspect shows –1 across large areas	Large flat regions in DEM	Expected for flat input; check DEM resolution
Curvature is noisy on fine-resolution DEMs	Sensor noise dominates at small spatial scales	Apply `Gaussian Filter` (σ ≈ 1–2 cells) before curvature
Units mismatch — Z factor warning	Horizontal CRS in metres but DEM z in feet	Set Z conversion factor to `0.3048`

Validation Checklist

DEM uses a projected CRS (not geographic degrees).
No unexpected flat artefacts introduced by depression filling.
Slope range plausible for local relief (inspect histogram).
Aspect –1 cells are spatially limited to genuine flats.
Curvature raster has a near-symmetric distribution centred on 0.
Hillshade visually matches known ridgelines and valley geometry.

Terrain Derivatives

Accumulation Curvature

Function name: accumulation_curvature

Description

This tool calculates the accumulation curvature from a digital elevation model (DEM). Accumulation curvature is the product of profile (vertical) and tangential (horizontal) curvatures at a location (Shary, 1995). This variable has positive values, zero or greater. Florinsky (2017) states that accumulation curvature is a measure of the extent of local accumulation of flows at a given point in the topographic surface. Accumulation curvature is measured in units of m-2.

The user must specify the name of the input DEM (dem) and the output raster (output). The The Z conversion factor (zfactor) is only important when the vertical and horizontal units are not the same in the DEM. When this is the case, the algorithm will multiply each elevation in the DEM by the Z Conversion Factor. Curvature values are often very small and as such the user may opt to log-transform the output raster (log). Transforming the values applies the equation by Shary et al. (2002):

Θ' = sign(Θ) ln(1 + 10n|Θ|)

where Θ is the parameter value and n is dependent on the grid cell size.

For DEMs in projected coordinate systems, the tool uses the 3rd-order bivariate Taylor polynomial method described by Florinsky (2016). Based on a polynomial fit of the elevations within the 5x5 neighbourhood surrounding each cell, this method is considered more robust against outlier elevations (noise) than other methods. For DEMs in geographic coordinate systems (i.e. angular units), the tool uses the 3x3 polynomial fitting method for equal angle grids also described by Florinsky (2016).

References

Florinsky, I. (2016). Digital terrain analysis in soil science and geology. Academic Press.

Florinsky, I. V. (2017). An illustrated introduction to general geomorphometry. Progress in Physical Geography, 41(6), 723-752.

Shary PA (1995) Land surface in gravity points classification by a complete system of curvatures. Mathematical Geology 27: 373–390.

Shary P. A., Sharaya L. S. and Mitusov A. V. (2002) Fundamental quantitative methods of land surface analysis. Geoderma 107: 1–32.

Parameter	Recommended value
Input D8 pointer	`d8_pointer.tif`
Output type	`Cells`
Log-transform output	☐ (disable for threshold-based channel extraction)
Output	`d8_accum.tif`

Parameter	Recommended value
Pour points	`outlets.shp`
Flow accumulation	`d8_accum.tif`
Snap distance (map units)	`200` (metres — adjust to point accuracy)
Output	`outlets_snapped.shp`

Parameter	Recommended value
D8 pointer	`d8_pointer.tif`
Pour points	`outlets_snapped.shp`
Output	`watersheds.tif`

Parameter	Recommended value
D8 pointer	`d8_pointer.tif`
Streams raster	`streams.tif`
Output	`strahler.tif`

Whitebox Workflows for QGIS User Manual