Skip to content

carto_flow.symbol_cartogram.layout_result

Layout result classes for symbol cartograms.

This module defines the immutable LayoutResult that captures the output of layout algorithms, and the Transform dataclass for per-geometry transforms.

Classes:

  • LayoutResult –

    Immutable output from layout algorithm.

  • Transform –

    Transformation applied to a symbol.

LayoutResult dataclass 

LayoutResult(
    canonical_symbol: Symbol,
    transforms: list[Transform],
    base_size: float,
    positions: NDArray[floating],
    sizes: NDArray[floating],
    adjacency: NDArray[floating],
    bounds: tuple[float, float, float, float],
    crs: str | None = None,
    algorithm_info: dict[str, Any] = dict(),
    simulation_history: Any = None,
    valid_mask: NDArray[bool_] | None = None,
)

Immutable output from layout algorithm.

Contains canonical symbol and per-geometry transforms, plus the serializable preprocessing data (positions, sizes, adjacency, bounds, crs). The original GeoDataFrame is NOT stored here (too large for serialization).

Attributes:

  • canonical_symbol (Symbol) –

    The base symbol shape for this layout.

  • transforms (list[Transform]) –

    One transform per input geometry.

  • base_size (float) –

    Reference size for scaling.

  • positions (NDArray[floating]) –

    Original centroid positions, shape (n, 2).

  • sizes (NDArray[floating]) –

    Symbol sizes, shape (n,).

  • adjacency (NDArray[floating]) –

    Adjacency matrix from original geometries, shape (n, n).

  • bounds (tuple[float, float, float, float]) –

    Geographic bounds (xmin, ymin, xmax, ymax).

  • crs (str | None) –

    CRS information as WKT string from source GeoDataFrame.

  • algorithm_info (dict) –

    Algorithm-specific metadata.

  • simulation_history (SimulationHistory | None) –

    Per-iteration diagnostics and optional position snapshots.

Methods:

  • from_serialized –

    Reconstruct from serialized data.

  • serialize –

    Serialize for persistence.

  • style –

    Apply styling to create symbol cartogram.

from_serialized classmethod 

from_serialized(data: dict[str, Any]) -> LayoutResult

Reconstruct from serialized data.

Parameters:

  • data (dict) –

    Serialized layout result from serialize().

Returns:

Examples:

>>> import json
>>> serialized = json.load(open("layout.json"))
>>> result = LayoutResult.from_serialized(serialized)
>>> cartogram = result.style(symbol="circle")

serialize 

serialize() -> dict[str, Any]

Serialize for persistence.

Returns:

  • dict –

    Serialized representation of the layout result.

Notes

All data is serialized including positions, sizes, adjacency, bounds, crs. The original GeoDataFrame is NOT stored - it must be provided separately when attribute merging is needed via SymbolCartogram.to_geodataframe().

Examples:

>>> import json
>>> result = create_layout(gdf, "population")
>>> serialized = result.serialize()
>>> json.dump(serialized, open("layout.json", "w"))

style 

style(
    styling: Styling | None = None, **kwargs
) -> SymbolCartogram

Apply styling to create symbol cartogram.

Parameters:

  • styling (Styling or None, default: None ) –

    Pre-configured Styling object.

  • **kwargs –

    Convenience kwargs for simple cases (symbol, scale, etc.) Creates a temporary Styling object internally.

Returns:

Transform dataclass 

Transform(
    position: tuple[float, float] = (0.0, 0.0),
    rotation: float = 0.0,
    scale: float = 1.0,
    reflection: bool = False,
)

Transformation applied to a symbol.

Note: This is an internal class that stores rotation in radians. User-facing APIs (Styling, TransformedSymbol) use degrees for convenience.

Attributes:

  • position (tuple[float, float]) –

    Center position (x, y) for the symbol.

  • rotation (float) –

    Rotation angle in radians (counter-clockwise). Default: 0.0 User-facing APIs accept degrees and convert internally.

  • scale (float) –

    Scale multiplier. Default: 1.0

  • reflection (bool) –

    Whether to reflect the symbol about the vertical axis. Default: False

Methods:

  • compose –

    Compose this transform with another.

compose 

compose(other: Transform) -> Transform

Compose this transform with another.

The resulting transform applies this transform first, then the other.

Parameters:

  • other (Transform) –

    Transform to apply after this one.

Returns: