Documentation

Overview

The --bbox option filters features to a geographic bounding box before tile generation. This dramatically reduces processing time and output size for regional extracts.

geolith \
  --data ./overture-data \
  --output region.pmtiles \
  --bbox west,south,east,north

Coordinates are in WGS84 decimal degrees (longitude, latitude). The format is:

--bbox <west_lng>,<south_lat>,<east_lng>,<north_lat>

Common Regions

Asia

# India
--bbox 68.1,6.7,97.4,35.5

# Japan
--bbox 127.5,30.0,146.0,46.0

# Southeast Asia
--bbox 92.0,-11.0,141.0,28.5

Europe

# Western Europe
--bbox -10.0,36.0,25.0,60.0

# United Kingdom
--bbox -8.2,49.9,1.8,60.9

# Germany
--bbox 5.9,47.3,15.0,55.1

Americas

# Continental United States
--bbox -125.0,24.5,-66.9,49.4

# California
--bbox -124.4,32.5,-114.1,42.0

# Brazil
--bbox -73.9,-33.7,-34.8,5.3

Africa & Middle East

# Africa
--bbox -17.5,-34.8,51.4,37.3

# Middle East
--bbox 34.0,12.0,63.0,42.0

Oceania

# Australia
--bbox 113.0,-44.0,154.0,-10.0

# New Zealand
--bbox 166.0,-47.5,179.0,-34.0

How Filtering Works

  1. Parquet Predicate Pushdown — The bounding box is pushed down to the Parquet reader as a row group filter. Row groups whose spatial extent doesn't intersect the bbox are skipped entirely (no I/O).
  2. Feature Filtering — Individual features are tested against the bbox. Only features whose geometry intersects the bounding box are processed.
  3. Tile Clipping — Features near the bbox edges are clipped to tile boundaries as usual. Tiles entirely outside the bbox are never generated.

For very small regions (city-level), the Parquet predicate pushdown can skip 99%+ of row groups, making extraction nearly instant even from a full planet dataset.

Combining with Max Zoom

Use --bbox with --max-zoom to control both spatial extent and detail level:

# High-detail city extract
geolith \
  --data ./overture-data \
  --output mumbai.pmtiles \
  --bbox 72.7,18.85,73.05,19.3 \
  --max-zoom 15

# Low-detail continental overview
geolith \
  --data ./overture-data \
  --output europe-overview.pmtiles \
  --bbox -10.0,36.0,25.0,60.0 \
  --max-zoom 10