# What Processing Tasks Are Handled by the GeoLibre Python Sidecar?

> Discover what processing tasks the GeoLibre Python sidecar handles. Learn about its Whitebox workflows, GDAL conversions, rasterio ops, GeoPandas analysis, Sedona SQL, and AI segmentation capabilities.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: internals
- Published: 2026-07-31

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/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**

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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**

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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**

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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**

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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:

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