# GeoLibre PMTiles Transformations: Vector Conversion and Subset Extraction Explained

> Discover GeoLibre PMTiles transformations: convert vector data and extract geographic subsets. Optimize your vector datasets with efficient PMTiles conversions.

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

---

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

```typescript
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`](https://github.com/opengeos/GeoLibre/blob/main/tests/wasm-convert.test.ts).*

### Converting Vector Data to PMTiles (Server)

```python
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`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/conversion.py).*

### Extracting a Geographic Subset

```typescript
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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/pmtiles-extract.ts).*

## Summary

- **GeoLibre supports vector-to-PMTiles conversion** through both browser-based WebAssembly ([`wasm-convert.ts`](https://github.com/opengeos/GeoLibre/blob/main/wasm-convert.ts)) and server-side FastAPI endpoints ([`conversion.py`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/pmtiles-extract.ts) for extraction logic and [`packages/processing/src/wasm-convert.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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.