Label Placement

class mappyng.toponyme.LabelConfig(font_size=10.0, font_family='sans-serif', font_weight='normal', color='#000000', halo_color='#ffffff', halo_width=2.0, priority_col=None, min_priority=None, max_labels=None, initial_position='NE', candidate_positions=<factory>, label_offset=4.0, max_displacement=40.0, avoid_overlap=True, allow_hide=True, allow_symbol_overlap=False, leader_lines=True, leader_threshold=1.5, leader_color='#666666', leader_width=0.5, wrap=True, wrap_max_chars=12, numbered_above=None, numbered_legend_position=None, numbered_circle_r=5.0, numbered_circle_fill='#ffffff', numbered_circle_stroke='#333333', numbered_legend_bg='white', numbered_legend_bg_opacity=0.88, numbered_legend_border='#cccccc', numbered_legend_title=None, n_sweeps=50, initial_temperature=1.0, final_temperature=0.01, seed=42, target='main', w_LL=30.0, w_LO=25.0, w_LC=100.0, w_LA=30.0, w_D=1.0, w_OR=3.0, w_OOB=1000.0)[source]

Bases: object

Label placement configuration for Label.

Parameters:

  • font_size (float) – Label font size in SVG px (default 10.0).

  • font_family (str) – Font family (default "sans-serif").

  • font_weight (str) – Font weight (default "normal").

  • color (str) – Label text color (default "#000000").

  • halo_color (str or None) – Halo (text outline) color. None disables the halo.

  • halo_width (float) – Halo stroke width in SVG px (default 2.0).

  • priority_col (str or None) – Column name used for priority ranking (higher value = placed first).

  • min_priority (float or None) – Minimum priority threshold; rows below it are skipped.

  • max_labels (int or None) – Hard cap on the number of labels placed.

  • initial_position (str) – Starting candidate position (default "NE"). One of: "NE", "E", "SE", "S", "SW", "W", "NW", "N".

  • label_offset (float) – Distance from anchor point to label edge in SVG px (default 4.0).

  • max_displacement (float) – Maximum distance (px) a label may be moved away from its initial position, measured between the label edge and the edge of the symbol at its anchor (default 40.0).

  • avoid_overlap (bool) – Enable label-label overlap avoidance (default True).

  • allow_hide (bool) – Allow labels to be hidden when they cannot be placed without overlap (default True).

  • allow_symbol_overlap (bool) – With allow_hide, keep a label that still covers a map symbol (situation marker, proportional circle) after placement, instead of hiding it (default False).

  • leader_lines (bool) – Draw leader lines when label is displaced beyond leader_threshold (default True).

  • leader_threshold (float) – Minimum displacement (× label height) that triggers a leader line.

  • wrap (bool) – Wrap long labels at dashes (default True).

  • wrap_max_chars (int) – Max characters per line before wrapping (default 12).

  • numbered_above (int or None) – Switch to numbered-circle mode when label count exceeds this value. None = always use text labels.

  • n_sweeps (int) – Number of simulated-annealing sweeps (default 50).

  • seed (int or None) – Random seed for reproducible placement (default 42).

  • target (str) – Viewport to place labels on: "main" (default), "zoom", or "cartouche:<index>".

__init__(font_size=10.0, font_family='sans-serif', font_weight='normal', color='#000000', halo_color='#ffffff', halo_width=2.0, priority_col=None, min_priority=None, max_labels=None, initial_position='NE', candidate_positions=<factory>, label_offset=4.0, max_displacement=40.0, avoid_overlap=True, allow_hide=True, allow_symbol_overlap=False, leader_lines=True, leader_threshold=1.5, leader_color='#666666', leader_width=0.5, wrap=True, wrap_max_chars=12, numbered_above=None, numbered_legend_position=None, numbered_circle_r=5.0, numbered_circle_fill='#ffffff', numbered_circle_stroke='#333333', numbered_legend_bg='white', numbered_legend_bg_opacity=0.88, numbered_legend_border='#cccccc', numbered_legend_title=None, n_sweeps=50, initial_temperature=1.0, final_temperature=0.01, seed=42, target='main', w_LL=30.0, w_LO=25.0, w_LC=100.0, w_LA=30.0, w_D=1.0, w_OR=3.0, w_OOB=1000.0)
allow_hide: bool = True
allow_symbol_overlap: bool = False
avoid_overlap: bool = True
candidate_positions: list[str]
color: str = '#000000'
final_temperature: float = 0.01
font_family: str = 'sans-serif'
font_size: float = 10.0
font_weight: str = 'normal'
halo_color: str | None = '#ffffff'
halo_width: float = 2.0
initial_position: str = 'NE'
initial_temperature: float = 1.0
label_offset: float = 4.0
leader_color: str = '#666666'
leader_lines: bool = True
leader_threshold: float = 1.5
leader_width: float = 0.5
max_displacement: float = 40.0
max_labels: int | None = None
min_priority: float | None = None
n_sweeps: int = 50
numbered_above: int | None = None
numbered_circle_fill: str = '#ffffff'
numbered_circle_r: float = 5.0
numbered_circle_stroke: str = '#333333'
numbered_legend_bg: str = 'white'
numbered_legend_bg_opacity: float = 0.88
numbered_legend_border: str = '#cccccc'
numbered_legend_position: dict | None = None
numbered_legend_title: str | None = None
priority_col: str | None = None
seed: int | None = 42
target: str = 'main'
w_D: float = 1.0
w_LA: float = 30.0
w_LC: float = 100.0
w_LL: float = 30.0
w_LO: float = 25.0
w_OOB: float = 1000.0
w_OR: float = 3.0
wrap: bool = True
wrap_max_chars: int = 12