carto-flow

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 force-based or grid-based layout.
• Proportional cartograms — region polygons are split or shrunk to show sub-group proportions within each geographic unit.

Features

• Diffusion-based flow cartogram morphing with FFT-accelerated Poisson solver
• Multi-resolution processing for large datasets
• Force-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

pip install carto-flow

Or with uv:

uv add carto-flow

Requires Python 3.10+.

Quick example

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()

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 — step-by-step guides for each cartogram type
• How-to guides — task-focused recipes
• Reference — full API reference
• Explanations — background on algorithms and design

Changelog

CHANGELOG.md lists the changes in each release. Upgrading from 1.x requires code changes in the symbol cartogram API; the migration guide gives the old and new form of every affected call.

License

See LICENSE.