Whitebox WASM Engine vs Python Sidecar for Geoprocessing: What's the Difference?

The Whitebox WASM engine runs geoprocessing tools directly in the browser via WebAssembly with zero installation required, while the Python sidecar executes tools in a separate FastAPI process using the native whitebox-workflows package for larger datasets and heavier workloads.

GeoLibre, an open-source geospatial processing platform developed by opengeos, provides two interchangeable back-ends for running Whitebox geoprocessing tools. Understanding the difference between the client-side Whitebox WASM engine and the Python sidecar helps you choose the right execution model for your data size, latency requirements, and deployment constraints.

Where Each Engine Runs

Client-Side Whitebox WASM Engine

The WASM engine executes directly in the browser (or Tauri desktop WebView) as a WebAssembly (WASI) binary. No server infrastructure, no Python interpreter, and no external dependencies are required.

• Implementation resides in packages/processing/src/wasm-client.ts [source]
• The geolibre-wasm/tools bundle contains the wbtools_oss engine plus GeoLibre-authored extensions
• Lazy-loaded at approximately 5 MB gzipped
• Executes inside an in-memory WASI filesystem

Python Sidecar

The sidecar runs in a separate FastAPI process (backend/geolibre_server) that launches a native Python interpreter to import and execute the whitebox-workflows package.

• Core logic in backend/geolibre_server/geolibre_server/app/whitebox.py [source]
• Uses official whitebox-workflows package (≥ 2.0.2)
• The /whitebox/run endpoint receives a WhiteboxRunRequest, spawns a subprocess in a temporary directory, and streams output back

Memory, Resources, and Performance

Characteristic	WASM Engine	Python Sidecar
Memory ceiling	~4 GiB (browser WebAssembly limit)	Host machine RAM only
Threading	Single-threaded	Multi-core capable
Large datasets	Must fall back to sidecar	Native handling
Latency	In-process, no network overhead	HTTP inter-process communication adds latency
Throughput	Faster for typical vector/raster sizes	Faster for very large inputs with native I/O

Installation and Deployment

WASM engine offers zero-install deployment:

• Shipped with the web application
• No pip, uv, or native wheels needed
• Works offline once loaded

Python sidecar requires environment setup:

• Python with whitebox-workflows, rio-cogeo, and optional extras
• Runtime managed via uv on-demand
• Customizable via GEOLIBRE_WHITEBOX_PACKAGE environment variable

Fault Isolation and Reliability

Both engines provide crash isolation, but differently:

• WASM crashes: Browser tab reload recovers without affecting the application
• Sidecar crashes: Isolated to the separate FastAPI process; requires HTTP retry logic and adds recovery complexity

Feature Parity and Algorithm Support

The WASM engine provides identical algorithms and outputs as the sidecar. The WASM binary is a compiled superset of Whitebox tools, as noted in wasm-client.ts lines 5-7 [source].

The sidecar adds Python ecosystem access:

• Native third-party raster utilities
• Python-only extensions
• Custom preprocessing or postprocessing scripts

Code Examples

Running a Tool with the Client-Side WASM Engine

import { runWhiteboxToolWasm } from "@geolibre/processing";

const request = {
  tool_id: "slope",
  parameters: { z_factor: "2" },
};

const job = await runWhiteboxToolWasm(request);
console.log("WASM job finished, output files:", job.output_paths);

Running the Same Tool Through the Python Sidecar

import fetch from "node-fetch";

const response = await fetch("http://localhost:8765/whitebox/run", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    tool_id: "slope",
    parameters: { z_factor: "2" },
    include_pro: false,
    tier: "open",
  }),
});
const job = await response.json();
console.log("Sidecar job ID:", job.job_id);

Key Source Files

Component	Path	Purpose
WASM runner	packages/processing/src/wasm-client.ts	Core runner and tool-manifest handling
Sidecar router	backend/geolibre_server/geolibre_server/app/whitebox.py	FastAPI endpoints, request models, runtime management
Tool catalog	apps/geolibre-desktop/public/whitebox-catalog-snapshot.json	Shared tool definitions used by both engines
WASM conversion	packages/processing/src/wasm-convert.ts	COG output formatting for browser-side results
Sidecar conversion	backend/geolibre_server/geolibre_server/app/conversion.py	COG post-processing for Python-run jobs

Summary

• Choose the WASM engine for interactive, low-latency processing without installation overhead—ideal for buffers, reprojections, and simple raster operations on moderately sized data
• Choose the Python sidecar for batch processing, datasets exceeding 4 GiB, multi-core workloads, or when you need Python ecosystem integrations
• Both engines share the same tool catalog and produce equivalent outputs, enabling seamless fallback from browser-side to server-side execution

Frequently Asked Questions

Can I use both engines in the same GeoLibre deployment?

Yes. GeoLibre automatically routes jobs based on data size, tool availability, and user preference. The same tool_id and parameters work identically in both the runWhiteboxToolWasm() function and the /whitebox/run HTTP endpoint.

What happens if a WASM job runs out of memory?

When a WASM operation approaches or exceeds the ~4 GiB browser limit, GeoLibre can transparently fall back to the Python sidecar if configured. The wasm-client.ts implementation detects large inputs and recommends server-side execution.

Does the Python sidecar require a permanent server?

No. The sidecar launches on-demand via uv and can run locally on a developer machine or as a containerized service. Environment variables control which Python packages and versions are used.

Are Whitebox Pro tools available in both engines?

Pro tools require authentication and are gated by tier validation. The WASM engine respects the same tier and include_pro flags as the sidecar, though some Pro features may be restricted in the open-source WASM bundle depending on your license.

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