Metadata-Version: 2.4
Name: freestiler
Version: 0.1.4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT 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
Classifier: Typing :: Typed
Requires-Dist: geopandas>=0.14
Requires-Dist: shapely>=2.0
Requires-Dist: pyproj>=3.0
Requires-Dist: numpy>=1.24
Requires-Dist: build>=1.2 ; extra == 'dev'
Requires-Dist: maturin>=1.7,<2.0 ; extra == 'dev'
Requires-Dist: pyarrow>=14 ; extra == 'dev'
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: twine>=5.1 ; extra == 'dev'
Requires-Dist: pyarrow>=14 ; extra == 'test'
Requires-Dist: pytest>=7.0 ; extra == 'test'
Provides-Extra: dev
Provides-Extra: test
License-File: LICENSE.md
Summary: Rust-powered MLT/MVT vector tile engine for Python
Keywords: gis,geospatial,maplibre,mvt,pmtiles,vector-tiles
Home-Page: https://walker-data.com/freestiler/
Author-email: Kyle Walker <kyle@walker-data.com>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://walker-data.com/freestiler/articles/python.html
Project-URL: Homepage, https://walker-data.com/freestiler/
Project-URL: Issues, https://github.com/walkerke/freestiler/issues
Project-URL: Repository, https://github.com/walkerke/freestiler

# freestiler for Python

`freestiler` builds PMTiles vector tile archives from GeoPandas data,
GeoParquet files, and DuckDB spatial queries using a Rust tiling engine.

Features:

- MapLibre Tiles (`mlt`) and Mapbox Vector Tiles (`mvt`)
- Multi-layer tilesets
- Point clustering
- Feature coalescing
- Exponential feature dropping for low zoom levels

## Why this package exists

- Python-native API backed by the same Rust tiler as the R package
- PMTiles output instead of tile directory trees
- Direct DuckDB SQL tiling
- Streaming point tiling for large DuckDB query results

## Installation

Install from PyPI:

```bash
pip install freestiler
```

Published PyPI wheels ship the native feature set:

- GeoPandas input
- Multi-layer tiling and feature management
- Direct GeoParquet file input
- DuckDB-backed file input
- DuckDB SQL query support

If a wheel is not available for your platform, `pip` will build from source and
requires a Rust toolchain.

## Quick Start

```python
import geopandas as gpd
from freestiler import freestile

gdf = gpd.read_file("counties.shp")

freestile(gdf, "counties.pmtiles", layer_name="counties")
```

That example is intentionally small. The more interesting path is tiling
directly from DuckDB:

```python
from freestiler import freestile_query

freestile_query(
    query="SELECT * FROM read_parquet('blocks.parquet') WHERE state = 'NC'",
    output="nc_blocks.pmtiles",
    layer_name="blocks",
)
```

For very large point tables, use `streaming="always"` and prefer
`tile_format="mvt"` for maximum viewer compatibility.

## Source Builds

Published wheels include GeoParquet and DuckDB support by default. To build
from a local checkout:

```bash
git clone https://github.com/walkerke/freestiler.git
cd freestiler/python
python3 -m venv .venv
source .venv/bin/activate
pip install maturin
python3 -m maturin develop --release
```

To build an installable wheel instead of using an editable install:

```bash
python3 -m maturin build --release --out dist
pip install dist/freestiler-*.whl
```

## Links

- Documentation: https://walker-data.com/freestiler/articles/python.html
- Source: https://github.com/walkerke/freestiler
- Issues: https://github.com/walkerke/freestiler/issues

