carto_flow.voronoi_cartogram.api

Convenience wrapper: create_voronoi_cartogram.

Functions:

• create_voronoi_cartogram –

  Run Lloyd relaxation (or FFT flow) on GeoDataFrame centroids.

create_voronoi_cartogram

create_voronoi_cartogram(
    gdf: GeoDataFrame,
    *,
    weights: str | ndarray | None = None,
    backend: ExactBackend | RasterBackend | None = None,
    options: VoronoiOptions | None = None,
    group_by: str | None = None,
    boundary: str | Any = "union",
) -> VoronoiCartogram

Run Lloyd relaxation (or FFT flow) on GeoDataFrame centroids.

Distributes the centroid of each geometry in gdf so that every point claims an equal-area (or proportionally weighted) Voronoi cell within the outer union boundary (CVT — Centroidal Voronoi Tessellation).

Parameters:

• gdf (GeoDataFrame) –

  Input polygons. One point is placed at each geometry's centroid.

• weights (str, array-like of float, or None, default: None ) –

  Per-geometry weights. Pass a column name (str) to look up values from gdf, or a numeric array-like of length len(gdf). A heavier point claims territory proportional to its weight. None = uniform weights.

• backend (ExactBackend, RasterBackend, or None, default: None ) –

  Algorithm backend. Each backend class exposes only the parameters relevant to its algorithm:

  • :class:~carto_flow.voronoi_cartogram.backends.RasterBackend (default) — raster NN Lloyd; 10-50x faster than exact. Set boundary=ElasticBoundary(...) with relaxation=0.0 for pure FFT-flow mode (no Lloyd).
  • :class:~carto_flow.voronoi_cartogram.backends.ExactBackend — exact scipy Voronoi + shapely clipping.

  None → RasterBackend() (resolution=300).

• options (VoronoiOptions or None, default: None ) –

  Run-control settings (iteration count, stopping criteria, history recording). Defaults to :class:VoronoiOptions with all defaults.

• group_by (str or None, default: None ) –

  Column in gdf identifying a grouping of rows (e.g. state for congressional districts). When set, each group is expected to form a contiguous region in the Voronoi tessellation. Topology repair (if enabled via options.fix_topology) will use this grouping for stage 1 (group contiguity). None = no contiguity tracking.

• boundary (str or shapely Geometry, default: 'union' ) –

  Outer clipping boundary for the Voronoi tessellation. Accepted forms:

  • "union" (default) — union of all input geometries.
  • "bbox" — axis-aligned bounding box of the union.
  • "convex_hull" — convex hull of the union.
  • "circle" — minimum enclosing circle of the union (64-segment approximation).
  • shapely Geometry — used directly as the outer boundary.

  When using :class:~carto_flow.voronoi_cartogram.backends.ElasticBoundary, simple shapes (e.g. "bbox") are automatically densified to roughly backend.resolution vertices before the elastic deformation is initialized, ensuring smooth FFT-driven boundary deformation.

Returns:

• VoronoiCartogram –

  Result object with:

  • positions — final centroid coordinates, shape (G, 2)
  • cells — clipped Voronoi cell polygons, shape (G,)
  • metrics — convergence summary
  • convergence_history — list of area_cv values per iteration
  • history — per-iteration snapshots when options.record_history is set, else None
  • to_geodataframe() — source GDF with Voronoi cells as geometry
  • plot() — choropleth of the cells

Examples:

>>> import geopandas as gpd
>>> from carto_flow import (
...     create_voronoi_cartogram,
...     ExactBackend, RasterBackend, VoronoiOptions,
...     RelaxationSchedule,
... )

Default (raster Lloyd, resolution=300):

>>> result = create_voronoi_cartogram(gdf)

Exact backend with custom schedule:

>>> result = create_voronoi_cartogram(
...     gdf,
...     backend=ExactBackend(relaxation=RelaxationSchedule(start=1.9, decay=0.95)),
...     options=VoronoiOptions(n_iter=100),
... )

Raster + geodesic distance:

>>> result = create_voronoi_cartogram(
...     gdf, backend=RasterBackend(resolution=300, distance_mode="geodesic")
... )

Pure FFT-flow (no Lloyd):

>>> from carto_flow import ElasticBoundary
>>> result = create_voronoi_cartogram(
...     gdf,
...     backend=RasterBackend(
...         resolution=300,
...         relaxation=0.0,
...         boundary=ElasticBoundary(strength=0.3, step_scale=0.8),
...         distance_mode="geodesic",
...     ),
... )