Skip to content

carto_flow.symbol_cartogram.layout

Layout algorithms for symbol cartograms.

This module defines the Layout ABC and concrete layout implementations that compute positions and transforms, returning immutable LayoutResult.

Classes:

Functions:

CentroidLayout 

CentroidLayout(
    options: CentroidLayoutOptions | None = None,
    /,
    **kwargs,
)

Bases: Layout

Layout that places symbols at geometry centroids.

Places symbols at the centroids of the original geometries, with optional local overlap removal.

Returns LayoutResult with CircleSymbol as canonical symbol.

Parameters:

  • options (CentroidLayoutOptions, default: None ) –

    Full options object. Defaults to CentroidLayoutOptions().

  • **kwargs –

    Individual option overrides applied on top of options.

Examples:

>>> layout = CentroidLayout()  # Default: remove overlap
>>> layout = CentroidLayout(remove_overlap=False)  # Just centroids
>>> layout = CentroidLayout(spacing=0.1)  # Larger gaps

Methods:

  • compute –

    Place symbols at centroids with optional overlap removal.

compute 

compute(
    data: LayoutData,
    show_progress: bool = True,
    save_history: bool = False,
) -> LayoutResult

Place symbols at centroids with optional overlap removal.

Parameters:

  • data (LayoutData) –

    Preprocessed layout data.

  • show_progress (bool, default: True ) –

    Display progress feedback during placement.

  • save_history (bool, default: False ) –

    Record position snapshots per iteration.

Returns:

  • LayoutResult –

    Immutable layout result with CircleSymbol as canonical.

CirclePackingLayout 

CirclePackingLayout(
    options: CirclePackingLayoutOptions | None = None,
    /,
    **kwargs,
)

Bases: Layout

Layout using two-stage circle packing simulation.

Two-stage approach: 1. Overlap Resolution: Global expansion + overlap projection 2. Circle Packing: Force-based with contact reaction constraint

This algorithm preserves topology better than CirclePhysicsLayout by using distance-gated angular forces and contact reaction.

Parameters:

  • options (CirclePackingLayoutOptions, default: None ) –

    Full options object. Defaults to CirclePackingLayoutOptions().

  • **kwargs –

    Individual option overrides.

Methods:

  • compute –

    Run circle packing simulation and return result.

compute 

compute(
    data: LayoutData,
    show_progress: bool = True,
    save_history: bool = False,
) -> LayoutResult

Run circle packing simulation and return result.

Parameters:

  • data (LayoutData) –

    Preprocessed layout data.

  • show_progress (bool, default: True ) –

    Display progress feedback during placement.

  • save_history (bool, default: False ) –

    Record position snapshots per iteration.

Returns:

  • LayoutResult –

    Immutable layout result with CircleSymbol as canonical.

CirclePhysicsLayout 

CirclePhysicsLayout(
    options: CirclePhysicsLayoutOptions | None = None,
    /,
    **kwargs,
)

Bases: Layout

Layout using velocity-based physics simulation.

Two-phase approach: 1. Separation phase: Strong repulsion until overlaps resolved 2. Settling phase: Gentle attraction while maintaining separation

Parameters:

  • options (CirclePhysicsLayoutOptions, default: None ) –

    Full options object. Defaults to CirclePhysicsLayoutOptions().

  • **kwargs –

    Individual option overrides.

Methods:

  • compute –

    Run physics simulation and return result.

compute 

compute(
    data: LayoutData,
    show_progress: bool = True,
    save_history: bool = False,
) -> LayoutResult

Run physics simulation and return result.

Parameters:

  • data (LayoutData) –

    Preprocessed layout data.

  • show_progress (bool, default: True ) –

    Display progress feedback during placement.

  • save_history (bool, default: False ) –

    Record position snapshots per iteration.

Returns:

  • LayoutResult –

    Immutable layout result with CircleSymbol as canonical.

GridBasedLayout 

GridBasedLayout(
    options: GridBasedLayoutOptions | None = None,
    /,
    **kwargs,
)

Bases: Layout

Layout from grid-based assignment.

Returns LayoutResult with appropriate Symbol based on tiling type.

Parameters:

  • options (GridBasedLayoutOptions, default: None ) –

    Full options object (positional only). Defaults to GridBasedLayoutOptions().

  • **kwargs –

    Individual option overrides applied on top of options. Raises TypeError for unrecognized names.

Examples:

>>> layout = GridBasedLayout(tiling="hexagon")
>>> layout = GridBasedLayout(my_opts, neighbor_weight=0.5)

Methods:

  • compute –

    Run grid assignment and return result.

compute 

compute(
    data: LayoutData,
    show_progress: bool = True,
    save_history: bool = False,
) -> LayoutResult

Run grid assignment and return result.

Parameters:

  • data (LayoutData) –

    Preprocessed layout data.

  • show_progress (bool, default: True ) –

    Display progress feedback during placement.

  • save_history (bool, default: False ) –

    Record position snapshots per iteration.

Returns:

  • LayoutResult –

    Immutable layout result with appropriate canonical symbol.

Layout

Bases: ABC

Abstract base for layout algorithms.

Layouts compute positions and transforms, returning immutable LayoutResult.

Methods:

  • compute –

    Run layout algorithm and return immutable result.

compute abstractmethod 

compute(
    data: LayoutData,
    show_progress: bool = True,
    save_history: bool = False,
) -> LayoutResult

Run layout algorithm and return immutable result.

Parameters:

  • data (LayoutData) –

    Preprocessed data from prepare_layout_data().

  • show_progress (bool, default: True ) –

    Display progress feedback during placement.

  • save_history (bool, default: False ) –

    Record position snapshots per iteration.

Returns:

  • LayoutResult –

    Immutable result with canonical symbol and transforms.

get_layout 

get_layout(name: str) -> Layout

Instantiate a registered layout by name.

Parameters:

  • name (str) –

    Registered layout name.

Returns:

  • Layout –

    New layout instance.

Raises:

  • ValueError –

    If name is not registered.

register_layout 

register_layout(name: str, cls: type[Layout]) -> None

Register a layout class by name.

Parameters:

  • name (str) –

    Name to register under.

  • cls (type[Layout]) –

    Layout class to register.