Metadata-Version: 2.4
Name: gpq-tiles
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Provides-Extra: dev
Summary: Fast GeoParquet to PMTiles converter
Keywords: geoparquet,pmtiles,vector-tiles,mvt,geospatial
Home-Page: https://github.com/geoparquet-io/gpq-tiles
Author-email: Nissim Lebovits <nlebovits@pm.me>
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/geoparquet-io/gpq-tiles
Project-URL: Repository, https://github.com/geoparquet-io/gpq-tiles

# gpq-tiles

[![CI](https://github.com/geoparquet-io/gpq-tiles/actions/workflows/ci.yml/badge.svg)](https://github.com/geoparquet-io/gpq-tiles/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/geoparquet-io/gpq-tiles/branch/main/graph/badge.svg)](https://codecov.io/gh/geoparquet-io/gpq-tiles)
[![Crates.io](https://img.shields.io/crates/v/gpq-tiles.svg)](https://crates.io/crates/gpq-tiles)
[![PyPI](https://img.shields.io/pypi/v/gpq-tiles.svg)](https://pypi.org/project/gpq-tiles/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

Fast GeoParquet → PMTiles converter in Rust.

## Status

**Phase 5 complete** (329 tests passing). Core library and CLI are production-ready. Python bindings are basic but functional — [property filtering, streaming modes, and progress callbacks tracked in #45](https://github.com/geoparquet-io/gpq-tiles/issues/45).

| Interface | Status | Feature Completeness |
|-----------|--------|---------------------|
| **CLI** | ✅ Production | Full (property filters, streaming, progress, compression) |
| **Rust API** | ✅ Production | Full (all core functionality exposed) |
| **Python API** | ⚠️ Basic | Basic conversion only (see [#45](https://github.com/geoparquet-io/gpq-tiles/issues/45)) |

## Quick Start

```bash
# Install
cargo install gpq-tiles

# Basic conversion
gpq-tiles input.parquet output.pmtiles --min-zoom 0 --max-zoom 14

# With property filtering (matches tippecanoe -y/-x/-X flags)
gpq-tiles input.parquet output.pmtiles --include name --include population
gpq-tiles input.parquet output.pmtiles --exclude internal_id
gpq-tiles input.parquet output.pmtiles --exclude-all  # geometry only

# With compression options
gpq-tiles input.parquet output.pmtiles --compression zstd  # fastest decompression
```

**Python** (basic API — property filters coming in [#45](https://github.com/geoparquet-io/gpq-tiles/issues/45)):
```python
from gpq_tiles import convert
convert("input.parquet", "output.pmtiles", min_zoom=0, max_zoom=14, compression="zstd")
```

**Suppress warnings:**
```bash
gpq-tiles input.parquet output.pmtiles --quiet  # No optimization warnings
```

**Rust:**
```rust
use gpq_tiles_core::pipeline::{generate_tiles, TilerConfig};
let config = TilerConfig::new(0, 14);
let tiles = generate_tiles(Path::new("input.parquet"), &config)?;
```

## Features

- **Fast** — Parallel tile generation with Rayon, space-filling curve sorting
- **Correct** — MVT spec compliance, golden tests against tippecanoe v2.49.0
- **Smart** — Density-based feature dropping, tiny polygon removal, point thinning
- **Flexible** — Property filtering (`--include`/`--exclude`), compression options (gzip/brotli/zstd)
- **Efficient** — Tile deduplication via XXH3 hashing and run_length encoding
- **Streaming** — Process files larger than memory via row-group streaming

## Best Practices

For optimal performance with large files, optimize your GeoParquet input:

```bash
# Check and fix GeoParquet formatting with geoparquet-io
gpio check all --fix input.parquet
```

gpq-tiles will warn if input files aren't optimized. See [geoparquet-io](https://github.com/geoparquet-io/geoparquet-io) for file optimization tools.

## Project Structure

```
crates/
├── core/     # All tiling logic (gpq-tiles-core)
├── cli/      # Thin wrapper (gpq-tiles)
└── python/   # pyo3 bindings
```

## Development

```bash
git clone git@github.com:geoparquet-io/gpq-tiles.git && cd gpq-tiles
git config core.hooksPath .githooks  # Enable pre-commit hooks
cargo build && cargo test
```

**Prerequisites:** Rust 1.75+, protoc (`brew install protobuf` / `apt install protobuf-compiler`)

**Key commands:**
```bash
cargo test                    # Run all tests (333 total)
cargo bench                   # Run benchmarks
cargo fmt && cargo clippy     # Format and lint
cargo tarpaulin --out html    # Coverage report
```

## Documentation

| Document | Purpose |
|----------|---------|
| [ROADMAP.md](ROADMAP.md) | Implementation phases and progress |
| [DEVELOPMENT.md](DEVELOPMENT.md) | Development workflow, Python setup |
| [context/ARCHITECTURE.md](context/ARCHITECTURE.md) | Design decisions, tippecanoe divergences |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
| [CLAUDE.md](CLAUDE.md) | AI assistant instructions |

## Contributing

1. Fork → branch → make changes with tests → `cargo test && cargo fmt && cargo clippy`
2. Push → open PR with clear description
3. All logic goes in `crates/core`, not CLI/Python

**Commit format:** `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `perf:`, `chore:`

## License

Apache License 2.0. See [LICENSE](LICENSE).

## Acknowledgments

Built on [tippecanoe](https://github.com/felt/tippecanoe) algorithms, [geoarrow-rs](https://github.com/geoarrow/geoarrow-rs), and the Rust geospatial ecosystem. Part of [geoparquet-io](https://github.com/geoparquet-io/geoparquet-io).

