Markers#

markers.py#

Marker registry for Plot1D and Plot2D panels inside a Figure.

The public API mirrors matplotlib’s collection kwargs:

plot.add_circles(offsets, name=”group1”,
facecolors=”#ff0000”, edgecolors=”#ffffff”, radius=5, labels=[…])

plot.markers[“circles”][“group1”].set(offsets=new_offsets, radius=3)

Design#

MarkerGroup – a single named collection of markers (one type).
MarkerTypeDict – dict-like for one type; mutations propagate to the plot.
MarkerRegistry – top-level two-level dict: registry[type][name].

All state is stored as plain Python dicts; no traitlets here. The _push callback is supplied by the parent plot and is responsible for serialising the full registry into the panel’s JSON trait on the Figure widget.

Wire-format translation#

The JS renderer uses the same internal field names as the standalone viewers (color, fill_color, fill_alpha, sizes, etc.). MarkerGroup stores matplotlib-style names and to_wire() translates before JSON serialisation.

Per-marker colours#

edgecolors and facecolors accept either one colour for the whole group or a sequence of colours parallel to the markers — matplotlib’s edgecolors=[...] / scatter c=[...]:

plot.add_circles(offsets, edgecolors=["#f00", "#0f0", "#00f"], radius=3)

A sequence shorter than the group cycles, as matplotlib’s colour cycle does. This works for every marker type on both 1-D and 2-D panels.

Calibrated coordinates on 2-D panels#

On a Plot2D, transform="data" positions are image pixels. Pass coords="data" to give positions and lengths in the panel’s calibrated axis units instead; the group keeps those values and converts them through Plot2D.transform each time it is serialised, so it stays put when the panel is re-calibrated:

plot = ax.imshow(img, axes=[x_nm, y_nm], units="nm")
plot.add_circles([[11.0, -2.0]], radius=0.5, coords="data")

Classes

`MarkerGroup`	A named collection of markers of one type on one plot.
`MarkerTypeDict`	Dict-like container for all named groups of one marker type.
`MarkerRegistry`	Top-level two-level marker registry for a plot.

Full Reference

class anyplotlib.markers.MarkerGroup(marker_type, name, kwargs, push_fn, parent=None)[source]

Bases: object

A named collection of markers of one type on one plot.

Parameters:

marker_type (str) – One of the supported marker types ('circles', 'lines', …).
name (str) – User-facing name (key in the parent MarkerTypeDict).
kwargs (dict) – Initial matplotlib-style kwargs for this group.
push_fn (callable) – Zero-arg callback that serialises the full registry and pushes it to the parent figure trait.
parent (MarkerTypeDict | None)

property marker_type: str: The marker type, e.g. "circles" or "lines" (read-only).

property name: str: The group’s key in plot.markers[marker_type] (read-only).

get(key, default=None)[source]

Return a property as last given to the constructor or set() (matplotlib-style name, in the group’s coords frame).

>>> group.get("edgecolors")
'#ff0000'

Parameters:: key (str)

property coords: str

"pixel" or "data".

Only meaningful for transform="data" groups on a 2-D image panel, where "pixel" (the default) means image pixels and "data" the calibrated axis values. On 1-D panels both mean data coordinates. Change it with group.set(coords=...); the stored values are then reinterpreted, not converted.

Type:: Frame of this group’s positions and lengths

set(**kwargs)[source]

Update one or more properties and push the change to the plot.

Parameters:: **kwargs (dict) – Properties to update (e.g., offsets, radius, facecolors). Matplotlib-style names are translated to wire format. Positions and lengths are read in the group’s coords frame.
Return type:: None

remove()[source]

Remove this group from its parent and trigger a re-render.

Return type:: None

to_wire(group_id)[source]

Return a dict in the JS wire format for this marker group.

Parameters:: group_id (str) – Unique identifier for this marker group (usually UUID).
Returns:: Wire-format dict with type-specific structure, ready for JSON serialization and transmission to the JavaScript renderer.
Return type:: dict

class anyplotlib.markers.MarkerTypeDict(marker_type, push_fn, transform_fn=None)[source]

Bases: object

Dict-like container for all named groups of one marker type.

Any modification (__setitem__, __delitem__) automatically triggers the _push_fn callback so the plot re-renders.

Parameters:

marker_type (str) – Type of markers (e.g., ‘circles’, ‘arrows’, ‘lines’).
push_fn (callable) – Zero-arg callback to trigger re-render on mutations.

keys()[source]: Return group names.

values()[source]: Return MarkerGroup objects.

items()[source]: Return (name, MarkerGroup) pairs.

pop(name, *args)[source]

Remove and return a MarkerGroup by name.

Parameters:

name (str) – Name of the group to remove.
*args (optional) – Default value if name is not found.

Returns:

The removed group, or default value if provided.

Return type:

MarkerGroup

Raises:

KeyError – If name is not found and no default is provided.

to_wire_list()[source]

Serialise all groups to a list of wire-format dicts.

Return type:: list

class anyplotlib.markers.MarkerRegistry(push_fn, allowed=None, transform_fn=None)[source]

Bases: object

Top-level two-level marker registry for a plot.

Usage:

plot.markers["circles"]["group1"].set(offsets=new_offsets)

plot.markers is a MarkerRegistry. Indexing by type returns a MarkerTypeDict (auto-created on first access).

Parameters:: allowed (frozenset | None)

add(marker_type, name=None, **kwargs)[source]

Add a marker group, returning the MarkerGroup.

Parameters:

marker_type (str) – Type string, e.g. 'circles', 'lines', 'arrows'.
name (str, optional) – Group name. Auto-generated ('circles_1' etc.) if None.
**kwargs (dict) – Matplotlib-style kwargs for the group (offsets, radius, colors, etc.). coords="data" gives positions and lengths in calibrated axis units on a 2-D image panel (see MarkerGroup.coords).

Returns:

The created marker group. Call .set() to update, or access properties as attributes.

Return type:

MarkerGroup

Examples

>>> group = registry.add("circles", name="my_circles", offsets=[[10, 20]], radius=5)
>>> group.set(radius=8)

remove(marker_type, name)[source]

Remove a named marker group and trigger re-render.

Parameters:

marker_type (str) – Type of the group.
name (str) – Name of the group to remove.

Raises:

KeyError – If the type or name is not found.

Return type:

None

clear()[source]

Remove all markers of all types and trigger re-render.

Return type:: None

to_wire_list()[source]

Flatten the full registry to a list of wire-format dicts.

Returns:: Wire-format dicts ready for JSON serialization and JS rendering.
Return type:: list of dict