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

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

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

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 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:

• 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

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:

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)
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
URL utilities	Deep-link parsing and generation	apps/geolibre-desktop/src/lib/whitebox-tool-url.ts
Processing dialog	Tool form UI, sidecar API client	ProcessingDialog.tsx (UI component)
Sidecar API	Execution endpoint, runtime management	backend/geolibre_server/geolibre_server/app/whitebox.py
Runtime utilities	Virtual env, package installation	backend/geolibre_server/geolibre_server/app/runtime.ts

Summary

• GeoLibre's Whitebox integration uses a static catalog (whitebox-menu-catalog.ts) for instant menu rendering without runtime dependencies
• URL-based state management (whitebox-tool-url.ts) enables shareable deep links with tool IDs and parameters preserved in ?tool= query strings
• FastAPI sidecar (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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}