carto_flow.voronoi_cartogram.animation

Animation utilities for Voronoi cartogram results.

Functions:

• animate_voronoi_history –

  Animate Lloyd relaxation through per-iteration snapshots.

• save_animation –

  Save a matplotlib animation to file (GIF, MP4, etc.).

Examples:

>>> from carto_flow.voronoi_cartogram import create_voronoi_cartogram, VoronoiOptions
>>> from carto_flow.voronoi_cartogram.animation import animate_voronoi_history, save_animation
>>> options = VoronoiOptions(record_history=True, record_cells=True, n_iter=50)
>>> result = create_voronoi_cartogram(gdf, options=options)
>>> anim = animate_voronoi_history(result, fps=10)
>>> save_animation(anim, "voronoi.gif", fps=10)

animate_voronoi_history

animate_voronoi_history(
    result: VoronoiCartogram,
    *,
    show_cells: bool = True,
    show_points: bool = True,
    show_convergence_title: bool = True,
    cell_style: dict | None = None,
    point_style: dict | None = None,
    figsize: tuple[float, float] = (8, 6),
    fps: int = 15,
    repeat: bool = True,
) -> FuncAnimation

Animate Lloyd relaxation through per-iteration snapshots.

Requires VoronoiOptions(record_history=True) when running :func:~carto_flow.voronoi_cartogram.create_voronoi_cartogram. Set record_cells=True to also animate cell polygons.

Parameters:

• result (VoronoiCartogram) –

  The cartogram with a populated :attr:~VoronoiCartogram.history.

• show_cells (bool, default: True ) –

  Animate cell polygons if they were recorded (record_cells=True). Falls back to point scatter only when cells are unavailable. Default True.

• show_points (bool, default: True ) –

  Overlay generator point positions. Default True.

• show_convergence_title (bool, default: True ) –

  Include iteration number and CV(area) in the title. Default True.

• cell_style (dict or None, default: None ) –

  Styling for cell polygons, merged over defaults {"facecolor": "#d0e4f7", "edgecolor": "#1a5276", "linewidth": 0.4, "alpha": 0.7}. All keys forwarded to GeoDataFrame.plot().

• point_style (dict or None, default: None ) –

  Styling for generator points, merged over defaults {"s": 14, "c": "#e74c3c", "zorder": 3, "linewidths": 0}. All keys forwarded to ax.scatter().

• figsize (tuple of float, default: (8, 6) ) –

  Figure size.

• fps (int, default: 15 ) –

  Frames per second (used as a hint for the interval; pass to save_animation separately to control output fps).

• repeat (bool, default: True ) –

  Whether the animation loops. Default True.

Returns:

• FuncAnimation –

Raises:

• RuntimeError –

  If result.history is None (history was not recorded).

save_animation

save_animation(
    anim: FuncAnimation,
    path: str | Path,
    *,
    fps: int = 15,
    dpi: int = 100,
    writer: str | None = None,
    **kwargs: Any,
) -> None

Save a matplotlib animation to file.

Parameters:

• anim (FuncAnimation) –

  The animation to save (e.g. from :func:animate_voronoi_history).

• path (str or Path) –

  Output path. The format is inferred from the file extension: .gif uses Pillow, .mp4 / .mov use ffmpeg, .html produces an HTML widget.

• fps (int, default: 15 ) –

  Frames per second. Default 15.

• dpi (int, default: 100 ) –

  Dots per inch. Default 100.

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

  Explicit matplotlib writer name (e.g. "pillow", "ffmpeg"). None (default) infers from the file extension.

• **kwargs (Any, default: {} ) –

  Additional keyword arguments forwarded to FuncAnimation.save().