GeoLibre File Format Support and DuckDB‑WASM Spatial Conversion: A Complete Guide

GeoLibre imports vector formats including GeoJSON, GeoParquet, FlatGeobuf, zipped Shapefile, GeoPackage, KML/KMZ, and GML, using DuckDB‑WASM Spatial's ST_Read function and GDAL‑backed drivers for conversion.

GeoLibre is an open‑source geospatial data viewer built on top of MapLibre GL‑JS and DuckDB‑WASM Spatial. Understanding which file formats GeoLibre can import and how DuckDB‑WASM Spatial handles their conversion is essential for working with diverse spatial datasets directly in the browser. This article examines the supported formats and the conversion pipeline implemented in the opengeos/GeoLibre codebase.

Supported Vector File Formats in GeoLibre

GeoLibre's Add Data interface supports the following vector formats, as documented in docs/user-guide/adding-data.md:

Format	Handling Strategy
GeoJSON	Direct parsing or DuckDB‑WAMS Spatial fallback
GeoParquet	Native DuckDB Parquet reader with Spatial extension
FlatGeobuf	Streaming parser with spatial index support
Zipped Shapefile (*.zip)	Primary: shpjs parser; fallback to ST_Read
GeoPackage (*.gpkg)	DuckDB‑WASM Spatial ST_Read with GDAL driver
KML / KMZ	Custom KML parser for styles; geometry‑only fallback to ST_Read
GML	DuckDB‑WASM Spatial ST_Read with GDAL driver
Other GDAL‑supported formats	Generic ST_Read path for any compiled GDAL driver

Raster formats including Cloud‑Optimized GeoTIFF (COG) and standard GeoTIFF are supported via maplibre-gl-raster, though this article focuses on vector import mechanics.

How DuckDB‑WASM Spatial Converts Imported Files

The conversion pipeline centers on DuckDB‑WASM Spatial, a WebAssembly‑compiled extension that brings GDAL‑powered spatial operations to the browser. In docs/architecture.md, the architecture is described as using DuckDB‑WASM for "formats that need conversion before MapLibre can render them."

GeoParquet: Native Parquet Reader

GeoParquet files bypass GDAL entirely. The system loads the Spatial extension first, then executes DuckDB's native Parquet reader:

SELECT * FROM read_parquet('path/to/file.parquet')

This approach delivers fast, column‑wise access optimized for cloud‑native workflows. The Spatial extension automatically recognizes geometry columns encoded in the GeoParquet specification.

GDAL‑Backed Formats: The ST_Read Function

For formats requiring GDAL drivers, GeoLibre constructs SQL queries using DuckDB‑WASM Spatial's ST_Read function. The core pattern appears throughout the codebase:

SELECT * FROM ST_Read('path/to/file', keep_wkb=true, layer='layerName')

Key parameters include:

• keep_wkb=true — Preserves Well‑Known Binary geometry encoding for efficient downstream processing
• layer='...' — Selects specific layers from multi‑layer sources like GeoPackage or FileGDB

The ST_Read function is implemented in DuckDB‑WASM Spatial's GDAL integration, compiled to WebAssembly. This enables browser‑based access to drivers that would traditionally require a full GDAL installation.

Zipped Shapefile: Dual‑Strategy Parsing

Zipped Shapefiles receive special handling due to their ubiquity and complexity. As noted in docs/architecture.md:

1. Primary path: The shpjs JavaScript library parses the ZIP archive client‑side, extracting .shp, .dbf, and .prj components
2. Fallback path: If shpjs encounters malformed files or missing components, GeoLibre automatically retries with ST_Read, leveraging GDAL's more robust Shapefile driver

// Conceptual flow from duckdb-vector-loader.ts
async function loadShapefile(fileBlob: Blob) {
  try {
    // Attempt pure-JavaScript parsing
    const geojson = await shpjs.readZip(fileBlob);
    return geojson;
  } catch (parseError) {
    // Fallback to DuckDB-WASM Spatial
    const sql = `SELECT * FROM ST_Read('${filePath}', keep_wkb=true)`;
    return await duckDb.query(sql);
  }
}

KML/KMZ: Preserving Styles with Custom Parser

KML files present unique challenges because they contain SimpleStyle properties (fill colors, stroke widths, icons) that standard GDAL readers may discard. GeoLibre employs a custom KML parser to preserve these styling attributes. When styling information is absent or the parser encounters unsupported constructs, the system falls back to ST_READ for geometry extraction.

This dual approach ensures that Google Earth‑exported datasets retain their visual appearance while maintaining robust import capabilities.

Metadata Extraction with ST_Read_Meta

Before loading features, GeoLibre queries layer metadata to determine coordinate reference systems and available layers:

SELECT * FROM ST_Read_Meta('path/to/file')

The metadata query enables:

• Automatic CRS detection and reprojection to EPSG:4326 for MapLibre compatibility
• Layer selection UI for multi‑layer sources
• Schema inspection for attribute type inference

If metadata cannot be materialized—common with older file schemas—the import proceeds with WGS84 as a safe default.

Implementation in Source Files

apps/geolibre-desktop/src/lib/duckdb-vector-loader.ts

This module implements the central loading logic, constructing ST_Read queries and managing the parser fallback chain. It handles:

• File extension detection and route selection
• SQL query generation with proper escaping (see packages/processing/src/types.ts for safe quoting guidelines)
• Result transformation to GeoJSON for MapLibre consumption

packages/processing/src/topology-tools.ts

Downstream processing demonstrates ST_Read usage in topology operations, confirming the conversion pipeline's output is compatible with advanced spatial analysis.

Performance and Security Considerations

The DuckDB‑WASM approach provides near‑native performance for format conversion while maintaining browser sandbox security. Key characteristics:

• WebAssembly isolation — GDAL operations run in a memory‑safe VM
• Streaming reads — Large files are processed without full memory loading
• SQL injection prevention — File paths are parameterized; see packages/processing/src/types.ts for secure construction patterns

Summary

• GeoLibre imports eight major vector format categories, from simple GeoJSON to complex multi‑layer GeoPackages
• DuckDB‑WASM Spatial serves as the universal conversion engine, exposing GDAL capabilities through the ST_Read SQL function
• Format‑specific optimizations include native Parquet reading, shpjs Shapefile parsing, and custom KML style preservation
• Automatic fallback chains ensure robust imports even with malformed or edge‑case files
• The architecture in docs/architecture.md and implementation in duckdb-vector-loader.ts demonstrate production‑ready patterns for browser‑based geospatial workflows

Frequently Asked Questions

What is the fastest format to import in GeoLibre?

GeoParquet offers the best performance due to its native DuckDB Parquet reader pathway, which avoids GDAL overhead and enables column‑pruned, predicate‑pushdown queries directly in the browser.

Why does GeoLibre use both shpjs and ST_Read for Shapefiles?

The shpjs parser provides faster client‑side parsing for well‑formed files, while ST_Read offers superior robustness for corrupted or complex Shapefiles. This dual strategy maximizes success rates without sacrificing speed for typical cases.

Can GeoLibre import data from URLs directly?

Yes. The duckdb-vector-loader.ts implementation supports HTTP‑accessible files. URLs are passed to ST_Read or specialized fetchers, enabling direct import from cloud storage or geospatial data APIs without local file handling.

Is KML styling preserved when imported into GeoLibre?

Yes, but only through the custom KML parser. If this parser fails and the system falls back to ST_Read, geometry will import but SimpleStyle properties (colors, stroke widths) may be lost. For best results, ensure KML files follow Google Earth's standard styling conventions.

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