Metadata-Version: 2.4
Name: carto-flow
Version: 1.1.2
Summary: This is a library for creating cartographs.
Project-URL: Homepage, https://bright-fakl.github.io/carto-flow/
Project-URL: Repository, https://github.com/bright-fakl/carto-flow
Project-URL: Documentation, https://bright-fakl.github.io/carto-flow/
Author-email: FKloosterman <devfakl@gmail.com>
License-File: LICENSE
Keywords: python
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.10
Requires-Dist: geopandas>=1.0.1
Requires-Dist: joblib>=1.5.2
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: numba>=0.60.0
Requires-Dist: numpy>=2.0.2
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyfftw>=0.14.0
Requires-Dist: scipy>=1.13.1
Requires-Dist: shapely>=2.1.0
Requires-Dist: tactile>=0.1.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: data
Requires-Dist: censusdis>=1.2.4; extra == 'data'
Description-Content-Type: text/markdown

# carto-flow

[![Release](https://img.shields.io/github/v/release/bright-fakl/carto-flow)](https://github.com/bright-fakl/carto-flow/releases)
[![Build Status](https://img.shields.io/github/actions/workflow/status/bright-fakl/carto-flow/main.yml?branch=main&label=build)](https://github.com/bright-fakl/carto-flow/actions/workflows/main.yml)
[![codecov](https://codecov.io/gh/bright-fakl/carto-flow/branch/main/graph/badge.svg)](https://codecov.io/gh/bright-fakl/carto-flow)
[![Commit Activity](https://img.shields.io/github/commit-activity/m/bright-fakl/carto-flow)](https://github.com/bright-fakl/carto-flow/graphs/commit-activity)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/bright-fakl/carto-flow/blob/main/LICENSE)

A Python library for creating cartograms from geographic data.

## Overview

carto-flow transforms geographic vector data into cartograms — maps where region sizes or symbols are scaled to represent a data variable such as population, GDP, or election results. It supports three cartogram styles:

- **Flow cartograms** — regions are continuously deformed so their areas are proportional to a variable, while preserving shape and topology as much as possible (diffusion-based algorithm).
- **Symbol cartograms** — regions are replaced by proportional symbols (circles, squares, hexagons, or custom isohedral tiles) arranged using physics-based or grid-based layout.
- **Proportional cartograms** — region polygons are split or shrunk to show sub-group proportions within each geographic unit.

![Cartogram Gallery](https://github.com/bright-fakl/carto-flow/raw/main/cartogram-example.png)

## Features

- Diffusion-based flow cartogram morphing with FFT-accelerated Poisson solver
- Multi-resolution processing for large datasets
- Physics-based symbol placement with overlap resolution and topology preservation
- Isohedral tile support for custom symbol shapes
- Split and shrink operations for proportional cartograms
- Dot density cartogram support
- Rich visualization utilities built on matplotlib and geopandas

## Installation

```bash
pip install carto-flow
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv add carto-flow
```

Requires Python 3.10+.

## Quick example

```python
import geopandas as gpd
from carto_flow.flow_cartogram import morph_gdf

gdf = gpd.read_file("countries.gpkg")
result = morph_gdf(gdf, values=gdf["population"])
result.cartogram_gdf.plot()
```

```python
from carto_flow.symbol_cartogram import create_symbol_cartogram

layout = create_symbol_cartogram(gdf, values=gdf["population"])
layout.plot()
```

## Documentation

Full documentation is available at **<https://bright-fakl.github.io/carto-flow/>**, including:

- [Tutorials](https://bright-fakl.github.io/carto-flow/tutorials/) — step-by-step guides for each cartogram type
- [How-to guides](https://bright-fakl.github.io/carto-flow/how-to/) — task-focused recipes
- [Reference](https://bright-fakl.github.io/carto-flow/reference/) — full API reference
- [Explanations](https://bright-fakl.github.io/carto-flow/explanations/) — background on algorithms and design

## License

See [LICENSE](LICENSE).
