/backend/geolibre_server/README.md

GeoLibre Server (Python sidecar)

Optional FastAPI backend for heavy geoprocessing. Not required to run GeoLibre Desktop UI.

Install

cd backend/geolibre_server
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

Run

uvicorn geolibre_server.app.main:app --host 127.0.0.1 --port 8765 --reload

Or:

geolibre-server

Test

python -m pytest

Whitebox runtime

Whitebox tools use a dedicated GeoLibre-managed Python environment. On first use, the sidecar looks for uv; if it is not available, it downloads the official uv standalone installer and installs uv into the GeoLibre runtime cache. It then creates a Whitebox virtual environment and installs whitebox-workflows.

Useful overrides:

GEOLIBRE_RUNTIME_DIR=/path/to/cache
GEOLIBRE_UV=/path/to/uv
GEOLIBRE_UV_DIR=/path/to/managed-uv
GEOLIBRE_WHITEBOX_ENV=/path/to/whitebox-venv
GEOLIBRE_WHITEBOX_PACKAGE='whitebox-workflows>=2.0.2'
WBW_EXTERNAL_PYTHON=/path/to/python

Conversion runtime

The Processing → Conversion menu uses a dedicated managed runtime (DuckDB + rio-cogeo + freestiler), bootstrapped the same way as Whitebox: the sidecar finds or installs uv, creates a virtual environment, and installs the conversion packages on first use.

• Vector → GeoParquet and CSV → GeoParquet also run entirely in the browser with DuckDB-WASM, so they work in the web build with no sidecar.
• Vector → FlatGeobuf, Vector → PMTiles, and Raster → COG have no in-browser writer and require the sidecar.

To enable them, install the optional extras and run the sidecar:

pip install -e ".[conversion]"
geolibre-server

For the web build, serve the app from localhost:5173 — CORS is restricted to that origin and the Tauri origins, so other ports cannot reach the sidecar.

Useful overrides:

GEOLIBRE_CONVERSION_PYTHON=/path/to/python   # reuse an existing env (skip bootstrap)
GEOLIBRE_CONVERSION_ENV=/path/to/venv        # managed runtime location
GEOLIBRE_CONVERSION_PACKAGES='duckdb>=1.1.0 rio-cogeo>=5.0.0 freestiler>=0.1.0'  # whitespace-separated
GEOLIBRE_CONVERSION_ROOTS=/data:/srv/geo      # confine inputs/outputs to these roots (os.pathsep-separated; unset = no restriction)

When the sidecar is reachable by untrusted same-origin content (e.g. the bundled Docker image), set GEOLIBRE_CONVERSION_ROOTS so conversions cannot read or overwrite arbitrary filesystem paths. It is unset by default for the desktop app, where paths are the user's own filesystem.

Spatial SQL runtime (Apache Sedona)

The Apache Sedona engine of the SQL Workspace runs Sedona spatial SQL on SedonaDB (the single-node Rust engine) through the /sql endpoints. It is an optional extra:

pip install -e ".[sedona]"   # apache-sedona[db] + geopandas + shapely
geolibre-server

The sidecar reports availability through /sql/status. When the extra is not installed (or the sidecar is not running), the SQL Workspace falls back to the in-browser CereusDB engine — a WebAssembly build of SedonaDB — so the Apache Sedona engine works with no sidecar too. /sql/run registers each posted layer as a named view, runs one statement, and returns rows (geometry as WKT) plus a GeoJSON FeatureCollection when the result has a geometry column.

Endpoints

Method	Path	Description
GET	/health	Health check
GET	/algorithms	List algorithms
POST	/run	Run algorithm (501 placeholder)
GET	/conversion/status	Conversion runtime availability
POST	/conversion/vector-to-geoparquet	Vector → Hilbert-sorted GeoParquet
POST	/conversion/vector-to-flatgeobuf	Vector → Hilbert-sorted FlatGeobuf
POST	/conversion/csv-to-geoparquet	CSV (lon/lat) → GeoParquet
POST	/conversion/vector-to-pmtiles	Vector → PMTiles (freestiler)
POST	/conversion/raster-to-cog	Raster → Cloud Optimized GeoTIFF
GET	/conversion/jobs/{id}	Conversion job status
GET	/sql/status	Spatial SQL (SedonaDB) availability
POST	/sql/run	Run Sedona spatial SQL over registered layers
GET	/ml/status	Segmentation backend availability + models
POST	/ml/segment/text	Text-prompt segmentation (SAM 3)
POST	/ml/segment/automatic	Automatic mask generation
POST	/ml/segment/predict	Box/point prompt segmentation

AI segmentation runtime (SamGeo / SAM 3)

The /ml endpoints back GeoLibre's AI segmentation toolbox. They are a thin reverse-proxy in front of a separate samgeo-api server (the REST server shipped with segment-geospatial), which runs SAM 3 and returns GeoJSON. The heavy model stack (PyTorch + SAM 3) is not imported into this sidecar; install and run it on its own (ideally on a GPU host):

# the model server (in an env with a working PyTorch build)
pip install "segment-geospatial[api,samgeo3]"
# the sidecar's ml extra (just an HTTP client)
pip install -e ".[ml]"

samgeo-api is launched on demand when it is on the PATH, otherwise the proxy returns available: false with an actionable message. The desktop app runs the sidecar in a managed (uv) environment that includes the ml extra but not segment-geospatial, so samgeo-api is not on its PATH; launch the desktop app with GEOLIBRE_ML_SAMGEO_URL set to an external samgeo-api (the spawned sidecar inherits the app's environment). Configuration:

Variable	Purpose
GEOLIBRE_ML_SAMGEO_URL	Proxy to an already-running samgeo-api (no child process is launched).
GEOLIBRE_ML_SAMGEO_CMD	Command to launch samgeo-api on demand (default samgeo-api).
GEOLIBRE_ML_DEFAULT_MODEL	Model the UI defaults to (default sam3).

Each /ml/segment/* request takes a multipart file plus model_version (default sam3) and output_format (default geojson).

Future stack

The sidecar will further integrate (see docs/roadmap.md):

• Leafmap — notebook-style geospatial utilities

GDAL/Rasterio (raster tools), GeoPandas (vector engine), DuckDB Spatial (conversion), WhiteboxTools, Apache Sedona (spatial SQL), and GeoAI/SamGeo segmentation now ship as optional extras (raster, vector, conversion, whitebox, sedona, ml).

Tauri will bundle the sidecar as an externalBin in a later release.