carto_flow.symbol_cartogram.options¶

Configuration options for symbol cartogram generation.

Classes:

AdjacencyMode –

How adjacency is computed.
CentroidLayoutOptions –

Options for centroid-based placement.
CirclePackingLayoutOptions –

Options for CirclePackingLayout (two-stage with contact reaction).
CirclePhysicsLayoutOptions –

Options for CirclePhysicsLayout (velocity-based physics).
ForceMode –

How attraction force magnitude is computed.
GridBasedLayoutOptions –

Options for grid-based placement.
SymbolOrientation –

How symbols are oriented relative to their tile.
SymbolShape –

Shape of the symbols.

AdjacencyMode ¶

Bases: str, Enum

How adjacency is computed.

CentroidLayoutOptions `dataclass` ¶

CentroidLayoutOptions(
    spacing: float = 0.05,
    remove_overlap: bool = True,
    max_iterations: int = 20,
    overlap_tolerance: float = 0.0001,
)

Options for centroid-based placement.

Places symbols at geometry centroids with optional overlap removal.

Parameters:

spacing (float, default: 0.05 ) –

Gap between symbols as fraction of average symbol size. Default: 0.05
remove_overlap (bool, default: True ) –

Whether to run overlap removal after placing at centroids. Default: True
max_iterations (int, default: 20 ) –

Maximum iterations for overlap resolution. Default: 20
overlap_tolerance (float, default: 0.0001 ) –

Tolerance for overlap resolution convergence. Default: 1e-4

Methods:

validate –

Validate options.

validate ¶

validate() -> None

Validate options.

CirclePackingLayoutOptions `dataclass` ¶

CirclePackingLayoutOptions(
    max_iterations: int = 500,
    convergence_tolerance: float = 0.025,
    spacing: float = 0.05,
    compactness: float = 0.1,
    topology_weight: float = 1.0,
    overlap_tolerance: float = 0.0001,
    global_step_fraction: float = 0.5,
    local_step_fraction: float = 0.5,
    topology_gate_distance: float = 2.5,
    neighbor_weight: float = 1.0,
    origin_weight: float = 0.1,
    force_mode: ForceMode = ForceMode.DIRECTION,
    contact_tolerance: float = 0.02,
    max_step: float = 0.3,
    contact_transfer_ratio: float = 0.5,
    contact_elasticity: float = 0.0,
    size_sensitivity: float = 0.0,
    expansion_max_iterations: int = 20,
    max_expansion_factor: float = 2.0,
    contact_iterations: int = 3,
    overlap_projection_iters: int = 5,
    step_smoothing_window: int = 20,
    convergence_window: int = 50,
    adaptive_ema: bool = True,
)

Options for CirclePackingLayout (two-stage with contact reaction).

This simulator uses a fundamentally different approach: - Stage 1 (Feasibility): Global expansion + overlap projection - Stage 2 (Refinement): Force-based with contact reaction constraint

The contact reaction allows circles to slide along each other without penetrating, enabling tighter packing while preserving topology.

Parameters:

max_iterations (int, default: 500 ) –

Maximum iterations for simulation. Default: 500
convergence_tolerance (float, default: 0.025 ) –

Threshold for declaring convergence. Default: 1e-4
overlap_tolerance (float, default: 0.0001 ) –

Overlap tolerance for overlap resolution convergence, as fraction of average radius. Resolution completes when max overlap is below this. Default: 1e-4
global_step_fraction (float, default: 0.5 ) –

Fraction of exact global expansion to apply per iteration (0-1]. Higher = faster convergence but may overshoot. Default: 0.5
local_step_fraction (float, default: 0.5 ) –

Fraction of local pairwise separation to apply per iteration (0-1]. At 1.0, each circle moves 0.5 * overlap (its half of the full correction). At 0.5 (default), each moves 0.25 * overlap. Default: 0.5
topology_gate_distance (float, default: 2.5 ) –

Topology force distance gate. Forces only act when circles are within topology_gate_distance * (r_i + r_j) distance. Default: 2.5
neighbor_weight (float, default: 1.0 ) –

Neighbor tangency force strength. Pulls separated neighbors together. Default: 0.5
origin_weight (float, default: 0.1 ) –

Origin attraction force strength. Pulls each circle toward its original position. Set to 0 to disable. Default: 0.0 - 0: No origin attraction (current behavior) - 0.1-0.5: Gentle pull toward original positions - > 1.0: Strong pull, may interfere with topology preservation
force_mode (ForceMode, default: DIRECTION ) –

How attraction force magnitude is computed. Applies to both the global centroid attraction force and the origin attraction force. Default: ForceMode.DIRECTION - DIRECTION: Constant magnitude with drop-off near target - LINEAR: Force proportional to distance (spring) - NORMALIZED: Force proportional to distance / radius
contact_tolerance (float, default: 0.02 ) –

Contact detection tolerance as fraction of radii sum. Default: 0.02
max_step (float, default: 0.3 ) –

Maximum step size as fraction of average radius. Default: 0.3
contact_transfer_ratio (float, default: 0.5 ) –

Balance between cancel (0) and transfer (1) of compressive forces at contact points. Default: 0.5 - 0: Cancel (dissipate) compressive forces - 1: Transfer compressive forces between circles - 0.5: Equal mix
contact_elasticity (float, default: 0.0 ) –

Controls net compression vs bounce behavior. Default: 0.0 - 0: Neutral (momentum conserved) - < 0: Compression remains (forces tend to pass through) - > 0: Bounce behavior (forces tend to reflect) Note: Only has effect when 0 < contact_transfer_ratio < 1.
size_sensitivity (float, default: 0.0 ) –

Controls how step size scales with circle radius in packing phase. Default: 0.0 - 0: All circles use avg_radius (current behavior, backward compatible) - 1: Larger circles move faster (proportional to radius) - -1: Larger circles move slower (inverse relationship) - Other values: Interpolate between these behaviors
expansion_max_iterations (int, default: 20 ) –

Maximum outer iterations for overlap resolution. Default: 20
max_expansion_factor (float, default: 2.0 ) –

Maximum expansion factor clamp per iteration. Must be > 1.0. Default: 2.0
contact_iterations (int, default: 3 ) –

Number of contact reaction passes per packing step. Default: 3
overlap_projection_iters (int, default: 5 ) –

Overlap projection iterations per packing step. Default: 5
step_smoothing_window (int, default: 20 ) –

EMA effective window size for step smoothing. Default: 20
convergence_window (int, default: 50 ) –

EMA effective window size for displacement convergence tracking. Default: 50
adaptive_ema (bool, default: True ) –

Whether EMA uses adaptive warmup (alpha starts at 1/k). Default: True

Methods:

validate –

Validate options.

validate ¶

validate() -> None

Validate options.

CirclePhysicsLayoutOptions `dataclass` ¶

CirclePhysicsLayoutOptions(
    max_iterations: int = 500,
    convergence_tolerance: float = 0.0001,
    spacing: float = 0.05,
    compactness: float = 0.5,
    topology_weight: float = 0.3,
    damping: float = 0.85,
    dt: float = 0.15,
    max_velocity: float = 3.0,
    k_repel: float = 15.0,
    k_attract: float = 2.0,
)

Options for CirclePhysicsLayout (velocity-based physics).

This simulator uses a two-phase approach: 1. Separation phase: Strong repulsion until overlaps resolved 2. Settling phase: Gentle attraction while maintaining separation

Parameters:

max_iterations (int, default: 500 ) –

Maximum iterations for simulation. Default: 500
convergence_tolerance (float, default: 0.0001 ) –

Threshold for declaring convergence. Default: 1e-4
damping (float, default: 0.85 ) –

Velocity damping factor (0-1, exclusive). Higher values cause faster energy dissipation. Default: 0.85
dt (float, default: 0.15 ) –

Integration timestep. Larger values give faster but less stable simulation. Default: 0.15
max_velocity (float, default: 3.0 ) –

Maximum velocity magnitude (clamped). Default: 3.0
k_repel (float, default: 15.0 ) –

Repulsion force coefficient. Higher values push overlapping circles apart more aggressively. Default: 15.0
k_attract (float, default: 2.0 ) –

Base attraction force coefficient. Default: 2.0

Methods:

validate –

Validate options.

validate ¶

validate() -> None

Validate options.

ForceMode ¶

Bases: str, Enum

How attraction force magnitude is computed.

Applies to both origin attraction force and global centroid attraction force.

GridBasedLayoutOptions `dataclass` ¶

GridBasedLayoutOptions(
    tiling: object = "hexagon",
    grid_size: int
    | tuple[int, int]
    | Literal["auto"] = "auto",
    origin_weight: float = 0.5,
    neighbor_weight: float = 0.5,
    topology_weight: float = 0.5,
    compactness: float = 0.1,
    spacing: float = 0.05,
    fill_holes: bool = True,
    min_hole_fraction: float = 0.5,
    fix_islands: bool = True,
    verbose: bool = False,
    symbol_shape: SymbolShape | None = None,
    symbol_orientation: SymbolOrientation = SymbolOrientation.UPRIGHT,
    rotation: float = 0.0,
)

Options for grid-based placement.

The assignment cost function combines four terms, harmonized with the TopologyPreservingSimulator force terminology:

origin_weight: Preference for assigning regions near their original centroid positions (analogous to origin attraction force).
neighbor_weight: Keep adjacent regions close on the grid (analogous to neighbor tangency force).
topology_weight: Preserve the relative direction between neighbors (analogous to angular topology force).
compactness: Prefer central/compact placement on the grid (analogous to global centroid attraction).

Parameters:

tiling (Tiling or str, default: 'hexagon' ) –

Tiling to use. Can be a Tiling instance for full control, or a string shorthand: "square", "hexagon", "triangle", "quadrilateral". Default is "hexagon".
grid_size (int, tuple, or "auto", default: 'auto' ) –

Number of grid cells. "auto" creates ~2x regions cells.
origin_weight (float, default: 0.5 ) –

Weight for assigning regions near their original centroids. Default: 1.0.
neighbor_weight (float, default: 0.5 ) –

Weight for keeping adjacent regions close on the grid. Default: 0.3.
topology_weight (float, default: 0.5 ) –

Weight for preserving relative neighbor orientations. Default: 0.0.
compactness (float, default: 0.1 ) –

Weight for compact/central placement. Default: 0.0.
spacing (float, default: 0.05 ) –

Gap between symbols as fraction of cell size (0-1). Used when computing the maximum symbol size that fits within grid cells.
fill_holes (bool, default: True ) –

If True, post-process the assignment to fill internal holes — unoccupied tiles surrounded by occupied tiles that don't correspond to geographic gaps in the original geometries. Islands and genuine geographic gaps (e.g. internal lakes) are preserved. Default: False.
min_hole_fraction (float, default: 0.5 ) –

Minimum area of a geographic interior ring, as a fraction of one tile's area, for it to count as a genuine geographic gap. Rings smaller than this are treated as boundary artifacts and ignored. Default: 0.5.
fix_islands (bool, default: True ) –

If True, post-process the assignment to reassign regions that are disconnected from the main assignment cluster to tiles adjacent to the cluster. True geographic islands (regions not adjacent to any other region) are preserved. Default: False.
verbose (bool, default: False ) –

If True, print diagnostic information during fill_holes and fix_islands processing. Default: False.
symbol_shape (SymbolShape or None, default: None ) –

Target symbol shape. When set, the grid algorithm computes grid-appropriate sizes to prevent overlap. None skips adjustment.
symbol_orientation (SymbolOrientation, default: UPRIGHT ) –

How symbols are oriented relative to their tile. UPRIGHT keeps symbols axis-aligned; WITH_TILE rotates/flips with the tile.
rotation (float, default: 0.0 ) –

Rotation angle for the entire tiling grid in degrees (counter-clockwise). Default: 0.0 (no rotation).

Methods:

validate –

Validate options.

validate ¶

validate() -> None

Validate options.

SymbolOrientation ¶

Bases: str, Enum

How symbols are oriented relative to their tile.

SymbolShape ¶

Bases: str, Enum

Shape of the symbols.

carto_flow.symbol_cartogram.options¶

AdjacencyMode ¶

CentroidLayoutOptions dataclass ¶

validate ¶

CirclePackingLayoutOptions dataclass ¶

validate ¶

CirclePhysicsLayoutOptions dataclass ¶

validate ¶

ForceMode ¶

GridBasedLayoutOptions dataclass ¶

validate ¶

SymbolOrientation ¶

SymbolShape ¶

CentroidLayoutOptions `dataclass` ¶

CirclePackingLayoutOptions `dataclass` ¶

CirclePhysicsLayoutOptions `dataclass` ¶

GridBasedLayoutOptions `dataclass` ¶