# How the Whitebox Geoprocessing Toolbox Integrates with the GeoLibre UI: A Complete Technical Guide

> Discover how GeoLibre integrates the Whitebox geoprocessing toolbox via a three-layer architecture for seamless catalog menu generation, deep-linking, and backend execution with FastAPI.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-01

---

**GeoLibre integrates the Whitebox Next Gen geoprocessing toolbox through a three-layer architecture spanning catalog-based menu generation, URL-based deep-linking with parameter handling, and backend execution via a FastAPI sidecar that manages the Python runtime environment.**

The **Whitebox geoprocessing toolbox integration** in GeoLibre enables desktop and web users to access hundreds of geospatial analysis tools through a unified interface. This integration is implemented across the opengeos/GeoLibre repository as a coordinated system connecting the React-based frontend, Tauri desktop shell, and Python sidecar backend.

## Catalog and Menu Generation for Whitebox Tools

The GeoLibre UI builds its **Processing** menu from a static snapshot of the Whitebox catalog rather than querying the runtime dynamically. This design ensures instant menu rendering and offline availability.

### The Static Catalog Source

The authoritative tool list resides in [`apps/geolibre-desktop/src/lib/whitebox-menu-catalog.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/whitebox-menu-catalog.ts). This file exports the **`WHITEBOX_MENU_CATALOG`** constant containing:

- Complete tool ID registry for every Whitebox and GeoLibre-authored WASM tool
- Human-readable display names mapped to technical identifiers
- Hierarchical sub-category groupings for menu organization

The menu component imports this catalog directly and renders the nested submenu structure that users navigate. This approach eliminates runtime dependencies for basic UI functionality—users can browse available tools even when the Python sidecar is offline.

### Catalog Maintenance

The static catalog is regenerated when Whitebox releases new versions or when GeoLibre authors additional WASM-based geoprocessing tools. The `KNOWN_TOOL_IDS` set—derived from this catalog—serves as the validation authority for all tool references throughout the application.

## Deep-Linking and Parameter Handling with URL Integration

GeoLibre implements **stateful URL architecture** for Whitebox tools, enabling shareable deep links that preserve tool selection and parameter configurations.

### URL Parsing and Validation

The [`apps/geolibre-desktop/src/lib/whitebox-tool-url.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/whitebox-tool-url.ts) module provides three core functions:

- **`whiteboxToolFromSearch`** – Parses `?tool=` query parameters from the current URL, validates the tool ID against `KNOWN_TOOL_IDS`, and extracts additional non-reserved parameters as tool inputs
- **`whiteboxToolFromLocation`** – Higher-level wrapper that processes the full location object
- **`buildWhiteboxToolShareUrl`** – Constructs shareable URLs pre-populated with tool ID and parameters

### Deep-Link Workflow

When a user selects a Whitebox tool through the menu, the application:

1. Updates the URL with `?tool={toolId}` plus any configured parameters
2. Renders the Processing dialog with form fields pre-populated from URL state
3. Enables "Copy link" functionality that calls `buildWhiteboxToolShareUrl` to generate portable URLs

This mechanism supports collaboration workflows—analysts can share exact tool configurations via URL rather than screenshots or written instructions.

### Code Example: Creating Shareable Tool URLs

```typescript
import { buildWhiteboxToolShareUrl, GEOLIBRE_WEB_APP_URL } from "./whitebox-tool-url";

// Pre-select the "adaptive_filter" tool with specific parameters
const toolId = "adaptive_filter";
const params = { radius: "5", sigma: "2.0" };
const shareUrl = buildWhiteboxToolShareUrl(toolId, params, GEOLIBRE_WEB_APP_URL);

console.log(shareUrl);
// → https://web.geolibre.app/?tool=adaptive_filter&radius=5&sigma=2.0

```

### Code Example: Parsing Incoming Deep Links

```typescript
import { whiteboxToolFromLocation } from "./whitebox-tool-url";

const target = whiteboxToolFromLocation();
if (target && target.known) {
  // Open Processing dialog with pre-selected tool and parameters
  openProcessingDialog(target.toolId, target.parameters);
}

```

## Backend Execution via the FastAPI Sidecar

The actual geoprocessing work is delegated to a **Python sidecar** that manages the Whitebox runtime environment. This architecture isolates heavy computation from the UI thread and enables consistent behavior across desktop (Tauri) and web deployments.

### Sidecar API Endpoint

The `/whitebox/run` endpoint defined in [`backend/geolibre_server/geolibre_server/app/whitebox.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/whitebox.py) receives execution requests with this contract:

- **Request body**: `tool_id`, `parameters`, and execution context
- **Response**: Streamed results including logs, output file paths, and completion status

### Runtime Environment Management

The sidecar handles environment setup through functions referenced from [`backend/geolibre_server/geolibre_server/app/runtime.ts`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/runtime.ts):

- **Virtual environment creation** – Isolated Python environment per installation
- **Package availability** – Ensures `whitebox_workflows` is importable before execution
- **Subprocess sandboxing** – Launches tools in controlled processes with resource limits

### Execution Guardrails

Three constants enforce operational boundaries:

- **`MAX_IN_FLIGHT_JOBS`** – Concurrent execution limit
- **`MAX_RETAINED_JOBS`** – Historical result retention cap
- **`_whitebox_run_timeout_secs`** – Per-run timeout threshold

These limits prevent resource exhaustion from runaway geoprocessing jobs.

### Code Example: Frontend Tool Execution Request

```typescript
async function runWhiteboxTool(toolId: string, parameters: Record<string, string>) {
  const response = await fetch("/whitebox/run", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tool_id: toolId, parameters })
  });

  if (!response.ok) throw new Error(`Run failed: ${response.status}`);
  const result = await response.json();
  return result; // Contains logs, output files, execution status
}

```

### Code Example: Backend Runtime Validation

Before executing any tool, the sidecar validates environment readiness. From [`whitebox.py`](https://github.com/opengeos/GeoLibre/blob/main/whitebox.py):

```python
def _check_python_import(python_executable: str) -> None:
    """Raise if a Python executable cannot import ``whitebox_workflows``."""
    completed = subprocess.run(
        [python_executable, "-c",
         "import whitebox_workflows as wbw; print(getattr(wbw, '__version__', 'unknown'))"],
        check=False,
        capture_output=True,
        text=True,
        env=_clean_env(),
        timeout=RUNTIME_DISCOVERY_TIMEOUT_SECS,
        **_subprocess_startup_kwargs(),
    )
    if completed.returncode != 0:
        raise RuntimeBootstrapError(f"{python_executable}: import failed – {completed.stderr}")

```

## Complete Execution Flow

The Whitebox geoprocessing toolbox integration follows this end-to-end sequence:

1. **Menu selection** – User clicks a tool in the Processing menu (populated from `WHITEBOX_MENU_CATALOG` in [`whitebox-menu-catalog.ts`](https://github.com/opengeos/GeoLibre/blob/main/whitebox-menu-catalog.ts))
2. **Dialog initialization** – UI opens the Processing dialog, URL updates via `buildWhiteboxToolShareUrl` pattern, form renders with tool schema
3. **Parameter configuration** – User adjusts inputs; state syncs to URL for shareability
4. **Execution trigger** – Frontend POSTs to `/whitebox/run` with validated parameters
5. **Runtime preparation** – Sidecar checks Python environment via `_check_python_import` and related runtime utilities
6. **Subprocess execution** – Tool runs in sandboxed Python process with timeout and concurrency limits
7. **Result streaming** – Logs and outputs stream to UI; completion status triggers result rendering (rasters, vectors, tabular data)

## Key Integration Files

| Component | Purpose | Source Location |
|-----------|---------|-----------------|
| Static tool catalog | Menu population, ID validation | [`apps/geolibre-desktop/src/lib/whitebox-menu-catalog.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/whitebox-menu-catalog.ts) |
| URL utilities | Deep-link parsing and generation | [`apps/geolibre-desktop/src/lib/whitebox-tool-url.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/whitebox-tool-url.ts) |
| Processing dialog | Tool form UI, sidecar API client | [`ProcessingDialog.tsx`](https://github.com/opengeos/GeoLibre/blob/main/ProcessingDialog.tsx) (UI component) |
| Sidecar API | Execution endpoint, runtime management | [`backend/geolibre_server/geolibre_server/app/whitebox.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/whitebox.py) |
| Runtime utilities | Virtual env, package installation | [`backend/geolibre_server/geolibre_server/app/runtime.ts`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/runtime.ts) |

## Summary

- **GeoLibre's Whitebox integration** uses a static catalog ([`whitebox-menu-catalog.ts`](https://github.com/opengeos/GeoLibre/blob/main/whitebox-menu-catalog.ts)) for instant menu rendering without runtime dependencies
- **URL-based state management** ([`whitebox-tool-url.ts`](https://github.com/opengeos/GeoLibre/blob/main/whitebox-tool-url.ts)) enables shareable deep links with tool IDs and parameters preserved in `?tool=` query strings
- **FastAPI sidecar** ([`whitebox.py`](https://github.com/opengeos/GeoLibre/blob/main/whitebox.py)) isolates Python geoprocessing in a managed runtime with enforced resource limits
- **Three-layer architecture** separates concerns: catalog presentation, stateful URL handling, and sandboxed backend execution
- **Cross-platform consistency**—the same integration patterns work in Tauri desktop builds and web deployments

## Frequently Asked Questions

### How does GeoLibre handle Whitebox tool updates?

The `WHITEBOX_MENU_CATALOG` in [`whitebox-menu-catalog.ts`](https://github.com/opengeos/GeoLibre/blob/main/whitebox-menu-catalog.ts) is a static snapshot regenerated when new Whitebox versions release or GeoLibre authors additional WASM tools. The UI menu updates automatically when this file changes; no runtime catalog queries are needed for basic functionality.

### Can users share Whitebox tool configurations with colleagues?

Yes. The `buildWhiteboxToolShareUrl` function in [`whitebox-tool-url.ts`](https://github.com/opengeos/GeoLibre/blob/main/whitebox-tool-url.ts) generates portable URLs containing the tool ID and all parameter values. Recipients opening these URLs see the Processing dialog pre-populated with identical settings.

### What happens if the Python sidecar is unavailable?

The Processing menu remains browsable since it relies solely on the static catalog. However, tool execution fails with an error when the frontend cannot reach the `/whitebox/run` endpoint. The UI typically indicates sidecar connectivity status.

### How does GeoLibre prevent runaway geoprocessing jobs?

The sidecar enforces three limits: `MAX_IN_FLIGHT_JOBS` for concurrency, `MAX_RETAINED_JOBS` for result history, and `_whitebox_run_timeout_secs` for per-job execution time. Exceeding any limit queues or rejects the job with an explanatory error.