GeoLibre PMTiles Transformations: Vector Conversion and Subset Extraction Explained

GeoLibre supports two primary PMTiles transformations: converting vector datasets (Shapefile, GeoJSON) into PMTiles archives via WebAssembly or FastAPI, and extracting geographic subsets from existing PMTiles files to create smaller, self-contained archives.

The opengeos/GeoLibre repository provides specialized tooling for creating and manipulating PMTiles archives, focusing exclusively on vector-to-tile workflows and archive subsetting. These PMTiles transformations enable both browser-based processing through WebAssembly and server-side conversion via a FastAPI sidecar, while raster data is handled separately through Cloud-Optimized GeoTIFF generation.

Supported PMTiles Transformation Types

GeoLibre implements two distinct transformation categories for PMTiles archives. The codebase explicitly excludes raster-to-PMTiles conversion, routing raster workflows to COG (Cloud-Optimized GeoTIFF) generation instead.

Vector to PMTiles Conversion

This transformation packs vector datasets—including Shapefiles and GeoJSON—into a single PMTiles archive containing Mapbox Vector Tiles (MVT). The conversion preserves source metadata, attribution, and compression settings while generating a portable, self-contained tileset. According to the source code, this is implemented in two locations:

• Browser environment: packages/processing/src/wasm-convert.ts handles client-side conversion via the geolibre-wasm module
• Server environment: backend/geolibre_server/geolibre_server/app/conversion.py validates zoom levels (0 ≤ min ≤ max ≤ 24) before invoking the freestiler script

PMTiles Subset Extraction

The extractPmtiles function in packages/processing/src/pmtiles-extract.ts enables geographic clipping of existing archives. This transformation accepts a bounding box and zoom range, then fetches only the required tile blobs via parallel HTTP Range requests to assemble a new, smaller PMTiles file. The implementation uses the PmtilesExtractor WebAssembly class and streams progress via PmtilesExtractProgress for UI feedback and abort handling.

How the Transformations Work

Each transformation follows a distinct execution path optimized for its runtime environment, whether browser-based WebAssembly or Python FastAPI endpoints.

Browser-Based Vector Conversion

The client-side implementation exposes the vector_to_pmtiles command through the geolibre-wasm module, registered in apps/geolibre-desktop/src/lib/whitebox-menu-catalog.ts. The convertVectorWithWasm function processes vector data entirely within the browser, making it suitable for privacy-sensitive workflows or offline usage. The resulting archive maintains the source's tile type and compression metadata.

Server-Side Vector Conversion

The FastAPI endpoint POST /vector-to-pmtiles (defined in backend/geolibre_server/geolibre_server/app/conversion.py) accepts JSON payloads containing input paths, layer names, and zoom constraints. After validation, the endpoint executes the freestiler shell script (_PMTILES_SCRIPT) to generate the archive server-side, returning a job ID for asynchronous polling via /jobs/{id}.

Geographic Subset Extraction

When extracting subsets, extractPmtiles performs four specific operations:

1. Parses the source archive header to identify tile_type, min_zoom, max_zoom, and bounds
2. Calculates which tile blobs intersect the requested bounding box and zoom range
3. Issues parallel HTTP Range requests with retry logic to fetch only necessary bytes
4. Assembles a new .pmtiles archive containing exclusively the selected tiles

The helper function pmtilesTileTypeKind (also in pmtiles-extract.ts) maps tile-type codes (1 for MVT/vector, others for raster) to ensure correct layer treatment in the map view.

Code Examples for PMTiles Transformations

These practical implementations demonstrate the API surface for both creation and extraction workflows.

Converting Vector Data to PMTiles (Browser)

import { convertVectorWithWasm } from "geolibre-wasm";
import { renderRasterToPmtiles } from "@geolibre/processing";

// Convert a GeoJSON feature collection to PMTiles
await convertVectorWithWasm(
  { name: "points.geojson", data: pointsGeoJson },
  "points.pmtiles"
);

Reference implementation available in tests/wasm-convert.test.ts.

Converting Vector Data to PMTiles (Server)

import httpx

payload = {
    "input_path": "/data/roads.shp",
    "output_path": "/data/roads.pmtiles",
    "layer_name": "roads",
    "min_zoom": 0,
    "max_zoom": 14,
}
response = httpx.post("http://localhost:8765/vector-to-pmtiles", json=payload)
print(response.json())   # Contains job ID; poll /jobs/{id} for status

Endpoint defined in backend/geolibre_server/geolibre_server/app/conversion.py.

Extracting a Geographic Subset

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

const result = await extractPmtiles(
  "https://example.com/planet.pmtiles",
  {
    bbox: [-120, 35, -119, 36],   // WGS‑84 degrees
    minZoom: 10,
    maxZoom: 12,
    concurrency: 8,
  }
);

// result.archive is a Uint8Array containing the new PMTiles file

Core logic implemented in packages/processing/src/pmtiles-extract.ts.

Summary

• GeoLibre supports vector-to-PMTiles conversion through both browser-based WebAssembly (wasm-convert.ts) and server-side FastAPI endpoints (conversion.py), with zoom validation constraints of 0 to 24.
• Subset extraction enables geographic clipping of existing archives using the extractPmtiles function and PmtilesExtractor class, fetching only required tiles via HTTP Range requests.
• Raster-to-PMTiles is explicitly not supported; raster workflows should use the raster-to-cog tooling for Cloud-Optimized GeoTIFFs instead.
• Implementation files include packages/processing/src/pmtiles-extract.ts for extraction logic and packages/processing/src/wasm-convert.ts for client-side vector conversion.

Frequently Asked Questions

What input formats does GeoLibre support for PMTiles creation?

GeoLibre accepts standard vector geospatial formats including Shapefiles and GeoJSON for conversion to PMTiles archives. The vector_to_pmtiles command processes these formats in both browser and server environments while preserving the source coordinate reference system and metadata.

Does GeoLibre support raster to PMTiles conversion?

No, GeoLibre does not provide built-in raster-to-PMTiles conversion capabilities. According to the source code, raster data should be converted to Cloud-Optimized GeoTIFFs (COG) using the raster-to-cog workflow instead. The pmtilesTileTypeKind helper function in pmtiles-extract.ts handles reading existing raster PMTiles for display purposes only.

How does the PMTiles extraction handle large archives?

The extraction process uses parallel HTTP Range requests with configurable concurrency (defaulting to 8 simultaneous requests) to fetch only the specific tile blobs required for the requested bounding box and zoom range. This approach avoids downloading the entire source archive and includes retry logic for failed range requests, with progress streamed via PmtilesExtractProgress for real-time monitoring.

Can I convert PMTiles back to vector formats like GeoJSON?

The current GeoLibre codebase does not implement PMTiles-to-vector extraction as a built-in transformation. While the extractPmtiles function can create smaller PMTiles subsets, it outputs PMTiles archives rather than decoded vector formats. Vector data would need to be sourced from the original files used to create the PMTiles archive.

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