plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/layers/paint.py

@@ -0,0 +1,614 @@
+"""Aesthetics resolved after training: series colors, mapped colors and sizes (through the
+series' color and size axes, :mod:`plot_io.mapped`), markers.
+
+A layer names its paint by a **role** (:class:`Paint`): ``marker`` (a :class:`MarkerStyle`),
+``stroke`` (lines and segments: color, width, dash), ``band`` (filled bands), ``key`` (a
+legend entry's ``(fill, stroke)``), ``text`` (labels), ``gradient`` (a color map's legend
+symbol), with options.  A role's colors come from a **source**
+(:func:`color_of`): the series color, it at ``opacity``, a color setting, or a method of the
+series giving the colors of its sets or items.  Presets add roles with :func:`role`.
+
+:class:`MarkerStyle` resolves the marker settings of a call (with a prefix: ``marker_`` on
+lines, error bars, stems, regressions and box outliers) into the arguments of vec_io's
+``draw_markers``.
+"""
+
+import array
+from typing import Any
+
+from vec_io.arrays import doubles
+
+from ..canvas import Canvas
+from .. import kernels
+from ..markers import area_factor, resolve
+from ..settings import Setting, number
+from ..validators import Custom, typed
+from ..color.values import resolve_color, with_alpha
+from ..lines import dash_of
+from ..spec import auto_colors as _auto_colors
+from ..values import Values, is_computed, paint, size_value
+
+__all__ = ["Paint", "ROLES", "role", "color_of", "memo", "paint", "colors_only", "size_value", "MarkerStyle", "permuted",
+           "order_settings", "order_index", "density_points", "xy_density_points",
+           "density_stats", "faded",
+           "color_map_of", "point_values", "base_color", "base_colors", "auto_colors",
+           "COLOR_SETTINGS", "SIZE_SETTINGS", "color_sources", "size_sources"]
+
+#: Settings that may hold colors to map (numbers or a ``Density``).
+COLOR_SETTINGS = ("color", "edge_color", "marker_color", "marker_edge_color")
+#: Settings that may hold sizes to map.
+SIZE_SETTINGS = ("size",)
+
+
+# ---------------------------------------------------------------------------
+# Paint roles
+# ---------------------------------------------------------------------------
+
+#: The paint roles: ``name → fn(series, ctx, glyph, **options)``.
+ROLES: dict[str, Any] = {}
+
+
+def role(name: str) -> Any:
+    """Register a paint role: ``fn(series, ctx, glyph, **options)`` gives the resolved
+    aesthetics of a layer (``glyph``: for its legend symbol)."""
+    def add(fn: Any) -> Any:
+        ROLES[name] = fn
+        return fn
+    return add
+
+
+class Paint:
+    """A layer's paint: role ``name`` of ``series`` with ``options``, resolved in a drawing
+    context (:meth:`resolve`, through :meth:`~plot_io.layers.core.Layer.style`)."""
+
+    __slots__ = ("series", "name", "options")
+
+    def __init__(self, series: Any, name: str, **options: Any) -> None:
+        if name not in ROLES:
+            raise ValueError(f"{series.kind}: unknown paint role {name!r} (roles: "
+                             f"{', '.join(sorted(ROLES))})")
+        self.series = series
+        self.name = name
+        self.options = options
+
+    def __repr__(self) -> str:
+        return f"Paint({self.name!r})"
+
+    def resolve(self, ctx: Any, glyph: bool) -> Any:
+        return ROLES[self.name](self.series, ctx, glyph, **self.options)
+
+
+def color_of(series: Any, ctx: Any, source: Any, index: int | None = None) -> Any:
+    """A color from ``source``: ``None``; ``"base"`` (the series color); ``"faded"`` (it
+    at ``opacity``); ``"name()"``, a method of the series called with ``ctx`` (a color, or
+    one per set: item ``index``); else a color setting's name."""
+    if source is None:
+        return None
+    if source == "base":
+        lv = series._lv
+        if lv is not None and lv.color is not None and lv.parts[0][0] is series:
+            return lv.item_colors(series, ctx)            # each point by its color level
+        return base_color(series, ctx)
+    if source == "faded":
+        return with_alpha(base_color(series, ctx), series.resolve("opacity"))
+    if source.endswith("()"):
+        v = getattr(series, source[:-2])(ctx)
+        if index is None:
+            return v
+        return v[index] if index < len(v) else None
+    return ctx.color(series.resolve(source))
+
+
+def memo(ctx: Any, key: Any, compute: Any) -> Any:
+    """``compute()`` once per drawing context of a plot (styles shared by a call's
+    layers)."""
+    cache = ctx.root.__dict__.setdefault("_memo", {})
+    if key not in cache:
+        cache[key] = compute()
+    return cache[key]
+
+
+@role("marker")
+def _marker_role(s: Any, ctx: Any, glyph: bool, prefix: str = "", color: Any = "base",
+                 n: int = 0, order: bool = False, once: bool = False,
+                 when: Any = None) -> Any:
+    """Markers (:class:`MarkerStyle`) of settings ``prefix…``; ``order``: in
+    ``draw_order``; ``once``: once per drawing context; ``when``: a condition
+    (:func:`~plot_io.layers.grammar.holds`; else no markers)."""
+    from .grammar import holds
+    if not holds(s, when):
+        return None
+
+    def make() -> MarkerStyle:
+        return MarkerStyle(s, ctx, prefix, color_of(s, ctx, color), n, glyph,
+                           order_index(s, n) if order and not glyph else None)
+
+    st = memo(ctx, (id(s), prefix, glyph), make) if once else make()
+    st.simplify = s.resolve("simplify")
+    return st
+
+
+@role("stroke")
+def _stroke_role(s: Any, ctx: Any, glyph: bool, color: Any = "base", index: Any = None,
+                 width: str = "line_width", dash: bool = False, opacity: bool = False,
+                 extra: tuple[str, ...] = (), fixed: Any = None, drop_zero: bool = False,
+                 empty: bool = False) -> dict[str, Any]:
+    """Lines and segments: ``color`` (a source, :func:`color_of`), the ``width`` setting,
+    the dash of ``line_style`` (``dash``), ``opacity`` (1 when unset); drawn on the axes
+    (not ``glyph``): the ``extra`` settings and ``fixed`` values, no color when the width
+    is 0 (``drop_zero``) or the set is ``empty``."""
+    w = s.resolve(width)
+    p = {"color": color_of(s, ctx, color, index), "width": w}
+    if dash:
+        p["dash"] = dash_of(s.resolve("line_style"), w)
+    if opacity:
+        o = s.resolve("opacity")
+        p["opacity"] = 1.0 if o is None else o
+    if not glyph:
+        if (drop_zero and not w) or empty:
+            p["color"] = None
+        for k in extra:
+            p[k] = s.resolve(k)
+        if fixed:
+            p.update(fixed)
+    return p
+
+
+@role("band")
+def _band_role(s: Any, ctx: Any, glyph: bool, color: Any = "base", index: Any = None,
+               opacity: str | float | None = None, edges: bool = False,
+               extra: tuple[str, ...] = ()) -> dict[str, Any]:
+    """Filled bands: ``color`` (a source), ``opacity`` (a number, or the setting named), the
+    ``color_below`` and outline settings (``edges``), the ``extra`` settings."""
+    p = {"color": color_of(s, ctx, color, index)}
+    if opacity is not None:
+        p["opacity"] = s.resolve(opacity) if isinstance(opacity, str) else opacity
+    if edges:
+        p["below"] = ctx.color(s.resolve("color_below"))
+        p["edge"] = ctx.color(s.resolve("edge_color"))
+        p["edge_width"] = s.resolve("edge_width")
+    for k in extra:
+        p[k] = s.resolve(k)
+    return p
+
+
+@role("key")
+def _key_role(s: Any, ctx: Any, glyph: bool, fill: Any = None, stroke: Any = None,
+              index: Any = None, marker: Any = None, when: Any = None) -> tuple[Any, Any]:
+    """A legend entry's ``(fill, stroke)``: two sources (:func:`color_of`); ``"marker"``:
+    the first colors of the ``marker`` paint's legend markers; ``"symbol"``: the colors of
+    the ``marker`` paint's legend symbol (rectangles); ``when``: a setting whose width
+    must be non-zero for the stroke."""
+    def one(source: Any, which: str) -> Any:
+        if source == "marker":
+            return marker.resolve(ctx, True).first_color(which)
+        if source == "symbol":
+            return marker.resolve(ctx, True)[which]
+        return color_of(s, ctx, source, index)
+    if when is not None and not s.resolve(when):
+        stroke = None
+    return one(fill, "fill"), one(stroke, "stroke")
+
+
+@role("text")
+def _text_role(s: Any, ctx: Any, glyph: bool, font: Any = None, **extra: Any) -> dict[str, Any]:
+    """Labels: ``font(ctx)``, and the ``extra`` values (functions of ``ctx`` called)."""
+    return {"font": font(ctx), **{k: (v(ctx) if callable(v) else v) for k, v in extra.items()}}
+
+
+@role("gradient")
+def _gradient_role(s: Any, ctx: Any, glyph: bool, cmap: Any = None) -> dict[str, Any]:
+    """A color map drawn as a gradient (``cmap()``: the map, or ``None``)."""
+    return {"map": cmap()}
+
+
+# ---------------------------------------------------------------------------
+# Series colors and maps
+# ---------------------------------------------------------------------------
+
+def auto_colors(series: Any, ctx: Any) -> list[Any]:
+    """The plot's colors the series took in training (one per value set)."""
+    cols = _auto_colors(series) or [None]
+    return [ctx.color(c) for c in cols]
+
+
+def base_colors(series: Any, ctx: Any, keys: list[Any], what: str = "sets",
+                items: bool = False, saturation: bool = True) -> list[Any]:
+    """The base color of each set (or each item, ``items``) named by ``keys``, before
+    opacity: numbers through the series' color axis (items), the colors given (one, a
+    list, a dict by set or item), else the plot's colors (each set its color; items the series
+    color); ``saturation`` applied when the series has it."""
+    from ..color.values import desaturate
+    s = series
+    c = s.resolve("color")
+    n = len(keys)
+    cols: list[Any]
+    if items and isinstance(c, Values):
+        from ..mapped import color_axis_of, unit_of
+        from ..presets._util import per_category
+        axis = color_axis_of(s)
+        cm, t = axis.color_map(), unit_of(axis)
+        cols = [cm(t(v)) for v in per_category(s, keys, c.data, what)]
+    elif isinstance(c, dict) and items:
+        cols = [ctx.color(c[k]) if c.get(k) is not None else None for k in keys]
+    elif isinstance(c, dict):
+        unknown = [k for k in c if k not in keys]
+        if unknown:
+            raise ValueError(f"color: no {what[:-1]} {unknown[0]!r}")
+        auto = auto_colors(s, ctx) if len(c) < n else []
+        cols = [ctx.color(c[k]) if k in c else (auto[i] if i < len(auto) else None)
+                for i, k in enumerate(keys)]
+    elif isinstance(c, list):
+        if len(c) != n:
+            raise ValueError(f"{len(c)} colors for {n} {what}")
+        cols = [ctx.color(x) for x in c]
+    elif items:
+        cols = [base_color(s, ctx)] * n
+    elif c is not None:
+        cols = [ctx.color(c)] * n
+    else:
+        cols = auto_colors(s, ctx)
+    sat = s.resolve("saturation") if saturation and "saturation" in s.SETTINGS else 1.0
+    if sat != 1.0:
+        cols = [desaturate(x, sat) if x is not None else None for x in cols]
+    return cols
+
+
+def base_color(series: Any, ctx: Any) -> Any:
+    """The series color: its own, or the plot's color it was given."""
+    c = series.resolve("color") if "color" in series.SETTINGS else None
+    if c is None:
+        c = (_auto_colors(series) or [None])[0]
+    return ctx.color(c)
+
+
+def color_map_of(series: Any) -> Any:
+    """The gradient numbers in the series' colors are drawn with (its color axis')."""
+    from ..mapped import color_axis_of
+    return color_axis_of(series).color_map()
+
+
+def point_values(series: Any, v: Any) -> Any:
+    """The numbers of a value setting: given ``Values``, sizes, or a computed ``Density``."""
+    if isinstance(v, Values):
+        return v.data
+    if is_computed(v):
+        return series.cached(("density", id(v)), lambda: v.compute(series))
+    return v
+
+
+def color_sources(series: Any) -> list[tuple[Any, Any]]:
+    """``(color axis, values)`` of the series' color settings holding numbers or a
+    density."""
+    from ..mapped import color_axis_of
+    out = []
+    for name in COLOR_SETTINGS:
+        if name in series.SETTINGS:
+            v = series.resolve(name)
+            if isinstance(v, Values) or is_computed(v):
+                out.append((color_axis_of(series), point_values(series, v)))
+    return out
+
+
+def size_sources(series: Any) -> list[tuple[Any, Any]]:
+    """``(size axis, values)`` of the series' size settings mapping values."""
+    from ..mapped import size_axis_of
+    out = []
+    for name in SIZE_SETTINGS:
+        axis = size_axis_of(series, name)
+        if axis is not None:
+            out.append((axis, point_values(series, series.resolve(name))))
+    return out
+
+
+def colors_only(v: Any) -> Any:
+    """A color or a list of colors (series whose colors are per value set, not mapped)."""
+    out = paint(v)
+    if isinstance(out, Values) or is_computed(out):
+        raise ValueError("expected a color or a list of colors (values to map are not "
+                         "accepted here)")
+    return out
+
+
+def permuted(v: Any, idx: Any) -> Any:
+    """A per-point column (list, ``array('d')``, ``(n, 4)`` buffer) reordered by ``idx``
+    (gathered in C for numeric columns); single values unchanged."""
+    if isinstance(v, list):
+        return [v[i] for i in idx]
+    if isinstance(v, array.array):
+        n = len(idx)
+        if len(v) == 4 * n and n != 4:                    # flat RGBA
+            return kernels.take(memoryview(v).cast("B").cast("d", (len(v) // 4, 4)), idx)
+        return kernels.take(v, idx)
+    if isinstance(v, memoryview) and v.ndim == 2:
+        m: Any = v
+        k = m.shape[1]
+        out_mv: Any = memoryview(kernels.take(m, idx)).cast("B")
+        return out_mv.cast("d", (len(idx), k))
+    return v
+
+
+def order_index(series: Any, n: int) -> Any:
+    """The drawing order of a series' ``draw_order`` setting, or ``None`` (call order)."""
+    from ..density import Density
+    o = series.resolve("draw_order")
+    if o is None:
+        return None
+    descending = False
+    if isinstance(o, str):
+        descending = o.startswith("-")
+        dens = next((series.resolve(k) for k in ("color", "size", "opacity")
+                     if k in series.SETTINGS and isinstance(series.resolve(k), Density)), None)
+        o = dens if dens is not None else series.cached("order_density", Density)
+    if isinstance(o, Density):
+        keys = point_values(series, o)
+    elif isinstance(o, Values):
+        keys = o.data
+    else:
+        keys = o
+    if len(keys) != n:
+        raise ValueError(f"draw_order: {len(keys)} order keys for {n} points")
+    return kernels.argsort(keys, descending=descending)
+
+
+@typed("Literal['density', '-density'] | Density | Column")
+def order_value(v: Any) -> Any:
+    """``draw_order``: ``"density"``, ``"-density"``, a ``Density`` or sort keys per
+    point."""
+    from ..density import Density
+    if isinstance(v, Density):
+        return v
+    if isinstance(v, str):
+        if v.strip().lower() in ("density", "-density"):
+            return v.strip().lower()
+        raise ValueError(f"expected 'density', '-density' or sort keys, got {v!r}")
+    if isinstance(v, (bytes, bytearray)):
+        raise ValueError(f"expected 'density', '-density' or sort keys, got {v!r}")
+    return doubles(v.to_numpy() if hasattr(v, "to_numpy") else v)
+
+
+_OPACITY = number(0, 1)
+
+
+@typed("SupportsFloat | Literal['density'] | Density")
+def _opacity_value(v: Any) -> Any:
+    from ..density import Density
+    if isinstance(v, Density):
+        return v
+    if isinstance(v, str) and v.strip().lower() == "density":
+        return Density()
+    return _OPACITY(v)
+
+
+#: ``opacity``: a number in [0, 1], or ``"density"`` / a ``Density``.
+opacity_value = Custom(_opacity_value, like=_OPACITY)
+
+
+def order_settings() -> dict[str, Setting]:
+    """``draw_order``, ``opacity`` (numbers or a density) and ``opacity_range``."""
+    from ..settings import pair
+    return {
+        "draw_order": Setting(order_value,
+                              doc="Drawing order: `\"density\"` (densest drawn last), "
+                                  "`\"-density\"`, or sort keys per point (ascending); "
+                                  "default: call order."),
+        "opacity": Setting(opacity_value, inherited=True,
+                         doc="Opacity, multiplying the colors' own; or `\"density\"` / a "
+                             "`Density`, mapped linearly to `opacity_range`."),
+        "opacity_range": Setting(pair(number(0, 1)),
+                               doc="Opacities of the least and most dense points when "
+                                   "`opacity` is a density."),
+    }
+
+
+def density_points(series: Any, xs: Any, ys: Any) -> tuple[Any, Any]:
+    """Points ``(xs, ys)`` on the plot's axis positions (log axes in log space)."""
+    from ..scales import get_scale
+    out = []
+    for v, axis in ((xs, series.plot.x_axis), (ys, series.plot.y_axis)):
+        name = axis.resolve("scale")
+        fn = get_scale(name, axis.resolve("linthresh")).function \
+            if name not in (None, "category", "time") else None
+        out.append(kernels.scaled(v, 1.0, 0.0, fn) if fn else doubles(v))
+    return out[0], out[1]
+
+
+def xy_density_points(series: Any, xs: Any, ys: Any) -> tuple[Any, Any]:
+    """:func:`density_points` of an ``(x, y)`` series, whose ``orientation="horizontal"``
+    puts x on the plot's y axis."""
+    if "orientation" in series.SETTINGS and series.resolve("orientation") == "horizontal":
+        return density_points(series, ys, xs)
+    return density_points(series, xs, ys)
+
+
+def density_stats(series: Any) -> dict[str, Any]:
+    """``{"density": values}`` when a setting of the series maps a density."""
+    from ..density import Density
+    for k in ("color", "edge_color", "size", "opacity", "draw_order"):
+        if k in series.SETTINGS and isinstance(series.resolve(k), Density):
+            return {"density": point_values(series, series.resolve(k))}
+    if "draw_order" in series.SETTINGS and isinstance(series.resolve("draw_order"), str):
+        return {"density": point_values(series, series.cached("order_density", Density))}
+    return {}
+
+
+def faded(paint: Any, opacity: float) -> Any:
+    """A resolved paint (a color, a list of colors or flat RGBA values) at ``opacity``; a
+    list's colors computed once per distinct color."""
+    if isinstance(paint, array.array):
+        out = array.array("d", paint)
+        out[3::4] = kernels.scaled(out[3::4], opacity)
+        return out
+    if isinstance(paint, list):
+        done: dict[Any, Any] = {}
+        colors: list[Any] = []
+        for c in paint:
+            if c is None:
+                colors.append(None)
+                continue
+            k = c if isinstance(c, (str, tuple)) else id(c)
+            if k not in done:
+                done[k] = with_alpha(c, opacity)
+            colors.append(done[k])
+        return colors
+    if isinstance(paint, memoryview):      # (n, 4) colors from a ColorMap
+        flat = faded(array.array("d", paint.cast("B").cast("d")), opacity)
+        return memoryview(flat).cast("B").cast("d", (len(flat) // 4, 4))
+    return with_alpha(paint, opacity)
+
+
+class MarkerStyle:
+    """Resolved marker arguments for ``Canvas.draw_markers`` (the paint of a ``Points``
+    layer)."""
+
+    def __init__(self, series: Any, ctx: Any, prefix: str = "", default_color: Any = None,
+                 n: int = 0, glyph: bool = False, order: Any = None) -> None:
+        self.glyph_only = glyph
+        self.order = None if glyph else order
+        self.simplify: Any = None
+        g = series.resolve
+        p = prefix
+        size_name = "size" if not p else "marker_size"
+        color_name = "color" if not p else "marker_color"
+        opacity = g("opacity")
+        if is_computed(opacity) and glyph:
+            opacity = series.resolve("opacity_range")[1]
+        elif is_computed(opacity):
+            lo, hi = series.resolve("opacity_range")
+            vals = self._take(point_values(series, opacity))
+            _, vmin, vmax = kernels.extent(vals, None)
+            span = (vmax - vmin) if vmax > vmin else 1.0
+            k = (hi - lo) / span
+            opacity = kernels.scaled(vals, k, lo - k * vmin, None, nan=0.0)
+        self.opacity = 1.0 if opacity is None else opacity
+        marker = g("marker")
+        basis = g("size_basis")
+        size = g(size_name)
+        if isinstance(marker, list):
+            marker = self._take(marker)
+        if isinstance(size, array.array):
+            size = self._take(size)
+        if isinstance(marker, list) and glyph:
+            marker = marker[0]
+        if isinstance(marker, list):
+            if len(marker) != n:
+                raise ValueError(f"{len(marker)} markers for {n} points")
+            resolved = [resolve(m) for m in marker]
+            self.marker: Any = [r[0] for r in resolved]
+            factor: Any = array.array("d", [area_factor(m) if basis == "area" else 1.0
+                                            for m in marker])
+        else:
+            self.marker = resolve(marker)[0]
+            factor = area_factor(marker) if basis == "area" else 1.0
+        from ..mapped import size_axis_of
+        size_axis = size_axis_of(series, size_name)
+        if size_axis is not None and glyph:
+            size = sum(size_axis.size_map().diameters(series)) / 2
+        elif size_axis is not None:
+            from ..mapped import trained
+            values = self._take(point_values(series, size))
+            st = trained(size_axis)
+            assert st.scale is not None
+            size = size_axis.size_map().map(values, st.flo, st.fhi, st.scale.function, series)
+        if isinstance(size, array.array) and glyph:
+            finite = sorted(v for v in size[::max(1, len(size) // 1000)] if v == v)
+            size = finite[len(finite) // 2] if finite else 4.0
+        if isinstance(size, array.array):
+            if len(size) != n:
+                raise ValueError(f"{series.kind} setting {size_name!r}: {len(size)} sizes "
+                                 f"for {n} points")
+            if isinstance(factor, array.array):
+                size = array.array("d", [s * f for s, f in zip(size, factor)])
+            elif factor != 1.0:
+                size = kernels.scaled(size, factor)
+        elif isinstance(factor, array.array):
+            size = array.array("d", [size * f for f in factor])
+        else:
+            size = size * factor
+        self.size = size
+        fill = g(color_name)
+        if fill is None:
+            fill = default_color
+        self.fill = self._paint(fill, series, ctx, n, color_name)
+        edge = g(f"{p}edge_color")
+        filled = g(f"{p}fill") is True
+        opacity = g(f"{p}fill_opacity") if filled else 0.0
+        opaque = filled and (opacity is None or opacity >= 1)
+        if edge == "auto":                            # white around opaque markers
+            edge = "white" if opaque else None
+        self.stroke = self._paint(edge, series, ctx, n, f"{p}edge_color")
+        self.line_width = g(f"{p}edge_width")
+        if not opaque and self.fill is not None:
+            if self.stroke is None:
+                self.stroke = self.fill
+            self.fill = faded(self.fill, opacity) if filled else None
+        if self.stroke is None or not self.line_width:
+            self.stroke, self.line_width = None, None
+
+    def _paint(self, value: Any, series: Any, ctx: Any, n: int, name: str) -> Any:
+        if value is None:
+            return None
+        mapped = isinstance(value, Values) or is_computed(value)
+        if mapped and self.glyph_only:
+            return color_map_of(series)(0.5)
+        if isinstance(value, list) and self.glyph_only:
+            return resolve_color(next((c for c in value if c is not None), None), ctx.cycle)
+        if isinstance(value, memoryview) and self.glyph_only:
+            return tuple(value[0, k] for k in range(4)) if len(value) else None
+        if mapped:
+            values = self._take(point_values(series, value))
+            if len(values) != n:
+                raise ValueError(f"{series.kind}: {name} has {len(values)} color values for "
+                                 f"{n} points")
+            from ..mapped import color_axis_of, colors_of
+            return colors_of(color_axis_of(series), values)
+        if isinstance(value, memoryview):
+            if len(value) != n:
+                raise ValueError(f"{series.kind}: {name} has {len(value)} colors for {n} points")
+            return self._take(value)
+        if isinstance(value, list):
+            if len(value) != n:
+                raise ValueError(f"{series.kind}: {name} has {len(value)} colors for {n} points")
+            return [resolve_color(c, ctx.cycle) for c in self._take(value)]
+        return resolve_color(value, ctx.cycle)
+
+    def first_color(self, which: str = "fill") -> Any:
+        v = self.fill if which == "fill" else self.stroke
+        if v is None or isinstance(v, (str, tuple)):
+            return v
+        if isinstance(v, list):
+            return next((c for c in v if c is not None), None)
+        if isinstance(v, array.array):        # flat RGBA
+            return tuple(v[:4]) if len(v) >= 4 else None
+        if isinstance(v, memoryview) and v.ndim == 2:
+            m: Any = v
+            return tuple(m[0, k] for k in range(m.shape[1])) if len(m) else None
+        try:
+            return tuple(v[0])
+        except (TypeError, IndexError):
+            return None
+
+    def _take(self, v: Any) -> Any:
+        """A per-point input in drawing order (``draw_order``), before colors are mapped."""
+        return v if self.order is None or v is None else permuted(v, self.order)
+
+    def draw(self, canvas: Canvas, xs: Any, ys: Any, simplify: Any) -> None:
+        if self.fill is None and self.stroke is None:
+            return
+        canvas.draw_markers(xs, ys, marker=self.marker, size=self.size, fill=self.fill,
+                            stroke=self.stroke, stroke_width=self.line_width,
+                            opacity=self.opacity, simplify=simplify)
+
+    def key_values(self) -> tuple[Any, ...] | None:
+        """``(marker, size, fill, stroke, line_width, opacity)`` of the marker a legend
+        symbol draws (the median size, the first colors); ``None`` when it has no color."""
+        size = self.size
+        if not isinstance(size, (int, float)):
+            finite = [s for s in size if s == s]
+            size = sorted(finite)[len(finite) // 2] if finite else 4.0
+        marker = self.marker[0] if isinstance(self.marker, list) else self.marker
+        fill = self.first_color("fill")
+        stroke = self.first_color("stroke")
+        if fill is None and stroke is None:
+            return None
+        return marker, size, fill, stroke, self.line_width, self.opacity