tylertoo

Fast GeoParquet → PMTiles converter in Rust.

tylertoo takes its name from "Tippecanoe and Tyler Too", the 1840 U.S. campaign slogan. It's a nod to tippecanoe, the vector-tile tool this project measures itself against — tylertoo runs alongside it.

Features:

• COG-style multi-resolution overviews embedded in GeoParquet (tylertoo overview) — the file stays valid, exact, SQL-queryable GeoParquet
• PMTiles export from an overview file (tylertoo export-pmtiles)
• One-shot GeoParquet → PMTiles (tylertoo tiles, or the bare form)
• Quality ladder tuned against tippecanoe: class ranking (Overture auto-detect), visibility gates, density budget, point clustering, line coalescing
• Memory-bounded streaming conversion — a 632k-polygon / 38M-vertex file converts to a full z0–14 overview pyramid in ~45 s at ~1.4 GB peak RSS, or a default z0–6 pyramid in ~7 s at ~0.4 GB (16-core machine)
• Remote inputs (s3://, https://, gs://) read via byte-range requests — with --bbox, extract a city from a remote country-scale file while downloading only the matching row groups (Remote Reads)
• Attribute filtering (--filter / --where) — tile only the features matching a SQL-WHERE-style predicate ("confidence > 0.8", "crop IN ('soy', 'corn')"), with parquet row-group statistics pushdown so non-matching row groups are never read (or fetched, on remote input); composes with --bbox (Tuning guide)
• Spec validation (tylertoo validate)
• PMTiles → GeoParquet decoding (tylertoo decode) — tippecanoe-decode semantics, any PMTiles v3 MVT archive

⚠️ Work in Progress: Code is generated with Claude; take it with a grain of salt. --Nissim

Install

cargo install tylertoo    # CLI
pip install tylertoo      # Python

Usage

# One-shot: GeoParquet in, PMTiles out (recommended)
tylertoo input.parquet output.pmtiles --min-zoom 0 --max-zoom 14

# Keep the reusable multi-resolution overview file too — one run, both artifacts
tylertoo input.parquet output.pmtiles --max-zoom 14 \
  --keep-overview overviews.parquet

The one-shot form materializes an intermediate overview GeoParquet before exporting (at least input-sized — it is not zero-disk). Its path and size are logged, --spill-dir / $TMPDIR control where it lives, and a free-space preflight warns when the volume looks too small.

The Two-Step Workflow

The overview GeoParquet file is the interesting artifact — build it explicitly when you want to validate it, query it, or re-export with different flags without re-converting:

# 1. Embed multi-resolution levels in a GeoParquet file
tylertoo overview input.parquet overviews.parquet \
  --min-zoom 0 --max-zoom 14

# 2. Validate against the spec
tylertoo validate overviews.parquet

# 3. Export a PMTiles archive for map rendering
tylertoo export-pmtiles overviews.parquet output.pmtiles

To match what tiles writes, pass export-pmtiles --min-zoom <the overview's requested minimum> — otherwise the archive header starts at the coarsest level that actually holds features.

Every tuning knob is available on the one-shot tiles command as well as on overview / export-pmtiles — see Overview Tuning. Defaults are calibrated on rendered corpus sweeps and are meant to look right out of the box.

Decoding PMTiles back to GeoParquet

# Extract one zoom of any PMTiles v3 vector archive as GeoParquet
tylertoo decode input.pmtiles output.parquet --zoom 14

The output is the tiled representation (simplified, clipped, duplicated across tiles and zooms — no round-trip guarantee), with zoom/layer/ mvt_id provenance columns for filtering. See Decoding PMTiles.

Input Preparation

Inputs must be WGS84 (EPSG:4326), and should be Hilbert-sorted with sane row groups. Use geoparquet-io:

gpio convert reproject input.parquet prepared.parquet \
  -d EPSG:4326 --hilbert --row-group-size 100000

Python

from tylertoo import overview, export_pmtiles, validate

overview("input.parquet", "overviews.parquet", min_zoom=0, max_zoom=14)
validate("overviews.parquet")
export_pmtiles("overviews.parquet", "output.pmtiles")

# One-shot facade (deprecated in favor of the two-step API)
from tylertoo import convert
convert("input.parquet", "output.pmtiles", min_zoom=0, max_zoom=14)

Documentation

• Getting Started — Installation, one-shot conversion, the two-step workflow
• Diving Deeper — Input prep, zoom tuning, remote/multi-file input, bounded memory
• Reference — Generated CLI, Python, and Rust API surface
• Overview Tuning — Every generalization knob explained
• Decoding PMTiles — PMTiles → GeoParquet, limitations included
• Format Spec (draft) — The geo:overviews format contract

Development

git clone https://github.com/geoparquet-io/tylertoo.git && cd tylertoo
git config core.hooksPath .githooks
cargo build && cargo check

See CONTRIBUTING.md and DEVELOPMENT.md for details.

License

Apache-2.0