plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/labels.py

@@ -0,0 +1,566 @@
+"""The label placer: labels at anchors, of given sizes, within a box, placed by a policy.
+
+* :func:`spread`: positions along one axis, each label as near its wish as the others
+  allow, none overlapping, all within the box; when they do not fit, the labels of lowest
+  order are dropped;
+* :func:`column`: :func:`spread` labels in a column at one x, with elbow leaders back to
+  their anchors (pie outside labels);
+* :func:`drop`: labels kept in order, one overlapping a kept one dropped (value labels,
+  contour labels);
+* :func:`fits`: whether a label fits a cell (heatmap labels: fit or drop);
+* :func:`row`: names of features on rows (genome intervals): each name left of, right of
+  or inside its feature, clamped to the view, shortened where the whole name finds no
+  room, or dropped
+  (:func:`spot`: the first position a name can take, others aside);
+* :func:`around`: labels of points, each beside its point or on rings further out (with a
+  leader), meeting no other label and no point; dropped where no room is left.
+
+Labels are quads on the page (:func:`quad`); :func:`bar_labels` places value labels on
+bars, histogram bins and pie wedges.
+"""
+
+import bisect
+import math
+from typing import Any
+
+from .canvas import Canvas
+from . import kernels
+from .color.values import ink_for
+from .settings import one_of
+from .text import Font, lines_run, measure
+
+__all__ = ["check_labels", "bar_labels", "label_size", "PAD", "FIT", "spread", "column",
+           "drop", "fits", "row", "spot", "NAME_POSITIONS", "quad", "run_quad", "around"]
+
+#: Gap between a bar's end and its label (em: × the label's font size).
+PAD = 0.25
+#: Room a label inside a bar keeps from its edges (em).
+FIT = 0.2
+
+
+def check_labels(v: Any) -> Any:
+    if v is True:
+        return "outside"
+    if v is False or v is None:
+        return False
+    return one_of("inside", "outside", "center")(v)
+
+
+def label_size(canvas: Canvas, text: Any, font: Font, horizontal: bool,
+               pad: float | None = None) -> float:
+    """Room (px) a value label takes along a bar beyond its end: its width on horizontal
+    bars, its height on vertical ones, plus ``pad`` (px; default ``PAD`` em)."""
+    w, a, d = measure(canvas, text, font)
+    return (w if horizontal else a + d) + (PAD * font.size if pad is None else pad)
+
+
+def bar_labels(canvas: Canvas, rects: list[tuple[float, float, float, float, bool]],
+               texts: list[Any], fills: list[Any], where: str, horizontal: bool,
+               font: Font, stacked: bool = False,
+               pad: float | None = None) -> list[tuple[Any, float, float, Any, str, str]]:
+    """Placed labels ``(text, x, y, color, ha, va)`` of bars ``(x0, y0, x1, y1,
+    negative)`` (page units): ``outside`` beyond the bar's end, ``inside`` just within it,
+    ``center`` in its middle.  A label that does not fit inside its bar goes outside, or
+    is left out on a ``stacked`` bar (outside, it would cover the next part).  ``pad``:
+    the gap to the bar's end (px; default ``PAD`` em)."""
+    if pad is None:
+        pad = PAD * font.size
+    fit = FIT * font.size
+    out: list[tuple[Any, float, float, Any, str, str]] = []
+    for (x0, y0, x1, y1, negative), text, fill in zip(rects, texts, fills):
+        if text is None or text == "":
+            continue
+        place = where
+        if where in ("inside", "center"):
+            w, a, d = measure(canvas, text, font)
+            room = (x1 - x0, y1 - y0)
+            along = (w if horizontal else a + d) + (pad if where == "inside" else fit)
+            across = (a + d if horizontal else w) + fit
+            if along > (room[0] if horizontal else room[1]) \
+                    or across > (room[1] if horizontal else room[0]):
+                if stacked:
+                    continue
+                place = "outside"
+        inner = place in ("inside", "center")
+        color = ink_for(fill) if inner else font.color
+        if place == "center":
+            out.append((text, (x0 + x1) / 2, (y0 + y1) / 2, color, "center", "center"))
+            continue
+        if horizontal:
+            end = x0 if negative else x1
+            o = (place == "outside") != negative
+            out.append((text, end + (pad if o else -pad), (y0 + y1) / 2, color,
+                        "left" if o else "right", "center"))
+        else:
+            end = y1 if negative else y0
+            up = (place == "outside") != negative
+            if up:
+                out.append((text, (x0 + x1) / 2, end - pad, color, "center", "bottom"))
+            else:
+                out.append((text, (x0 + x1) / 2, end + pad, color, "center", "top"))
+    keep = drop([quad(canvas, t[0], font, *t[1:3], *t[4:6]) for t in out])
+    return [t for t, k in zip(out, keep) if k]
+
+
+# ---------------------------------------------------------------------------
+# The placer
+# ---------------------------------------------------------------------------
+
+Quad = list[tuple[float, float]]
+
+
+def run_quad(fonts: Any, r: Any) -> Quad | None:
+    """The corners of a placed run (:class:`~plot_io.text.Run`; a tuple of runs: the box
+    of their lines) on the page, rotated with it; ``None`` for nothing drawn."""
+    runs = [x for x in (r if isinstance(r, tuple) else (r,)) if x is not None]
+    if not runs:
+        return None
+    r0 = runs[0]
+    t = math.radians(r0.rotation)
+    c, s = math.cos(t), math.sin(t)
+    us, vs = [], []
+    for one in runs:
+        w, a, d = measure(fonts, one.content, one.font)
+        us += [one.dx, one.dx + w]
+        vs += [one.dy - a, one.dy + d]
+    return [(r0.x + u * c + v * s, r0.y - u * s + v * c)
+            for u, v in ((min(us), min(vs)), (max(us), min(vs)), (max(us), max(vs)),
+                         (min(us), max(vs)))]
+
+
+def quad(fonts: Any, text: Any, font: Font, x: float, y: float, ha: str = "left",
+         va: str = "baseline", angle: float = 0.0) -> Quad | None:
+    """The corners of ``text`` anchored at ``(x, y)`` as drawn (lines split at ``\\n``,
+    rotated by ``angle`` degrees about the anchor)."""
+    return run_quad(fonts, lines_run(fonts, text, x, y, font, ha, va, angle))
+
+
+def _overlap(p: Quad, q: Quad) -> bool:
+    """Whether convex quads ``p`` and ``q`` overlap (separating axes: their edges)."""
+    for poly in (p, q):
+        for i in range(4):
+            ax = poly[(i + 1) % 4][1] - poly[i][1]
+            ay = poly[i][0] - poly[(i + 1) % 4][0]
+            a = [x * ax + y * ay for x, y in p]
+            b = [x * ax + y * ay for x, y in q]
+            if min(max(a), max(b)) <= max(min(a), min(b)):
+                return False
+    return True
+
+
+def drop(quads: list[Quad | None], order: list[float] | None = None) -> list[bool]:
+    """Which labels to keep: taken by decreasing ``order`` (default: as given), a label
+    overlapping one kept before it is dropped."""
+    n = len(quads)
+    idx = sorted(range(n), key=lambda i: -order[i]) if order is not None else range(n)
+    keep = [False] * n
+    cell = 64.0
+    grid: dict[tuple[int, int], list[int]] = {}
+    for i in idx:
+        q = quads[i]
+        if q is None:
+            continue
+        xs, ys = [p[0] for p in q], [p[1] for p in q]
+        if not all(math.isfinite(v) for v in xs + ys):
+            continue
+        cells = [(gx, gy) for gx in range(int(min(xs) // cell), int(max(xs) // cell) + 1)
+                 for gy in range(int(min(ys) // cell), int(max(ys) // cell) + 1)]
+        near = {j for c in cells for j in grid.get(c, ())}
+        if any(_overlap(q, quads[j]) for j in near):       # type: ignore[arg-type]
+            continue
+        keep[i] = True
+        for c in cells:
+            grid.setdefault(c, []).append(i)
+    return keep
+
+
+def spread(wants: list[float], sizes: list[float], lo: float, hi: float,
+           order: list[float] | None = None) -> list[float | None]:
+    """Centres along one axis of labels wanting theirs at ``wants`` and taking ``sizes``
+    (their extent and the gap after them): in the order of their wishes, none
+    overlapping, all within ``lo``–``hi``, each as near its wish as the others allow.  When
+    they do not fit, the labels of lowest ``order`` (default: the last) are dropped
+    (``None``)."""
+    n = len(wants)
+    keep = set(range(n))
+    rank = sorted(range(n), key=lambda i: order[i] if order is not None else -i)
+    total = sum(sizes)
+    for i in rank:
+        if total <= hi - lo + 1e-9:
+            break
+        keep.discard(i)
+        total -= sizes[i]
+    seq = sorted(keep, key=lambda i: (wants[i], i))
+    pos: dict[int, float] = {}
+    edge = lo
+    for i in seq:                                   # down from the top
+        pos[i] = max(wants[i], edge + sizes[i] / 2)
+        edge = pos[i] + sizes[i] / 2
+    edge = hi
+    for i in reversed(seq):                         # up from the bottom
+        pos[i] = min(pos[i], edge - sizes[i] / 2)
+        edge = pos[i] - sizes[i] / 2
+    return [pos.get(i) for i in range(n)]
+
+
+def column(anchors: list[tuple[float, float]], wants: list[float], sizes: list[float],
+           x: float, elbow: float, lo: float, hi: float, order: list[float] | None = None
+           ) -> list[tuple[float, tuple[float, ...]] | None]:
+    """Labels in a column at ``x``: per label its y (:func:`spread` within ``lo``–``hi``)
+    and an elbow leader from its anchor through the point ``elbow`` px before the column
+    at the label's height; ``None``: dropped."""
+    ys = spread(wants, sizes, lo, hi, order)
+    out: list[tuple[float, tuple[float, ...]] | None] = []
+    for (ax, ay), y in zip(anchors, ys):
+        if y is None:
+            out.append(None)
+            continue
+        kx = x - elbow if x >= ax else x + elbow
+        end = x - 2.0 if x >= ax else x + 2.0
+        out.append((y, (ax, ay, kx, y, end, y)))
+    return out
+
+
+def fits(fonts: Any, text: Any, font: Font, w: float, h: float, pad: float) -> bool:
+    """Whether ``text`` with ``pad`` px of room on each axis fits a cell ``w`` × ``h``."""
+    tw, a, d = measure(fonts, text, font)
+    return tw + pad <= abs(w) and a + d + pad <= abs(h)
+
+
+# ---------------------------------------------------------------------------
+# Names on rows
+# ---------------------------------------------------------------------------
+
+#: The positions ``name_position`` tries, in order.
+NAME_POSITIONS = {"auto": ("left", "right", "inside"), "left": ("left",),
+                  "right": ("right",), "inside": ("inside",)}
+
+#: A placed name: its anchor x, its alignment (``"left"``, ``"right"``, ``"center"``)
+#: and where it went (``"left"``, ``"right"``, ``"inside"``; ``"edge"``: at the view's
+#: edge, over the visible part of a feature crossing it).
+Spot = tuple[float, str, str]
+
+
+def _candidates(a: float, b: float, w: float, lo: float, hi: float, gap: float,
+                positions: tuple[str, ...]) -> list[tuple[float, float, Spot, bool]]:
+    """The spans ``(s, e)`` a name ``w`` wide may take beside feature ``[a, b]`` within the
+    view ``lo``–``hi``, in the order of ``positions``, with its spot and whether it lies
+    over the feature.  A feature crossing an edge is named at that edge, over its visible
+    part when the name leaves some of it uncovered."""
+    out: list[tuple[float, float, Spot, bool]] = []
+    for p in positions:
+        if p == "left":
+            if a - gap - w >= lo:
+                out.append((a - gap - w, a - gap, (a - gap, "right", "left"), False))
+            elif a < lo < b and lo + w + gap <= min(b, hi):
+                out.append((lo, lo + w, (lo, "left", "edge"), True))
+        elif p == "right":
+            if b + gap + w <= hi:
+                out.append((b + gap, b + gap + w, (b + gap, "left", "right"), False))
+            elif a < hi < b and hi - w - gap >= max(a, lo):
+                out.append((hi - w, hi, (hi, "right", "edge"), True))
+        else:
+            va, vb = max(a, lo), min(b, hi)
+            if vb - va >= w + 2 * gap:
+                c = (va + vb) / 2
+                out.append((c - w / 2, c + w / 2, (c, "center", "inside"), True))
+    return out
+
+
+def spot(a: float, b: float, w: float, lo: float, hi: float, gap: float,
+         positions: tuple[str, ...]) -> tuple[float, float] | None:
+    """The footprint of feature ``[a, b]`` with its name ``w`` wide at the first position
+    it can take in the view (other features aside), a ``gap`` beyond the name; ``None``:
+    the name fits nowhere."""
+    c = _candidates(a, b, w, lo, hi, gap, positions)
+    if not c:
+        return None
+    s, e = c[0][:2]
+    return min(a, s - gap), max(b, e + gap)
+
+
+def row(spans: list[tuple[float, float]], widths: list[float | None], rows: list[int],
+        lo: float, hi: float, gap: float, positions: tuple[str, ...],
+        order: list[float] | None = None,
+        taken: dict[int, tuple[float, float]] | None = None,
+        cut: Any = None) -> list[Spot | None]:
+    """Names of features ``spans`` (px) on ``rows``: per feature its :data:`Spot` or
+    ``None`` (no name: width ``None``, or no room).  Features are taken by decreasing
+    ``order`` (default: by start); each takes the first of ``positions`` (see
+    :func:`_candidates`) whose span, ``gap`` apart, meets no other feature of its row, no
+    name placed before it and no span of ``taken`` (per row, a span kept free).
+
+    ``cut``: names shortened where the whole name finds no room, after every whole name
+    of the row is placed.  An object with ``steps(i)`` (the shortenings of name ``i``,
+    shortest first; 0: none) and ``width(i, k)`` (its width shortened by ``k``, 1 the
+    shortest); the longest that finds room is kept and recorded as ``cut.kept[i] = k``."""
+    n = len(spans)
+    out: list[Spot | None] = [None] * n
+    by_row: dict[int, list[int]] = {}
+    for i in sorted(range(n), key=lambda i: (spans[i][0], i)):
+        by_row.setdefault(rows[i], []).append(i)
+    for r, idx in by_row.items():
+        lefts = [spans[i][0] for i in idx]
+        reach: list[float] = []                   # the rightmost end so far, by start
+        for i in idx:
+            reach.append(max(spans[i][1], reach[-1]) if reach else spans[i][1])
+        at = {i: k for k, i in enumerate(idx)}
+        name_lo: list[float] = []                 # names placed: disjoint, by start
+        name_hi: list[float] = []
+        if taken and r in taken:
+            name_lo.append(taken[r][0])
+            name_hi.append(taken[r][1])
+
+        def free(i: int, w: float) -> tuple[float, float, Spot] | None:
+            """The first place name ``i``, ``w`` wide, can take in the row."""
+            k = at[i]
+            for s, e, place, over in _candidates(*spans[i], w, lo, hi, gap, positions):
+                if over:                          # others than the feature itself
+                    hit = (k > 0 and reach[k - 1] > s - gap) \
+                        or (k + 1 < len(idx) and lefts[k + 1] < e + gap)
+                else:
+                    j = bisect.bisect_left(lefts, e + gap)
+                    hit = j > 0 and reach[j - 1] > s - gap
+                if hit:
+                    continue
+                p = bisect.bisect_left(name_lo, s)
+                if (p and name_hi[p - 1] > s - gap) \
+                        or (p < len(name_lo) and name_lo[p] < e + gap):
+                    continue
+                return s, e, place
+            return None
+
+        def take(i: int, got: tuple[float, float, Spot]) -> None:
+            s, e, place = got
+            p = bisect.bisect_left(name_lo, s)
+            name_lo.insert(p, s)
+            name_hi.insert(p, e)
+            out[i] = place
+
+        seq = idx if order is None else sorted(idx, key=lambda i: (-order[i], spans[i][0]))
+        missed = []
+        for i in seq:
+            w = widths[i]
+            if w is None:
+                continue
+            got = free(i, w)
+            if got is None:
+                missed.append(i)
+            else:
+                take(i, got)
+        for i in missed if cut is not None else ():
+            hi_k = cut.steps(i)
+            if not hi_k or free(i, cut.width(i, 1)) is None:
+                continue
+            lo_k, best = 1, 1                     # the longest shortening with room
+            while lo_k < hi_k:
+                mid = (lo_k + hi_k + 1) // 2
+                if free(i, cut.width(i, mid)) is not None:
+                    lo_k, best = mid, mid
+                else:
+                    hi_k = mid - 1
+            got = free(i, cut.width(i, best))
+            if got is not None:
+                take(i, got)
+                cut.kept[i] = best
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Labels of points
+# ---------------------------------------------------------------------------
+
+#: Directions ``(dx, dy)`` of the positions tried beside a point, in order: right, left,
+#: above, below, then the diagonals.
+_BESIDE = ((1, 0), (-1, 0), (0, -1), (0, 1), (1, -1), (-1, -1), (1, 1), (-1, 1))
+#: Angles tried on each ring further out.
+_RING = 16
+
+Box = tuple[float, float, float, float]
+
+
+class _Grid:
+    """Boxes or discs hashed by square cells of ``cell`` px."""
+
+    def __init__(self, cell: float) -> None:
+        self.cell = cell
+        self.cells: dict[tuple[int, int], list[int]] = {}
+
+    def span(self, x0: float, y0: float, x1: float, y1: float) -> Any:
+        c = self.cell
+        return [(i, j) for i in range(int(x0 // c), int(x1 // c) + 1)
+                for j in range(int(y0 // c), int(y1 // c) + 1)]
+
+    def near(self, x0: float, y0: float, x1: float, y1: float) -> set[int]:
+        cells = self.cells
+        return {k for key in self.span(x0, y0, x1, y1) for k in cells.get(key, ())}
+
+
+class _Points:
+    """Points in columns ``cell`` px wide, each sorted by y (sorted by the kernels): the
+    points near a box by bisection."""
+
+    def __init__(self, xs: Any, ys: Any, cell: float) -> None:
+        self.cell = cell
+        self.cols: dict[int, tuple[Any, Any]] = {}
+        order = kernels.argsort(xs)
+        sx = kernels.take(xs, order)
+        n, i = len(sx), 0
+        while i < n and not math.isfinite(sx[i]):          # NaN and -inf first
+            i += 1
+        while i < n and math.isfinite(sx[i]):
+            c = math.floor(sx[i] / cell)
+            j = max(bisect.bisect_left(sx, (c + 1) * cell, i), i + 1)
+            idx = order[i:j]
+            cy = kernels.take(ys, idx)
+            oy = kernels.argsort(cy)
+            col_y = kernels.take(cy, oy)
+            k = 0
+            while k < len(col_y) and col_y[k] != col_y[k]:
+                k += 1
+            self.cols[c] = (kernels.take(kernels.take(xs, idx), oy)[k:], col_y[k:])
+            i = j
+
+    def hit(self, x0: float, y0: float, x1: float, y1: float, r: float) -> bool:
+        """Whether a disc of radius ``r`` about a point meets box ``(x0, y0, x1, y1)``."""
+        cell, r2 = self.cell, r * r
+        for c in range(math.floor((x0 - r) / cell - 1e-9),
+                       math.floor((x1 + r) / cell + 1e-9) + 1):
+            col = self.cols.get(c)
+            if col is None:
+                continue
+            cx, cy = col
+            for k in range(bisect.bisect_left(cy, y0 - r), bisect.bisect_right(cy, y1 + r)):
+                px, py = cx[k], cy[k]
+                dx = x0 - px if px < x0 else px - x1 if px > x1 else 0.0
+                dy = y0 - py if py < y0 else py - y1 if py > y1 else 0.0
+                if dx * dx + dy * dy <= r2:
+                    return True
+        return False
+
+
+def around(points: tuple[Any, Any], radius: float, picks: list[int],
+           sizes: list[tuple[float, float]], box: Box, gap: float, reach: float,
+           taken: list[Box] | None = None) -> list[tuple[float, float, bool] | None]:
+    """Centres of the labels of points ``points`` (page ``(xs, ys)``; discs of
+    ``radius``): for each of ``picks`` (point indices, in priority order) with its label
+    of ``sizes`` ``(w, h)``, ``(x, y, leader)`` or ``None`` (no room).  A label takes the
+    first free position of: 8 beside its point (``gap`` px from its disc), then rings every
+    half label height out to ``reach`` px from it, 16 angles each (those get ``leader``: a
+    line from the point to the nearest point of the label's box).  Free: within ``box``,
+    meeting no label or leader placed before it, no box of ``taken`` (labels placed are
+    added to it) and no point's disc, its leader crossing no label and no leader.
+    Deterministic."""
+    xs, ys = points
+    hmax = max((h for _, h in sizes), default=0.0)
+    cell = max(hmax, 2 * radius, 4.0)
+    bx0, by0, bx1, by1 = box
+    pts = _Points(xs, ys, cell)
+    placed = taken if taken is not None else []
+    labels = _Grid(cell)
+    for k, b in enumerate(placed):
+        for key in labels.span(*b):
+            labels.cells.setdefault(key, []).append(k)
+    lines: list[Box] = []                               # leaders placed
+    leads = _Grid(cell)
+
+    lcells, dcells = labels.cells, leads.cells
+
+    def free(x0: float, y0: float, x1: float, y1: float) -> bool:
+        if x0 < bx0 or y0 < by0 or x1 > bx1 or y1 > by1:
+            return False
+        if pts.hit(x0, y0, x1, y1, radius):
+            return False
+        j0, j1 = int(y0 // cell), int(y1 // cell) + 1
+        for i in range(int(x0 // cell), int(x1 // cell) + 1):
+            for j in range(j0, j1):
+                for k in lcells.get((i, j), ()):
+                    a0, b0, a1, b1 = placed[k]
+                    if a0 < x1 and x0 < a1 and b0 < y1 and y0 < b1:
+                        return False
+                for k in dcells.get((i, j), ()):
+                    if _crosses(lines[k], (x0, y0, x1, y1)):
+                        return False
+        return True
+
+    out: list[tuple[float, float, bool] | None] = []
+    d = radius + gap
+    for i, (w, h) in zip(picks, sizes):
+        x, y = xs[i], ys[i]
+        got = None
+        if math.isfinite(x) and math.isfinite(y):
+            hw, hh = w / 2, h / 2
+            for cx, cy, ring in _spots(x, y, d, hw, hh, reach):
+                if not free(cx - hw, cy - hh, cx + hw, cy + hh):
+                    continue
+                line = (x, y, min(max(x, cx - hw), cx + hw), min(max(y, cy - hh), cy + hh))
+                if ring and (any(_crosses(line, placed[k]) for k in labels.near(*_bounds(line)))
+                             or any(_meet(line, lines[k]) for k in leads.near(*_bounds(line)))):
+                    continue
+                got = (cx, cy, ring)
+                if ring:
+                    for key in leads.span(*_bounds(line)):
+                        leads.cells.setdefault(key, []).append(len(lines))
+                    lines.append(line)
+                break
+        out.append(got)
+        if got is not None:
+            b = (got[0] - w / 2, got[1] - h / 2, got[0] + w / 2, got[1] + h / 2)
+            for key in labels.span(*b):
+                labels.cells.setdefault(key, []).append(len(placed))
+            placed.append(b)
+    return out
+
+
+def _bounds(line: Box) -> Box:
+    x0, y0, x1, y1 = line
+    return min(x0, x1), min(y0, y1), max(x0, x1), max(y0, y1)
+
+
+def _meet(p: Box, q: Box) -> bool:
+    """Whether segments ``p`` and ``q`` cross (touching ends do not)."""
+    def side(ax: float, ay: float, bx: float, by: float, cx: float, cy: float) -> float:
+        return (bx - ax) * (cy - ay) - (by - ay) * (cx - ax)
+    d1 = side(*q[:2], *q[2:], *p[:2])
+    d2 = side(*q[:2], *q[2:], *p[2:])
+    d3 = side(*p[:2], *p[2:], *q[:2])
+    d4 = side(*p[:2], *p[2:], *q[2:])
+    return d1 * d2 < 0 and d3 * d4 < 0
+
+
+def _crosses(line: Box, b: Box) -> bool:
+    """Whether segment ``line`` passes through the inside of box ``b`` (Liang–Barsky)."""
+    x0, y0, x1, y1 = line
+    dx, dy = x1 - x0, y1 - y0
+    t0, t1 = 0.0, 1.0
+    for p, q in ((-dx, x0 - b[0]), (dx, b[2] - x0), (-dy, y0 - b[1]), (dy, b[3] - y0)):
+        if p == 0:
+            if q <= 0:
+                return False
+        else:
+            t = q / p
+            if p < 0:
+                t0 = max(t0, t)
+            else:
+                t1 = min(t1, t)
+            if t0 >= t1:
+                return False
+    return True
+
+
+def _spots(x: float, y: float, d: float, hw: float, hh: float, reach: float) -> Any:
+    """The centres a label ``2·hw`` × ``2·hh`` tries around point ``(x, y)``: beside it,
+    its box ``d`` px away, then on rings (``True``) every ``hh`` px out to ``reach``."""
+    for dx, dy in _BESIDE:
+        if dx and dy:
+            yield x + dx * (d * 0.7071 + hw), y + dy * (d * 0.7071 + hh), False
+        else:
+            yield x + dx * (d + hw), y + dy * (d + hh), False
+    step = max(hh, 1.0)
+    r = d + step
+    while r <= reach:
+        for k in range(_RING):
+            t = 2 * math.pi * k / _RING
+            c, s = math.cos(t), -math.sin(t)
+            yield x + c * (r + hw), y + s * (r + hh), True
+        r += step

plot_io/layers/__init__.py

@@ -0,0 +1,100 @@
+"""Layers: plot types as ``stat → position → geom`` presets.
+
+* :mod:`~plot_io.layers.base`: :class:`Series`, the model of a call (data and settings);
+* :mod:`~plot_io.layers.core`: :class:`Layer`, :class:`Call`, :class:`Table`;
+* :mod:`~plot_io.layers.stats`, :mod:`~plot_io.layers.positions`,
+  :mod:`~plot_io.layers.geoms`: the three parts of a layer;
+* :mod:`~plot_io.layers.pipeline`: compute, positions and color training per plot;
+* :mod:`~plot_io.layers.paint`: colors, mapped values and markers;
+* :mod:`~plot_io.layers.context`: the drawing context and the orientation swap.
+
+The plot types themselves are presets in :mod:`plot_io.presets` (and
+:mod:`plot_io.genome`); :func:`add_layer` (``registry.layers.add``) adds one as a
+method of ``Plot`` (a layer in the plot), of ``Figure`` (a new plot holding it) and of facet
+sets (a layer per panel).  The built-in types' methods are in :mod:`plot_io._methods`
+(generated, typed); a type added by a user is attached to the classes.
+"""
+
+from typing import Any, Callable
+
+from .base import Series
+from .core import Call, Entry, Layer, Table
+
+__all__ = ["Series", "Layer", "Call", "Entry", "Table", "add_layer", "layer_types", "layer_type",
+           "figure_call"]
+
+_TYPES: dict[str, Any] = {}
+
+
+def add_layer(name: str, factory: Callable[..., Any]) -> None:
+    """Add ``plot.<name>(…)``: it calls ``factory(…, plot=plot)``; ``figure.<name>(…)``:
+    the same in a new plot of the figure (a track in a tracks layout), which takes the plot
+    settings ``factory`` lacks (and ``title``); ``facets.<name>(…)``: one per panel.  A
+    factory that is a :class:`Series` subclass is also a style class (``"Name.setting"``
+    style keys)."""
+    from .._methods import LAYERS
+    from ..facets import PanelSet
+    from ..figure import Figure
+    from ..plot import Plot
+    if not name.isidentifier() or name.startswith("_"):
+        raise ValueError(f"layer names are identifiers not starting with _, got {name!r}")
+    if name in LAYERS and name not in _TYPES:       # a built-in type: its methods exist
+        _TYPES[name] = factory
+        return
+    for owner in (Plot, Figure, PanelSet):
+        if getattr(owner, name, None) is not None and name not in _TYPES:
+            raise ValueError(f"{owner.__name__} already has {name!r}")
+
+    def method(self: Any, *args: Any, **settings: Any) -> Any:
+        return factory(*args, plot=self, **settings)
+
+    def figure_method(self: Any, *args: Any, **settings: Any) -> Any:
+        return figure_call(self, factory, args, settings)
+
+    def facet_method(self: Any, *args: Any, **settings: Any) -> Any:
+        return self.call(name, args, settings)
+
+    from .base import call_signature
+    try:
+        sig = call_signature(factory, drop=("plot",), first=("self",))
+    except (TypeError, ValueError):                 # a callable inspect cannot read
+        sig = None
+    doc = getattr(factory, "__doc__", None)
+    first = doc.strip().splitlines()[0] if doc else f"A {name} layer."
+    for owner, fn, what in ((Plot, method, first),
+                            (Figure, figure_method, f"A new plot holding: {first}"),
+                            (PanelSet, facet_method, f"One per panel: {first}")):
+        fn.__name__ = name
+        fn.__qualname__ = f"{owner.__name__}.{name}"
+        fn.__doc__ = what
+        if sig is not None:
+            fn.__signature__ = sig              # type: ignore[attr-defined]
+        setattr(owner, name, fn)
+    _TYPES[name] = factory
+
+
+def figure_call(figure: Any, factory: Any, args: tuple[Any, ...],
+                settings: dict[str, Any]) -> Any:
+    """``factory(*args, **settings)`` in a new plot of ``figure`` (``figure.<name>(…)``),
+    which takes the plot settings among ``settings``; a failed call leaves no plot."""
+    before = list(figure._areas)
+    settings = dict(settings)
+    plot = figure._new_plot(factory, settings)
+    try:
+        return factory(*args, plot=plot, **settings)
+    except BaseException:
+        for k in [k for k in figure._areas if k not in before]:
+            del figure._areas[k]
+        raise
+
+
+def layer_type(name: str) -> Any:
+    """The factory of layer ``name``."""
+    if name not in _TYPES:
+        raise ValueError(f"unknown layer {name!r} (registered: {', '.join(sorted(_TYPES))})")
+    return _TYPES[name]
+
+
+def layer_types() -> dict[str, Any]:
+    """The registered layer names and their factories."""
+    return dict(_TYPES)