carto_flow.symbol_cartogram.symbols¶

Symbol creation utilities for symbol cartograms.

Classes:

CircleSymbol –

Circle inscribed in the unit square (radius = 0.5).
DiamondSymbol –

Diamond (square rotated 45°) inscribed in unit circle (radius = 0.5).
HexagonSymbol –

Hexagon inscribed in the unit square.
IsohedralTileSymbol –

Isohedral tiling tile as symbol with modifiable parameters/curves.
PentagonSymbol –

Regular pentagon inscribed in unit circle (radius = 0.5).
SquareSymbol –

Square filling the unit square (half-side = 0.5).
StarSymbol –

N-pointed star inscribed in unit circle (outer radius = 0.5).
Symbol –

A symbol defined in the unit square [-0.5, 0.5]².
TileSymbol –

Symbol whose shape matches a tiling's canonical tile.
TransformedSymbol –

Wrapper that applies rotation/reflection to a base symbol.
TriangleSymbol –

Equilateral triangle inscribed in unit circle (radius = 0.5).

Functions:

create_circle –

Create a circular polygon.
create_hexagon –

Create an axis-aligned hexagonal polygon.
create_square –

Create an axis-aligned square polygon.
create_symbols –

Create symbol polygons, supporting per-geometry specification.
resolve_symbol –

Resolve a symbol specification to a :class:Symbol instance.

CircleSymbol ¶

Bases: Symbol

Circle inscribed in the unit square (radius = 0.5).

Methods:

modify –

Return self (circle has no modifiable parameters).

Attributes:

area_factor (float) –

Circle is the reference: area = π * size².

area_factor `property` ¶

area_factor: float

Circle is the reference: area = π * size².

modify ¶

modify(**params) -> Symbol

Return self (circle has no modifiable parameters).

DiamondSymbol ¶

Bases: Symbol

Diamond (square rotated 45°) inscribed in unit circle (radius = 0.5).

Methods:

modify –

Return self (diamond has no modifiable parameters).

modify ¶

modify(**params) -> DiamondSymbol

Return self (diamond has no modifiable parameters).

HexagonSymbol ¶

HexagonSymbol(pointy_top: bool = True)

Bases: Symbol

Hexagon inscribed in the unit square.

Parameters:

pointy_top (bool, default: True ) –

If True (default), hexagon has a vertex at top.

Methods:

modify –

Return new symbol with modified parameters.

modify ¶

modify(
    pointy_top: bool | None = None, **params
) -> HexagonSymbol

Return new symbol with modified parameters.

Parameters:

pointy_top (bool or None, default: None ) –

If provided, set the orientation.

Returns:

HexagonSymbol –

New symbol with modified parameters.

IsohedralTileSymbol ¶

IsohedralTileSymbol(
    tiling_type: int,
    prototile_params: list[float] | None = None,
    edge_curves: dict[int, list[tuple[float, float]]]
    | None = None,
    edge_curve_modes: dict[int, str] | None = None,
)

Bases: Symbol

Isohedral tiling tile as symbol with modifiable parameters/curves.

Unlike TileSymbol which just wraps a polygon, this class wraps IsohedralTiling and supports: - Prototile parameter modification - Edge curve customization - Immutable modify() pattern for styling

The symbol is normalized to have bounding_radius = 0.5, matching the convention of other symbols (TileSymbol, HexagonSymbol, etc.).

Parameters:

tiling_type (int) –

Isohedral type number (IH1-IH93).
prototile_params (list[float], default: None ) –

Free parameters for the tiling type.
edge_curves (dict[int, list[tuple]], default: None ) –

Custom edge curves keyed by shape ID.

Methods:

modify –

Return new symbol with modified parameters.
unit_polygon –

Return normalized prototile with bounding_radius = 0.5.

Attributes:

bounding_radius (float) –

Bounding radius is always 0.5 after normalization.
inscribed_radius (float) –

Inscribed radius after normalization.

bounding_radius `property` ¶

bounding_radius: float

Bounding radius is always 0.5 after normalization.

inscribed_radius `property` ¶

inscribed_radius: float

Inscribed radius after normalization.

modify ¶

modify(
    prototile_params: list[float] | None = None,
    edge_curves: dict[int, list[tuple[float, float]]]
    | None = None,
    edge_curve_modes: dict[int, str] | None = None,
    **params,
) -> IsohedralTileSymbol

Return new symbol with modified parameters.

Merges new parameters/curves with existing ones.

Parameters:

prototile_params (list[float] or None, default: None ) –

New prototile parameters (replaces existing).
edge_curves (dict or None, default: None ) –

New edge curves (merged with existing).
edge_curve_modes (dict or None, default: None ) –

New edge curve modes (merged with existing).

Returns:

IsohedralTileSymbol –

New symbol with modified parameters.

unit_polygon ¶

unit_polygon() -> Polygon

Return normalized prototile with bounding_radius = 0.5.

PentagonSymbol ¶

PentagonSymbol(pointy_top: bool = True)

Bases: Symbol

Regular pentagon inscribed in unit circle (radius = 0.5).

Parameters:

pointy_top (bool, default: True ) –

If True (default), pentagon has a vertex at top. If False, has a flat edge at top.

Methods:

modify –

Return new symbol with modified orientation.

modify ¶

modify(
    pointy_top: bool | None = None, **params
) -> PentagonSymbol

Return new symbol with modified orientation.

Parameters:

pointy_top (bool or None, default: None ) –

If provided, set the orientation.

SquareSymbol ¶

Bases: Symbol

Square filling the unit square (half-side = 0.5).

Methods:

modify –

Return self (square has no modifiable parameters).

modify ¶

modify(**params) -> Symbol

Return self (square has no modifiable parameters).

StarSymbol ¶

StarSymbol(
    n_points: int = 5, inner_radius_ratio: float = 0.4
)

Bases: Symbol

N-pointed star inscribed in unit circle (outer radius = 0.5).

Parameters:

n_points (int, default: 5 ) –

Number of star points. Default is 5.
inner_radius_ratio (float, default: 0.4 ) –

Ratio of inner (valley) radius to outer radius. Default is 0.4.

Methods:

modify –

Return new symbol with modified parameters.

modify ¶

modify(
    n_points: int | None = None,
    inner_radius_ratio: float | None = None,
    **params,
) -> StarSymbol

Return new symbol with modified parameters.

Parameters:

n_points (int or None, default: None ) –

New number of points. If None, keeps current.
inner_radius_ratio (float or None, default: None ) –

New inner radius ratio. If None, keeps current.

Symbol ¶

Bases: ABC

A symbol defined in the unit square [-0.5, 0.5]².

Subclass this to create custom symbols. The symbol geometry is defined once in unit coordinates via :meth:unit_polygon, then scaled and positioned by :meth:create.

Properties :attr:bounding_radius and :attr:inscribed_radius are used by placement algorithms to convert between symbol size and the effective collision radius.

Methods:

create –

Create a scaled, optionally transformed polygon at center.
get_geometry –

Return shapely geometry for this symbol.
modify –

Return new symbol with modified parameters.
unit_polygon –

Return the symbol as a polygon in [-0.5, 0.5]².

Attributes:

area_factor (float) –

Factor to convert area-equivalent size to native half-extent.
bounding_radius (float) –

Radius of the bounding circle of the unit polygon.
inscribed_radius (float) –

Radius of the largest inscribed circle centered at the origin.

area_factor `property` ¶

area_factor: float

Factor to convert area-equivalent size to native half-extent.

For a symbol with area-equivalent size S (where the symbol area should equal π * S²), the native half-extent used for rendering is S * area_factor.

This ensures that symbols of different shapes with the same area-equivalent size have the same visual area.

Returns:

float –

The area correction factor.

bounding_radius `property` ¶

bounding_radius: float

Radius of the bounding circle of the unit polygon.

Used by circle-based simulators as the collision radius.

inscribed_radius `property` ¶

inscribed_radius: float

Radius of the largest inscribed circle centered at the origin.

Equal to the distance from the origin to the nearest polygon edge.

create ¶

create(
    center: tuple[float, float],
    size: float | tuple[float, float],
    rotation: float = 0.0,
    flipped: bool = False,
) -> Polygon

Create a scaled, optionally transformed polygon at center.

Parameters:

center (tuple[float, float]) –

Center coordinates (x, y).
size (float or tuple[float, float]) –

Scalar size (isotropic) or (sx, sy) for anisotropic scaling. The unit polygon is scaled by 2 * size in each direction so that size corresponds to the half-extent.
rotation (float, default: 0.0 ) –

Rotation angle in degrees (counter-clockwise). Applied after scaling and flipping, before translation.
flipped (bool, default: False ) –

Whether to reflect the symbol about the vertical axis before rotation. Used for tiling patterns that involve reflection.

get_geometry ¶

get_geometry(
    position: tuple[float, float],
    size: float,
    transform: Transform | None = None,
    offset: tuple[float, float] = (0.0, 0.0),
) -> Polygon

Return shapely geometry for this symbol.

Default implementation uses unit_polygon() + transform application. Subclasses may override for efficiency.

Parameters:

position (tuple[float, float]) –

Center position (x, y).
size (float) –

Symbol size (radius or half-width).
transform (Transform or None, default: None ) –

Additional rotation (radians), scale, reflection. If None, uses identity transform.
offset (tuple[float, float], default: (0.0, 0.0) ) –

Offset in unit coordinates, applied after scaling but before rotation/reflection. Used for FILL mode fitting where the symbol center is shifted from the tile center.

Returns:

Polygon –

The transformed symbol geometry.

modify ¶

modify(**params) -> Symbol

Return new symbol with modified parameters.

Default implementation returns self (immutable). Subclasses with parameters should override.

Parameters:

**params –

Parameters to modify (subclass-specific).

Returns:

Symbol –

Modified symbol (may be same instance if no changes).

unit_polygon `abstractmethod` ¶

unit_polygon() -> Polygon

Return the symbol as a polygon in [-0.5, 0.5]².

TileSymbol ¶

TileSymbol(polygon: Polygon)

Bases: Symbol

Symbol whose shape matches a tiling's canonical tile.

Normalizes an arbitrary polygon to fit in the unit square with bounding radius = 0.5, centered at the origin.

Parameters:

polygon (Polygon) –

The tile polygon (at any scale). Centroid is translated to the origin and the polygon is scaled so that the bounding radius (max distance from center to vertex) equals 0.5.

Methods:

modify –

Return self (TileSymbol does not support modification).

modify ¶

modify(**params) -> Symbol

Return self (TileSymbol does not support modification).

TransformedSymbol ¶

TransformedSymbol(
    base: Symbol,
    rotation: float = 0.0,
    reflection: bool = False,
)

Bases: Symbol

Wrapper that applies rotation/reflection to a base symbol.

The transformation is applied BEFORE fitting, so the fit is computed on the transformed shape. This is useful for FILL mode where a rotated symbol (e.g., a diamond) needs different fit characteristics than the base symbol (e.g., a square).

Parameters:

base (Symbol) –

The base symbol to transform.
rotation (float, default: 0.0 ) –

Rotation angle in degrees (counter-clockwise). Applied before reflection.
reflection (bool, default: False ) –

Whether to reflect the symbol about the vertical axis. Applied after rotation.

Examples:

Create a diamond (45° rotated square):

>>> diamond = TransformedSymbol(SquareSymbol(), rotation=45)
>>> styling = Styling(symbol=diamond, fit_mode='fill')

Create a mirrored hexagon:

>>> mirrored = TransformedSymbol(HexagonSymbol(), reflection=True)

Methods:

modify –

Return new symbol with modified transformation.
unit_polygon –

Return the transformed unit polygon.

Attributes:

bounding_radius (float) –

Bounding radius of transformed symbol.
inscribed_radius (float) –

Inscribed radius of transformed symbol.

bounding_radius `property` ¶

bounding_radius: float

Bounding radius of transformed symbol.

inscribed_radius `property` ¶

inscribed_radius: float

Inscribed radius of transformed symbol.

modify ¶

modify(
    rotation: float | None = None,
    reflection: bool | None = None,
    **params,
) -> TransformedSymbol

Return new symbol with modified transformation.

Parameters:

rotation (float or None, default: None ) –

New rotation angle in degrees. If None, keeps current.
reflection (bool or None, default: None ) –

New reflection flag. If None, keeps current.

Returns:

TransformedSymbol –

New symbol with modified transformation.

unit_polygon ¶

unit_polygon() -> Polygon

Return the transformed unit polygon.

TriangleSymbol ¶

TriangleSymbol(pointing_up: bool = True)

Bases: Symbol

Equilateral triangle inscribed in unit circle (radius = 0.5).

Parameters:

pointing_up (bool, default: True ) –

If True (default), triangle points upward. If False, points downward.

Methods:

modify –

Return new symbol with modified orientation.

modify ¶

modify(
    pointing_up: bool | None = None, **params
) -> TriangleSymbol

Return new symbol with modified orientation.

Parameters:

pointing_up (bool or None, default: None ) –

If provided, set the orientation.

create_circle ¶

create_circle(
    center: tuple[float, float],
    radius: float,
    n_points: int = 32,
) -> Polygon

Create a circular polygon.

Parameters:

center (tuple[float, float]) –

Center coordinates (x, y).
radius (float) –

Circle radius.
n_points (int, default: 32 ) –

Number of points to approximate the circle. Default is 32.

Returns:

Polygon –

Circular polygon.

create_hexagon ¶

create_hexagon(
    center: tuple[float, float],
    size: float,
    pointy_top: bool = True,
) -> Polygon

Create an axis-aligned hexagonal polygon.

Parameters:

center (tuple[float, float]) –

Center coordinates (x, y).
size (float) –

Distance from center to vertex.
pointy_top (bool, default: True ) –

If True, hexagon has a vertex at top (pointy-top orientation). If False, hexagon has a flat edge at top (flat-top orientation). Default is True.

Returns:

Polygon –

Hexagonal polygon.

create_square ¶

create_square(
    center: tuple[float, float], half_side: float
) -> Polygon

Create an axis-aligned square polygon.

Parameters:

center (tuple[float, float]) –

Center coordinates (x, y).
half_side (float) –

Half the side length (distance from center to edge).

Returns:

Polygon –

Square polygon.

create_symbols ¶

create_symbols(
    positions: NDArray[floating],
    sizes: NDArray[floating],
    symbol: SymbolParam,
    rotations: NDArray[floating] | None = None,
    flipped: NDArray[bool_] | None = None,
) -> list[Polygon]

Create symbol polygons, supporting per-geometry specification.

Parameters:

positions (np.ndarray of shape (n, 2)) –

Symbol center positions.
sizes (np.ndarray of shape (n,) or (n, 2)) –

Symbol sizes (isotropic or anisotropic).
symbol (str, Symbol, or sequence thereof) –

A single symbol specification applied to all geometries, or a sequence of length n for per-geometry symbols.
rotations (np.ndarray of shape (n,), default: None ) –

Per-symbol rotation angles in degrees. If None, no rotation.
flipped (np.ndarray of shape (n,), default: None ) –

Per-symbol flip flags. If None, no flipping.

Returns:

list[Polygon] –

resolve_symbol ¶

resolve_symbol(spec: SymbolSpec) -> Symbol

Resolve a symbol specification to a :class:Symbol instance.

Parameters:

spec (str or Symbol) –

A built-in name ("circle", "square", "hexagon") or a :class:Symbol instance.

Returns:

Symbol –

Raises:

ValueError –

If spec is a string that doesn't match a built-in symbol.
TypeError –

If spec is not a string or :class:Symbol.

carto_flow.symbol_cartogram.symbols¶

CircleSymbol ¶

area_factor property ¶

modify ¶

DiamondSymbol ¶

modify ¶

HexagonSymbol ¶

modify ¶

IsohedralTileSymbol ¶

bounding_radius property ¶

inscribed_radius property ¶

modify ¶

unit_polygon ¶

PentagonSymbol ¶

modify ¶

SquareSymbol ¶

modify ¶

StarSymbol ¶

modify ¶

Symbol ¶

area_factor property ¶

bounding_radius property ¶

inscribed_radius property ¶

create ¶

get_geometry ¶

modify ¶

unit_polygon abstractmethod ¶

TileSymbol ¶

modify ¶

TransformedSymbol ¶

bounding_radius property ¶

inscribed_radius property ¶

modify ¶

unit_polygon ¶

TriangleSymbol ¶

modify ¶

create_circle ¶

create_hexagon ¶

create_square ¶

create_symbols ¶

resolve_symbol ¶

area_factor `property` ¶

bounding_radius `property` ¶

inscribed_radius `property` ¶

area_factor `property` ¶

bounding_radius `property` ¶

inscribed_radius `property` ¶

unit_polygon `abstractmethod` ¶

bounding_radius `property` ¶

inscribed_radius `property` ¶