What Processing Tasks Are Handled by the GeoLibre Python Sidecar?

The GeoLibre Python sidecar is a FastAPI service that executes heavy-weight geoprocessing tasks—including Whitebox workflows, GDAL conversions, rasterio operations, GeoPandas analysis, Apache Sedona SQL, and AI segmentation—that cannot run in the browser bundle.

The opengeos/GeoLibre repository includes an optional Python sidecar that extends the desktop application with server-side processing capabilities. When installed, this sidecar runs locally on 127.0.0.1:8765 and handles computationally intensive operations that exceed the limitations of WebAssembly or browser-based execution environments.

Sidecar Architecture and Communication

The sidecar is implemented as a FastAPI application located in backend/geolibre_server/. It is started automatically by the GeoLibre desktop app or manually via the geolibre-server CLI command. The architecture follows a simple local HTTP pattern where the Electron frontend proxies complex geoprocessing requests to the Python runtime.

When the sidecar is unavailable, the UI gracefully falls back to in-browser alternatives such as DuckDB-WASM for conversions or Pyodide for lightweight GeoPandas operations, though with reduced performance and capability.

Whitebox Toolbox Integration

The sidecar provides full access to the Whitebox Workflows suite through dedicated endpoints in geolibre_server/app/whitebox.py. This integration handles terrain analysis, hydrological modeling, and LiDAR processing that require the complete WhiteboxTools backend.

Key endpoint pattern: /whitebox/*

Example: Fill Sinks operation

curl -X POST http://127.0.0.1:8765/whitebox/fill_sinks \
     -F "dem=@dem.tif" \
     -F "output=@filled.tif"

This endpoint streams raster data to the sidecar, executes the Whitebox algorithm in a managed Python environment, and returns the processed output path.

Data Conversion Pipeline

The conversion module (geolibre_server/app/conversion.py) handles format transformations requiring the GDAL and rio-cogeo stack. These operations generate cloud-optimized geospatial formats essential for web visualization.

Supported conversions:

• Vector → FlatGeobuf (/conversion/vector-to-flatgeobuf)
• Vector → PMTiles (/conversion/vector-to-pmtiles)
• Raster → COG (/conversion/raster-to-cog)

Example: Convert GeoJSON to PMTiles

curl -X POST http://127.0.0.1:8765/conversion/vector-to-pmtiles \
     -H "Content-Type: application/json" \
     -d '{"input_path":"mydata.geojson","output_path":"tiles.pmtiles","zoom":12}'

These endpoints require the conversion extra dependencies and execute GDAL commands in isolated subprocess calls within the sidecar environment.

Raster Processing with Rasterio

Common raster operations are exposed through geolibre_server/app/raster.py using the rasterio library. This module handles tasks that require direct access to geospatial raster libraries unavailable in browser contexts.

Available operations: hillshade, slope, aspect, reproject, resample, clip, polygonize, and contour generation.

Example: Generate Hillshade

curl -X POST http://127.0.0.1:8765/raster/hillshade \
     -F "file=@dem.tif" \
     -F "z_factor=1.0" \
     -F "output_path=hillshade.tif"

The raster processing pipeline supports multipart file uploads and returns cloud-optimized outputs when possible.

Vector Processing with GeoPandas

Projection-aware vector operations are handled by geolibre_server/app/vector.py using GeoPandas and Shapely. These endpoints execute geometric calculations requiring accurate metric projections and spatial predicates.

Supported tasks: buffer generation, centroid calculation, dissolve operations, and coordinate reference system transformations.

Unlike client-side turf.js or similar libraries, these operations handle complex coordinate transformations and large dataset operations that exceed browser memory constraints.

Spatial SQL via Apache Sedona

The sidecar executes spatial SQL queries through Apache Sedona via endpoints defined in geolibre_server/app/sql.py. This enables advanced spatial analytics using SQL syntax over registered vector layers.

Key endpoints:

• /sql/run - Submit spatial SQL queries
• /sql/status - Check query execution status

SedonaDB integration allows for distributed spatial joins, spatial indexing, and complex geometric predicates on large vector datasets without loading entire files into browser memory.

AI Segmentation Proxy

Computer vision tasks are handled by the ML module (geolibre_server/app/ml.py), which proxies requests to an external samgeo-api server. This architecture supports SamGeo and SAM 3 models for automated feature extraction from imagery.

Segmentation modes:

• Text-prompt segmentation (/ml/segment/text)
• Automatic mask generation
• Point-prompt segmentation

Example: Text-Prompt Segmentation

curl -X POST http://127.0.0.1:8765/ml/segment/text \
     -F "file=@image.tif" \
     -F "prompt=trees"

The sidecar manages the heavy GPU inference workload while the desktop UI handles visualization of generated vector masks.

PostGIS Connectivity

Optional PostGIS support is implemented in geolibre_server/app/postgis.py, providing endpoints to query remote PostgreSQL/PostGIS databases (/postgis/*). These connections are protected by allow-list configurations to prevent unauthorized database access.

This integration enables direct SQL queries against enterprise spatial databases, returning results as GeoJSON or FlatGeobuf for immediate visualization in the GeoLibre interface.

Installation and Optional Dependencies

The sidecar is an optional component installed via pip extras. The modular dependency structure allows users to install only required processing capabilities:

pip install -e ".[whitebox, conversion, raster, vector, sedona, ml]"

Dependency groups:

• whitebox - WhiteboxTools integration
• conversion - GDAL/rio-cogeo stack
• raster - rasterio processing
• vector - GeoPandas engine
• sedona - Apache Sedona spatial SQL
• ml - SamGeo segmentation proxy

All components run within the same FastAPI process on port 8765, with automatic route registration based on installed extras.

Summary

• The GeoLibre Python sidecar is a FastAPI service providing server-side geoprocessing for the desktop application.
• It handles Whitebox workflows, GDAL conversions (FlatGeobuf, PMTiles, COG), rasterio operations, and GeoPandas vector processing.
• Advanced capabilities include Apache Sedona spatial SQL, SamGeo AI segmentation, and PostGIS connectivity.
• The sidecar operates on 127.0.0.1:8765 and is optional; the UI falls back to DuckDB-WASM or Pyodide when unavailable.
• Install specific capabilities using pip extras: whitebox, conversion, raster, vector, sedona, and ml.

Frequently Asked Questions

Is the Python sidecar required to run GeoLibre?

No. The sidecar is entirely optional. GeoLibre functions as a standalone desktop application using WebAssembly-based alternatives like DuckDB-WASM for conversions and Pyodide for lightweight vector operations. However, the sidecar is required for WhiteboxTools integration, large-scale raster processing, and AI segmentation features.

How does the sidecar communicate with the GeoLibre desktop application?

The sidecar exposes a local HTTP API on 127.0.0.1:8765. The Electron-based desktop app detects the sidecar on startup and routes eligible processing requests to these endpoints. Communication occurs entirely on the local machine with no external network requirements, ensuring data privacy and low latency.

What happens if I attempt to use a sidecar feature without installing the optional dependencies?

If the sidecar is not running or lacks specific extras (e.g., attempting Whitebox processing without pip install .[whitebox]), the GeoLibre UI will either disable the relevant menu options or attempt to fall back to browser-based alternatives. For conversions, DuckDB-WASM handles basic transformations; however, Whitebox and AI segmentation features will display an error indicating the sidecar is unavailable.

Can the GeoLibre Python sidecar run on a remote server?

The default configuration binds to localhost (127.0.0.1) for security. While the codebase could theoretically support remote deployment by changing the bind address and configuring CORS, the architecture is designed for local execution to maintain data locality and avoid exposing geoprocessing endpoints to network attacks. Remote PostGIS querying is supported, but the processing sidecar itself expects local deployment.

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