carto_flow.symbol_cartogram.styling¶

Styling class for symbol cartograms.

This module defines the Styling class that collects styling decisions and applies them to LayoutResult to produce SymbolCartogram instances.

Classes:

FitMode –

How to fit a styled symbol inside the canonical tile.
Styling –

Collects styling decisions, then applies to LayoutResult.

FitMode ¶

Bases: Enum

How to fit a styled symbol inside the canonical tile.

Attributes:

INSIDE (str) –

Conservative fit: symbol is guaranteed to fit inside tile (centered). Uses inscribed_radius / bounding_radius ratio.
AREA (str) –

Area-preserving fit: symbol area equals tile area. Symbol may extend outside tile boundaries.
FILL (str) –

Optimal fit with center shift: maximizes symbol size while staying inside tile. May shift symbol center from tile center.

Styling ¶

Styling(
    symbol: Symbol | str | None = None,
    scale: float = 1.0,
    rotation: float = 0.0,
    reflection: bool = False,
    fit_mode: FitMode
    | Literal["inside", "area", "fill"] = FitMode.INSIDE,
)

Collects styling decisions, then applies to LayoutResult.

Supports incremental styling with fluent API.

Parameters:

symbol (Symbol or str or None, default: None ) –

Symbol instance or string shorthand ("circle", "hexagon", "square"). If None, uses the canonical symbol from LayoutResult.
scale (float, default: 1.0 ) –

Global scale multiplier. Default: 1.0
rotation (float, default: 0.0 ) –

Additional rotation in degrees (counter-clockwise). Default: 0.0
reflection (bool, default: False ) –

Whether to reflect symbols. Default: False
fit_mode (FitMode or str, default: INSIDE ) –

How to fit styled symbol inside canonical tile: - "inside": Conservative fit, symbol guaranteed inside tile (default) - "area": Area-preserving, symbol area equals tile area - "fill": Optimal fit with center shift, maximizes symbol size

Examples:

>>> # Simple styling
>>> styling = Styling(symbol="hexagon", scale=0.9)
>>> cartogram = styling.apply(layout_result)

>>> # With fit mode
>>> styling = Styling(symbol="circle", fit_mode="fill")
>>> cartogram = styling.apply(layout_result)

>>> # Fluent API
>>> styling = (Styling()
...     .set_symbol("hexagon")
...     .transform(scale=0.9)
...     .set_symbol("star", indices=[5, 10, 15]))
>>> cartogram = styling.apply(layout_result)

>>> # Per-geometry overrides
>>> styling = Styling().set_symbol("hexagon").transform(scale=0.8, indices=[0, 1, 2])
>>> cartogram = styling.apply(layout_result)

Methods:

__repr__ –

Return string representation of Styling.
apply –

Apply styling to layout and produce cartogram.
set_params –

Set symbol parameters for all or specific geometries.
set_symbol –

Set symbol for all or specific geometries.
transform –

Apply additional transform for all or specific geometries.

repr ¶

__repr__() -> str

Return string representation of Styling.

apply ¶

apply(layout_result: LayoutResult) -> SymbolCartogram

Apply styling to layout and produce cartogram.

Parameters:

layout_result (LayoutResult) –

Immutable layout output from compute().

Returns:

SymbolCartogram –

Rendered cartogram with styled symbols.

set_params ¶

set_params(
    params: dict[str, Any] | list | ndarray,
    indices: list[int] | None = None,
    mask: list[bool] | ndarray | None = None,
) -> Styling

Set symbol parameters for all or specific geometries.

Parameters are passed to symbol.modify() to create modified symbols. Useful for symbols with configurable parameters like IsohedralTileSymbol.

Parameters:

params (dict or list or ndarray) –

Parameters to pass to symbol.modify(), or array of parameter dicts.
indices (list of int or None, default: None ) –

Geometry indices to apply to. None = all geometries.
mask (list of bool or np.ndarray or None, default: None ) –

Boolean mask indicating which geometries to apply the parameters to.

Returns:

Styling –

Self for method chaining.

Examples:

>>> styling = Styling().set_params({"pointy_top": False})
>>> styling = Styling().set_params({"prototile_params": [0.5, 0.3]})
>>> styling = Styling().set_params([{"a": 1}, {"b": 2}])  # Positional
>>> styling = Styling().set_params({"pointy_top": True}, mask=[True, False, True])  # Masked

set_symbol ¶

set_symbol(
    symbol: Symbol | str | list | ndarray,
    indices: list[int] | None = None,
    mask: list[bool] | ndarray | None = None,
) -> Styling

Set symbol for all or specific geometries.

Parameters:

symbol (Symbol or str or list or ndarray) –

Symbol instance, string shorthand ("circle", "hexagon", "square"), or array of values.
indices (list of int or None, default: None ) –

Geometry indices to apply to. None = all geometries.
mask (list of bool or np.ndarray or None, default: None ) –

Boolean mask indicating which geometries to apply the symbol to.

Returns:

Styling –

Self for method chaining.

Examples:

>>> styling = Styling().set_symbol("hexagon")
>>> styling = Styling().set_symbol("circle", indices=[0, 1, 2])
>>> styling = Styling().set_symbol(["circle", "hexagon", "square"])  # Positional
>>> styling = Styling().set_symbol("star", mask=[True, False, True])  # Boolean mask

transform ¶

transform(
    scale: float | list | ndarray = 1.0,
    rotation: float | list | ndarray = 0.0,
    reflection: bool | list | ndarray = False,
    indices: list[int] | None = None,
    mask: list[bool] | ndarray | None = None,
) -> Styling

Apply additional transform for all or specific geometries.

Parameters:

scale (float or list or ndarray, default: 1.0 ) –

Scale multiplier (default 1.0)
rotation (float or list or ndarray, default: 0.0 ) –

Additional rotation in degrees (counter-clockwise, default 0.0)
reflection (bool or list or ndarray, default: False ) –

Whether to reflect (default False)
indices (list of int or None, default: None ) –

Geometry indices to apply to. None = all geometries.
mask (list of bool or np.ndarray or None, default: None ) –

Boolean mask indicating which geometries to apply the transform to.

Returns:

Styling –

Self for method chaining.

Examples:

>>> styling = Styling().transform(scale=0.9)
>>> styling = Styling().transform(rotation=45, reflection=True)
>>> styling = Styling().transform(scale=0.8, indices=[0, 1, 2])
>>> styling = Styling().transform(scale=[0.9, 1.0, 0.8])  # Positional
>>> styling = Styling().transform(rotation=45, mask=[True, False, True])  # Masked

carto_flow.symbol_cartogram.styling¶

FitMode ¶

Styling ¶

__repr__ ¶

apply ¶

set_params ¶

set_symbol ¶

transform ¶

repr ¶