plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/mapped.py

@@ -0,0 +1,522 @@
+"""Color and size axes: the scales of values drawn as colors and as sizes.
+
+Numbers given as colors (per point, per cell, per category) or as sizes go through an axis,
+as positions do: its scale and limits take them to [0, 1], then a gradient (a
+:class:`~plot_io.ColorMap`) or a range of sizes (a :class:`~plot_io.SizeMap`) gives the color
+or the diameter.  :class:`ColorAxis` and :class:`SizeAxis` are axes like ``plot.x_axis``
+(scale, limits, ticks, number format, label); a colorbar and a size key are their guides.
+
+* A series that maps values has axes of its own (``series.color_axis``,
+  ``series.size_axis``), configured by its ``color_*`` and ``size_*`` settings
+  (``color_limits`` is the axis' ``limits``, ``color_scale`` its ``scale``, ``color_map``
+  its gradient).
+* A shared axis (``figure.color_axis(…)``, ``figure.size_axis(…)``) is given to series as
+  ``color_axis=`` or ``size_axis=``; it holds the gradient (or sizes), the limits and the
+  scale, and its automatic limits cover every series using it.
+* The figure's ``share_color`` (``share_size``) trains the own color (size) axes of the
+  plots of a group together, as ``share_x`` does for x axes.
+
+:func:`train` resolves every axis used in a layout (scale, then limits over its values)
+into an :class:`~plot_io.axis.AxisState`, kept in the render (``Render.scales``), and
+groups the series of each trained size axis into one size key (``Render.size_keys``).
+"""
+
+import math
+from array import array
+from collections.abc import Callable
+from typing import Any
+
+from ._methods import ColorAxisMixin, SizeAxisMixin
+from . import kernels
+from .axis import Axis, AxisState
+from .color.maps import MAP_WORDS, ColorMap, check_color_map, chosen_map, kind_settings
+from .scales import NUMERIC_SCALES
+from .settings import (DECLINE, Setting, Settings, cascade, given_rule, number, one_of,
+                       table)
+from .spec import current
+from .values import check_size_map as _check_size_map
+from .validators import typed
+
+__all__ = ["ColorAxis", "SizeAxis", "color_axis_of", "size_axis_of", "shared_axis", "own_axis",
+           "group_axes", "train", "trained", "SizeGroup", "size_keys", "size_group",
+           "colors_of", "unit_of", "check_color_axis", "check_size_axis"]
+
+
+def _scale_setting(what: str) -> Setting:
+    return Setting(one_of(*NUMERIC_SCALES),
+                   doc=f"Scale of the {what}: `linear`, `log` (base 10), `ln` (base e), "
+                       "`log2`, `log10`, `sqrt`, `exp`, `symlog` or `logit`; default "
+                       "`linear`.")
+
+
+def _from_series(name: str, key: str | None = None) -> Callable[[Any], Any]:
+    """Rule of an own axis' setting ``name``: the series' ``key`` (default ``color_<name>``,
+    ``size_<name>``), when it has one."""
+    @given_rule
+    def rule(axis: "_MappedAxis") -> Any:
+        s = axis.series
+        nonlocal key
+        if key is None:
+            key = f"{axis.PREFIX}_{name}"
+        if s is None or key not in s.SETTINGS:
+            return DECLINE
+        v = s._raw(key)
+        return DECLINE if v is None else v
+    return rule
+
+
+class _MappedAxis(Axis):
+    """An axis of mapped values: a series' own (``series``) or shared (owned by a figure)."""
+
+    ROLE = "c"
+    PREFIX = "color"
+
+    def __init__(self, figure: Any = None, **settings: Any) -> None:
+        self.series: Any = None
+        super().__init__(figure, self.ROLE)
+        if settings:
+            self.set(**settings)
+
+    @classmethod
+    def own(cls, series: Any) -> Any:
+        """The own axis of ``series`` (its parent: the series' settings flow into it)."""
+        axis = cls.__new__(cls)
+        axis.series = series
+        Axis.__init__(axis, series, cls.ROLE)
+        return axis
+
+    def __repr__(self) -> str:
+        owner = "shared" if self.series is None else repr(self.series)
+        return f"{type(self).__name__}({owner})"
+
+    def _box(self, kind: str, name: str) -> float:
+        if kind in ("across", "along"):           # of the guide drawing it (a colorbar)
+            r = current()
+            boxes = r.boxes.get(id(self)) if r is not None else None
+            vertical = bool(boxes and boxes.get("vertical"))
+            kind = "axes_width" if (kind == "across") == vertical else "axes_height"
+        return Settings._box(self, kind, name)
+
+
+class ColorAxis(ColorAxisMixin, _MappedAxis):
+    """The axis of values drawn as colors: scale, limits, ticks and number format, and the
+    gradient (``color_map``).  ``figure.color_axis(…)`` makes a shared one, given to series
+    as ``color_axis=``; a colorbar is its guide.
+
+    A series that maps values has its own color axis (``series.color_axis``): its ``scale``
+    is the series' ``color_scale``, its ``limits`` the series' ``color_limits``, its gradient
+    the series' ``color_map``; a ``scale`` or ``limits`` set on the axis itself wins.  A
+    shared axis covers every series using it, and those take no ``color_map``,
+    ``color_limits`` or ``color_scale`` of their own (an error); one made alone
+    (``plt.ColorAxis()``) joins the figure of its first series.  The members of a ``group=``
+    call share one.  The figure's ``share_color`` makes the own axes of each group of plots
+    one (one ``color_limits`` or scale for the group; two different ones are an error),
+    each series keeping its gradient.  Training: before the layout, limits come from the
+    values as for x and y axes (``limits``, quantiles, ``include_zero``), without padding
+    unless ``padding`` is set.  Values past the limits take the gradient's ``under`` and
+    ``over`` colors, missing values and values outside the scale's domain its ``bad`` color
+    (the latter with a warning).
+    """
+
+    SETTINGS = table(**{**Axis.SETTINGS, "scale": _scale_setting("mapped values")},
+                     color_map=Setting(check_color_map,
+                                       doc="The gradient: a `ColorMap`, a map name or "
+                                           "colors (alias `cmap`), `\"auto\"` "
+                                           "(`sequential_map`, or `diverging_map` about a "
+                                           "`center`) or a kind (that kind's map)."),
+                     center=Setting(number(),
+                                    doc="The value at the map's middle; the limits "
+                                        "symmetric about it unless given; the colorbar "
+                                        "marks it."),
+                     **kind_settings())
+    RULES = {"limits": _from_series("limits"), "scale": _from_series("scale"),
+             "color_map": _from_series("map"), "center": _from_series("center", "center")}
+
+    def color_map(self) -> ColorMap:
+        """The gradient values are drawn with (in the axis' color variant): with a
+        ``center``, its middle at the centre (a part of it when the limits are given
+        unevenly about the centre)."""
+        center = self.resolve("center")
+        v = self.resolve("color_map")
+        if not isinstance(v, ColorMap) and not (isinstance(v, str) and v in MAP_WORDS):
+            v = "auto"                      # a series' colors by level, or its one color
+        cm = chosen_map(self, v, "sequential" if center is None else "diverging")
+        if center is None:
+            return cm
+        r = current()
+        st = r.scales.get(id(self)) if r is not None else None
+        if st is None or st.scale is None:
+            return cm
+        fc = st.scale.f(center)
+        d = max(fc - st.flo, st.fhi - fc)
+        if not (math.isfinite(fc) and d > 0):
+            return cm
+        a, b = (st.flo - fc + d) / (2 * d), (st.fhi - fc + d) / (2 * d)
+        if a <= 1e-12 and b >= 1 - 1e-12:
+            return cm
+        return cm.truncated(max(a, 0.0), min(b, 1.0))
+
+
+
+
+class SizeAxis(SizeAxisMixin, _MappedAxis):
+    """The axis of values drawn as marker sizes: scale, limits, the values and number
+    format of its size key (``ticks``, ``tick_format``), its title (``label``), and the
+    sizes (``size_map``).  ``figure.size_axis(…)`` makes a shared one, given to series as
+    ``size_axis=``; a size key is its guide.
+
+    As :class:`ColorAxis`, for sizes: the series' own (``series.size_axis``: ``size_scale``,
+    ``size_limits``, ``size_map``), shared by ``figure.size_axis()``, or made one per group by
+    the figure's ``share_size``, which also gives the group one size key beside its plots.
+    """
+
+    ROLE = "s"
+    PREFIX = "size"
+
+    SETTINGS = table(**{**Axis.SETTINGS, "scale": _scale_setting("mapped values")},
+                     size_map=Setting(_check_size_map,
+                                      doc="The sizes: a `SizeMap` or a pair of diameters; "
+                                          "default `SizeMap()`."))
+    RULES = {"limits": _from_series("limits"), "scale": _from_series("scale"),
+             "size_map": _from_series("map")}
+
+    def _levels(self, name: str) -> tuple[tuple[str, ...], ...]:
+        return (tuple(c for level in Settings._levels(self, name) for c in level),)
+
+    def size_map(self) -> Any:
+        """The sizes values are drawn with."""
+        from .sizemaps import DEFAULT
+        m = self.resolve("size_map")
+        return DEFAULT if m is None else m
+
+
+@typed("ColorAxis")
+def check_color_axis(v: Any) -> Any:
+    if isinstance(v, ColorAxis):
+        return v
+    raise ValueError(f"expected a ColorAxis (figure.color_axis(…)), got {v!r}")
+
+
+@typed("SizeAxis")
+def check_size_axis(v: Any) -> Any:
+    if isinstance(v, SizeAxis):
+        return v
+    raise ValueError(f"expected a SizeAxis (figure.size_axis(…)), got {v!r}")
+
+
+# ---------------------------------------------------------------------------
+# The axis of a series
+# ---------------------------------------------------------------------------
+
+def own_axis(series: Any, cls: type) -> Any:
+    """The own axis of class ``cls`` of ``series``, made on first use."""
+    key = f"_{cls.PREFIX}_axis"               # type: ignore[attr-defined]
+    axis = series.__dict__.get(key)
+    if axis is None:
+        axis = cls.own(series)                 # type: ignore[attr-defined]
+        series.__dict__[key] = axis
+    return axis
+
+
+def shared_axis(series: Any, what: str) -> Any:
+    """The shared axis given as ``color_axis=`` (``size_axis=``), or ``None``."""
+    name = f"{what}_axis"
+    if name not in series.SETTINGS:
+        return None
+    axis = series.resolve(name)
+    if axis is not None:
+        given = [n for n in (f"{what}_map", f"{what}_limits", f"{what}_scale")
+                 if series.is_set(n)]
+        if given:
+            raise ValueError(f"{series.kind}: {', '.join(given)} belong to the shared "
+                             f"{what} axis given as {name}= (set them there)")
+    return axis
+
+
+def color_axis_of(series: Any) -> ColorAxis:
+    """The color axis numbers in the series' colors go through: the shared one given as
+    ``color_axis=``, else the series' own."""
+    axis = shared_axis(series, "color")
+    return axis if axis is not None else own_axis(series, ColorAxis)
+
+
+def size_axis_of(series: Any, name: str = "size") -> SizeAxis | None:
+    """The size axis of a size setting holding values to map, or ``None`` (sizes in px):
+    a density always maps; numbers per point map with a ``size_map`` or a ``size_axis``."""
+    from .values import is_computed
+    if name not in series.SETTINGS or "size_map" not in series.SETTINGS:
+        return None
+    v = series.resolve(name)
+    computed = is_computed(v)
+    if not computed and isinstance(v, (int, float)):
+        return None
+    axis = shared_axis(series, "size")
+    if axis is not None:
+        return axis
+    if computed or series.resolve("size_map") is not None:
+        return own_axis(series, SizeAxis)
+    return None
+
+
+def _maps_colors(v: Any) -> bool:
+    from .values import Values, is_computed, paint
+    if v is None:
+        return False
+    try:
+        out = paint(v)
+    except (TypeError, ValueError):
+        return False
+    return isinstance(out, Values) or is_computed(out)
+
+
+#: Keywords of a call that configure its color or size axis, and the axis' names for them.
+_AXIS_KEYS = {"color": {"color_map": "color_map", "color_limits": "limits",
+                        "color_scale": "scale"},
+              "size": {"size_map": "size_map", "size_limits": "limits", "size_scale": "scale"}}
+
+
+def group_axes(cls: type, kw: dict[str, Any]) -> None:
+    """The keywords of a ``group=`` call, given shared color and size axes where the call
+    maps values: its members are one call, on one axis each (the ``color_*``/``size_*``
+    keywords go to the axes)."""
+    settings = getattr(cls, "SETTINGS", {})
+    from .layers.paint import COLOR_SETTINGS
+    from .values import is_computed
+    for what, axis_cls in (("color", ColorAxis), ("size", SizeAxis)):
+        name = f"{what}_axis"
+        if name not in settings or kw.get(name) is not None:
+            continue
+        keys = _AXIS_KEYS[what]
+        if what == "color":
+            maps = any(_maps_colors(kw.get(k)) for k in COLOR_SETTINGS)
+        else:
+            v = kw.get("size")
+            density = is_computed(v) or (isinstance(v, str) and v.strip().lower() == "density")
+            maps = density or (kw.get("size_map") is not None and v is not None
+                               and not isinstance(v, (int, float, str)))
+        if maps:
+            kw[name] = axis_cls(**{to: kw.pop(k) for k, to in keys.items()
+                                   if kw.get(k) is not None})
+
+
+# ---------------------------------------------------------------------------
+# Training
+# ---------------------------------------------------------------------------
+
+class _Values:
+    """Values on a mapped axis, read by its training as a call's values are by an x axis."""
+
+    __slots__ = ("data",)
+    SETTINGS: dict[str, Any] = {}
+
+    def __init__(self, data: Any) -> None:
+        self.data = data
+
+    def has_axis(self, role: str) -> bool:
+        return True
+
+    def categories(self, role: str) -> None:
+        return None
+
+    def extent(self, role: str, scale: Any) -> tuple[int, float, float]:
+        return kernels.extent(self.data, scale.function)
+
+    def values(self, role: str) -> Any:
+        return array("d", [v for v in kernels.doubles(self.data) if math.isfinite(v)])
+
+    def sticky(self, role: str) -> list[float]:
+        return []
+
+    def zero_default(self, role: str) -> bool:
+        return False
+
+    def zero_padding(self, role: str) -> bool:
+        return False
+
+    def inverts(self, role: str) -> bool:
+        return False
+
+
+def _explicit(axis: Any, name: str) -> bool:
+    """Whether an axis' setting is given (on it, or by its series' settings)."""
+    return cascade(axis, name)[2] in ("own", "rule")
+
+
+def train(fig: Any, areas: list[Any]) -> None:
+    """Train every color and size axis of the figure's layout ``areas``: the axes of the
+    calls' mapped values, those of colorbars and size legends, the own color (size) axes of
+    plots sharing them (``share_color``, ``share_size``) together; into the render's
+    ``scales``.  Then the size keys of the trained size axes (``size_keys``)."""
+    from .colorbar import Colorbar
+    from .layers.pipeline import plot_calls
+    from .legend import SizeLegend
+    from .plot import Plot
+    from . import sharing
+    r = current()
+    assert r is not None
+    r.scales.clear()
+    axes: dict[int, Any] = {}
+    values: dict[int, list[Any]] = {}
+    plot_of: dict[int, Any] = {}              # own axes: the plot of their series
+
+    def use(axis: Any, v: Any = None, plot: Any = None) -> None:
+        axes.setdefault(id(axis), axis)
+        vs = values.setdefault(id(axis), [])
+        if callable(v):                       # values counted for the placed axes
+            v = v()
+        if v is not None:
+            vs.append(v)
+        if plot is not None and axis.series is not None:
+            plot_of[id(axis)] = plot
+
+    for a in areas:
+        if isinstance(a.obj, Plot):
+            for p in [a.obj, *a.obj.twins]:
+                for c in plot_calls(p):
+                    for axis, v in c.color_sources:
+                        use(axis, v, a.obj)
+                    for axis, v in c.size_sources:
+                        use(axis, v, a.obj)
+            for cb in a.obj.colorbars:
+                use(cb.axis)
+        elif isinstance(a.obj, Colorbar):
+            use(a.obj.axis)
+        elif isinstance(a.obj, SizeLegend):
+            use(a.obj.size_axis)
+    for cb in fig.colorbars:
+        use(cb.axis)
+    root = {k: k for k in axes}
+
+    def find(k: int) -> int:
+        while root[k] != k:
+            k = root[k]
+        return k
+    r.levels.clear()
+    r.levels_group.clear()
+    for role, cls in (("color", ColorAxis), ("size", SizeAxis)):
+        for members, _ in sharing.groups(fig, areas, role):
+            in_group = {id(m.obj) for m in members}
+            if role == "color":
+                r.levels_group.update((k, id(members[0].obj)) for k in in_group)
+            ids = [k for k, p in plot_of.items()
+                   if id(p) in in_group and isinstance(axes[k], cls)]
+            for k in ids[1:]:
+                ra, rb = find(ids[0]), find(k)
+                if ra != rb:
+                    root[rb] = ra
+    grouped: dict[int, list[int]] = {}
+    for k in axes:
+        grouped.setdefault(find(k), []).append(k)
+    for ids in grouped.values():
+        members = [axes[k] for k in ids]
+        lead = members[0]
+        if len(members) > 1:
+            role = "size" if isinstance(lead, SizeAxis) else "color"
+            lead = members[sharing.leader(members, role, _explicit)]
+        st = AxisState(lead)
+        st.resolve([_Values(v) for k in ids for v in values[k]], False)
+        for k in ids:
+            r.scales[k] = st
+    r.size_keys = size_keys(areas)
+
+
+class SizeGroup:
+    """The series of one trained size axis and one size map, across a layout: they have
+    one size key.  ``axis``: the first one's size axis; ``users``: every series; ``listed``:
+    those whose ``size_key`` is ``"legend"``; ``plot``: the plot whose legend shows the
+    key (``None``: a size legend area shows it, or no series is listed)."""
+
+    __slots__ = ("axis", "users", "listed", "plot")
+
+    def __init__(self, axis: Any) -> None:
+        self.axis = axis
+        self.users: list[Any] = []
+        self.listed: list[Any] = []
+        self.plot: Any = None
+
+
+def _size_key(axis: Any) -> tuple[int, str] | None:
+    r = current()
+    st = r.scales.get(id(axis)) if r is not None else None
+    return None if st is None else (id(st), repr(axis.size_map()))
+
+
+def size_keys(areas: list[Any]) -> dict[Any, SizeGroup]:
+    """The size keys of a layout, by trained axis and size map.  Series of a shared size axis
+    (one axis, or own axes trained as one by ``share_size``) in several plots have one key,
+    in the legend of the rightmost of those plots (the topmost of those); a size legend
+    area showing the axis takes it out of the plot legends."""
+    from .legend import SizeLegend
+    from .plot import Plot
+    out: dict[Any, SizeGroup] = {}
+    place: dict[Any, tuple[int, int]] = {}
+    for a in areas:
+        if not isinstance(a.obj, Plot):
+            continue
+        for p in [a.obj, *a.obj.twins]:
+            for s in p.series:
+                axis = size_axis_of(s)
+                key = None if axis is None else _size_key(axis)
+                if key is None:
+                    continue
+                g = out.get(key)
+                if g is None:
+                    g = out[key] = SizeGroup(axis)
+                g.users.append(s)
+                if "size_key" not in s.SETTINGS or s.resolve("size_key") != "legend":
+                    continue
+                g.listed.append(s)
+                rank = (-a.c1, a.r0)
+                if g.plot is None or rank < place[key]:
+                    g.plot, place[key] = p, rank
+    for a in areas:
+        if isinstance(a.obj, SizeLegend):
+            g = out.get(_size_key(a.obj.size_axis))
+            if g is not None:
+                g.plot = None
+    return out
+
+
+def trained(axis: Any) -> AxisState:
+    """The trained state of a color or size axis in the render in progress."""
+    r = current()
+    st = r.scales.get(id(axis)) if r is not None else None
+    if st is None:
+        raise ValueError(f"{axis!r} maps no values of the figure being drawn (values of "
+                         "this setting are not mapped by its series)")
+    return st
+
+
+def size_group(axis: Any) -> SizeGroup | None:
+    """The size key group of a trained size axis in the render in progress."""
+    r = current()
+    key = _size_key(axis)
+    return None if key is None or r is None else r.size_keys.get(key)
+
+
+def unit_of(axis: Any) -> Callable[[float], float]:
+    """``v -> t``: a value's position on the trained axis (0 and 1 at the limits)."""
+    st = trained(axis)
+    assert st.scale is not None
+    f, flo = st.scale.f, st.flo
+    span = (st.fhi - st.flo) or 1.0
+    return lambda v: (f(v) - flo) / span
+
+
+def colors_of(axis: Any, values: Any) -> Any:
+    """Colors of many values through a trained color axis (an ``(n, 4)`` buffer); values
+    outside the scale's domain (0 on a log scale) take the map's ``bad`` color, as missing
+    ones, with a warning naming their count."""
+    st = trained(axis)
+    assert st.scale is not None
+    if st.scale.function is not None:
+        outside = kernels.extent(values)[0] - kernels.extent(values, st.scale.function)[0]
+        if outside:
+            import warnings
+            warnings.warn(f"{outside} color value{'s' if outside > 1 else ''} outside the "
+                          f"{st.scale.name} scale's domain: drawn in the color map's bad "
+                          "color", stacklevel=2)
+    span = st.fhi - st.flo
+    k = 1.0 / span if span else 0.0
+    ts = kernels.scaled(values, k, -st.flo * k, st.scale.function, **st.scale.options)
+    return axis.color_map().colors_at(ts)

plot_io/markers.py

@@ -0,0 +1,110 @@
+"""Marker shapes: unit paths centred on the origin (y down) and their areas.
+
+vec_io draws markers from paths; the names live here.  The paths of ``square``,
+``diamond``, ``triangle_up``, ``triangle_down``, ``plus`` and ``cross`` are those vec_io
+0.3 bundled.
+"""
+
+import math
+import re
+from typing import Any
+
+from vec_io import Path
+from vec_io.geometry import ellipse_path, parse_path_data
+
+from .settings import MARKER_ALIASES
+
+__all__ = ["MARKERS", "add_marker", "resolve", "marker_area"]
+
+_S3 = math.sqrt(3.0)
+_T = f"{_S3 / 3!r}"
+_H = f"{_S3 / 6!r}"
+
+_DATA = {
+    "square": "M-0.5 -0.5 H0.5 V0.5 H-0.5 Z",
+    "diamond": "M0 -0.5 L0.5 0 L0 0.5 L-0.5 0 Z",
+    "triangle_up": f"M0 -{_T} L0.5 {_H} L-0.5 {_H} Z",
+    "triangle_down": f"M0 {_T} L0.5 -{_H} L-0.5 -{_H} Z",
+    "triangle_left": f"M-{_T} 0 L{_H} -0.5 L{_H} 0.5 Z",
+    "triangle_right": f"M{_T} 0 L-{_H} 0.5 L-{_H} -0.5 Z",
+    "plus": "M-0.5 -0.15 H-0.15 V-0.5 H0.15 V-0.15 H0.5 V0.15 H0.15 V0.5 H-0.15 V0.15 H-0.5 Z",
+    "cross": "M-0.5 -0.29 L-0.29 -0.5 L0 -0.21 L0.29 -0.5 L0.5 -0.29 L0.21 0 L0.5 0.29 "
+             "L0.29 0.5 L0 0.21 L-0.29 0.5 L-0.5 0.29 L-0.21 0 Z",
+}
+
+#: Exact areas of the unit shapes (fractions of the unit box).
+_AREAS = {
+    "circle": math.pi / 4,
+    "square": 1.0,
+    "diamond": 0.5,
+    "triangle_up": _S3 / 4,
+    "triangle_down": _S3 / 4,
+    "triangle_left": _S3 / 4,
+    "triangle_right": _S3 / 4,
+    "plus": 0.51,
+    "cross": 0.5754,
+}
+
+#: Registered shapes: name → (path, area).
+MARKERS: dict[str, tuple[Path, float]] = {"circle": (ellipse_path(0, 0, 0.5, 0.5), math.pi / 4)}
+MARKERS.update((name, (parse_path_data(d), _AREAS[name])) for name, d in _DATA.items())
+
+_ALIASES = MARKER_ALIASES
+
+
+_PATH_DATA = re.compile(r"^\s*[Mm]\s*[-+.\d]")
+
+
+def _is_path_data(value: Any) -> bool:
+    return isinstance(value, str) and _PATH_DATA.match(value) is not None
+
+
+def _name(name: str) -> str:
+    key = name.strip().lower().replace("-", "_")
+    return _ALIASES.get(key, key)
+
+
+def add_marker(name: str, path: Any) -> None:
+    """Add a marker shape: a ``vec_io.Path`` or SVG path data in a unit box centred on the
+    origin.  Its area is measured from the outline."""
+    p = _as_path(path)
+    MARKERS[_name(name)] = (p, float(p.area()))
+
+
+def _as_path(path: Any) -> Path:
+    if isinstance(path, Path):
+        return path
+    if _is_path_data(path):
+        return parse_path_data(path)
+    raise ValueError(f"expected a vec_io Path or path data, got {path!r}")
+
+
+def resolve(marker: Any) -> tuple[Path, float]:
+    """``(path, area)`` of a marker name, ``Path`` or path data."""
+    if isinstance(marker, str) and not _is_path_data(marker):
+        try:
+            return MARKERS[_name(marker)]
+        except KeyError:
+            names = ", ".join(sorted(MARKERS))
+            raise ValueError(f"unknown marker {marker!r} (use {names}, a Path or path data)") \
+                from None
+    p = _as_path(marker)
+    return p, float(p.area())
+
+
+def check_marker(marker: Any) -> Any:
+    resolve(marker)
+    if isinstance(marker, str) and not _is_path_data(marker):
+        return _name(marker)
+    return marker
+
+
+def marker_area(marker: Any) -> float:
+    """Area of a marker's unit shape (fraction of its unit box)."""
+    return resolve(marker)[1]
+
+
+def area_factor(marker: Any) -> float:
+    """Size factor that gives ``marker`` the area of a circle of the same size."""
+    a = marker_area(marker)
+    return math.sqrt((math.pi / 4) / a) if a > 0 else 1.0