plot-io 0.1.0__py3-none-any.whl

plot_io/render.py

@@ -0,0 +1,1122 @@
+"""Layout and drawing of figures.
+
+Drawing a figure resolves every plot (scales, limits, map limits), measures the
+decorations of each area for its axes size, solves the grid (gutters for
+``align="axes"``, boxes for ``align="borders"``), repeats until the axes sizes settle,
+then draws.  All lengths here are points.
+"""
+
+import math
+from collections.abc import Sequence
+from typing import Any
+
+import pdf_io
+
+from . import _backend
+from .axis import AxisState
+from .limits import needs_quantiles, resolve_limits
+from .scales import get_scale
+from .series import DrawContext
+from .style import resolve_color
+from .text import Font, box, draw_text, measure, superscript
+
+__all__ = ["draw", "save", "to_bytes", "size", "Layout"]
+
+
+
+# ---------------------------------------------------------------------------
+# Arrangement
+# ---------------------------------------------------------------------------
+
+
+def _z(item: Any) -> float:
+    """Drawing order key: ``z``, unset (call order) counting as 0 (sorting is stable)."""
+    z = item.get("z")
+    return 0.0 if z is None else z
+
+class Area:
+    """A plot or colorbar placed on cells ``[r0, r1) × [c0, c1)``."""
+
+    def __init__(self, obj: Any, r0: int, c0: int, r1: int, c1: int) -> None:
+        self.obj = obj
+        self.r0, self.c0, self.r1, self.c1 = r0, c0, r1, c1
+        self.state: Any = None
+        self.margins = (0.0, 0.0, 0.0, 0.0)      # left, right, top, bottom
+        self.axes = (0.0, 0.0, 0.0, 0.0)         # x0, y0, x1, y1
+        self.box = (0.0, 0.0, 0.0, 0.0)
+
+    @property
+    def is_bar(self) -> bool:
+        """A colorbar or a size legend: an area of fixed thickness."""
+        from .colorbar import Colorbar
+        from .legend import SizeLegend
+        return isinstance(self.obj, (Colorbar, SizeLegend))
+
+
+def arrange(fig: Any, only: Any = None) -> tuple[list[Area], int, int]:
+    """The areas of the figure and the grid size."""
+    if only is not None:
+        return [Area(only, 0, 0, 1, 1)], 1, 1
+    items = list(fig._areas.items())
+    grid = fig.get("grid")
+    if grid is not None:
+        areas = []
+        for k, obj in items:
+            cells = [(i, j) for i, r in enumerate(grid) for j, v in enumerate(r) if v == k]
+            if not cells:
+                raise ValueError(f"id {k!r} is not in the grid")
+            r0 = min(c[0] for c in cells)
+            c0 = min(c[1] for c in cells)
+            areas.append(Area(obj, r0, c0, max(c[0] for c in cells) + 1,
+                              max(c[1] for c in cells) + 1))
+        return areas, len(grid), len(grid[0])
+    n = len(items)
+    rows, cols, order = fig.get("rows"), fig.get("cols"), fig.get("order")
+    if rows and cols:
+        nr, nc = rows, cols
+        by_row = order != "col"
+    elif cols:
+        nc = cols
+        nr = max(1, math.ceil(n / cols))
+        by_row = order != "col"
+    elif rows:
+        nr = rows
+        nc = max(1, math.ceil(n / rows))
+        by_row = order == "row"
+    else:
+        nc = max(1, math.ceil(math.sqrt(n)))
+        nr = max(1, math.ceil(n / nc))
+        by_row = order != "col"
+    areas = []
+    for i, (_, obj) in enumerate(items):
+        r, c = (i // nc, i % nc) if by_row else (i % nr, i // nr)
+        areas.append(Area(obj, r, c, r + 1, c + 1))
+    return areas, nr, nc
+
+
+# ---------------------------------------------------------------------------
+# Color and size map limits
+# ---------------------------------------------------------------------------
+
+def resolve_maps(series: Sequence[Any], extra: Sequence[Any] = ()) -> dict[int, tuple]:
+    """Limits of every color and size map used, after the map's scale function:
+    ``id(map) → (flo, fhi, data_lo, data_hi)``."""
+    users: dict[int, tuple[Any, list[Any]]] = {}
+    for s in series:
+        for m, values in list(s.color_sources()) + list(s.size_sources()):
+            users.setdefault(id(m), (m, []))[1].append(values)
+    for m in extra:
+        users.setdefault(id(m), (m, []))
+    out: dict[int, tuple] = {}
+    for key, (m, value_list) in users.items():
+        scale = get_scale(m.scale)
+        count, lo, hi = 0, math.inf, -math.inf
+        for v in value_list:
+            n, a, b = _backend.extent(v, scale.function)
+            if n:
+                count += n
+                lo, hi = min(lo, a), max(hi, b)
+        if not count:
+            lo, hi = (1.0, 10.0) if scale.name.startswith("log") else (0.0, 1.0)
+        qs = needs_quantiles(m.limits)
+        qmap: dict[float, float] = {}
+        if qs:
+            from array import array
+            allv = array("d")
+            for v in value_list:
+                allv.extend(_backend.doubles(v))
+            allv = array("d", [x for x in allv if scale.contains(x)])
+            qmap = dict(zip(qs, _backend.quantiles(allv, qs)))
+        a, b, _, _ = resolve_limits(m.limits, lo, hi, lambda q: qmap[q])
+        fa, fb = scale.f(a), scale.f(b)
+        if not (math.isfinite(fa) and math.isfinite(fb)):
+            raise ValueError(f"map limits {a!r}/{b!r} are outside the {scale.name} scale's domain")
+        if fa == fb:
+            fa, fb = fa - 0.5, fb + 0.5
+        out[key] = (fa, fb, lo, hi)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Plot state: resolution, measurement, drawing
+# ---------------------------------------------------------------------------
+
+def _label_content(state: AxisState) -> Any:
+    """The axis title: its label, or the label it takes from a data column."""
+    label = state.axis.get("label")
+    return state.auto_label if label is None else label
+
+
+def _offset_content(state: AxisState) -> Any:
+    """What is written at the end of the axis: the common ×10ᵏ factor of the tick labels,
+    or the common date part of a time axis; ``None`` when there is none."""
+    if state.offset:
+        return state.offset
+    if not state.factor:
+        return None
+    from .numbers import NumberStyle
+    style = NumberStyle.of(state.axis)
+    return ["\u00d710", superscript(style.exponent(state.factor))]
+
+
+class PlotState:
+    """A plot while its figure is drawn."""
+
+    def __init__(self, plot: Any, maps: dict[int, tuple], palette: Any = None) -> None:
+        self.plot = plot
+        self.maps = maps
+        self.x = AxisState(plot.x_axis)
+        self.y = AxisState(plot.y_axis)
+        series = list(plot.series)
+        self.series = sorted(series, key=_z)
+        from .palettes import palette_colors
+        twins = list(getattr(plot, "twins", []))
+        colored = series + [s for t in twins for s in t.series]   # palette continues
+        n_auto = sum(s.palette_count() for s in colored
+                     if s.USES_PALETTE and not s.has_own_color())
+        refs = [int(v[1:]) + 1 for s in colored for v in s.settings().values()
+                if isinstance(v, str) and v[:1] == "C" and v[1:].isdigit()]
+        if palette is None:
+            palette = palette_colors(plot.get("palette"), max([n_auto] + refs))
+        self.palette = palette
+        i = 0
+        for s in (colored if not getattr(plot, "twin_of", None) else []):
+            if s.USES_PALETTE and not s.has_own_color():
+                k = s.palette_count()
+                s._auto_colors = [palette[(i + j) % len(palette)] for j in range(k)]
+                s._auto_color = s._auto_colors[0]
+                i += k
+            else:
+                s._auto_color = None
+                s._auto_colors = None
+        kinds = {s.AXES for s in series}
+        if len(kinds) > 1:
+            raise ValueError(f"{plot!r} mixes series drawn without axes (pie) and with axes")
+        self.axes_on = plot.get("axes") and kinds != {False}
+        decos = list(plot.decorations)
+        self.decorations = decos
+        limit_items = series + [d for d in decos if d.get("extend_limits")]
+        self.limit_items, self.padded = limit_items, self.axes_on
+        for role, st in (("x", self.x), ("y", self.y)):
+            st.auto_label = next((t for t in (s.axis_title(role) for s in series)
+                                  if t is not None), None)
+        self.twins = [PlotState(t, maps, palette) for t in twins]
+        self.role_items = {"x": list(limit_items), "y": list(limit_items)}
+        for t in self.twins:                       # a twin shares the other axis
+            shared = "x" if t.plot.twin_of[1] == "y" else "y"
+            self.role_items[shared] += t.limit_items
+        self.x.resolve(self.role_items["x"], self.padded)
+        self.y.resolve(self.role_items["y"], self.padded)
+        for t in self.twins:
+            shared = "x" if t.plot.twin_of[1] == "y" else "y"
+            mine, theirs = getattr(self, shared), getattr(t, shared)
+            theirs.copy_limits(mine)
+            theirs.shared = mine
+        from .colorbar import BarState
+        from .legend import LegendState
+        self.bars = [BarState(cb, maps, plot) for cb in plot.colorbars]
+        self.legend = LegendState(self)
+        self.ticks_for: tuple[float, float] | None = None
+
+    # -- measurement ----------------------------------------------------------------
+
+    def measure(self, canvas: Any, w: float, h: float) -> tuple[float, float, float, float]:
+        """Margins (left, right, top, bottom) around axes ``w`` × ``h``."""
+        plot = self.plot
+        x, y = self.x, self.y
+        w, h = max(w, 1.0), max(h, 1.0)
+        x.compute_ticks(canvas, w, True)
+        y.compute_ticks(canvas, h, False)
+        self.ticks_for = (w, h)
+        left = right = top = bottom = 0.0
+        over_l = over_r = over_t = over_b = 0.0
+        y_offset = False            # a ×10ᵏ factor or date part above the y axis
+        xa, ya = plot.x_axis, plot.y_axis
+        if self.axes_on and xa.get("visible"):
+            out, _ = x.tick_out()
+            font = x.tick_font()
+            labels = [(t, t.label) for t in x.ticks if t.major and t.label is not None
+                      and not x.hide_labels]
+            xh = out + xa.get("spine_offset")
+            mirror = (out + xa.get("spine_offset")) if xa.get("mirror") and x.ticks else 0.0
+            if labels:
+                xh += xa.get("tick_pad") + max(box(canvas, lab, font, x.rotation)[1]
+                                               for _, lab in labels)
+                mapper = x.mapper(0.0, w)
+                for t, lab in labels:
+                    bw = box(canvas, lab, font, x.rotation)[0]
+                    p = mapper(t.value)
+                    if x.rotation:
+                        over_l = max(over_l, bw - p)
+                    else:
+                        over_l = max(over_l, bw / 2 - p)
+                        over_r = max(over_r, p + bw / 2 - w)
+            content = None if x.hide_labels else _label_content(x)
+            offset = None if x.hide_labels else _offset_content(x)
+            row = 0.0
+            if content is not None:
+                _, a, d = measure(canvas, content, x.label_font())
+                row = a + d
+            if offset is not None:
+                row = max(row, box(canvas, offset, font, 0.0)[1])
+            if row:
+                xh += xa.get("label_pad") + row
+            if x.on_far_side():
+                top, bottom = xh, mirror
+            else:
+                top, bottom = mirror, xh
+        if self.axes_on and ya.get("visible"):
+            out, _ = y.tick_out()
+            font = y.tick_font()
+            labels = [(t, t.label) for t in y.ticks if t.major and t.label is not None
+                      and not y.hide_labels]
+            yw = out + ya.get("spine_offset")
+            mirror = (out + ya.get("spine_offset")) if ya.get("mirror") and y.ticks else 0.0
+            if labels:
+                yw += ya.get("tick_pad") + max(box(canvas, lab, font, y.rotation)[0]
+                                               for _, lab in labels)
+                mapper = y.mapper(h, 0.0)
+                for t, lab in labels:
+                    bh = box(canvas, lab, font, y.rotation)[1]
+                    p = mapper(t.value)
+                    over_t = max(over_t, bh / 2 - p)
+                    over_b = max(over_b, p + bh / 2 - h)
+            content = None if y.hide_labels else _label_content(y)
+            if content is not None:
+                _, a, d = measure(canvas, content, y.label_font())
+                yw += ya.get("label_pad") + a + d
+            if y.on_far_side():
+                left, right = mirror, yw
+            else:
+                left, right = yw, mirror
+            offset = None if y.hide_labels else _offset_content(y)
+            if offset is not None:
+                ow, oh = box(canvas, offset, font, 0.0)
+                top += ya.get("tick_pad") + oh
+                y_offset = True
+                if y.on_far_side():
+                    over_r = max(over_r, ow - yw)
+                else:
+                    over_l = max(over_l, ow - yw)
+        self._twin_extent = [0.0, 0.0, 0.0, 0.0]
+        for tw in self.twins:
+            tl, tr, tt, tb = tw.measure(canvas, w, h)
+            if tw.plot.twin_of[1] == "y":
+                left, right = left + tl, right + tr
+                over_t, over_b = max(over_t, tt), max(over_b, tb)
+            else:
+                top, bottom = top + tt, bottom + tb
+                over_l, over_r = max(over_l, tl), max(over_r, tr)
+            for k, v in enumerate((tl, tr, tt, tb)):
+                self._twin_extent[k] += v
+        title = plot.title
+        text = title.get("text")
+        if text is not None:
+            _, a, d = measure(canvas, text, self.title_font())
+            stacked = x.on_far_side() or y_offset
+            top = (top if stacked else 0.0) + max(
+                title.get("pad") + a + d, 0.0 if stacked else top)
+        lw, lh = self.legend.measure(canvas)
+        pos = self.legend.position()
+        if lw and pos == "outside right":
+            right += plot.legend.get("pad") + lw
+        elif lh and pos == "outside top":
+            top += plot.legend.get("pad") + lh
+        elif lh and pos == "outside bottom":
+            bottom += plot.legend.get("pad") + lh
+        for bar in self.bars:
+            side = bar.position
+            extent = bar.measure_attached(canvas, w if side in ("top", "bottom") else h)
+            if side == "right":
+                right += extent
+            elif side == "left":
+                left += extent
+            elif side == "top":
+                top += extent
+            else:
+                bottom += extent
+        return (max(left, over_l), max(right, over_r), max(top, over_t), max(bottom, over_b))
+
+    def title_font(self) -> Font:
+        t = self.plot.title
+        return Font(t.get("font_size"), t.get("font_family"), t.get("font_weight"),
+                    color=t.get("color"))
+
+    def aspect_rect(self, rect: tuple[float, float, float, float]) -> tuple:
+        aspect = self.plot.get("aspect") or (None if self.axes_on else 1.0)
+        if not aspect:
+            return rect
+        x0, y0, x1, y1 = rect
+        w, h = x1 - x0, y1 - y0
+        dx = abs(self.x.fhi - self.x.flo) or 1.0
+        dy = abs(self.y.fhi - self.y.flo) or 1.0
+        want = aspect * dy / dx           # h / w
+        if h > w * want:
+            nh = w * want
+            y0 += (h - nh) / 2
+            y1 = y0 + nh
+        else:
+            nw = h / want
+            x0 += (w - nw) / 2
+            x1 = x0 + nw
+        return (x0, y0, x1, y1)
+
+    # -- drawing --------------------------------------------------------------------
+
+    def draw(self, canvas: Any, rect: tuple[float, float, float, float]) -> None:
+        plot = self.plot
+        x0, y0, x1, y1 = rect
+        w, h = x1 - x0, y1 - y0
+        if self.ticks_for is None or abs(self.ticks_for[0] - w) > 0.01 \
+                or abs(self.ticks_for[1] - h) > 0.01:
+            self.x.compute_ticks(canvas, w, True)
+            self.y.compute_ticks(canvas, h, False)
+        palette = self.palette
+        ctx = DrawContext(canvas, plot, rect, self.x, self.y, self.maps, palette)
+        ctx.figure_size = getattr(self, "figure_size", (x1, y1))
+        bg = plot.get("background")
+        if bg is not None:
+            canvas.save()
+            canvas.fill_style = resolve_color(bg, palette)
+            canvas.fill_rect(x0, y0, w, h)
+            canvas.restore()
+        if self.axes_on:
+            self._grid(canvas, ctx)
+        items = sorted(list(self.series) + self.decorations, key=_z)
+        clipped = None
+        try:
+            for s in items:
+                want = bool(plot.get("clip")) and (s.get("clip") if "clip" in s.SETTINGS
+                                                   else True)
+                if want != clipped:
+                    if clipped is not None:
+                        canvas.restore()
+                    canvas.save()
+                    if want:
+                        canvas.begin_path()
+                        canvas.rect(x0, y0, w, h)
+                        canvas.clip()
+                        canvas.begin_path()
+                    clipped = want
+                r = s.get("rasterize") if "rasterize" in s.SETTINGS else None
+                if r:
+                    dpi = None if r is True else float(r)
+                    with canvas.group(rasterize=True, dpi=dpi):
+                        s.draw(ctx)
+                else:
+                    s.draw(ctx)
+        finally:
+            if clipped is not None:
+                canvas.restore()
+        tctxs = []
+        for t in self.twins:
+            if t.ticks_for is None or abs(t.ticks_for[0] - w) > 0.01 \
+                    or abs(t.ticks_for[1] - h) > 0.01:
+                t.x.compute_ticks(canvas, w, True)
+                t.y.compute_ticks(canvas, h, False)
+            tctx = DrawContext(canvas, t.plot, rect, t.x, t.y, self.maps, palette)
+            tctx.figure_size = ctx.figure_size
+            tctxs.append((t, tctx))
+            t._grid(canvas, tctx)
+            canvas.save()
+            if plot.get("clip"):
+                canvas.begin_path()
+                canvas.rect(x0, y0, w, h)
+                canvas.clip()
+                canvas.begin_path()
+            for s in sorted(t.series, key=_z):
+                s.draw(tctx)
+            canvas.restore()
+        for s in self.series:
+            s.draw_overlay(ctx)
+        border = plot.get("border")
+        if border is not None and plot.get("border_width"):
+            canvas.save()
+            canvas.stroke_style = resolve_color(border, palette)
+            canvas.line_width = plot.get("border_width")
+            canvas.begin_path()
+            canvas.rect(x0, y0, w, h)
+            canvas.stroke()
+            canvas.restore()
+        if self.axes_on:
+            self._spines(canvas, rect)
+            self._axis_x(canvas, ctx)
+            self._axis_y(canvas, ctx)
+        for t, tctx in tctxs:
+            t._spines(canvas, rect)
+            t._axis_x(canvas, tctx)
+            t._axis_y(canvas, tctx)
+            if t.legend.active():
+                t.legend.draw(canvas, tctx)
+        if self.twins:                      # attached items start beyond the twin axes
+            self._left_used += self._twin_extent[0]
+            self._right_used += self._twin_extent[1]
+            self._top_used += self._twin_extent[2]
+            self._bottom_used += self._twin_extent[3]
+        self._top_bars = sum(b.measure_attached(canvas, w) for b in self.bars
+                             if b.position == "top")
+        self._title(canvas, rect)
+        self.legend.draw(canvas, ctx)
+        offsets = {"left": 0.0, "right": 0.0, "top": 0.0, "bottom": 0.0}
+        for bar in self.bars:
+            offsets[bar.position] += bar.draw_attached(canvas, rect, offsets[bar.position],
+                                                       self.attached_base(bar.position))
+
+    def attached_base(self, side: str) -> float:
+        """Distance from the axes to where attached colorbars start on ``side``."""
+        if side == "right" and self.legend.outside() == "outside right":
+            return self._right_used + self.plot.legend.get("pad") + self.legend.size[0]
+        if side == "right":
+            return self._right_used
+        if side == "top" and self._top_used:
+            return self._top_used
+        if side == "bottom" and self.legend.outside() == "outside bottom":
+            return self._bottom_used + self.plot.legend.get("pad") + self.legend.size[1]
+        if side == "bottom":
+            return self._bottom_used
+        if side == "left":
+            return self._left_used
+        if side == "top" and self.legend.outside() == "outside top":
+            return self.plot.legend.get("pad") + self.legend.size[1]
+        return 0.0
+
+    _bottom_used = 0.0
+    _left_used = 0.0
+    _top_used = 0.0
+    _right_used = 0.0
+    _top_bars = 0.0
+
+    def _grid(self, canvas: Any, ctx: DrawContext) -> None:
+        for state, horizontal in ((self.x, False), (self.y, True)):
+            axis = state.axis
+            if axis.get("minor_grid"):
+                self._grid_lines(canvas, ctx, state.minor_grid_positions(), horizontal,
+                                 axis.get("minor_grid_color"), axis.get("minor_grid_width"),
+                                 axis.get("minor_grid_style"))
+            if axis.get("grid"):
+                self._grid_lines(canvas, ctx, [t.value for t in state.ticks if t.major],
+                                 horizontal, axis.get("grid_color"), axis.get("grid_width"),
+                                 axis.get("grid_style"))
+        for state, horizontal in ((self.x, False), (self.y, True)):
+            axis = state.axis
+            if (axis.get("zero_line") and state.scale is not None
+                    and min(state.lo, state.hi) <= 0.0 <= max(state.lo, state.hi)
+                    and math.isfinite(state.f(0.0))):
+                self._grid_lines(canvas, ctx, [0.0], horizontal, axis.get("zero_line_color"),
+                                 axis.get("zero_line_width"), "solid")
+
+    def _grid_lines(self, canvas: Any, ctx: DrawContext, values: list[float],
+                    horizontal: bool, color: Any, width: float, style: Any) -> None:
+        from .style import dash_of
+        x0, y0, x1, y1 = ctx.rect
+        canvas.save()
+        canvas.stroke_style = resolve_color(color, ctx.palette)
+        canvas.line_width = width
+        canvas.line_dash = dash_of(style, width)
+        canvas.begin_path()
+        mapper = ctx.ymap if horizontal else ctx.xmap
+        for v in values:
+            p = mapper(v)
+            if horizontal:
+                canvas.move_to(x0, p)
+                canvas.line_to(x1, p)
+            else:
+                canvas.move_to(p, y0)
+                canvas.line_to(p, y1)
+        canvas.stroke()
+        canvas.restore()
+
+    def _spines(self, canvas: Any, rect: tuple[float, float, float, float]) -> None:
+        x0, y0, x1, y1 = rect
+        spines = set(self.plot.get("spines"))
+        swap = {"left": "right", "right": "left", "top": "bottom", "bottom": "top"}
+        if self.x.on_far_side():
+            spines = {swap[s] if s in ("top", "bottom") else s for s in spines}
+        if self.y.on_far_side():
+            spines = {swap[s] if s in ("left", "right") else s for s in spines}
+        if not self.plot.is_set("spines"):
+            if self.x.bare:
+                spines -= {"bottom", "top"}
+            if self.y.bare:
+                spines -= {"left", "right"}
+        xa, ya = self.plot.x_axis, self.plot.y_axis
+        ox, oy = xa.get("spine_offset"), ya.get("spine_offset")
+        xs0, xs1 = self._trim(self.x, xa, x0, x1, True)
+        ys0, ys1 = self._trim(self.y, ya, y0, y1, False)
+        lines = {"left": (ya, x0 - oy, ys0, x0 - oy, ys1),
+                 "right": (ya, x1 + oy, ys0, x1 + oy, ys1),
+                 "bottom": (xa, xs0, y1 + ox, xs1, y1 + ox),
+                 "top": (xa, xs0, y0 - ox, xs1, y0 - ox)}
+        canvas.save()
+        canvas.line_cap = "square"
+        for side in ("left", "right", "bottom", "top"):
+            if side not in spines:
+                continue
+            axis, a, b, c, d = lines[side]
+            lw = axis.get("line_width")
+            if not lw:
+                continue
+            canvas.stroke_style = resolve_color(axis.get("line_color"), self.palette)
+            canvas.line_width = lw
+            canvas.begin_path()
+            canvas.move_to(a, b)
+            canvas.line_to(c, d)
+            canvas.stroke()
+        canvas.restore()
+
+    def _trim(self, state: AxisState, axis: Any, p0: float, p1: float,
+              horizontal: bool) -> tuple[float, float]:
+        """Extent of an axis line: the axes side, or (``spine_trim``) first to last major
+        tick."""
+        if not axis.get("spine_trim"):
+            return p0, p1
+        majors = [t.value for t in state.ticks if t.major]
+        if not majors:
+            return p0, p1
+        m = state.mapper(p0, p1) if horizontal else state.mapper(p1, p0)
+        ps = [m(v) for v in majors]
+        return min(ps), max(ps)
+
+    def _ticks(self, canvas: Any, state: AxisState, mapper: Any, horizontal: bool,
+               base: float, flip: bool = False) -> None:
+        """Tick marks; ``base`` is the axis line coordinate (y for x axes, x for y axes);
+        ``flip``: on the opposite side of the axes (``mirror``)."""
+        axis = state.axis
+        out, inside = state.tick_out()
+        if not state.ticks or not (out or inside):
+            return
+        if flip:
+            out, inside = -out, -inside
+        canvas.save()
+        canvas.stroke_style = resolve_color(axis.get("tick_color"), self.palette)
+        canvas.line_width = axis.get("tick_width")
+        ml = axis.get("minor_tick_length") * (-1.0 if flip else 1.0)
+        m_out, m_in = (ml if out else 0.0), (ml if inside else 0.0)
+        canvas.begin_path()
+        for t in state.ticks:
+            p = mapper(t.value)
+            o, i = (out, inside) if t.major else (m_out, m_in)
+            if horizontal:
+                canvas.move_to(p, base - i)
+                canvas.line_to(p, base + o)
+            else:
+                canvas.move_to(base + i, p)
+                canvas.line_to(base - o, p)
+        canvas.stroke()
+        canvas.restore()
+
+    def _axis_x(self, canvas: Any, ctx: DrawContext) -> None:
+        axis = self.plot.x_axis
+        x0, y0, x1, y1 = ctx.rect
+        self._bottom_used = self._top_used = 0.0
+        if not axis.get("visible"):
+            return
+        state = self.x
+        top = state.on_far_side()
+        sign = -1.0 if top else 1.0                 # away from the axes
+        off = axis.get("spine_offset")
+        edge, other = (y0, y1) if top else (y1, y0)
+        base = edge + sign * off
+        self._ticks(canvas, state, ctx.xmap, True, base, flip=top)
+        if axis.get("mirror"):
+            self._ticks(canvas, state, ctx.xmap, True, other - sign * off, flip=not top)
+        out, _ = state.tick_out()
+        y = base + sign * out
+        va = "bottom" if top else "top"
+        font = state.tick_font()
+        labels = [t for t in state.ticks if t.major and t.label is not None
+                  and not state.hide_labels]
+        if labels:
+            y += sign * axis.get("tick_pad")
+            rows = 0.0
+            for t in labels:
+                p = ctx.xmap(t.value)
+                if state.rotation:
+                    draw_text(canvas, t.label, p, y, font, "left" if top else "right", va,
+                              state.rotation)
+                else:
+                    draw_text(canvas, t.label, p, y, font, "center", va)
+                rows = max(rows, box(canvas, t.label, font, state.rotation)[1])
+            y += sign * rows
+        content = None if state.hide_labels else _label_content(state)
+        offset = None if state.hide_labels else _offset_content(state)
+        if content is not None or offset is not None:
+            y += sign * axis.get("label_pad")
+            row = 0.0
+            if content is not None:
+                lf = state.label_font()
+                draw_text(canvas, content, (x0 + x1) / 2, y, lf, "center", va)
+                _, a, d = measure(canvas, content, lf)
+                row = a + d
+            if offset is not None:
+                draw_text(canvas, offset, x1, y, font, "right", va)
+                row = max(row, box(canvas, offset, font, 0.0)[1])
+            y += sign * row
+        if top:
+            self._top_used = y0 - y
+        else:
+            self._bottom_used = y - y1
+
+    def _axis_y(self, canvas: Any, ctx: DrawContext) -> None:
+        axis = self.plot.y_axis
+        x0, y0, x1, y1 = ctx.rect
+        self._left_used = self._right_used = 0.0
+        if not axis.get("visible"):
+            return
+        state = self.y
+        right = state.on_far_side()
+        sign = 1.0 if right else -1.0               # away from the axes
+        off = axis.get("spine_offset")
+        edge, other = (x1, x0) if right else (x0, x1)
+        base = edge + sign * off
+        self._ticks(canvas, state, ctx.ymap, False, base, flip=right)
+        if axis.get("mirror"):
+            self._ticks(canvas, state, ctx.ymap, False, other - sign * off, flip=not right)
+        out, _ = state.tick_out()
+        x = base + sign * out
+        font = state.tick_font()
+        labels = [t for t in state.ticks if t.major and t.label is not None
+                  and not state.hide_labels]
+        if labels:
+            x += sign * axis.get("tick_pad")
+            widest = 0.0
+            for t in labels:
+                p = ctx.ymap(t.value)
+                draw_text(canvas, t.label, x, p, font, "left" if right else "right", "center",
+                          state.rotation)
+                widest = max(widest, box(canvas, t.label, font, state.rotation)[0])
+            x += sign * widest
+        content = None if state.hide_labels else _label_content(state)
+        if content is not None:
+            x += sign * axis.get("label_pad")
+            lf = state.label_font()
+            draw_text(canvas, content, x, (y0 + y1) / 2, lf, "center",
+                      "top" if right else "bottom", 90.0)
+            _, a, d = measure(canvas, content, lf)
+            x += sign * (a + d)
+        if right:
+            self._right_used = x - x1
+        else:
+            self._left_used = x0 - x
+        offset = None if state.hide_labels else _offset_content(state)
+        if offset is not None:
+            above = self._top_used or (self.x.tick_out()[0] if self.plot.x_axis.get("mirror")
+                                       else 0.0)
+            yb = y0 - above - axis.get("tick_pad")
+            draw_text(canvas, offset, base, yb, font, "right" if right else "left", "bottom")
+            self._top_used = above + axis.get("tick_pad") + box(canvas, offset, font, 0.0)[1]
+
+    def _title(self, canvas: Any, rect: tuple[float, float, float, float]) -> None:
+        t = self.plot.title
+        text = t.get("text")
+        if text is None:
+            return
+        x0, y0, x1, _ = rect
+        y = y0 - t.get("pad") - self._top_bars - self._top_used
+        if self.legend.outside() == "outside top":
+            y -= self.plot.legend.get("pad") + self.legend.size[1]
+        if t.get("over") == "plot":
+            x0 -= self._left_used
+        align = t.get("align")
+        x = {"center": (x0 + x1) / 2, "left": x0, "right": x1}[align]
+        ha = {"center": "center", "left": "left", "right": "right"}[align]
+        draw_text(canvas, text, x, y, self.title_font(), ha, "bottom")
+
+
+# ---------------------------------------------------------------------------
+# Layout
+# ---------------------------------------------------------------------------
+
+class Layout:
+    """Solved geometry: figure size and the rectangles of every area (points)."""
+
+    def __init__(self, areas: list[Area], width: float, height: float) -> None:
+        self.areas = areas
+        self.width = width
+        self.height = height
+        self.title: tuple[float, float, float] | None = None    # x, y (top), width
+        self.rule: tuple[float, float, float, float] | None = None   # x, y, width, height
+
+
+def _split(n: int, ratios: list[float] | None, what: str) -> list[float]:
+    if ratios is None:
+        return [1.0] * n
+    if len(ratios) != n:
+        raise ValueError(f"{what} has {len(ratios)} values for {n} {'columns' if what == 'widths' else 'rows'}")
+    return list(ratios)
+
+
+def _solve_axis(areas: list[Area], n: int, ratios: list[float], fixed_total: float | None,
+                cell: float, spacing: float, margin: float, align: str, horizontal: bool,
+                fixed_cells: dict[int, float]) -> tuple[list[float], list[float], float]:
+    """Positions and sizes of the cells along one direction, and the total length.
+    ``fixed_cells``: cells whose size is given (colorbar-only columns)."""
+    if horizontal:
+        def span(a): return a.c0, a.c1
+        def need(a): return a.margins[0], a.margins[1]
+    else:
+        def span(a): return a.r0, a.r1
+        def need(a): return a.margins[2], a.margins[3]
+    free = [i for i in range(n) if i not in fixed_cells]
+    rsum = sum(ratios[i] for i in free) or 1.0
+    if align == "axes":
+        lo_need = [0.0] * (n + 1)
+        hi_need = [0.0] * (n + 1)
+        for a in areas:
+            s0, s1 = span(a)
+            m0, m1 = need(a)
+            lo_need[s0] = max(lo_need[s0], m0)
+            hi_need[s1] = max(hi_need[s1], m1)
+        gut = [hi_need[i] + lo_need[i] + (margin if i in (0, n) else spacing)
+               for i in range(n + 1)]
+        if fixed_total is not None:
+            avail = fixed_total - sum(gut) - sum(fixed_cells.values())
+            sizes = [fixed_cells[i] if i in fixed_cells else max(1.0, avail * ratios[i] / rsum)
+                     for i in range(n)]
+        else:
+            sizes = [fixed_cells.get(i, cell * ratios[i]) for i in range(n)]
+        pos = []
+        p = gut[0]
+        for i in range(n):
+            pos.append(p)
+            p += sizes[i] + gut[i + 1]
+        return pos, sizes, p
+    if fixed_total is not None:
+        avail = fixed_total - 2 * margin - spacing * (n - 1) - sum(fixed_cells.values())
+        sizes = [fixed_cells[i] if i in fixed_cells else max(1.0, avail * ratios[i] / rsum)
+                 for i in range(n)]
+    else:
+        sizes = [fixed_cells.get(i, cell * ratios[i]) for i in range(n)]
+    pos = []
+    p = margin
+    for i in range(n):
+        pos.append(p)
+        p += sizes[i] + (spacing if i < n - 1 else 0.0)
+    return pos, sizes, p + margin
+
+
+def _bar_cells(areas: list[Area], n: int, horizontal: bool, align: str) -> dict[int, float]:
+    """Cells covered only by colorbars running across this direction: their size is the
+    bar's (``axes``) or the bar's box (``borders``)."""
+    out: dict[int, float] = {}
+    for i in range(n):
+        covering = [a for a in areas
+                    if (a.c0 <= i < a.c1 if horizontal else a.r0 <= i < a.r1)]
+        if not covering or not all(a.is_bar for a in covering):
+            continue
+        sizes = []
+        for a in covering:
+            bar = a.state
+            if bar.vertical != horizontal:
+                break
+            t = bar.thickness
+            if align == "borders":
+                m = a.margins
+                t += (m[0] + m[1]) if horizontal else (m[2] + m[3])
+            sizes.append(t)
+        else:
+            out[i] = max(sizes)
+    return out
+
+
+def solve(fig: Any, areas: list[Area], nr: int, nc: int, canvas: Any,
+          fixed: tuple[float, float] | None = None, height: float | None = None) -> Layout:
+    """Measure and place every area (iterating until the axes sizes settle)."""
+    k = fig.points_per_unit
+    align = fig.get("align")
+    spacing = fig.get("spacing") * k
+    margin = fig.get("margin") * k
+    if fixed is not None:
+        cw, ch = fixed
+        fw = fh = None
+    else:
+        fw = fig.get("width") * k if fig.is_set("width") else None
+        fh = fig.get("height") * k if fig.is_set("height") else None
+        if height is not None:
+            fh = height
+        cw = fig.get("plot_width") * k
+        ch = fig.get("plot_height") * k
+    wr = _split(nc, fig.get("widths") if fixed is None else None, "widths")
+    hr = _split(nr, fig.get("heights") if fixed is None else None, "heights")
+    sizes = {id(a): (cw, ch) for a in areas}
+    xs: list[float] = []
+    ys: list[float] = []
+    W = H = 0.0
+    for it in range(5):
+        for a in areas:
+            aw, ah = sizes[id(a)]
+            a.margins = a.state.measure(canvas, aw, ah)
+        xb = {} if (fig.is_set("widths") and fixed is None) else _bar_cells(areas, nc, True, align)
+        yb = {} if (fig.is_set("heights") and fixed is None) else _bar_cells(areas, nr, False, align)
+        xs, xw, W = _solve_axis(areas, nc, wr, fw, cw, spacing, margin, align, True, xb)
+        ys, yh, H = _solve_axis(areas, nr, hr, fh, ch, spacing, margin, align, False, yb)
+        changed = False
+        for a in areas:
+            x0 = xs[a.c0]
+            x1 = xs[a.c1 - 1] + xw[a.c1 - 1]
+            y0 = ys[a.r0]
+            y1 = ys[a.r1 - 1] + yh[a.r1 - 1]
+            l, r, t, b = a.margins
+            if align == "axes":
+                a.axes = (x0, y0, x1, y1)
+                a.box = (x0 - l, y0 - t, x1 + r, y1 + b)
+            else:
+                a.box = (x0, y0, x1, y1)
+                a.axes = (x0 + l, y0 + t, max(x0 + l + 1, x1 - r), max(y0 + t + 1, y1 - b))
+            if a.is_bar:
+                a.axes = a.state.bar_rect(a.axes)
+            new = (a.axes[2] - a.axes[0], a.axes[3] - a.axes[1])
+            old = sizes[id(a)]
+            if abs(new[0] - old[0]) > 0.25 or abs(new[1] - old[1]) > 0.25:
+                changed = True
+            sizes[id(a)] = new
+        if not changed:
+            break
+    for a in areas:
+        if not a.is_bar:
+            a.axes = a.state.aspect_rect(a.axes)
+    return Layout(areas, W, H)
+
+
+def _states(fig: Any, areas: list[Area]) -> None:
+    from .colorbar import BarState
+    from .plot import Plot
+
+    from .legend import SizeLegend, SizeLegendState
+    plots = [a.obj for a in areas if isinstance(a.obj, Plot)]
+    series = [s for p in plots for s in p.series]
+    extra = []
+    bars = [a.obj for a in areas if not isinstance(a.obj, (Plot, SizeLegend))]
+    for p in plots:
+        bars.extend(p.colorbars)
+    for cb in bars:
+        m = cb.color_map()
+        if m is not None:
+            extra.append(m)
+    maps = resolve_maps(series, extra)
+    for a in areas:
+        if isinstance(a.obj, Plot):
+            a.state = PlotState(a.obj, maps)
+        elif isinstance(a.obj, SizeLegend):
+            a.state = SizeLegendState(a.obj, maps)
+        else:
+            a.state = BarState(a.obj, maps, None)
+    from .sharing import apply
+    apply(fig, areas)
+
+
+def _title_layout(fig: Any, canvas: Any, width: float) -> Any:
+    t = fig.title
+    font = Font(t.get("font_size"), t.get("font_family"), t.get("font_weight"),
+                color=t.get("color"))
+    font.apply(canvas)
+    align = {"center": "center", "left": "start", "right": "end"}[t.get("align")]
+    return canvas.layout_text(t.get("text"), max(width, 1.0), align=align)
+
+
+def _title_box(fig: Any, lay: Layout) -> tuple[float, float]:
+    """Left edge and width the figure title is aligned within."""
+    from .plot import Plot
+    margin = fig.get("margin") * fig.points_per_unit
+    plots = [a for a in lay.areas if isinstance(a.obj, Plot)]
+    if fig.title.get("over") == "axes" and plots:
+        x0 = min(a.axes[0] for a in plots)
+        x1 = max(a.axes[2] for a in plots)
+        return x0, x1 - x0
+    return margin, lay.width - 2 * margin
+
+
+def _with_title(fig: Any, lay: Layout, areas: list[Area], nr: int, nc: int,
+                canvas: Any) -> Layout:
+    """The layout with the figure title's band at the top."""
+    if fig.title.get("text") is None:
+        return lay
+    x0, width = _title_box(fig, lay)
+    band = _title_layout(fig, canvas, width).height + fig.title.get("pad")
+    rule = 0.0
+    if fig.get("title_rule") is not None and fig.get("title_rule_width"):
+        rule = fig.get("title_rule_width") + 0.5 * fig.title.get("font_size")
+        band += rule
+    fixed = fig.is_set("height")
+    if fixed:
+        lay = solve(fig, areas, nr, nc, canvas, height=lay.height - band)
+        x0, width = _title_box(fig, lay)
+    for a in lay.areas:
+        a.axes = (a.axes[0], a.axes[1] + band, a.axes[2], a.axes[3] + band)
+        a.box = (a.box[0], a.box[1] + band, a.box[2], a.box[3] + band)
+    lay.height += band
+    top = fig.get("margin") * fig.points_per_unit
+    lay.title = (x0, top + rule, width)
+    if rule:
+        lay.rule = (x0, top, width, fig.get("title_rule_width"))
+    return lay
+
+
+def _context(a: Area) -> Any:
+    """A drawing context for area ``a`` once placed (no canvas: for layout decisions)."""
+    from .series import DrawContext
+    st = a.state
+    return DrawContext(None, a.obj, a.axes, st.x, st.y, st.maps, st.palette)
+
+
+def _refine(fig: Any, areas: list[Area], nr: int, nc: int, canvas: Any,
+            lay: Layout) -> Layout:
+    """Decisions that need the placed axes: hexagon lattices in page units (which change the
+    counts, hence the color maps), then legend positions for ``"auto"`` (which may move a
+    legend outside, changing the margins)."""
+    from .plot import Plot
+    for _ in range(3):
+        changed = False
+        for a in areas:
+            if isinstance(a.obj, Plot):
+                ctx = _context(a)
+                for s in a.obj.series:
+                    frame = getattr(s, "set_frame", None)
+                    if frame is not None and frame(ctx):
+                        changed = True
+        if not changed:
+            break
+        _states(fig, areas)
+        lay = solve(fig, areas, nr, nc, canvas)
+    moved = False
+    for a in areas:
+        if isinstance(a.obj, Plot):
+            leg = a.state.legend
+            if leg.active() and a.obj.legend.get("position") == "auto":
+                leg.choice = leg.choose(_context(a))
+                moved = moved or leg.choice.startswith("outside")
+    if moved:
+        lay = solve(fig, areas, nr, nc, canvas)
+    return lay
+
+
+def layout(fig: Any, canvas: Any, only: Any = None) -> Layout:
+    areas, nr, nc = arrange(fig, None)
+    _states(fig, areas)
+    lay = solve(fig, areas, nr, nc, canvas)
+    lay = _refine(fig, areas, nr, nc, canvas, lay)
+    if only is None:
+        return _with_title(fig, lay, areas, nr, nc, canvas)
+    target = next(a for a in areas if a.obj is only)
+    if fig.get("align") == "axes":
+        rect = target.axes
+    else:
+        rect = target.box
+    single = [Area(only, 0, 0, 1, 1)]
+    single[0].state = target.state
+    target.state.x.hide_labels = target.state.y.hide_labels = False   # alone: outer
+    return solve(fig, single, 1, 1, canvas, fixed=(rect[2] - rect[0], rect[3] - rect[1]))
+
+
+# ---------------------------------------------------------------------------
+# Output
+# ---------------------------------------------------------------------------
+
+def _draw_layout(fig: Any, lay: Layout, canvas: Any) -> None:
+    bg = fig.get("background")
+    if bg is not None:
+        canvas.save()
+        from .palettes import palette_colors
+        canvas.fill_style = resolve_color(bg, palette_colors(fig.get("palette")))
+        canvas.fill_rect(0, 0, lay.width, lay.height)
+        canvas.restore()
+    for a in lay.areas:
+        a.state.figure_size = (lay.width, lay.height)
+        if a.is_bar:
+            a.state.draw_area(canvas, a.axes)
+        else:
+            a.state.draw(canvas, a.axes)
+    if lay.rule is not None:
+        rx, ry, rw, rh = lay.rule
+        canvas.save()
+        canvas.fill_style = resolve_color(fig.get("title_rule"), ())
+        canvas.fill_rect(rx, ry, rw, rh)
+        canvas.restore()
+    if lay.title is not None:
+        x, y, width = lay.title
+        canvas.save()
+        _title_layout(fig, canvas, width).draw(x, y)
+        canvas.restore()
+
+
+def draw(fig: Any, canvas: Any, x: float = 0.0, y: float = 0.0,
+         only: Any = None) -> tuple[float, float]:
+    """Draw on a pdf_io canvas at ``(x, y)`` (page units); returns the size in points."""
+    canvas.save()
+    try:
+        scale = 1.0 / canvas.unit_scale
+        canvas.translate(x, y)
+        if scale != 1.0:
+            canvas.scale(scale)
+        lay = layout(fig, canvas, only)
+        _draw_layout(fig, lay, canvas)
+    finally:
+        canvas.restore()
+    return lay.width, lay.height
+
+
+_DOC_KEYS = ("title", "author", "subject", "keywords", "creator", "compress", "compression",
+             "font_dirs", "system_fonts", "base_dir", "color_mode", "ink_limit",
+             "icc_profile", "pdf_a", "creation_date", "simplify")
+
+
+def _render(fig: Any, only: Any, options: dict[str, Any],
+            pdf: bool) -> tuple[Any, Any, dict[str, Any]]:
+    # quality: of rasterized content in a PDF, of the image otherwise
+    keys = _DOC_KEYS + ("quality",) if pdf else _DOC_KEYS
+    doc_opts = {k: v for k, v in options.items() if k in keys}
+    if pdf and "quality" not in doc_opts and fig.get("quality") is not None:
+        doc_opts["quality"] = fig.get("quality")
+    rest = {k: v for k, v in options.items() if k not in keys}
+    unknown = set(rest) - {"dpi", "background", "quality"}
+    if unknown:
+        raise ValueError(f"unknown output option {sorted(unknown)[0]!r}")
+    doc = pdf_io.Document(**doc_opts)
+    scratch = pdf_io.Document(font_db=doc.font_db, pdf_a=doc_opts.get("pdf_a"))
+    probe = scratch.add_page(100, 100)
+    lay = layout(fig, probe, only)
+    page = doc.add_page(max(lay.width, 1.0), max(lay.height, 1.0), unit="pt")
+    _draw_layout(fig, lay, page)
+    return doc, page, rest
+
+
+def size(fig: Any, only: Any = None) -> tuple[float, float]:
+    probe = pdf_io.Document().add_page(100, 100)
+    lay = layout(fig, probe, only)
+    return lay.width, lay.height
+
+
+def to_bytes(fig: Any, format: str = "pdf", only: Any = None, **options: Any) -> bytes:
+    fmt = format.lower().lstrip(".")
+    if fmt == "pdf":
+        doc, page, rest = _render(fig, only, options, True)
+    else:
+        # An image: nothing is culled (see _backend.simplify_arg), so the page is not
+        # given the document-level simplify either.
+        with _backend.image_output():
+            doc, page, rest = _render(fig, only, {k: v for k, v in options.items()
+                                                  if k != "simplify"}, False)
+    dpi = rest.get("dpi", fig.get("dpi"))
+    bg = fig.get("background")
+    bg = rest.get("background", fig.get("image_background") if bg is None else bg)
+    if fmt == "pdf":
+        if set(rest) - {"background"}:
+            raise ValueError("dpi applies to PNG, JPEG and JPEG XL output")
+        return doc.to_bytes()
+    if fmt == "png":
+        return page.to_png(dpi=dpi, background=bg)
+    quality = rest.get("quality", fig.get("quality"))
+    q = {} if quality is None else {"quality": quality}
+    if fmt in ("jpg", "jpeg"):
+        return page.to_jpeg(dpi=dpi, background=bg, **q)
+    if fmt == "jxl":
+        return page.to_jxl(dpi=dpi, background=bg, **q)
+    raise ValueError(f"unknown format {format!r} (use pdf, png, jpeg or jxl)")
+
+
+def save(fig: Any, path: Any, only: Any = None, **options: Any) -> None:
+    import os
+    ext = os.path.splitext(os.fspath(path))[1].lower().lstrip(".") or "pdf"
+    data = to_bytes(fig, ext, only, **options)
+    with open(path, "wb") as f:
+        f.write(data)