plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/colorbar.py

@@ -0,0 +1,1426 @@
+"""Colorbars: the guides of color axes, and size keys: the guides of size axes.
+
+A colorbar draws its axis' gradient between the trained limits in one of two looks
+(``style``): a key (``"key"``), one line of the low limit, a short thick bar with round
+ends and the high limit, then the label; or a bar (``"bar"``), a long gradient with the
+axis' ticks and label.  A colorbar of a size axis is a size key: a key with sample
+markers of increasing size in place of the bar.  It is attached to a side of a plot (a
+band of the plot's box), sits in the lanes beside a set of plots (:class:`FigureColorbar`,
+``figure.add_colorbar`` or a shared axis), or in its own grid area
+(``figure.colorbar_area(…, id=…)``).
+"""
+
+import math
+from typing import TYPE_CHECKING, Any, Self, Unpack
+
+from vec_io import LinearGradient, Path, Span
+
+from .canvas import Canvas
+from ._methods import FigureColorbarMixin
+from . import groups
+from .axis import AxisState
+from .color.values import resolve_color
+from .settings import (Setting, Settings, boolean, canonical, either, literal, number, one_of,
+                       route, table, text)
+from .spec import current, set_boxes
+from .text import _CAP_HEIGHT, box, draw_run, measure, run
+from .guides import anchor, placement, set_place
+from .titles import ALIGNS, CREATED, SIDES, align_of
+from .units import resolve_raw
+from .validators import length
+
+if TYPE_CHECKING:
+    from .types import ColorbarSettings
+
+__all__ = ["Colorbar", "FigureColorbar", "Bar"]
+
+#: ``"auto"`` lengths: a key's, then a bar's.
+_AUTO = {"thickness": (4.0, 13.0), "length": (40.0, "100%"), "pad": ("0.8em", 11.0)}
+#: A key's end triangle (× the key's thickness): its depth from the inner corners to the tip,
+#: the gap to the bar (the same all along: its inner side is concentric with the bar's
+#: rounded end), the radius of its corners.
+_TRI_DEPTH, _TRI_GAP, _TRI_RADIUS = 0.9, 0.45, 0.25
+#: The ends' sizes along the bar (× its thickness): a dot, a block, a triangle (from its tip
+#: to the bar's end, less ``_END_GAP``).
+_END = {"dot": 1.0, "block": 0.5,
+        "triangle": _TRI_DEPTH + math.sqrt((0.5 + _TRI_GAP) ** 2 - 0.25) - 0.5 - 0.5}
+#: Gap between a key's bar and an end shape (× its thickness).
+_END_GAP = 1 / 2
+#: ``values="signs"``: a bold minus (always U+2212) and plus.
+SIGNS = ([Span("−", font_weight="bold")], [Span("+", font_weight="bold")])
+
+
+def own_area(cb: "Colorbar") -> bool:
+    """Whether a colorbar is in its own grid area (neither attached nor in the lanes)."""
+    return cb.plot is None and not cb.lanes
+
+
+def _orientation(cb: "Colorbar") -> str:
+    """``orientation="auto"``: vertical on the left and right and in an area of its own,
+    horizontal on top and bottom."""
+    if own_area(cb):
+        return "vertical"
+    kind, where = cb.placement()
+    if kind == "inside":
+        return "vertical" if where in ("center_left", "center_right") else "horizontal"
+    return "vertical" if where in ("left", "right") else "horizontal"
+
+
+def _extend_shape(cb: "Colorbar") -> str:
+    """``extend_shape="auto"``: a triangle on a key, a block on a bar."""
+    return "triangle" if cb.resolve("style") == "key" else "block"
+
+
+def _values(v: Any) -> Any:
+    """``"limits"``, ``"ticks"``, ``"signs"`` or a pair of texts (``None``: that end's
+    number)."""
+    if isinstance(v, str):
+        k = v.strip().lower()
+        if k in ("limits", "ticks", "signs"):
+            return k
+    elif isinstance(v, (tuple, list)) and len(v) == 2:
+        return tuple(None if x is None else text(x) for x in v)
+    raise ValueError(f"expected 'limits', 'ticks', 'signs' or a pair of texts, got {v!r}")
+
+
+def gradient_stops(cmap: Any, samples: int = 256) -> list[tuple[float, Any, float]]:
+    """``(offset, rgb, opacity)`` stops of a color map for a ``LinearGradient``: ``samples``
+    samples of a smooth map, two stops per step of a stepped one."""
+    stops: list[tuple[float, Any, float]] = []
+    if cmap.interpolation != "nearest":       # linear, smooth, spline: a sampled gradient
+        colors = cmap.table(samples)
+        stops = [(i / (samples - 1), c[:3], c[3]) for i, c in enumerate(colors)]
+    else:                                     # steps: each from its stop to the next
+        for i, (p, c) in enumerate(cmap.stops):
+            nxt = cmap.stops[i + 1][0] if i + 1 < len(cmap.stops) else 1.0
+            stops.append((p, c[:3], c[3]))
+            stops.append((nxt, c[:3], c[3]))
+    return stops
+
+class Colorbar(Settings):
+    """A colorbar: the guide of a color axis, attached to a plot (``plot.add_colorbar(…)``) or
+    in its own grid area (``figure.colorbar_area(…, id=…)``).  ``source``: a mapped series (its
+    color axis) or a color axis; ``colorbar.axis`` is the axis shown, whose limits, number
+    format and fonts the colorbar draws.
+
+    ``style="key"`` (default): one line of the low limit, a short bar with round ends filled
+    with the gradient, the high limit, then the label, centered on the bar's middle line in
+    the axis' tick label font (``em``: its size).  When the limits clip the data
+    (``extend``), a rounded triangle in the under or over color points away from that end, its
+    inner side following the bar's (``extend_shape``).
+    ``values``: ``"limits"`` (in the axis' ``tick_format``; ``"auto"`` rounds to two digits of
+    the range), ``"ticks"`` (along the bar), ``"signs"`` (a bold − and +) or a pair of texts
+    (``("Low", "High")``; ``None`` keeps that number).  Vertical (left and right): the high
+    limit above, the low below, the label above everything (``label_position``: ``end``,
+    ``start``, ``top``, ``side``).  ``style="bar"``: a long bar (``length`` ``100%``) with the
+    axis' ticks, tick labels and label beside it.
+
+    Attached (``side``, default ``bottom``): a band of the plot's box, after an outside
+    legend and before the titles, placed along the side by ``align``; ``orientation="auto"``
+    is horizontal on top and bottom.  A key longer than its axes side passes its ends.
+    ``inside`` (an anchor, or ``"auto"`` as a legend's) places it inside the axes, ``pad``
+    from their edges, before the legend, which avoids it; a bar is then ``50%`` long.
+    ``"auto"`` finding no free place inside attaches it at the bottom instead.  In
+    its own area (``figure.colorbar_area``) it is vertical, a bar along the neighbouring
+    axes (or boxes with ``align="borders"``).  Axis settings given to a colorbar go to its
+    axis: ``plot.add_colorbar(h, tick_format="{:.0%}")``.
+
+    A colorbar of a size axis is a size key: ``count`` sample markers of increasing size
+    between the limits (``0%  ·  •  ●  100%  label``), ``marker_gap`` apart, in grey or the
+    series' one color; ``values="ticks"`` or a series' ``size_key`` list puts a marker at
+    each value.  Every series mapping sizes has one under its plot by default
+    (``size_key="key"``); a colorbar of the same axis or a ``figure.size_legend`` area
+    replaces it.  On top or bottom a key joins the line of the keys before it when the line
+    fits the axes width (a dot plot's color and size keys side by side).  ``style``,
+    ``thickness``, ``length`` and ``extend`` do not apply to it.
+    """
+
+    SETTINGS = table(
+        side=Setting(one_of(*SIDES), doc="Side of the plot (or of the plots) it sits on; "
+                                         "setting it unsets `inside`."),
+        inside=Setting(anchor,
+                       doc="Place inside the axes of its plot instead (as a legend's: "
+                           "`auto`, `top_right`, …, `center_left`), `pad` from their edges "
+                           "(`auto` with no free place: at the bottom); setting it unsets "
+                           "`side`."),
+        align=Setting(one_of(*ALIGNS),
+                      doc="Place along its side: `start` (left, or top), `center`, `end` "
+                          "(right, or bottom), or an end by name: `left`, `right` on top "
+                          "and bottom, `top`, `bottom` on the left and right."),
+        order=Setting(number(), doc="Place among the colorbars of its side: lower is nearer "
+                                    "the axes; unset: creation order."),
+        style=Setting(one_of("key", "bar"),
+                      doc="`key`: one line of the limits around a short bar with round ends, "
+                          "then the label; `bar`: a long bar with the axis' ticks."),
+        orientation=Setting(one_of("auto", "vertical", "horizontal"), auto=_orientation,
+                            doc="Direction; `\"auto\"`: horizontal on top and bottom, "
+                                "vertical on the left and right and in an area of its own; "
+                                "inside the axes vertical at `center_left` and "
+                                "`center_right`."),
+        thickness=Setting(either(literal("auto"),
+                                 length(positive=True, percent="bar_thickness")),
+                          doc="Bar thickness; `\"auto\"`: 4 px on a key, 13 px on a bar."),
+        length=Setting(either(literal("auto"), length(positive=True, percent="bar_along")),
+                       doc="Bar length; `\"auto\"`: 40 px on a key, `100%` on a bar (`50%` "
+                           "inside the axes). A key given in `%` fills that part of the span "
+                           "with its texts and bar."),
+        values=Setting(_values, expr=False,
+                       doc="A key's end texts: `limits` (the axis' limits in its "
+                           "`tick_format`), `ticks` (the axis' ticks along the bar, "
+                           "lengthened to show at least two), `signs` "
+                           "(a bold − and +) or a pair of texts (`None`: that end's number)."),
+        value_gap=Setting(length(lo=0, percent="em"),
+                          doc="Gap between a key's end texts and its bar (and above or below "
+                              "a label on top or under it)."),
+        label_gap=Setting(length(lo=0, percent="em"),
+                          doc="Gap between a key's texts and its label, along the key."),
+        label_position=Setting(one_of("end", "start", "side", "top"),
+                               doc="A key's label: after the high end (`end`; above a "
+                                   "vertical key), before the low end (`start`; below a "
+                                   "vertical key), beside the bar (`side`: under a "
+                                   "horizontal key, rotated right of a vertical one) or above "
+                                   "the key (`top`). A bar reads `top` only: above a vertical "
+                                   "bar from its left edge, `value_gap` below the label; on a "
+                                   "horizontal bar from its start, past its ticks. Otherwise "
+                                   "a bar's label is centred past its ticks."),
+        pad=Setting(either(literal("auto"), length(lo=0, percent="bar_across")),
+                    doc="Gap between the axes and an attached colorbar (inside the axes: "
+                        "between it and their edges); `\"auto\"`: 0.8em on a key, 11 px on "
+                        "a bar."),
+        label=Setting(text, doc="Label: a string or rich content; default: the axis' "
+                                "`label`, else the name of the color column or density."),
+        extend=Setting(one_of("auto", "neither", "min", "max", "both"),
+                       doc="Ends in the under/over colors: `auto` shows them when the limits "
+                           "clip the data."),
+        extend_shape=Setting(one_of("auto", "dot", "block", "triangle"), auto=_extend_shape,
+                             doc="`dot`: a dot past the key's end; `block`: a separate block "
+                                 "at the end (within a bar's length); `triangle`: a triangle "
+                                 "past the end (on a key: rounded, its inner side following "
+                                 "the bar's round end); `\"auto\"`: `triangle` on a key, "
+                                 "`block` on a bar (a bar refuses `dot`)."),
+        frame=Setting(boolean, doc="Outline the bar (and its ends), following its shape."),
+        count=Setting(number(lo=1, integer=True),
+                      doc="A size key's markers below its high limit "
+                          "(`values=\"limits\"`)."),
+        marker_gap=Setting(length(lo=0, percent="em"),
+                           doc="Gap between a size key's markers (edge to edge)."),
+        **groups.Stroke.embed("frame_",
+                              only=("color", "line_width"),
+                              docs={"color": "Outline color.",
+                                    "line_width": "Outline width."}),
+    )
+
+    #: whether it sits in the lanes beside plots (:class:`FigureColorbar`)
+    lanes = False
+
+    def __init__(self, source: Any = None, plot: Any = None, figure: Any = None,
+                 **settings: Any) -> None:
+        from .color.maps import ColorMap
+        from .mapped import ColorAxis, SizeAxis
+        if isinstance(source, ColorMap):
+            raise ValueError("a colorbar shows a color axis: give a mapped series, or a "
+                             "shared figure.color_axis(color_map=…)")
+        cls = SizeAxis if isinstance(source, SizeAxis) else ColorAxis
+        axis_kw = {k: settings.pop(k) for k in list(settings)
+                   if k not in type(self).SETTINGS and canonical(k, cls.SETTINGS)
+                   in cls.SETTINGS}
+        #: a size key's values, one marker each (a series' ``size_key`` list)
+        self.marks: list[float] | None = None
+        own, = route(settings, [type(self)])
+        self.source = source
+        self.plot = plot
+        self.figure = figure if figure is not None else (plot.figure if plot is not None else None)
+        self.id: Any = None
+        super().__init__(**own)
+        if axis_kw:
+            self.axis.set(**axis_kw)
+
+    def _parent(self) -> Settings | None:
+        return self.plot if self.plot is not None else self.figure
+
+    def set(self, **settings: "Unpack[ColorbarSettings]") -> Self:  # type: ignore[override]
+        super().set(**settings)
+        set_place(self, dict(settings))
+        return self
+
+    def placement(self) -> tuple[str, Any]:
+        """``("inside", anchor)`` (attached to a plot only) or ``("side", side)``."""
+        if self.plot is None or "inside" not in self.SETTINGS:
+            return "side", self.resolve("side")
+        return placement(self, side_first=False)
+
+    def _font_size(self) -> float:
+        """The font size ``em`` is of: its axis' tick label font size."""
+        try:
+            axis = self.axis
+        except ValueError:
+            return super()._font_size()
+        return axis.resolve("tick_label_font_size")
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.source!r})"
+
+    def _candidates(self) -> list[Any]:
+        """The plots whose last mapped series it shows without a source."""
+        return [self.plot] if self.plot is not None else []
+
+    def shown(self, check: bool = False) -> Any:
+        """What the colorbar shows: its source, else the plot's last series with mapped
+        colors (``check``: a series source must map colors)."""
+        from .layers.pipeline import call_of
+        from .mapped import ColorAxis, SizeAxis
+        src = self.source
+        if isinstance(src, SizeAxis):
+            return src
+        if src is None:
+            for p in self._candidates():
+                src = next((s for s in reversed(p.series) if call_of(s).color_sources), None)
+                if src is not None:
+                    break
+        if src is None:
+            raise ValueError("colorbar without a source: give a mapped series or a color "
+                             "axis")
+        if check and not isinstance(src, ColorAxis) and not call_of(src).color_sources:
+            raise ValueError(f"{src!r} has no mapped colors to show")
+        return src
+
+    @property
+    def axis(self) -> Any:
+        """The color (or size) axis shown (its limits, number format and fonts are the
+        colorbar's)."""
+        from .mapped import ColorAxis, SizeAxis, color_axis_of
+        src = self.shown()
+        return src if isinstance(src, (ColorAxis, SizeAxis)) else color_axis_of(src)
+
+    @property
+    def sizes(self) -> bool:
+        """Whether it shows a size axis (a size key)."""
+        from .mapped import SizeAxis
+        return isinstance(self.source, SizeAxis)
+
+    def size_series(self) -> list[Any]:
+        """The series whose sizes a size key shows (their marker, their color)."""
+        from .mapped import size_group
+        axis = self.axis
+        g = size_group(axis)
+        if g is not None and g.users:
+            return list(g.users)
+        return [axis.series] if axis.series is not None else []
+
+    def color_map(self) -> Any:
+        """The gradient shown."""
+        return self.axis.color_map()
+
+    def auto_label(self) -> Any:
+        """The label: the setting, else the axis' label, else the source series' color
+        column name, else the name of a density it maps."""
+        label = self.resolve("label")
+        if label is not None:
+            return label
+        if self.sizes:
+            axis = self.axis
+            if axis.resolve("label") is not None:
+                return axis.resolve("label")
+            return next((s.columns["size"] for s in self.size_series()
+                         if "size" in getattr(s, "columns", {})), None)
+        from .mapped import ColorAxis
+        src = self.shown()
+        axis = src if isinstance(src, ColorAxis) else None
+        if axis is None and hasattr(src, "SETTINGS"):
+            from .mapped import color_axis_of
+            axis = color_axis_of(src)
+        if axis is not None and axis.resolve("label") is not None:
+            return axis.resolve("label")
+        if isinstance(src, ColorAxis):
+            return None
+        cols = getattr(src, "columns", {})
+        from .layers.paint import COLOR_SETTINGS
+        for name in COLOR_SETTINGS:
+            if name in cols:
+                return cols[name]
+        from .density import Density
+        for name in COLOR_SETTINGS:
+            if name in src.SETTINGS and isinstance(src.resolve(name), Density):
+                return src.resolve(name).label()
+        return None
+
+    @property
+    def vertical(self) -> bool:
+        return self.resolve("orientation") == "vertical"
+
+
+class FigureColorbar(FigureColorbarMixin, Colorbar):
+    """A colorbar of the figure (``figure.add_colorbar``, or made for a shared color
+    axis): the guide of a color axis, in the lanes beside a set of plots as figure titles
+    and legends are.
+
+    ``source`` defaults to the first covered plot's last mapped series.  It sits in the lanes
+    of :class:`FigureTitle` (over the same plots: legend, then colorbar, then title), placed
+    by ``align`` within the axes of its plots; a ``%`` ``length`` is of that span.  The covered
+    plots' attached colorbars of the same axis are left out.  When plots sharing a color
+    axis (``share_color``, or one ``figure.color_axis()``) have attached colorbars of it, one
+    figure colorbar replaces them: on the right of a row or of the figure, at the bottom of a
+    column, with the settings of the first; an attached colorbar whose ``side`` is set stays.
+    ``plot.save()`` leaves figure colorbars out (the attached ones show again).
+    """
+
+    SETTINGS = table(**{
+        **{k: v for k, v in Colorbar.SETTINGS.items() if k != "inside"},
+        "order": Setting(number(), doc="Place in its side's lanes, as figure titles' "
+                                       "`order`: lower is nearer the plots."),
+        "pad": Setting(either(literal("auto"), length(lo=0)),
+                       doc="Gap between the colorbar and the plots; `\"auto\"`: 0.8em on a "
+                           "key, 11 px on a bar."),
+    })
+
+    lanes = True
+
+    def __init__(self, figure: Any, source: Any = None, plots: Any = None,
+                 **settings: Any) -> None:
+        #: the plots it covers (``None``: every plot)
+        self.plots: list[Any] | None = plots
+        self._made = next(CREATED)
+        super().__init__(source, figure=figure, **settings)
+
+    def _candidates(self) -> list[Any]:
+        from .plot import Plot
+        if self.plots is not None:
+            return list(self.plots)
+        fig = self.figure
+        return [] if fig is None else [p for p in fig._areas.values() if isinstance(p, Plot)]
+
+
+class _Key:
+    """A key laid out in its own frame: the bar ``(x0, y0, x1, y1)`` (round ends), the end
+    shapes ``(shape, geometry, color)``, the texts ``(content, font, x, y, ha, va,
+    rotation)`` (the end texts from the bar's start, or the tick labels), the label (a
+    text, or ``None``) and the box around all."""
+
+    __slots__ = ("bar", "ends", "texts", "label", "box", "marks")
+
+    def __init__(self) -> None:
+        self.bar = (0.0, 0.0, 0.0, 0.0)
+        #: a size key's markers ``(cx, cy, diameter)``
+        self.marks: list[tuple[float, float, float]] = []
+        self.ends: list[tuple[str, Any, Any]] = []
+        self.texts: list[tuple[Any, ...]] = []
+        self.label: tuple[Any, ...] | None = None
+        self.box = (0.0, 0.0, 0.0, 0.0)
+
+    def add(self, rect: tuple[float, float, float, float]) -> None:
+        b = self.box
+        self.box = (min(b[0], rect[0]), min(b[1], rect[1]), max(b[2], rect[2]),
+                    max(b[3], rect[3]))
+
+
+def _text_rect(fonts: Any, item: tuple[Any, ...]) -> tuple[float, float, float, float]:
+    """The box of a key's text item in the key's frame."""
+    content, font, x, y, ha, va, rotation = item
+    w, a, d = measure(fonts, content, font)
+    if rotation:                                   # 90: reads upward, its top at x
+        return (x, y - w / 2, x + a + d, y + w / 2)
+    x0 = {"left": x, "center": x - w / 2, "right": x - w}[ha]
+    top = {"top": y, "center": y + _CAP_HEIGHT * font.size / 2 - a, "bottom": y - a - d}[va]
+    return (x0, top, x0 + w, top + a + d)
+
+
+class Bar:
+    """A colorbar's (or size key's) content (the guide's,
+    :class:`~plot_io.guides.GuideState`): its axis' trained limits, laid out as a key or a
+    bar for its place: inside or on a side of its plot, in the lanes (a figure colorbar),
+    or in its own area."""
+
+    form = "bar"
+    guide: Any = None
+
+    def __init__(self, cb: Colorbar, spot: tuple[str, Any]) -> None:
+        self.cb = cb
+        cb.shown(check=True)
+        self.axis = cb.axis
+        #: a size key: markers in place of the bar (always a key)
+        self.sizes = cb.sizes
+        self.cmap = None if self.sizes else self.axis.color_map()
+        self.label = cb.auto_label()
+        self.key = self.sizes or cb.resolve("style") == "key"
+        if not self.key and cb.resolve("extend_shape") == "dot":
+            raise ValueError('Colorbar: extend_shape="dot" is for a key; a bar takes "block" '
+                             'or "triangle"')
+        #: a size key's markers ``(value, diameter, label)`` (``label``: ``None`` between
+        #: the limits)
+        self.marks: list[tuple[float, float, Any]] = []
+        self.vertical = cb.vertical
+        kind, where = spot
+        #: the side it sits on (``None``: in its own area; inside the axes, the side its
+        #: ticks and texts are laid out for)
+        self.side: str | None = None if kind == "area" else \
+            where if kind in ("side", "lanes") else "right" if self.vertical else "bottom"
+        self.order = cb.resolve("order")
+        self.thickness = self.pad = 0.0
+        self.cell = 0.0                    # a key in its own area: its size across
+        #: how far an attached key passes the start and end of its axes side
+        self.over = (0.0, 0.0)
+        if kind == "area" and not self.key:  # a bar in its own area: no reference for %
+            self.thickness = self.size("thickness")
+            self.pad = self.size("pad")
+        self.tick_side = self.side or ("right" if self.vertical else "bottom")
+        self.sync()
+
+    def size(self, name: str, of: float | None = None) -> float:
+        """A length setting (``thickness``, ``length``, ``pad``) in px, ``"auto"`` as the
+        style's (``of``: what ``%`` is of)."""
+        cb = self.cb
+        v = cb.resolve(name) if of is None else cb.resolve(name, of=of)
+        if v != "auto":
+            return v
+        check: Any = cb.SETTINGS[name].check
+        return resolve_raw(cb, name, check, check(_AUTO[name][0 if self.key else 1]), of)
+
+    def sync(self) -> None:
+        """Take the axis' trained limits (again, once trained again: stats binned at the
+        axes' resolution) and the extension ends they imply."""
+        from .mapped import trained
+        st = trained(self.axis)
+        self.state = AxisState(self.axis)
+        self.state.copy_limits(st)
+        self.state._auto = (False, False)          # the colors' limits: no snapping
+        scale = self.state.scale
+        assert scale is not None
+        flo, fhi = st.flo, st.fhi
+        self.data = (scale.f(st.data_lo), scale.f(st.data_hi))
+        ext = "neither" if self.sizes else self.cb.resolve("extend")
+        if ext == "auto":
+            lo_clip = self.data[0] < flo - 1e-12 * abs(fhi - flo)
+            hi_clip = self.data[1] > fhi + 1e-12 * abs(fhi - flo)
+            ext = {(True, True): "both", (True, False): "min", (False, True): "max"}.get(
+                (lo_clip, hi_clip), "neither")
+        self.extend = ext
+
+    def _boxes(self, w: float, h: float) -> None:
+        """The boxes `%` of the colorbar's and its axis' settings refer to."""
+        set_boxes(self.cb, axes_width=w, axes_height=h)
+        set_boxes(self.axis, axes_width=w, axes_height=h, vertical=float(self.vertical))
+
+    def _start(self, s0: float, s1: float, size: float) -> float:
+        """Where something ``size`` long starts along ``s0``–``s1`` (``align``)."""
+        a = align_of(self.cb.resolve("align"))
+        if a == "start":
+            return s0
+        if a == "end":
+            return s1 - size
+        return s0 + (s1 - s0 - size) / 2
+
+    @property
+    def cell_size(self) -> float:
+        """Its size across, as a cell of the grid of its own (a bar's thickness)."""
+        return self.cell if self.key else self.thickness
+
+    # -- the key ----------------------------------------------------------------------
+
+    def _limits(self) -> tuple[Any, Any]:
+        """The axis' limits as text, in its ``tick_format``, with the same decimals (each
+        its own on log scales); the ``"auto"`` format without a ``precision`` rounds them
+        to two digits of their range (two significant digits each on log scales)."""
+        from .numbers import NumberStyle, format_numbers
+        st = self.state
+        a = self.axis
+        fmt, style = a.resolve("tick_format"), NumberStyle.of(a)
+        lo, hi = st.lo, st.hi
+        log = st.scale is not None and (st.scale.base is not None or st.scale.name == "logit")
+        if fmt == "auto" and style.precision is None:
+            lo, hi = _round_limits(lo, hi, log)
+        if log:                                  # each with its own digits
+            return (format_numbers([lo], fmt, style, "tick_format")[0],
+                    format_numbers([hi], fmt, style, "tick_format")[0])
+        out = format_numbers([lo, hi], fmt, style, "tick_format")
+        return out[0], out[1]
+
+    def _end_texts(self) -> tuple[Any, Any]:
+        """The low and high end texts ``(content, font)`` (``None``: none)."""
+        from .text import font_of
+        v = self.cb.resolve("values")
+        if v == "ticks" or (self.sizes and self.cb.marks is not None):
+            return None, None
+        st = self.state
+        numbers = st.tick_font()
+        if v == "signs":
+            return (SIGNS[0], numbers), (SIGNS[1], numbers)
+        lo, hi = self._limits()
+        if v == "limits":
+            return (lo, numbers), (hi, numbers)
+        a = self.axis
+        own = font_of(a, a.resolve("tick_label_font_size"), a.resolve("tick_label_weight"),
+                      color=a.resolve("tick_label_color"))
+        return tuple((n, numbers) if t is None else (t, own)        # type: ignore[return-value]
+                     for t, n in zip(v, (lo, hi)))
+
+    def _key_length(self, span: float, rest: float) -> float:
+        """The bar's length for a span ``span`` long, the rest of the key ``rest`` long."""
+        one = self.cb.resolve("length", of=1.0)
+        if one == "auto":
+            return self.size("length", span)
+        b = self.cb.resolve("length", of=2.0) - one       # its `%` part: px per px of span
+        if not b:
+            return one
+        return max(self.thickness, one + b * (span - 1.0) - rest)
+
+    def _key(self, fonts: Any, span: float) -> _Key:
+        """The key laid out for a span ``span`` long (what `%` of ``thickness`` and
+        ``length`` are of)."""
+        if self.sizes:
+            self._size_marks()
+            self.thickness = t = max([d for _, d, _ in self.marks] + [1.0])
+            gap = self.cb.resolve("marker_gap")
+            bar = sum(d for _, d, _ in self.marks) + gap * max(0, len(self.marks) - 1)
+            if self.vertical:
+                self._boxes(t, bar)
+            else:
+                self._boxes(bar, t)
+            return self._layout(fonts, bar)
+        self.thickness = t = self.size("thickness", span)
+        rest = self._layout(fonts, 0.0)
+        along = (rest.box[3] - rest.box[1]) if self.vertical else (rest.box[2] - rest.box[0])
+        bar = self._key_length(span, along)
+        if self.cb.resolve("values") == "ticks":
+            bar = self._ticks_length(fonts, bar)
+        if self.vertical:
+            self._boxes(t, bar)
+        else:
+            self._boxes(bar, t)
+        return self._layout(fonts, bar)
+
+    def _size_marks(self) -> None:
+        """A size key's markers: ``count`` values evenly spaced below the high limit (in
+        the scale's terms; the high limit's own marker, and a zero size at the low limit,
+        left out), or one per value of the axis' ticks (``values="ticks"``) or of the
+        series' ``size_key`` list, labelled."""
+        from .legend import SizeKey, size_key_labels, size_key_values
+        cb, st = self.cb, self.state
+        series = cb.size_series()
+        if not series:
+            self.marks = []
+            return
+        plot = cb.plot if cb.plot is not None else getattr(series[0], "plot", None)
+        if cb.marks is not None or cb.resolve("values") == "ticks":
+            values = size_key_values(self.axis, cb.marks)
+            labels: list[Any] = size_key_labels(self.axis, values, plot)
+        else:
+            scale = st.scale
+            assert scale is not None
+            n = cb.resolve("count")
+            flo, fhi = st.flo, st.fhi
+            first = SizeKey(self.axis, series, [st.lo], [None], None).sizes()[0]
+            fr = [(i + 1) / (n + 1) for i in range(n)] if first < 1e-9 else \
+                [i / n for i in range(n)]
+            values = [scale.inverse(flo + (fhi - flo) * f) for f in fr]
+            labels = [None] * len(values)
+        sizes = SizeKey(self.axis, series, values, labels, None).sizes()
+        self.marks = [(v, d, lab) for v, d, lab in zip(values, sizes, labels) if d > 0]
+
+    def marker_look(self) -> tuple[Any, Any, Any, float]:
+        """A size key's marker: ``(path, fill, stroke, stroke width)``: the series' marker
+        shape, grey, or the series' color when one series has one color."""
+        from .markers import resolve
+        from .values import Values, is_computed
+        series = self.cb.size_series()
+        s = series[0] if series else None
+        marker = s.resolve("marker") if s is not None and "marker" in s.SETTINGS else "circle"
+        marker = marker[0] if isinstance(marker, list) else marker
+        color: Any = "#888888"
+        if s is not None and len(series) == 1 and "color" in s.SETTINGS:
+            c = s.resolve("color")
+            if c is not None and not isinstance(c, (Values, list)) and not is_computed(c):
+                try:
+                    color = resolve_color(c, ())
+                except (TypeError, ValueError):
+                    pass
+        hollow = s is not None and "fill" in s.SETTINGS and s.resolve("fill") is False
+        width = s.resolve("edge_width") if hollow and s is not None else 0.0
+        return (resolve(marker)[0], None if hollow else color, color if hollow else None,
+                width or 1.0)
+
+    def _ticks_length(self, fonts: Any, bar: float) -> float:
+        """``bar``, lengthened by quarters until the axis labels at least two major ticks
+        along it."""
+        st = self.state
+        for _ in range(12):
+            st.compute_ticks(fonts, bar, not self.vertical)
+            if sum(1 for t in st.ticks if t.major and t.label is not None) >= 2:
+                break
+            bar *= 1.25
+        return bar
+
+    def _layout(self, fonts: Any, bar: float) -> _Key:
+        """The key with a bar ``bar`` long, in its frame: along x (horizontal) or y
+        (vertical, down) from 0, the bar's middle line at 0 across."""
+        cb, st = self.cb, self.state
+        t = self.thickness
+        vg, lg = cb.resolve("value_gap"), cb.resolve("label_gap")
+        where = cb.resolve("label_position")
+        label = self.label
+        lf = st.label_font()
+        lo, hi = self._end_texts()
+        inv = self.axis.resolve("invert")
+        first, last = (hi, lo) if inv else (lo, hi)     # at the bar's start, at its end
+        ends = dict(self._ends())
+        shape = cb.resolve("extend_shape")
+        s = _END[shape] * t
+        gap = _END_GAP * t
+        k = _Key()
+        texts = k.texts
+        ticks = cb.resolve("values") == "ticks"
+
+        def width(c: Any, f: Any) -> float:
+            return measure(fonts, c, f)[0]
+
+        def height(c: Any, f: Any) -> float:
+            _, a, d = measure(fonts, c, f)
+            return a + d
+
+        def end(at_start: bool, p: float) -> None:
+            """An end shape starting at ``p`` along the key."""
+            c = ends[at_start]
+            if shape == "dot":
+                geo: Any = (p + t / 2, 0.0, t / 2) if not self.vertical else (0.0, p + t / 2, t / 2)
+            elif shape == "block":
+                geo = (p, -t / 2, p + s, t / 2) if not self.vertical else (-t / 2, p, t / 2, p + s)
+            else:                    # a triangle pointing away, its inner side round
+                # the bar's rounded end: its centre ``mid`` along the key, ``d`` toward the tip
+                if not self.vertical:
+                    d = -1.0 if at_start else 1.0
+                    mid = p + s + gap + t / 2 if at_start else p - gap - t / 2
+                else:
+                    d = 1.0 if at_start else -1.0
+                    mid = p - gap - t / 2 if at_start else p + s + gap + t / 2
+                inner = mid + d * math.sqrt(((0.5 + _TRI_GAP) * t) ** 2 - (t / 2) ** 2)
+                tip = inner + d * _TRI_DEPTH * t
+                if not self.vertical:
+                    geo = ((tip, 0.0), (inner, -t / 2), (inner, t / 2), (mid, 0.0))
+                else:
+                    geo = ((0.0, tip), (-t / 2, inner), (t / 2, inner), (0.0, mid))
+            k.ends.append((shape, geo, c))
+
+        if not self.vertical:
+            x = 0.0
+            if label is not None and where == "start":
+                k.label = (label, lf, x, 0.0, "left", "center", 0.0)
+                x += width(label, lf) + lg
+            if first is not None:
+                texts.append((first[0], first[1], x, 0.0, "left", "center", 0.0))
+                x += width(*first) + vg
+            if True in ends:
+                end(True, x)
+                x += s + gap
+            k.bar = (x, -t / 2, x + bar, t / 2)
+            if self.sizes:
+                x = max(x + bar, self._place_marks(fonts, k))
+            else:
+                x += bar
+            if False in ends:
+                x += gap
+                end(False, x)
+                x += s
+            if ticks and bar > 0 and not self.sizes:
+                x = max(x, self._tick_labels(fonts, k, bar))
+            if last is not None:
+                x += vg
+                texts.append((last[0], last[1], x, 0.0, "left", "center", 0.0))
+                x += width(*last)
+            if label is not None and where == "end":
+                x += lg
+                k.label = (label, lf, x, 0.0, "left", "center", 0.0)
+        else:
+            y = 0.0
+            if label is not None and where in ("end", "top"):
+                k.label = (label, lf, 0.0, y, "center", "top", 0.0)
+                y += height(label, lf) + vg
+            top = None
+            if last is not None:
+                top = (last[0], last[1], 0.0, y, "center", "top", 0.0)
+                y += height(*last) + vg
+            if False in ends:
+                end(False, y)
+                y += s + gap
+            k.bar = (-t / 2, y, t / 2, y + bar)
+            y += bar
+            if self.sizes:
+                self._place_marks(fonts, k)
+            if True in ends:
+                y += gap
+                end(True, y)
+                y += s
+            if ticks and bar > 0 and not self.sizes:
+                self._tick_labels(fonts, k, bar)
+            if first is not None:
+                y += vg
+                texts.append((first[0], first[1], 0.0, y, "center", "top", 0.0))
+                y += height(*first)
+            if top is not None:                          # the texts from the start
+                texts.append(top)
+            if label is not None and where == "start":
+                y += vg
+                k.label = (label, lf, 0.0, y, "center", "top", 0.0)
+        k.box = k.bar
+        for cx, cy, d in k.marks:
+            k.add((cx - d / 2, cy - d / 2, cx + d / 2, cy + d / 2))
+        for shape_, geo, _ in k.ends:
+            k.add(_shape_rect(shape_, geo))
+        for item in texts + ([k.label] if k.label is not None else []):
+            k.add(_text_rect(fonts, item))
+        if label is not None and where in ("side", "top") and not (
+                self.vertical and where == "top"):
+            bx0, by0, bx1, by1 = k.bar
+            if self.vertical:                            # beside, reading upward
+                item = (label, lf, k.box[2] + vg, (by0 + by1) / 2, "center", "top", 90.0)
+            elif where == "top":
+                item = (label, lf, (bx0 + bx1) / 2, k.box[1] - vg, "center", "bottom", 0.0)
+            else:
+                item = (label, lf, (bx0 + bx1) / 2, k.box[3] + vg, "center", "top", 0.0)
+            k.label = item
+            k.add(_text_rect(fonts, item))
+        return k
+
+    def _place_marks(self, fonts: Any, k: _Key) -> float:
+        """A size key's markers along the bar of ``k``, smallest first (a vertical key's
+        largest at the top), their labels under them (right of a vertical key); returns
+        how far they reach along a horizontal key."""
+        x0, y0, x1, y1 = k.bar
+        gap = self.cb.resolve("marker_gap")
+        pad = self.axis.resolve("tick_pad")
+        font = self.state.tick_font()
+        reach = x1
+        marks = self.marks if not self.vertical else list(reversed(self.marks))
+        p = x0 if not self.vertical else y0
+        for _, d, lab in marks:
+            c = p + d / 2
+            p += d + gap
+            if not self.vertical:
+                k.marks.append((c, 0.0, d))
+                if lab is not None:
+                    k.texts.append((lab, font, c, y1 + pad, "center", "top", 0.0))
+                    reach = max(reach, c + box(fonts, lab, font)[0] / 2)
+            else:
+                k.marks.append((0.0, c, d))
+                if lab is not None:
+                    k.texts.append((lab, font, x1 + pad, c, "left", "center", 0.0))
+        return reach
+
+    def _tick_labels(self, fonts: Any, k: _Key, bar: float) -> float:
+        """The axis' tick labels along the bar of ``k`` (under a horizontal one, right of
+        a vertical one); returns how far they reach along a horizontal key."""
+        st = self.state
+        if abs(st.length - bar) > 0.01:
+            st.compute_ticks(fonts, bar, not self.vertical)
+        font = st.tick_font()
+        pad = self.axis.resolve("tick_pad")
+        x0, y0, x1, y1 = k.bar
+        reach = x1
+        if self.vertical:
+            mapper = st.mapper(y1, y0)
+        else:
+            mapper = st.mapper(x0, x1)
+        for tk in st.ticks:
+            if not tk.major or tk.label is None:
+                continue
+            p = mapper(tk.value)
+            if self.vertical:
+                k.texts.append((tk.label, font, x1 + pad, p, "left", "center", 0.0))
+            else:
+                k.texts.append((tk.label, font, p, y1 + pad, "center", "top", 0.0))
+                reach = max(reach, p + box(fonts, tk.label, font)[0] / 2)
+        oc = st.offset_label                   # ×10ᵏ: past the high end of the labels
+        if oc is not None:
+            if self.vertical:
+                k.texts.append((oc, font, x1 + pad, y0 - pad, "left", "bottom", 0.0))
+            else:
+                k.texts.append((oc, font, reach + pad, y1 + pad, "left", "top", 0.0))
+                reach += pad + box(fonts, oc, font)[0]
+        return reach
+
+    def _across(self, k: _Key, side: str) -> float:
+        bx0, by0, bx1, by1 = k.box
+        return (by1 - by0) if side in ("top", "bottom") else (bx1 - bx0)
+
+    def _place_key(self, fonts: Any, k: _Key, side: str, near: float, s0: float,
+                   s1: float) -> Any:
+        """Key ``k`` placed on ``side`` of what it covers, its near edge at ``near``
+        across the side, aligned within ``s0``–``s1`` along it."""
+        from .geometry import ColorKeyGeometry
+        bx0, by0, bx1, by1 = k.box
+        if side in ("top", "bottom"):
+            dx = self._start(s0, s1, bx1 - bx0) - bx0
+            dy = near - (by0 if side == "bottom" else by1)
+        else:
+            dy = self._start(s0, s1, by1 - by0) - by0
+            dx = near - (bx0 if side == "right" else bx1)
+        r = current()
+        boxes = (r.boxes.get(id(self.cb)), r.boxes.get(id(self.axis))) if r is not None \
+            else (None, None)
+
+        def moved(rect: tuple[float, float, float, float]) -> tuple[float, float, float, float]:
+            return (rect[0] + dx, rect[1] + dy, rect[2] + dx, rect[3] + dy)
+
+        ends = []
+        for shape, geo, c in k.ends:
+            if shape == "dot":
+                geo = (geo[0] + dx, geo[1] + dy, geo[2])
+            elif shape == "block":
+                geo = moved(geo)
+            else:
+                geo = tuple((px + dx, py + dy) for px, py in geo)
+            ends.append((shape, geo, c))
+
+        def placed(item: tuple[Any, ...]) -> Any:
+            content, font, x, y, ha, va, rotation = item
+            return run(fonts, content, x + dx, y + dy, font, ha, va, rotation)
+
+        runs = tuple(placed(item) for item in k.texts)
+        title = None if k.label is None else placed(k.label)
+        marks = tuple((cx + dx, cy + dy, d) for cx, cy, d in k.marks)
+        return ColorKeyGeometry(self, moved(k.bar), moved(k.box), tuple(ends), runs, title,
+                                boxes, marks)
+
+    # -- measurement ------------------------------------------------------------------
+
+    def _top_label(self) -> bool:
+        """A vertical bar with its label above it (``label_position="top"``)."""
+        return self.vertical and self.label is not None \
+            and self.cb.resolve("label_position") == "top"
+
+    def _labels_extent(self, fonts: Any, length: float) -> tuple[float, float, float]:
+        """A bar's space outside it for ticks, labels and its label, the overhang of end
+        labels along it, and its reach past its start (a vertical bar's top: the label
+        above it, ``label_position="top"``, included)."""
+        from .boxes import tick_label_extent
+        st = self.state
+        st.compute_ticks(fonts, length, not self.vertical)
+        axis = self.axis
+        out = st.tick_out()[0]
+        pad = axis.resolve("tick_pad")
+        across = out
+        over = 0.0
+        got = tick_label_extent(st, fonts, length, not self.vertical,
+                                self.tick_side in ("right", "top"))
+        if got is not None:
+            across += pad + got[0]
+            over = max(got[1], got[2])
+        row = 0.0
+        oc = st.offset_label
+        if oc is not None:          # ×10ᵏ: above a vertical bar, else in the label's row
+            ow, oh = box(fonts, oc, st.tick_font())
+            if self.vertical:
+                over = max(over, pad + oh)
+                across = max(across, out + pad + ow)
+            else:
+                row = oh
+        label = self.label
+        if self._top_label():
+            lw, a, d = measure(fonts, label, st.label_font())
+            tri = self.thickness if self.extend != "neither" and \
+                self.cb.resolve("extend_shape") == "triangle" else 0.0
+            above = max(tri, pad + box(fonts, oc, st.tick_font())[1] if oc is not None else 0.0)
+            top = max(over, above + self.cb.resolve("value_gap") + a + d)
+            return max(across, lw - self.thickness), over, top
+        if label is not None:
+            _, a, d = measure(fonts, label, st.label_font())
+            row = max(row, a + d)
+        if row:
+            across += axis.resolve("label_pad") + row
+        return across, over, over
+
+    def attach(self, w: float, h: float) -> float:
+        """A bar's thickness and pad for axes ``w`` × ``h`` (`%` is of the axes side across
+        the bar); returns its length (`%` of the side along it)."""
+        along, across = (h, w) if self.side in ("left", "right") else (w, h)
+        self.thickness = self.size("thickness", across)
+        self.pad = self.size("pad", across)
+        length = self.size("length", along)
+        thick, long = (self.thickness, length)
+        if self.vertical:
+            self._boxes(thick, long)
+        else:
+            self._boxes(long, thick)
+        return length
+
+    def _attached_key(self, fonts: Any, w: float, h: float) -> _Key:
+        """The key attached to axes ``w`` × ``h``, and how far it passes the ends of their
+        side (``over``)."""
+        flat = self.side in ("top", "bottom")
+        along, across = (w, h) if flat else (h, w)
+        self.pad = self.size("pad", across)
+        k = self._key(fonts, along)
+        bx0, by0, bx1, by1 = k.box
+        size = (bx1 - bx0) if flat else (by1 - by0)
+        start = self._start(0.0, along, size)
+        self.over = (max(0.0, -start), max(0.0, start + size - along))
+        return k
+
+    def measure_attached(self, fonts: Any, w: float, h: float) -> float:
+        """The band an attached colorbar takes beside axes ``w`` × ``h``: its pad and its
+        size across."""
+        if self.key:
+            k = self._attached_key(fonts, w, h)
+            assert self.side is not None
+            return self.pad + self._across(k, self.side)
+        length = self.attach(w, h)
+        across, over, top = self._labels_extent(fonts, length)
+        if self.extend != "neither" and self.cb.resolve("extend_shape") == "triangle":
+            over = max(over, self.thickness)
+        top = max(top, over)
+        along = h if self.side in ("left", "right") else w
+        start = self._start(0.0, along, length)
+        self.over = (max(0.0, top - start), max(0.0, start + length + over - along))
+        return self.pad + self.thickness + across
+
+    def measure_area(self, fonts: Any, w: float, h: float) -> tuple[float, float, float, float]:
+        """Margins of a colorbar in its own area ``w`` × ``h`` (a key's size across is its
+        ``cell``)."""
+        if self.key:
+            k = self._key(fonts, max(h if self.vertical else w, 1.0))
+            self.cell = self._across(k, "right" if self.vertical else "bottom")
+            return (0.0, 0.0, 0.0, 0.0)
+        length = h if self.vertical else w
+        self._boxes(w, h)
+        across, over, top = self._labels_extent(fonts, max(length, 1.0))
+        tri = self.thickness if self.extend != "neither" and \
+            self.cb.resolve("extend_shape") == "triangle" else 0.0
+        over = max(over, tri)
+        if self.vertical:
+            return (0.0, across, max(top, over), over)
+        return (over, over, 0.0, across)
+
+    def bar_rect(self, rect: tuple[float, float, float, float]) -> tuple:
+        x0, y0, x1, y1 = rect
+        t = self.cell_size
+        if self.vertical:
+            return (x0, y0, min(x1, x0 + t), y1)
+        return (x0, y0, x1, min(y1, y0 + t))
+
+    def lane_extent(self, fonts: Any, span: float) -> float:
+        """The size across of a colorbar in a lane over a span ``span`` long (its pad
+        left out)."""
+        assert self.side is not None
+        if self.key:
+            return self._across(self._key(fonts, span), self.side)
+        self.thickness = self.size("thickness", span)
+        length = self.size("length", span)
+        return self.thickness + self._labels_extent(fonts, length)[0]
+
+    def lane_pad(self) -> float:
+        return self.size("pad")
+
+    # -- placement --------------------------------------------------------------------
+
+    def key_width(self, fonts: Any, w: float, h: float) -> float:
+        """The length along its side of a horizontal key attached to axes ``w`` × ``h``."""
+        k = self._attached_key(fonts, w, h)
+        return k.box[2] - k.box[0]
+
+    def key_reach(self, fonts: Any, w: float, h: float) -> tuple[float, float]:
+        """A horizontal key attached on top or bottom of axes ``w`` × ``h``: from the axes
+        side, its pad and box to its middle line, and from there to its far edge."""
+        k = self._attached_key(fonts, w, h)
+        up, down = -k.box[1], k.box[3]
+        near, far = (up, down) if self.side == "bottom" else (down, up)
+        return self.pad + near, far
+
+    def place_attached(self, fonts: Any, axes: tuple, base: float,
+                       span: tuple[float, float] | None = None,
+                       line: float | None = None) -> Any:
+        """The colorbar attached to axes ``axes``, its band (its pad first) ``base`` px
+        from them.  A key sharing a line with others: ``span``, its place along the side,
+        and ``line``, how far the line's middle line is from where it starts (the keys'
+        middle lines aligned on it)."""
+        x0, y0, x1, y1 = axes
+        side = self.side
+        assert side is not None
+        if self.key:
+            k = self._attached_key(fonts, x1 - x0, y1 - y0)
+            start = base + self.pad
+            if line is not None:
+                start = base + line - (-k.box[1] if side == "bottom" else k.box[3])
+            near = {"bottom": y1 + start, "top": y0 - start, "right": x1 + start,
+                    "left": x0 - start}[side]
+            s0, s1 = span if span is not None else \
+                ((x0, x1) if side in ("top", "bottom") else (y0, y1))
+            return self._place_key(fonts, k, side, near, s0, s1)
+        length = self.attach(x1 - x0, y1 - y0)
+        start = base + self.pad
+        if side in ("left", "right"):
+            by0 = self._start(y0, y1, length)
+            bx0 = x1 + start if side == "right" else x0 - start - self.thickness
+            rect = (bx0, by0, bx0 + self.thickness, by0 + length)
+        else:
+            bx0 = self._start(x0, x1, length)
+            by0 = y1 + start if side == "bottom" else y0 - start - self.thickness
+            rect = (bx0, by0, bx0 + length, by0 + self.thickness)
+        return self._place_bar(fonts, rect)
+
+    def inside_size(self, fonts: Any, w: float, h: float) -> tuple[float, float, Any]:
+        """Inside axes ``w`` × ``h``: the size of its box (texts included) and how it is
+        laid out (a key, or a bar's ``(length, across, over)``)."""
+        pad = self.size("pad")
+        along = (h if self.vertical else w) - 2 * pad
+        if self.key:
+            k = self._key(fonts, max(along, 1.0))
+            bx0, by0, bx1, by1 = k.box
+            return bx1 - bx0, by1 - by0, k
+        self.thickness = self.size("thickness", w if self.vertical else h)
+        length = 0.5 * along if self.cb.resolve("length") == "auto" else \
+            self.size("length", along)
+        length = max(length, 1.0)
+        if self.vertical:
+            self._boxes(self.thickness, length)
+        else:
+            self._boxes(length, self.thickness)
+        across, over, top = self._labels_extent(fonts, length)
+        if self.extend != "neither" and self.cb.resolve("extend_shape") == "triangle":
+            over = max(over, self.thickness)
+        top = max(top, over)
+        ends = length + 2 * over if top == over else length + over + top
+        size = (self.thickness + across, ends) if self.vertical else \
+            (ends, self.thickness + across)
+        return size[0], size[1], (length, across, over, top)
+
+    def place_inside(self, fonts: Any, axes: tuple, at: Any) -> Any:
+        """The colorbar inside axes ``axes``, its box's top-left corner where
+        ``at(w, h, pad)`` puts a ``w`` × ``h`` box (its anchor, or the place ``"auto"``
+        chooses)."""
+        x0, y0, x1, y1 = axes
+        w, h, how = self.inside_size(fonts, x1 - x0, y1 - y0)
+        pad = self.size("pad")
+        tx, ty = at(w, h, pad)
+        if self.key:
+            if self.vertical:
+                return self._place_key(fonts, how, "right", tx, ty, ty + h)
+            return self._place_key(fonts, how, "bottom", ty, tx, tx + w)
+        length, _, over, top = how
+        t = self.thickness
+        rect = (tx, ty + top, tx + t, ty + top + length) if self.vertical else \
+            (tx + over, ty, tx + over + length, ty + t)
+        return self._place_bar(fonts, rect)
+
+    def place_lane(self, fonts: Any, near: float, s0: float, s1: float) -> Any:
+        """The colorbar in a lane: its near edge at ``near`` across its side, aligned
+        within ``s0``–``s1`` along it."""
+        side = self.side
+        assert side is not None
+        if self.key:
+            return self._place_key(fonts, self._key(fonts, s1 - s0), side, near, s0, s1)
+        self.thickness = t = self.size("thickness", s1 - s0)
+        length = self.size("length", s1 - s0)
+        a = self._start(s0, s1, length)
+        if side in ("top", "bottom"):
+            y = near if side == "bottom" else near - t
+            rect = (a, y, a + length, y + t)
+        else:
+            x = near if side == "right" else near - t
+            rect = (x, a, x + t, a + length)
+        self._boxes(rect[2] - rect[0], rect[3] - rect[1])
+        return self._place_bar(fonts, rect)
+
+    def place_area(self, fonts: Any, rect: tuple[float, float, float, float]) -> Any:
+        """The colorbar in its own area, at ``rect`` (a key along it, a bar filling it)."""
+        if self.key:
+            x0, y0, x1, y1 = rect
+            k = self._key(fonts, max((y1 - y0) if self.vertical else (x1 - x0), 1.0))
+            if self.vertical:
+                return self._place_key(fonts, k, "right", x0, y0, y1)
+            return self._place_key(fonts, k, "bottom", y0, x0, x1)
+        return self._place_bar(fonts, rect)
+
+    def _ends(self) -> list[tuple[bool, Any]]:
+        """The extension ends: ``(at the start, color)``; the start is the bottom of a
+        vertical bar, the left of a horizontal one."""
+        cmap, inv = self.cmap, self.axis.resolve("invert")
+        ends: list[tuple[bool, Any]] = []
+        if cmap is None:                          # a size key: no ends
+            return ends
+        if self.extend in ("min", "both"):
+            ends.append((not inv, cmap.under or cmap(0.0)))
+        if self.extend in ("max", "both"):
+            ends.append((inv, cmap.over or cmap(1.0)))
+        return ends
+
+    def _blocks(self, rect: tuple) -> tuple[tuple, list[tuple[tuple, Any]]]:
+        """The gradient's part of ``rect`` and the extension blocks ``(rect, color)``: each
+        block is half the thickness long, a fifth of the thickness apart from the bar."""
+        if self.cb.resolve("extend_shape") != "block":
+            return rect, []
+        x0, y0, x1, y1 = rect
+        b, gap = 0.5 * self.thickness, 0.2 * self.thickness
+        blocks = []
+        for at_start, c in self._ends():
+            if self.vertical:
+                if at_start:
+                    blocks.append(((x0, y1 - b, x1, y1), c))
+                    y1 -= b + gap
+                else:
+                    blocks.append(((x0, y0, x1, y0 + b), c))
+                    y0 += b + gap
+            else:
+                if at_start:
+                    blocks.append(((x0, y0, x0 + b, y1), c))
+                    x0 += b + gap
+                else:
+                    blocks.append(((x1 - b, y0, x1, y1), c))
+                    x1 -= b + gap
+        return (x0, y0, x1, y1), blocks
+
+    def _triangles(self, rect: tuple) -> list[tuple[tuple, Any]]:
+        """Extension triangles past the bar's ends (a dot is drawn as one on a bar):
+        ``(points, color)``."""
+        if self.extend == "neither":
+            return []
+        x0, y0, x1, y1 = rect
+        t = self.thickness
+        out = []
+        for at_start, c in self._ends():
+            if self.vertical:
+                pts = (((x0, y1), (x1, y1), ((x0 + x1) / 2, y1 + t)) if at_start else
+                       ((x0, y0), (x1, y0), ((x0 + x1) / 2, y0 - t)))
+            else:
+                pts = (((x0, y0), (x0, y1), (x0 - t, (y0 + y1) / 2)) if at_start else
+                       ((x1, y0), (x1, y1), (x1 + t, (y0 + y1) / 2)))
+            out.append((pts, c))
+        return out
+
+    def _place_bar(self, fonts: Any, rect: tuple[float, float, float, float]) -> Any:
+        """A bar's geometry with its rectangle (extension blocks included) at ``rect``."""
+        from .geometry import BarGeometry
+        r = current()
+        boxes = (r.boxes.get(id(self.cb)), r.boxes.get(id(self.axis))) if r is not None \
+            else (None, None)
+        outer = rect
+        rect, blocks = self._blocks(rect)
+        triangles = [] if blocks else self._triangles(rect)
+        x0, y0, x1, y1 = rect
+        length = (y1 - y0) if self.vertical else (x1 - x0)
+        st = self.state
+        if abs(st.length - length) > 0.01:
+            st.compute_ticks(fonts, length, not self.vertical)
+        axis = self.axis
+        side = self.tick_side
+        mapper = st.mapper(y1, y0) if self.vertical else st.mapper(x0, x1)
+        out, inside = st.tick_out(marks=True)
+        ml = axis.resolve("minor_tick_length")
+        base = {"right": x1, "left": x0, "bottom": y1, "top": y0}[side]
+        other = {"right": x0, "left": x1, "bottom": y0, "top": y1}[side]
+        sign = 1.0 if side in ("right", "bottom") else -1.0
+        marks = []
+        for t in st.ticks:
+            p = mapper(t.value)
+            o, i = (out, inside) if t.major else ((ml if out else 0.0), (ml if inside else 0.0))
+            ends = [(base - sign * i, base + sign * o)]
+            if axis.resolve("mirror") and i:
+                ends.append((other + sign * i, other))
+            for a, b in ends:
+                marks.append((a, p, b, p) if self.vertical else (p, a, p, b))
+        from .boxes import tick_label_extent, tick_label_runs
+        font = st.tick_font()
+        pad = axis.resolve("tick_pad")
+        pos = base + sign * (out + pad)
+        far = side in ("right", "top")
+        labels = tick_label_runs(st, fonts, mapper, pos, not self.vertical, far)
+        got = tick_label_extent(st, fonts, length, not self.vertical, far)
+        widest = got[0] if got is not None else 0.0
+        oc = st.offset_label                   # ×10ᵏ: as on the axes of plots
+        if oc is not None:
+            if self.vertical:
+                labels.append(run(fonts, oc, pos, y0 - pad, font,
+                                  "left" if sign > 0 else "right", "bottom"))
+            else:
+                labels.append(run(fonts, oc, x1, pos + sign * (widest + axis.resolve(
+                    "label_pad")), font, "right", "top" if sign > 0 else "bottom"))
+        title = None
+        if self._top_label():                  # above the bar (its ×10ᵏ, its triangle)
+            tri = self.thickness if triangles and any(not s for s, _ in self._ends()) \
+                else 0.0
+            above = max(tri, pad + box(fonts, oc, font)[1] if oc is not None else 0.0)
+            title = run(fonts, self.label, outer[0],
+                        outer[1] - above - self.cb.resolve("value_gap"), st.label_font(),
+                        "left", "bottom")
+        elif self.label is not None:
+            lf = st.label_font()
+            pos += sign * (widest + axis.resolve("label_pad"))
+            if self.vertical:
+                title = run(fonts, self.label, pos, (y0 + y1) / 2, lf, "center",
+                            "top" if sign > 0 else "bottom", 90.0)
+            elif self.cb.resolve("label_position") == "top":   # at its start
+                title = run(fonts, self.label, outer[0], pos, lf, "left",
+                            "top" if sign > 0 else "bottom")
+            else:
+                title = run(fonts, self.label, (x0 + x1) / 2, pos, lf, "center",
+                            "top" if sign > 0 else "bottom")
+        return BarGeometry(self, rect, tuple(blocks), tuple(triangles), tuple(marks),
+                           tuple(labels), title, boxes)
+
+    # -- drawing --------------------------------------------------------------------
+
+    def _gradient(self, x0: float, y0: float, x1: float, y1: float) -> Any:
+        """The axis' gradient along the bar ``(x0, y0, x1, y1)``."""
+        cmap = self.cmap
+        assert cmap is not None
+        stops = gradient_stops(cmap)
+        inv = self.axis.resolve("invert")
+        if self.vertical:
+            return LinearGradient(0, y0, 0, y1, stops) if inv else LinearGradient(0, y1, 0, y0, stops)
+        return LinearGradient(x1, 0, x0, 0, stops) if inv else LinearGradient(x0, 0, x1, 0, stops)
+
+    def draw(self, canvas: Canvas, g: Any) -> None:
+        """Draw the colorbar placed as ``g`` (see :meth:`place`)."""
+        r = current()
+        if r is not None:
+            for obj, b in zip((self.cb, self.axis), g.boxes):
+                if b is not None:
+                    r.boxes[id(obj)] = b
+        if self.key:
+            self._draw_key(canvas, g)
+            return
+        x0, y0, x1, y1 = g.rect
+        grad = self._gradient(x0, y0, x1, y1)
+        with canvas.state():
+            canvas.fill = grad
+            canvas.draw_rect(x0, y0, x1 - x0, y1 - y0, stroke=None)
+            for (bx0, by0, bx1, by1), c in g.blocks:
+                canvas.fill = c
+                canvas.draw_rect(bx0, by0, bx1 - bx0, by1 - by0, stroke=None)
+            for pts, c in g.triangles:
+                canvas.fill = c
+                path = Path().move_to(*pts[0])
+                for pt in pts[1:]:
+                    path.line_to(*pt)
+                canvas.draw_path(path.close(), stroke=None)
+            if self.cb.resolve("frame"):
+                canvas.stroke = resolve_color(self.cb.resolve("frame_color"), ())
+                canvas.stroke_width = self.cb.resolve("frame_width")
+                path = Path()
+                for bx0, by0, bx1, by1 in [g.rect] + [b for b, _ in g.blocks]:
+                    path.rect(bx0, by0, bx1 - bx0, by1 - by0)
+                canvas.draw_path(path, fill=None)
+        axis = self.axis
+        with canvas.state():
+            canvas.stroke = resolve_color(axis.resolve("tick_color"), ())
+            canvas.stroke_width = axis.resolve("tick_width")
+            path = Path()
+            for a, b, c, d in g.marks:
+                path.move_to(a, b).line_to(c, d)
+            canvas.draw_path(path, fill=None)
+        for lab in g.labels:
+            draw_run(canvas, lab)
+        draw_run(canvas, g.title)
+
+    def _draw_key(self, canvas: Canvas, g: Any) -> None:
+        """A key: the gradient clipped to the bar's rounded rectangle, the end shapes, the
+        frame along their outlines, the texts."""
+        if self.sizes:
+            path, fill, stroke, width = self.marker_look()
+            for cx, cy, d in g.marks:
+                canvas.draw_markers([cx], [cy], marker=path, size=d, fill=fill,
+                                    stroke=stroke, stroke_width=width)
+            for lab in g.values:
+                draw_run(canvas, lab)
+            draw_run(canvas, g.title)
+            return
+        x0, y0, x1, y1 = g.rect
+        w, h = x1 - x0, y1 - y0
+        radius = min(w, h) / 2
+        with canvas.state():
+            canvas.clip(Path().rect(x0, y0, w, h, rx=radius))
+            canvas.draw_rect(x0, y0, w, h, fill=self._gradient(x0, y0, x1, y1), stroke=None)
+        with canvas.state():
+            for shape, geo, c in g.ends:
+                canvas.fill = c
+                canvas.draw_path(_shape_path(Path(), shape, geo), stroke=None)
+            if self.cb.resolve("frame"):
+                canvas.stroke = resolve_color(self.cb.resolve("frame_color"), ())
+                canvas.stroke_width = self.cb.resolve("frame_width")
+                path = Path().rect(x0, y0, w, h, rx=radius)
+                for shape, geo, _ in g.ends:
+                    _shape_path(path, shape, geo)
+                canvas.draw_path(path, fill=None)
+        for lab in g.values:
+            draw_run(canvas, lab)
+        draw_run(canvas, g.title)
+
+
+def _round_limits(lo: float, hi: float, log: bool) -> tuple[float, float]:
+    """Limits rounded to two digits of their range (``log``: two significant digits
+    each)."""
+    def digits(v: float) -> float:
+        if not v or not math.isfinite(v):
+            return v
+        return round(v, max(0, 1 - math.floor(math.log10(abs(v)))))
+
+    span = abs(hi - lo)
+    if log or not span or not math.isfinite(span):
+        return digits(lo), digits(hi)
+    d = max(0, 1 - math.floor(math.log10(span)))
+    return round(lo, d), round(hi, d)
+
+
+def _shape_rect(shape: str, geo: Any) -> tuple[float, float, float, float]:
+    """The box of an end shape."""
+    if shape == "dot":
+        cx, cy, r = geo
+        return (cx - r, cy - r, cx + r, cy + r)
+    if shape == "block":
+        return geo
+    xs = [p[0] for p in geo[:3]]                 # a triangle: its corners (not the centre)
+    ys = [p[1] for p in geo[:3]]
+    return (min(xs), min(ys), max(xs), max(ys))
+
+
+def _shape_path(path: Path, shape: str, geo: Any) -> Path:
+    """``path`` with an end shape added."""
+    if shape == "dot":
+        return path.circle(*geo)
+    if shape == "block":
+        return path.rect(geo[0], geo[1], geo[2] - geo[0], geo[3] - geo[1])
+    return _round_triangle(path, *geo)
+
+
+def _round_triangle(path: Path, tip: tuple, a: tuple, b: tuple, c: tuple) -> Path:
+    """A key's end triangle: corners ``a``, ``b`` on a circle about ``c`` (the bar's rounded
+    end), its side between them along that circle (bulging toward ``tip``), every corner
+    rounded by ``_TRI_RADIUS`` × the triangle's height."""
+    r = _TRI_RADIUS * math.dist(a, b)
+    radius = math.dist(c, a)
+
+    def toward(p: tuple, q: tuple, length: float) -> tuple:
+        k = length / math.dist(p, q)
+        return (p[0] + (q[0] - p[0]) * k, p[1] + (q[1] - p[1]) * k)
+
+    def bend(path: Path, corner: tuple, end: tuple) -> None:
+        """From the current point round ``corner`` to ``end`` (a cubic near a circular arc)."""
+        point = path.current_point()
+        assert point is not None
+        x, y = point
+        k = 0.55
+        path.curve_to(x + (corner[0] - x) * k, y + (corner[1] - y) * k,
+                      end[0] + (corner[0] - end[0]) * k, end[1] + (corner[1] - end[1]) * k,
+                      end[0], end[1])
+
+    def angle(p: tuple) -> float:
+        return math.degrees(math.atan2(p[1] - c[1], p[0] - c[0]))
+
+    # the arc from a to b through the side facing the tip
+    t0, t1, mid = angle(a), angle(b), angle(tip)
+    sweep = (t1 - t0) % 360.0                    # clockwise on screen
+    clockwise = (mid - t0) % 360.0 < sweep
+    if not clockwise:
+        sweep -= 360.0
+    step = math.degrees(r / radius) * (1.0 if sweep > 0 else -1.0)
+    a_in, b_in = t0 + step, t0 + sweep - step     # where the corners' roundings meet the arc
+
+    def on(deg: float) -> tuple:
+        return (c[0] + radius * math.cos(math.radians(deg)),
+                c[1] + radius * math.sin(math.radians(deg)))
+
+    path.move_to(*toward(tip, a, r))
+    path.line_to(*toward(a, tip, r))
+    bend(path, a, on(a_in))
+    path.arc(c[0], c[1], radius, a_in, b_in, counterclockwise=sweep < 0)
+    bend(path, b, toward(b, tip, r))
+    path.line_to(*toward(tip, b, r))
+    bend(path, tip, toward(tip, a, r))
+    return path.close()