Skip to content

carto_flow.voronoi_cartogram.options

Run-control options for Voronoi cartogram generation.

Classes:

  • TopologyRepair –

    Settings for the periodic topology permutation pipeline.

  • VoronoiOptions –

    Run-control options for Voronoi cartogram generation.

TopologyRepair dataclass 

TopologyRepair(
    every: int = 5,
    max_passes: int = 3,
    group_contiguity: bool = True,
    adjacency: bool = True,
    orientation: bool = True,
)

Settings for the periodic topology permutation pipeline.

The pipeline permutes which geometry each generator represents (without moving generators); the next Lloyd step absorbs each swap. Three stages can be enabled independently:

  1. group_contiguity — ensure each group's generators occupy adjacent Voronoi cells (requires group_by in :func:~carto_flow.voronoi_cartogram.api.create_voronoi_cartogram).
  2. adjacency — permute slots so that input-adjacent geometry pairs have adjacent Voronoi cells.
  3. orientation — among already-adjacent pairs, align the relative direction between cell centroids with the direction between input centroids.

Parameters:

  • every (int, default: 5 ) –

    Run the pipeline every N iterations.

  • max_passes (int, default: 3 ) –

    Maximum repair passes per active stage per call. Kept small (default 3) to avoid slowing down each iteration; the loop over all iterations compensates.

  • group_contiguity (bool, default: True ) –

    Enable stage 1. Default True.

  • adjacency (bool, default: True ) –

    Enable stage 2. Default True.

  • orientation (bool, default: True ) –

    Enable stage 3. Default True.

VoronoiOptions dataclass 

VoronoiOptions(
    n_iter: int = 30,
    tol: float | None = None,
    area_cv_tol: float | None = None,
    simplify_tol: float | None = None,
    record_history: bool | int = False,
    record_cells: bool = False,
    show_progress: bool = False,
    debug: bool = False,
    prescale_components: bool = False,
    fix_topology: int | TopologyRepair | None = None,
    adj_min_shared_length: float | None = None,
)

Run-control options for Voronoi cartogram generation.

Algorithm-specific parameters (relaxation schedule, resolution, boundary treatment, distance mode, etc.) live on the backend objects (:class:~carto_flow.voronoi_cartogram.backends.ExactBackend, :class:~carto_flow.voronoi_cartogram.backends.RasterBackend). These options control only iteration count, stopping criteria, output recording, and topology repair.

Parameters:

  • n_iter (int, default: 30 ) –

    Maximum number of Lloyd iterations. 0 returns the initial clipped Voronoi diagram without any relaxation.

  • tol (float or None, default: None ) –

    Stop early when max centroid displacement falls below this value. None = run all n_iter iterations.

  • area_cv_tol (float or None, default: None ) –

    Stop early when the area coefficient of variation drops below this value. None = no area-CV stopping criterion. Can be combined with tol; the first condition that fires wins.

  • simplify_tol (float or None, default: None ) –

    Simplification tolerance for the outer boundary polygon before clipping. Reduces per-iteration cost for complex coastlines. None = no simplification.

  • record_history (bool or int, default: False ) –

    False — no history (default). True — record a snapshot at every iteration. int N — record a snapshot every N iterations. Snapshots are accessible via VoronoiCartogram.history.

  • record_cells (bool, default: False ) –

    Include clipped Voronoi cell polygons in each snapshot. Polygon construction is expensive; disable when only centroid positions are needed. Ignored when record_history=False.

  • show_progress (bool, default: False ) –

    Print per-iteration diagnostics (displacement, area CV, relaxation factor).

  • debug (bool, default: False ) –

    Enable verbose diagnostic output from backend internals: topology repair cycle details and geodesic cross-water labeling warnings.

  • prescale_components (bool, default: False ) –

    If True, detect connected-component groups (sets of geometries that touch or share a boundary) and uniformly scale each group to its target total area before running relaxation. Important when disconnected components (e.g. Alaska, Hawaii) start at very different sizes relative to their weights.

  • fix_topology (int, TopologyRepair, or None, default: None ) –

    Periodic topology permutation pipeline.

    • None (default) — disabled.
    • int N — enable all three stages, run every N iterations with max_passes=3.
    • :class:TopologyRepair — full control over cadence, passes, and which stages are active.
  • adj_min_shared_length (float or None, default: None ) –

    Minimum shared border length for two cells to be considered adjacent in topology repair. Pairs whose shared border is shorter than this value are not counted as adjacent. None (default) = no extra filter beyond the auto-computed distance_tolerance in :func:~carto_flow.geo_utils.adjacency.find_adjacent_pairs.

Examples:

>>> from carto_flow import create_voronoi_cartogram, RasterBackend, VoronoiOptions
>>> result = create_voronoi_cartogram(
...     gdf,
...     backend=RasterBackend(resolution=300),
...     options=VoronoiOptions(n_iter=50, show_progress=True),
... )
>>> # Record history every 5 iterations
>>> result = create_voronoi_cartogram(
...     gdf,
...     options=VoronoiOptions(record_history=5),
... )
>>> # Topology repair every 10 iterations, adjacency stage only
>>> from carto_flow import TopologyRepair
>>> result = create_voronoi_cartogram(
...     gdf,
...     options=VoronoiOptions(
...         fix_topology=TopologyRepair(every=10, group_contiguity=False, orientation=False)
...     ),
... )

Methods:

  • copy_with –

    Return a new VoronoiOptions with specified fields overridden.

copy_with 

copy_with(**kwargs: Any) -> VoronoiOptions

Return a new VoronoiOptions with specified fields overridden.