# GERS Conflation

> How geolith deduplicates features between OSM and Overture using the Global Entity Reference System.

## Overview

When building tiles from both OpenStreetMap and Overture Maps, many features exist in both datasets — the same building, road, or administrative boundary appears twice. geolith uses the [Overture Global Entity Reference System (GERS)](https://docs.overturemaps.org/gers/) to identify and eliminate these duplicates automatically.

**Key concept:** Overture publishes "bridge files" — Parquet files that map OSM element IDs to GERS UUIDs. When geolith finds a match, the OSM feature is skipped and the Overture version is kept.

## How It Works

### 1. Bridge File Loading

At pipeline start, geolith loads all bridge Parquet files into a `BridgeIndex` — a hash map from OSM element IDs (e.g., `w1182486582@1`) to GERS UUIDs. This index is thread-safe and shared across all reader threads.

### 2. OSM Deduplication

During OSM PBF reading, each feature's element ID is checked against the `BridgeIndex`. If a match is found, the OSM feature is dropped — Overture's version (already loaded in the Overture reading phase) takes precedence.

### 3. Spatial Fallback

For themes without GERS bridge files (places, POIs, landcover, water), geolith falls back to R-tree/H3 spatial deduplication. Features from OSM and Overture that overlap within a configurable distance threshold are deduplicated based on attribute similarity.

## Setup

### Download Bridge Files

```bash
aws s3 sync --no-sign-request \
  s3://overturemaps-us-west-2/bridgefiles/2026-02-18.0/dataset=OpenStreetMap/ \
  ./data/gers-bridge/
```

This produces approximately 32 GB across three themes:

- `buildings/` — 480 Parquet files (~21 GB)
- `transportation/` — 480 Parquet files (~11 GB)
- `divisions/` — 4 Parquet files (~255 MB)

### Directory Layout

Place bridge files as a sibling of your Overture data directory:

```
data/
├── overture/          ← --data
├── gers-bridge/       ← auto-discovered
│   ├── buildings/
│   │   ├── part-00000.zstd.parquet
│   │   └── ...
│   ├── transportation/
│   │   ├── part-00000.zstd.parquet
│   │   └── ...
│   └── divisions/
│       ├── part-00000.zstd.parquet
│       └── ...
├── planet-latest.osm.pbf
└── natural_earth.sqlite
```

## Configuration

### Auto-Discovery (Default)

No flags needed. geolith checks for `gers-bridge/` next to `--data` automatically:

```bash
geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles
```

If bridge files are found, the log shows:

```
INFO geolith::pipeline: Loaded 1099 GERS bridge files (buildings: 480, transportation: 480, divisions: 4)
```

### Explicit Bridge Directory

```bash
geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles \
  --bridge-dir /mnt/ssd/gers-bridge
```

### Individual Bridge Files

```bash
geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles \
  --bridge-files ./bridges/buildings.parquet \
  --bridge-files ./bridges/transportation.parquet
```

### Disable Conflation

```bash
geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles \
  --no-conflate
```

## Discovery Priority

geolith checks for bridge files in this order:

1. `--bridge-dir <path>` — explicit directory flag
2. `--bridge-files <path>` — individual file flags (additive with `--bridge-dir`)
3. `gers-bridge/` sibling — auto-discovered next to `--data`

If none are found, conflation is silently disabled and both OSM + Overture features are included as-is.

## Covered Themes

| Theme | Bridge Coverage | Fallback |
| --- | --- | --- |
| Buildings | GERS bridge files | — |
| Roads/Transit | GERS bridge files | — |
| Divisions/Boundaries | GERS bridge files | — |
| Places | — | Spatial dedup (R-tree/H3) |
| POIs | — | Spatial dedup (R-tree/H3) |
| Landcover | — | Spatial dedup (R-tree/H3) |
| Water | — | Spatial dedup (R-tree/H3) |

## Impact

With GERS conflation enabled on a planet build:

- **Buildings** — eliminates millions of duplicate building footprints
- **Roads** — removes duplicate road segments (OSM highways ↔ Overture transportation)
- **Divisions** — deduplicates administrative boundaries
- **Output size** — typically 15–30% smaller than without conflation
- **Visual quality** — no overlapping/doubled geometry artifacts

## Troubleshooting

**"No bridge files found"** — check that `gers-bridge/` is a sibling of your `--data` directory, or use `--bridge-dir` explicitly.

**"Loaded 0 bridge files"** — the directory exists but contains no `.parquet` files. Verify the download completed.

**Large output with conflation** — some features may not have GERS matches (new OSM edits, Overture coverage gaps). This is expected. Spatial fallback handles remaining themes.