Skip to content

carto_flow.voronoi_cartogram.fields

Voronoi field backend implementations.

Class hierarchy

BaseField Shared init (points, boundary, weights, topology springs, adhesion). _constrain_points, _apply_boundary_adhesion, _topology_spring, get_points.

ExactField(BaseField) Exact scipy Voronoi + shapely clipping.

RasterField(BaseField) Raster nearest-neighbor Lloyd, optionally with elastic boundary.

Classes:

  • BaseField –

    Shared infrastructure for all Voronoi field backends.

  • ExactField –

    Exact scipy Voronoi + shapely clipping (Lloyd relaxation).

  • RasterField –

    Raster nearest-neighbor Lloyd relaxation.

BaseField 

BaseField(
    arr: ndarray,
    boundary,
    *,
    adj_pairs: list[tuple[int, int]] | None = None,
    intra_adj_pairs: list[tuple[int, int]] | None = None,
    boundary_mask=None,
    adhesion_boundary=None,
    adhesion_strength: float = 1.0,
    weights=None,
)

Shared infrastructure for all Voronoi field backends.

Parameters:

  • arr ((ndarray, shape(n, 2))) –

    Initial point positions.

  • boundary (Geometry) –

    Outer boundary polygon (or MultiPolygon).

  • adj_pairs (list of (int, int) or None, default: None ) –

    Adjacent point index pairs for topology spring.

  • boundary_mask (array-like of bool or None, default: None ) –

    True marks centroids to snap to the outer boundary line.

  • adhesion_boundary (Geometry or None, default: None ) –

    Geometry whose boundary is used for snapping. Defaults to boundary. Pass the un-simplified polygon when boundary has been simplified for speed.

  • adhesion_strength (float, default: 1.0 ) –

    Snap strength in [0, 1]. 1.0 = full snap; 0 = off.

  • weights (array-like of float or None, default: None ) –

    Positive per-point weights. Normalized internally.

Methods:

  • area_cv –

    Coefficient of variation of cell areas (std / mean).

  • get_cells –

    Return clipped Voronoi cell polygons, shape (n,).

  • get_cells_for_contiguity –

    Return cells for mid-loop adjacency/contiguity checks.

  • get_points –

    Return current point positions, shape (n, 2).

area_cv 

area_cv() -> float

Coefficient of variation of cell areas (std / mean).

Raises RuntimeError if called before the first relax().

get_cells 

get_cells() -> np.ndarray

Return clipped Voronoi cell polygons, shape (n,).

get_cells_for_contiguity 

get_cells_for_contiguity() -> np.ndarray

Return cells for mid-loop adjacency/contiguity checks.

Defaults to get_cells(). Raster fields override this to use computation-resolution raster cells (faster; topology-equivalent).

get_points 

get_points() -> np.ndarray

Return current point positions, shape (n, 2).

ExactField 

ExactField(
    arr: ndarray,
    boundary,
    *,
    adj_pairs=None,
    intra_adj_pairs=None,
    boundary_mask=None,
    adhesion_boundary=None,
    adhesion_strength: float = 1.0,
    weights=None,
)

Bases: BaseField

Exact scipy Voronoi + shapely clipping (Lloyd relaxation).

Parameters:

  • arr (ndarray) –
  • boundary (ndarray) –
  • adj_pairs (ndarray) –
  • boundary_mask (ndarray) –
  • adhesion_boundary (ndarray) –
  • adhesion_strength (float, default: 1.0 ) –

    See :class:BaseField.

  • weights (float, default: 1.0 ) –

    See :class:BaseField.

Methods:

  • relax –

    Run one exact-Voronoi Lloyd step.

relax 

relax(
    relaxation_factor: float = 1.0,
    topology_weight: float = 0.0,
    intra_topology_weight: float = 0.0,
    **_kwargs: Any,
) -> None

Run one exact-Voronoi Lloyd step.

Parameters:

  • relaxation_factor (float, default: 1.0 ) –

    Over-relaxation factor (SOR).

  • topology_weight (float, default: 0.0 ) –

    Adjacency spring strength (cross-group pairs, or all pairs when intra_topology_weight=0).

  • intra_topology_weight (float, default: 0.0 ) –

    Spring strength for intra-group pairs (0 = disabled).

RasterField 

RasterField(
    arr: ndarray,
    boundary,
    *,
    resolution: int = 300,
    final_resolution: int | None = None,
    boundary_elasticity: float = 0.0,
    boundary_step_scale: float = 1.0,
    density_smooth: float | None = None,
    min_boundary_points: int | None = None,
    labeling: str = "euclidean",
    area_eq_weight: float = 0.0,
    weight_ramp_iters: int = 0,
    debug_geodesic: bool = False,
    cell_smoothing_px: float = CELL_SMOOTHING_TOLERANCE_PX,
    adj_pairs=None,
    intra_adj_pairs=None,
    boundary_mask=None,
    adhesion_boundary=None,
    adhesion_strength: float = 1.0,
    weights=None,
)

Bases: BaseField

Raster nearest-neighbor Lloyd relaxation.

Parameters:

  • arr (ndarray) –

    See :class:BaseField.

  • boundary (ndarray) –

    See :class:BaseField.

  • resolution (int, default: 300 ) –

    Grid resolution (longest dimension).

  • boundary_elasticity (float, default: 0.0 ) –

    Elastic boundary deformation strength [0, 1]. 0 = rigid hard-clip. > 0 = the boundary is deformed each iteration by an FFT velocity field driven by cell-area pressure. Setting boundary_elasticity > 0 with relaxation_factor=0 and relaxation_factor_min=0 disables Lloyd relaxation entirely, reproducing the pure FFT-flow algorithm.

  • boundary_step_scale (float, default: 1.0 ) –

    Boundary advection speed as a fraction of boundary_elasticity, in (0, 1].

  • density_smooth (float or None, default: None ) –

    Gaussian sigma for density field smoothing (requires boundary_elasticity > 0).

  • labeling (('euclidean', 'geodesic'), default: "euclidean" ) –

    Pixel labeling algorithm.

  • area_eq_weight (float, default: 0.0 ) –

    Power-diagram area equalizer learning rate.

  • debug_geodesic (bool, default: False ) –

    When True and labeling="geodesic", emit warnings for misplaced BFS seeds (cross-water labeling diagnostics).

  • cell_smoothing_px (float, default: CELL_SMOOTHING_TOLERANCE_PX ) –

    Tolerance for smoothing pixel staircases on extracted cells, in final-grid pixels (the extraction grid is final_resolution or 4x resolution). Resolution-independent by construction. 0 disables smoothing. For cartographic generalisation in map units, apply :func:carto_flow.geo_utils.simplify_coverage to the result instead.

  • adj_pairs –

    See :class:BaseField.

  • boundary_mask –

    See :class:BaseField.

  • adhesion_boundary –

    See :class:BaseField.

  • adhesion_strength –

    See :class:BaseField.

  • weights –

    See :class:BaseField.

Methods:

  • relax –

    Run one raster Lloyd step.

relax 

relax(
    relaxation_factor: float = 1.0,
    topology_weight: float = 0.0,
    area_eq_weight: float = 0.0,
    iteration: int = 0,
    intra_topology_weight: float = 0.0,
    **_kwargs: Any,
) -> None

Run one raster Lloyd step.