Metadata-Version: 2.3
Name: h3-toolkit
Version: 0.3.16
Summary: A toolkit for aggregating and visualizing geospatial data using H3 hexagonal grids
License: MIT
Keywords: h3,geospatial,polars,hexagon,aggregation
Author: Huang SyuanBo
Author-email: godspeed88168@gmail.com
Requires-Python: >=3.10.12,<4.0.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Provides-Extra: vis
Requires-Dist: aiohttp (>=3.11.14,<4.0.0)
Requires-Dist: geopandas (>=1.0.1,<2.0.0)
Requires-Dist: h3ronpy (>=0.22.0,<0.23.0)
Requires-Dist: mapclassify (>=2.8.0,<3.0.0) ; extra == "vis"
Requires-Dist: polars (>=1.2.1,<2.0.0)
Requires-Dist: pydeck (>=0.9.1,<0.10.0) ; extra == "vis"
Requires-Dist: tqdm (>=4.66.5,<5.0.0)
Project-URL: Homepage, https://github.com/CityScience-TaipeiTech/H3-ToolKits
Project-URL: Repository, https://github.com/CityScience-TaipeiTech/H3-ToolKits
Description-Content-Type: text/markdown

[![pypi](https://img.shields.io/pypi/v/h3_toolkit.svg)](https://pypi.python.org/pypi/h3_toolkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

# h3-toolkit

A Polars-native toolkit for aggregating and visualizing geospatial data using [Uber's H3 spatial indexing system](https://h3geo.org/).

**Documentation:** [https://h3-toolkit.readthedocs.io/](https://h3-toolkit.readthedocs.io/)

## Installation

```bash
pip install h3-toolkit

# With visualization support (pydeck, mapclassify)
pip install h3-toolkit[vis]
```

## Quick Example

```python
import geopandas as gpd
from h3_toolkit import H3Toolkit
from h3_toolkit.aggregation import Mean, Sum

# Load your vector data (e.g., census blocks, building footprints)
gdf = gpd.read_file("your_data.geojson")

result = (
    H3Toolkit()
    .process_from_vector(gdf, resolution=9)
    .set_aggregation_strategy({
        "population": Sum(),
        "income":     Mean(),
    })
    .get_result()
)

print(result)
# shape: (n, 3)
# ┌─────────────────┬────────────┬────────┐
# │ cell            ┆ population ┆ income │
# │ ---             ┆ ---        ┆ ---    │
# │ u64             ┆ f64        ┆ f64    │
# ╞═════════════════╪════════════╪════════╡
# │ 613194865823…   ┆ 1204.0     ┆ 52300. │
# └─────────────────┴────────────┴────────┘
```

## Features

- **Polars-native** — all aggregations run on Polars, no pandas overhead
- **Chainable API** — compose `process_from_vector`, `set_aggregation_strategy`, and `get_result` in a single pipeline
- **Multiple input formats** — vector (GeoDataFrame), raster, or existing H3 cells
- **Pluggable aggregation strategies** — `Sum`, `Mean`, `Count`, `EqualSplit`, `Centroid`, and more
- **Optional visualization** — built-in pydeck-based map rendering via the `vis` extra

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

## License

MIT © [City Science Lab @ TaipeiTech](https://github.com/CityScience-TaipeiTech), Syuan-Bo Huang

