Keys#

keys.py#

Floating image keys — a colour legend pinned over a panel.

A key is the scale bar’s sibling: a small picture that floats in a corner of the plot area, in screen space, and does not pan or zoom with the data. It is what you reach for when the colours in a plot mean something a colorbar cannot say — an inverse pole figure triangle over an orientation map, a hue wheel over a polarization vector field, a phase legend over a segmentation.

Deliberately not an inset axes. Figure.add_inset() gives you a draggable window with a title bar, a border and a full canvas stack — the right thing when the overlay is itself a plot you want to interact with, and much too heavy when it is a static picture that should read as part of the figure. A key has no chrome unless you ask for it, no event wiring, and one canvas shared by every key on the panel.

See anyplotlib._base_plot._BasePlot.add_key().

Classes

KeyOverlay

A floating image key pinned to a panel corner.

Full Reference

class anyplotlib.keys.KeyOverlay(plot, image_url, *, name=None, **kwargs)[source]#

Bases: object

A floating image key pinned to a panel corner.

Created by add_key(); not constructed directly.

Every property is settable through set(), which pushes to the renderer in one update:

key = plot.add_key(ipf_triangle, corner="bottom-right")
key.set(size=0.3, bgcolor="none")
key.visible = False          # plain attribute assignment also pushes

Parameters:: image_url (str)

property id: str#: Short unique identifier.

property name: str#

Caller-supplied name, or the id when none was given.

Use it with get_key().

set(**kwargs)[source]#

Update one or more properties and push once.

Accepts any of the constructor’s keyword arguments except image (use set_image() — it travels on a different channel).

Raises:: ValueError – On an unknown property name, or a value the constructor would also have rejected.
Return type:: None

set_image(image)[source]#

Replace the picture, keeping placement and styling.

Parameters:: image (array-like, bytes, or path) – Same input add_key() accepts.
Return type:: None

remove()[source]#

Remove this key from its panel.

Return type:: None

to_dict()[source]#

The light view-channel payload (no image bytes).

Return type:: dict

property image_url: str#: The data: URL the renderer decodes.

Creating a key

Keys are created from a panel, not constructed directly:

_BasePlot.add_key(image, *, corner='top-right', anchor=None, size=0.22, margin=10.0, bgcolor=None, border=None, border_width=1.0, radius=4.0, alpha=1.0, hover_only=False, visible=True, label=None, label_size=10.0, label_color=None, labels=None, name=None)[source]

Pin a floating image key over this panel.

A key is a small picture that floats in screen space over the plot area — it does not pan or zoom with the data. Use it for a colour legend a colorbar cannot express: an inverse pole figure triangle over an orientation map, a hue wheel over a polarization field, a phase key over a segmentation:

key = plot.add_key(ipf_triangle, corner="bottom-right", size=0.28)
wheel = plot.add_key(hue_wheel, corner="top-left",
                     bgcolor="none", hover_only=True)

This is the lightweight sibling of Figure.add_inset(). An inset is a draggable window with a title bar and its own canvas stack — the right tool when the overlay is a live plot. A key is a static picture with no chrome unless you ask for it, so it reads as part of the figure rather than as a floating panel.

Parameters:

image (array-like, bytes, or path) – An (H, W, 3|4) colour array (uint8, or float 0–1), the raw bytes of a PNG/JPEG/GIF/WebP, or a path to such a file. An RGBA array is the usual choice: alpha 0 outside the shape lets a triangle or a disc sit on the image without a rectangular card around it.
corner (str, optional) – "top-right" (default), "top-left", "bottom-right" or "bottom-left". Ignored when anchor is given.
anchor ((x_frac, y_frac), optional) – Free placement: the key’s centre as a fraction of the plot area, from its top-left. Overrides corner.
size (float, optional) – Width as a fraction of the plot area’s shorter side, so a key keeps its proportions when the panel is resized. Default 0.22. Height follows the image’s aspect ratio.
margin (float, optional) – Gap in CSS px between the key and the plot-area edge, for corner placement. Default 10.
bgcolor (str, optional) – CSS colour painted behind the image — e.g. "rgba(0,0,0,0.45)" for a legible card over busy data. Default None (fully transparent); "none" means the same thing.
border (str, optional) – CSS colour for a hairline around the card. Default None.
border_width (float, optional) – Border stroke width in px. Default 1.
radius (float, optional) – Corner radius of the card in px. Default 4.
alpha (float, optional) – Opacity of the whole key, 0–1. Default 1.
hover_only (bool, optional) – Show the key only while the pointer is over the panel. Default False. Useful for a reading aid you do not want sitting over the data all the time. PNG export renders the panel as though the pointer were over it, so a hover-only key is included in an exported figure — what you save is what you see while reading.
visible (bool, optional) – Draw the key at all. Default True.
label (str, optional) – Caption drawn under the image, mini-TeX enabled like axis labels.
label_size (float, optional) – Caption size in px. Default 10.
label_color (str, optional) – Caption colour. Default None (the theme’s tick-label colour).
labels (list, optional) –
Text drawn inside the key, for annotating the picture itself — an IPF triangle’s corner indices, a wheel’s compass points. Each entry is (x, y, text) or a dict with those keys plus optional size / color / align. x and y are fractions of the key image, so the text follows the picture when the key is resized. Mini-TeX works here as in any label:
```
tri.add_key(ipf, labels=[
    (0.02, 0.97, "[1 0 0]"),
    (0.98, 0.97, "[1 1 0]"),
    (0.98, 0.03, "[1 1 1]"),
])
```
name (str, optional) – Handle for get_key(). Defaults to the generated id.

Return type:

KeyOverlay