Skip to content

Collision Handling

One of the biggest contributors to the visual quality of a map is labeling, which includes choosing carefully what to label and also choosing good positions for those labels. Obviously, you don't want labels to collide with each other, but there's also a few more subtle things to consider when labeling points and areas on a map. Starplot has a CollisionHandler to control some of these things.

When you create a plot, you can specify the default collision handler that'll be used when plotting text. But, you can also override this default on all functions that plot text (either directly or as a side effect). There's one exception to this though: since constellation labels are area-based labels they have their own default collision handler.

New Feature

The collision handler is a newer feature of Starplot (introduced in version 0.19.0), and will continue to evolve in future versions. As always, if you notice any unexpected behavior with it, please open an issue on GitHub.

starplot.CollisionHandler dataclass 

CollisionHandler(
    allow_clipped: bool = False,
    allow_label_collisions: bool = False,
    allow_marker_collisions: bool = False,
    allow_constellation_line_collisions: bool = False,
    plot_on_fail: bool = False,
    attempts: int = 500,
    seed: int = None,
    anchor_fallbacks: list[AnchorPointEnum] = None,
)

Dataclass that describes how to handle label collisions with other objects, like text, markers, constellation lines, etc.

allow_clipped class-attribute instance-attribute 

allow_clipped: bool = False

If True, then labels will be plotted if they're clipped (i.e. part of the label is outside the plot area)

allow_label_collisions class-attribute instance-attribute 

allow_label_collisions: bool = False

If True, then labels will be plotted if they collide with another label

allow_marker_collisions class-attribute instance-attribute 

allow_marker_collisions: bool = False

If True, then labels will be plotted if they collide with another marker

allow_constellation_line_collisions class-attribute instance-attribute 

allow_constellation_line_collisions: bool = False

If True, then labels will be plotted if they collide with a constellation line

plot_on_fail class-attribute instance-attribute 

plot_on_fail: bool = False

If True, then labels will be plotted even if no allowed position is found. They will be plotted at their last attempted position.

attempts class-attribute instance-attribute 

attempts: int = 500

Max attempts to find a good label position

seed class-attribute instance-attribute 

seed: int = None

Random seed for randomly generating points

anchor_fallbacks class-attribute instance-attribute 

anchor_fallbacks: list[AnchorPointEnum] = None

If a point-based label's preferred anchor point results in a collision, then these fallbacks will be tried in sequence until a collision-free position is found.

Default: 

[
    AnchorPointEnum.BOTTOM_RIGHT,
    AnchorPointEnum.TOP_LEFT,
    AnchorPointEnum.TOP_RIGHT,
    AnchorPointEnum.BOTTOM_LEFT,
    AnchorPointEnum.BOTTOM_CENTER,
    AnchorPointEnum.TOP_CENTER,
    AnchorPointEnum.RIGHT_CENTER,
    AnchorPointEnum.LEFT_CENTER,
]