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, 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)

Bases: object

Label placement configuration for LabelLayer.

font_size

Label font size in SVG px (default 10.0).

Type:

float

font_family

Font family (default "sans-serif").

Type:

str

font_weight

Font weight (default "normal").

Type:

str

color

Label text color (default "#000000").

Type:

str

halo_color

Halo (text outline) color. None disables the halo.

Type:

str or None

halo_width

Halo stroke width in SVG px (default 2.0).

Type:

float

priority_col

Column name used for priority ranking (higher value = placed first).

Type:

str or None

min_priority

Minimum priority threshold; rows below it are skipped.

Type:

float or None

max_labels

Hard cap on the number of labels placed.

Type:

int or None

initial_position

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

Type:

str

label_offset

Distance from anchor point to label edge in SVG px (default 4.0).

Type:

float

max_displacement

Maximum displacement from the initial position before hiding (px).

Type:

float

avoid_overlap

Enable label-label overlap avoidance (default True).

Type:

bool

allow_hide

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

Type:

bool

leader_lines

Draw leader lines when label is displaced beyond leader_threshold (default True).

Type:

bool

leader_threshold

Minimum displacement (× label height) that triggers a leader line.

Type:

float

wrap

Wrap long labels at dashes (default True).

Type:

bool

wrap_max_chars

Max characters per line before wrapping (default 12).

Type:

int

numbered_above

Switch to numbered-circle mode when label count exceeds this value. None = always use text labels.

Type:

int or None

n_sweeps

Number of simulated-annealing sweeps (default 50).

Type:

int

seed

Random seed for reproducible placement (default 42).

Type:

int or None

target

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

Type:

str

__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, 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

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