plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/color/maps.py

@@ -0,0 +1,922 @@
+"""Color maps: every set of colors, with a kind.
+
+A :class:`ColorMap` is a gradient over [0, 1]: its colors, their interpolation, the
+colors below, above and of missing values, and its kind (``qualitative``,
+``sequential``, ``diverging``, ``cyclic`` or none), which decides how it colors
+categories and numbers.  Which values go to 0 and 1 (the limits, the scale) is the
+business of a color axis (:mod:`plot_io.mapped`).  One registry holds every map, the
+qualitative ones included.
+
+Colors are computed by plot_io's C library: smooth, spline and Oklab maps evaluated there,
+bulk lookups through a table of 4,096 entries (steps exactly).
+"""
+
+import array
+import bisect
+import functools
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from vec_io.paint import lchuv_to_srgb, oklab_to_srgb, srgb_to_oklab
+
+from .. import kernels
+from .._native import kernels as _native
+from ..settings import one_of
+from .data import KINDS, MAPS, QUALITATIVE, qualitative_colors
+from ..units import Fixed
+from ..validators import typed
+from .values import VARIANTS, Named, color, parse_named, rgba_of, scale_color, split_colors
+
+__all__ = ["ColorMap", "add_color_map", "color_map_names", "check_color_map", "check_map",
+           "check_series_map", "kind_settings", "COLOR_MAP_HINT", "as_color_map", "map_of", "chosen_map", "cycle_of", "hue", "KINDS_OF_MAPS",
+           "MAP_WORDS"]
+
+RGBA = tuple[float, float, float, float]
+#: Entries of the table that bulk lookups of continuous maps read.
+LUT_SIZE = 4096
+_CLEAR: RGBA = (0.0, 0.0, 0.0, 0.0)
+#: Alphas closer to 1 than one 8-bit level are 1 (the gradients' rounding gives 1 - 2e-16).
+_OPAQUE = 1.0 - 1.0 / 255
+
+
+def _snapped(flat: array.array) -> array.array:
+    """``flat`` (RGBA rows) with alphas within one 8-bit level of 1 set to 1."""
+    for i in range(3, len(flat), 4):
+        if _OPAQUE < flat[i] < 1.0:
+            flat[i] = 1.0
+    return flat
+_check_interpolation = one_of("linear", "nearest", "smooth", "spline")
+#: The kinds of color maps.
+KINDS_OF_MAPS = ("qualitative", "sequential", "diverging", "cyclic")
+_check_kind = one_of(*KINDS_OF_MAPS)
+#: Words of ``color_map`` choosing the map of a kind by the use: ``"auto"`` and the kinds.
+MAP_WORDS = ("auto",) + KINDS_OF_MAPS
+#: Colors of a qualitative function of n taken for its steps (numbers mapped onto it).
+FUNCTION_STEPS = 10
+
+
+def hue(n: int, c: float = 100.0, lum: float = 65.0, start: float = 15.0) -> tuple[str, ...]:
+    """ggplot2's default discrete colors (``scales::hue_pal()``): ``n`` hues evenly spaced
+    from ``start`` degrees, at chroma ``c`` and luminance ``lum``."""
+    n = max(n, 1)
+    return tuple("#" + "".join("%02X" % round(255 * v)
+                               for v in lchuv_to_srgb(lum, c, start + 360.0 * i / n))
+                 for i in range(n))
+
+
+def _hex(c: Any) -> str:
+    """``"#RRGGBB"`` of a color (``"#RRGGBBAA"`` when translucent)."""
+    rgba = rgba_of(c)
+    if rgba is None:
+        raise ValueError(f"invalid color {c!r}")
+    out = "#" + "".join("%02X" % round(255 * v) for v in rgba[:3])
+    return out if len(rgba) < 4 or rgba[3] >= 1 else out + "%02X" % round(255 * rgba[3])
+
+
+def _mix_lab(rgba: Sequence[float], lab: tuple[float, float, float], k: float
+             ) -> tuple[float, float, float, float]:
+    """``rgba`` moved by ``k`` toward ``lab`` in Oklab (alpha kept)."""
+    L, a, b = srgb_to_oklab(*rgba[:3])
+    r, g, bl = oklab_to_srgb(L + (lab[0] - L) * k, a + (lab[1] - a) * k, b + (lab[2] - b) * k)
+    return (r, g, bl, float(rgba[3]) if len(rgba) > 3 else 1.0)
+
+
+def _mix(c: Any, lab: tuple[float, float, float], k: float) -> str:
+    """``c`` moved by ``k`` toward ``lab`` in Oklab, as hex."""
+    rgba = rgba_of(c)
+    if rgba is None:
+        raise ValueError(f"invalid color {c!r}")
+    return _hex(_mix_lab(rgba, lab, k))
+
+
+def _fraction(k: Any) -> float:
+    from ..validators import real
+    x = real(k)
+    if x is None or not 0 <= x <= 1:
+        raise ValueError(f"expected an amount in 0–1, got {k!r}")
+    return x
+
+
+def _in(c: Any, variant: str) -> Any:
+    """A checked color in ``variant`` (a named color without its own variant word)."""
+    return c.in_variant(variant) if isinstance(c, Named) else c.value if isinstance(c, Fixed) \
+        else c
+
+
+def _sized(f: Callable[[int], Any], variant: str) -> Callable[[int], tuple[Any, ...]]:
+    """The colors of a function of n, checked, in ``variant``."""
+    def colors(n: int) -> tuple[Any, ...]:
+        try:
+            out = tuple(_in(color(c), variant) for c in f(max(n, 1)))
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"color map function {f!r}: {e}") from None
+        if not out:
+            raise ValueError(f"color map function {f!r}: no colors")
+        return out
+    return colors
+
+
+def _widen(colors: list[Any], count: int, sides: float) -> list[Any]:
+    """Each inner color ``count`` times, each end color ``round(sides × count)`` times."""
+    if isinstance(count, bool) or not isinstance(count, int) or count < 1:
+        raise ValueError(f"widen_colors must be a whole number ≥ 1, got {count!r}")
+    if not 0 <= sides <= 1:
+        raise ValueError(f"widen_sides must be in 0–1, got {sides!r}")
+    if count == 1 and sides == 1:
+        return colors
+    ends = round(sides * count)
+    if ends == 0 and len(colors) == 2:
+        raise ValueError(f"widen_sides={sides!r} with widen_colors={count!r} leaves no end "
+                         "colors, and a list of two colors has no others")
+    if len(colors) == 1:
+        return [colors[0]] * max(ends, 1)
+    return [colors[0]] * ends + [c for c in colors[1:-1] for _ in range(count)] \
+        + [colors[-1]] * ends
+
+
+def _rgba(color: Any, variant: str = "base") -> RGBA:
+    if isinstance(color, Named):
+        color = color.in_variant(variant)
+    elif isinstance(color, Fixed):
+        color = color.value
+    try:
+        c = rgba_of(scale_color(color, variant) or color)
+    except (TypeError, ValueError):
+        c = None
+    if c is None:
+        raise ValueError(f"invalid color {color!r}")
+    return (float(c[0]), float(c[1]), float(c[2]), float(c[3]) if len(c) > 3 else 1.0)
+
+
+def _named(c: Any) -> bool:
+    """Whether ``c`` is a named color without a variant word."""
+    if isinstance(c, Named):
+        return c.variant is None
+    try:
+        p = parse_named(c)
+    except ValueError:
+        return False
+    return p is not None and p[2] is None
+
+
+def _hex_stops(data: str) -> list[tuple[float, RGBA]]:
+    colors = [(int(data[i:i + 2], 16) / 255, int(data[i + 2:i + 4], 16) / 255,
+               int(data[i + 4:i + 6], 16) / 255, 1.0) for i in range(0, len(data), 6)]
+    n = len(colors) - 1
+    return [(i / n, c) for i, c in enumerate(colors)]
+
+
+class _Default:
+    """The value of an extreme not given (the map's own, or none); ``None`` is none."""
+
+    def __repr__(self) -> str:
+        return "DEFAULT"
+
+
+DEFAULT: Any = _Default()
+
+Stops = tuple[tuple[float, RGBA], ...]
+#: Registered maps, whole (extremes included), by name (filled below the class).
+_REGISTRY: dict[str, "ColorMap"] = {}
+_ALIASES = {"gray": "grey"}
+#: Short prefixes of map names: ``"bwr"`` is ``"blue_white_red"``, ``"bwr_hc"``
+#: ``"blue_white_red_hc"``.
+_PREFIXES = {"bwr": "blue_white_red"}
+
+
+def _expand(name: str) -> str:
+    """``name`` with a short prefix written out (``"bwr_hc_r"`` → ``"blue_white_red_hc_r"``)."""
+    head, sep, tail = name.partition("_")
+    full = _PREFIXES.get(head)
+    return name if full is None else full + sep + tail
+
+
+def color_map_names(kind: str | None = None) -> list[str]:
+    """The registered names, sorted: all, or those of maps of ``kind``."""
+    if kind is None:
+        return sorted(_REGISTRY)
+    kind = _check_kind(kind)
+    return sorted(n for n, cm in _REGISTRY.items() if cm.kind == kind)
+
+
+def add_color_map(name: str, color_map: Any, replace: bool = False,
+                  kind: str | None = None) -> None:
+    """Register a map, extremes included, under ``name`` (also usable reversed, as
+    ``name + "_r"``, and with a variant word first): a ``ColorMap`` or anything its
+    ``colors`` accepts, of ``kind`` when given (``kind="qualitative"``: a list of colors
+    taken in turn, or a function ``n -> colors``).  A bundled map is replaced only with
+    ``replace=True``."""
+    key = name.strip().lower() if isinstance(name, str) else ""
+    if not key:
+        raise ValueError(f"a color map name is a non-empty string, got {name!r}")
+    if key.endswith("_r"):
+        raise ValueError(f"color map name {name!r}: a name ending in _r is the reversed map "
+                         f"of the name before it")
+    if key in _ALIASES:
+        raise ValueError(f"color map name {name!r} is another name of {_ALIASES[key]!r}")
+    if _expand(key) != key:
+        raise ValueError(f"color map name {name!r} is short for {_expand(key)!r}")
+    if key.partition(" ")[2] and key.partition(" ")[0] in VARIANTS:
+        raise ValueError(f"color map name {name!r}: a variant word first gives a map in "
+                         f"that variant")
+    if key in _BUNDLED and not replace:
+        raise ValueError(f"{name!r} is a bundled color map: give replace=True to replace it")
+    if isinstance(color_map, ColorMap) and (kind is None or kind == color_map.kind):
+        _REGISTRY[key] = color_map
+    else:
+        _REGISTRY[key] = ColorMap(color_map, kind=kind)
+
+
+def _reverse_stops(stops: Stops, interpolation: str) -> list[tuple[float, RGBA]]:
+    """Stops of the reversed map (steps start at their stop: their edges flip)."""
+    if interpolation == "nearest":
+        ends = [p for p, _ in stops[1:]] + [1.0]
+        return [(1.0 - e, c) for e, (_, c) in zip(reversed(ends), reversed(stops))]
+    return [(1.0 - p, c) for p, c in reversed(stops)]
+
+
+def _split(key: str) -> tuple[str | None, str]:
+    """``(variant word or None, name)`` of ``"pastel tab10_custom"``."""
+    head, _, rest = key.partition(" ")
+    if rest and head in VARIANTS:
+        return head, rest.strip()
+    return None, key
+
+
+def _lookup(name: str) -> tuple["ColorMap", str]:
+    """The registered map ``name`` (reversed for ``_r``; in a variant for a variant word
+    first: ``"pastel tab10_custom"``), and its key."""
+    key = " ".join(name.strip().lower().split())
+    variant, rest = _split(key)
+    rest = _expand(rest)
+    reverse = rest.endswith("_r") and rest not in _REGISTRY
+    base = rest[:-2] if reverse else rest
+    base = _ALIASES.get(base, base)
+    if base not in _REGISTRY:
+        import difflib
+        near = difflib.get_close_matches(rest, _REGISTRY, n=1)
+        hint = f" (did you mean {near[0]!r}?)" if near else ""
+        raise ValueError(f"unknown color map {name!r}{hint}")
+    cm = _REGISTRY[base]
+    if variant is not None:
+        if cm._recolor is None:
+            raise ValueError(f"color map {name!r}: {base!r} has no named colors for the "
+                             f"variant {variant!r} to recolor")
+        cm = cm.in_variant(variant)
+    return (cm.reversed() if reverse else cm), key
+
+
+class ColorMap:
+    """A set of colors of a kind: a gradient over [0, 1].
+
+    ``colors``: a registered name (``"viridis"``, ``"viridis_r"`` reversed,
+    ``"pastel tab10_custom"`` a map of named colors in one variant), a list of colors
+    (evenly spaced, or at ``positions``), another ``ColorMap`` (copied) or a function
+    ``t -> color`` (with ``kind="qualitative"``: a function ``n -> colors``, called with
+    the number of colors needed); default ``"rainbow_lc"`` (not a
+    style's ``sequential_map``).
+
+    ``kind``: ``"qualitative"``, ``"sequential"``, ``"diverging"``, ``"cyclic"`` or
+    ``None`` (default; a copied or registered map keeps its own).  Categories and series
+    take the colors of a qualitative map, or of a map of no kind, in turn (cycling), and
+    ``n`` colors evenly spaced from the others (end to end; a cyclic map's ``n`` around
+    its circle): :meth:`colors`.  Numbers on a qualitative map are steps, one color per
+    bin (its ``interpolation`` defaults to ``"nearest"``); on the others they are
+    interpolated.  ``under``/``over``: colors below 0 and above 1, the values past the
+    color axis' limits (default: the end colors); ``bad``: color of missing values
+    (default: transparent).  Not given, a copied or registered map keeps its own; ``None``
+    is none.  ``positions`` apply to a list of colors only.
+    ``space``: interpolation between the colors, ``"oklab"`` (default: perceptually even)
+    or ``"srgb"``.  ``interpolation``: ``"linear"`` (default) between neighboring colors;
+    ``"nearest"``, equal steps (``n`` colors give ``n`` bins; with ``positions``, each step
+    starts at its position); ``"smooth"``, a Bézier curve with the colors as control
+    points (through the first and last only; no ``positions``); ``"spline"``, a monotone
+    cubic curve through every color (no overshoot between colors).
+
+    ``widen_colors`` repeats each inner color of a list that many times, and each end
+    color ``round(widen_sides × widen_colors)`` times, widening the band of each color.
+    A list can be one string, the colors separated by commas.
+
+    A map is a value: immutable (the methods return changed copies), equal to another with
+    the same stops, space, interpolation, extremes and kind (the name aside), and hashable.
+
+    ``cm(t)``: the color at t; ``colors_at(ts)``: bulk colors (continuous maps through a
+    table of 4,096 colors, steps exactly); alphas within 1/255 of 1 are drawn as 1;
+    ``table(n)``: n colors sampled evenly; ``colors(n)``: the colors categories take
+    (above); ``cells(values, lo, hi, mode)``:
+    what heatmap cells hand vec_io's ``draw_cells``.  ``reversed()`` (under and over
+    swapped), ``resampled(n)`` (n flat steps), ``truncated(lo, hi)`` (a part stretched to
+    [0, 1]), ``with_extremes(…)``, ``lighter(k=0.25)``, ``darker(k=0.25)`` and
+    ``mix(color, k)`` (each color moved by ``k`` toward white, black or ``color`` in
+    Oklab) and ``in_variant(variant)`` return copies.  ``repr`` of a registered map is ``ColorMap('viridis')``.
+    A map is a set of colors only: the limits and scale of the values are their color
+    axis'.
+
+    Bundled (names in any case; ``_r`` reverses): viridis, magma, inferno, plasma (van der
+    Walt and Smith, CC0); cividis (Nuñez, Anderton and Renslow); coolwarm (Moreland);
+    rocket, mako, flare, crest, vlag, icefire (seaborn, Waskom, BSD-3-Clause); jet; a
+    parula-like map; turbo (Mikhailov, Google, Apache-2.0); ``ggplot2`` (``#132B43`` →
+    ``#56B1F7``); the rainbows from named colors (violet, sky, green, yellow, orange, rose;
+    ``widen_colors=6, widen_sides=0.6``, ``"smooth"``): ``rainbow`` (level 0.5),
+    ``rainbow_lc`` (0.4, the default ``sequential_map``), ``rainbow_l0`` (from white, then 0.083 to 0.5),
+    ``rainbow_l0hh`` (from white, then 0.1 to 0.6),
+    ``rainbow_llhh`` (0.16 to 0.6), ``rainbow_llh`` (0.16 to
+    0.4), ``rainbow_hlh`` (dark ends, light middle); diverging ``blue_white_red``,
+    ``blue_white_red_hc`` (the default ``diverging_map``), ``blue_white_red_smooth`` (smooth
+    interpolation), ``blue_white_red_smooth_hc`` (``bwr`` is short
+    for ``blue_white_red``: ``"bwr"``, ``"bwr_hc"``, ``"bwr_smooth_r"``), ``blue_gray_red``, ``blue_gray_red_hc``; ColorBrewer's (Brewer,
+    Apache-2.0) sequential ``blues`` … ``ylorrd`` (9 colors) and diverging ``brbg``, ``piyg``,
+    ``prgn``, ``puor``, ``rdbu``, ``rdgy``, ``rdylbu``, ``rdylgn``, ``spectral`` (11);
+    Crameri's Scientific colour maps 8 (MIT): sequential ``batlow`` … ``navia``, diverging
+    ``broc``, ``cork``, ``vik``, ``lisbon``, ``tofino``, ``berlin``, ``roma``, ``bam``,
+    ``vanimo``, ``managua``, multi-sequential ``oleron``, ``bukavu``, ``fes`` (diverging,
+    their break at the centre), cyclic ``romao``, ``bamo``, ``broco``, ``corko``,
+    ``viko``.  Qualitative: ``tab10_custom`` (the default; tab10's hues as named colors: sky,
+    amber, emerald, rose, purple 0.4, brown, pink 0.4, gray, lime, cyan);
+    ``tableau10_custom`` (Tableau 10's hues as named colors: sky, amber, rose, teal 0.4,
+    green, yellow, fuchsia, pink 0.4, brown, gray 0.4); ``qual`` (gray, yellow, emerald, rose, sky, brown, purple, lime, cyan); ``okabe_ito``
+    (Okabe–Ito's eight colorblind-safe colors plus indigo and dark brown); ``tab10``
+    (matplotlib ≥ 2.0, d3's category10); ``matplotlib_classic``; ``tableau10`` (Vega-Lite);
+    seaborn's ``deep``, ``muted``, ``pastel``, ``bright``, ``dark``, ``colorblind``;
+    ``hue`` (ggplot2's ``hue_pal()``: n hues 360/n apart from 15°); ``matlab``;
+    ``chartjs``; ``plotly``; ``observable10``; ``office``; ``economist``;
+    ``fivethirtyeight``; ColorBrewer's ``set1``, ``set2``, ``set3``, ``paired``,
+    ``accent``, ``dark2``, ``pastel1``, ``pastel2``; Crameri's categorical sets
+    ``batlow_s`` … ``navia_s`` (100 colors, the first differing most).  The maps not named
+    diverging, cyclic or qualitative here are sequential.  ``plt.registry.color_maps.names(kind=…)``
+    lists them.
+    """
+
+    __slots__ = ("stops", "space", "interpolation", "under", "over", "bad", "name", "kind",
+                 "_colors", "_function", "_positions", "_key", "_hash", "_lut", "_recolor",
+                 "_variants")
+
+    stops: Stops
+    space: str
+    interpolation: str
+    under: RGBA | None
+    over: RGBA | None
+    bad: RGBA | None
+    name: str | None
+    kind: str | None
+    #: the colors taken in turn (a list, or a qualitative map's), in this map's variant
+    _colors: tuple[Any, ...] | None
+    #: a qualitative function ``n -> colors`` (checked, in this map's variant)
+    _function: Callable[[int], tuple[Any, ...]] | None
+    _positions: list[float]
+    _key: tuple[Any, ...]
+    _hash: int | None
+    _lut: array.array | None
+    #: the map in a color variant (``variant -> ColorMap``), when built from named colors
+    _recolor: Any
+    _variants: dict[str, "ColorMap"] | None
+
+    def __init__(self, colors: Any = "rainbow_lc", positions: Sequence[float] | None = None,
+                 under: Any = DEFAULT, over: Any = DEFAULT, bad: Any = DEFAULT,
+                 space: str | None = None, name: str | None = None,
+                 interpolation: str | None = None, widen_colors: int = 1,
+                 widen_sides: float = 1.0, kind: str | None = None,
+                 _variant: str = "base") -> None:
+        if not (isinstance(colors, (ColorMap, str)) or callable(colors)):
+            colors = list(colors)
+        args = (colors, positions, under, over, bad, space, name, interpolation, widen_colors,
+                widen_sides, kind)
+        kind = None if kind is None else _check_kind(kind)
+        varies = False
+        interp = "linear"
+        mode = None if interpolation is None else _check_interpolation(interpolation)
+        if mode == "smooth" and positions is not None:
+            raise ValueError("smooth interpolation takes no positions (the colors are "
+                             "Bézier control points)")
+        even = False                      # stops evenly spaced (re-spaced for steps)
+        default_space = "oklab"
+        stops: list[tuple[float, RGBA]]
+        listed: tuple[Any, ...] | None = None
+        function: Callable[[int], tuple[Any, ...]] | None = None
+        own_kind: str | None = None
+        even_steps = False
+        if isinstance(colors, str) and (parts := split_colors(colors)) is not None:
+            colors = parts                # "violet 0.4, sky 0.4, …"
+        is_list = not (isinstance(colors, (ColorMap, str)) or callable(colors))
+        if (widen_colors != 1 or widen_sides != 1.0) and not is_list:
+            raise ValueError("widen_colors and widen_sides apply to lists of colors")
+        if positions is not None and not is_list:
+            raise ValueError("positions apply to a list of colors")
+        own: tuple[Any, Any, Any] = (None, None, None)     # the extremes of a map copied
+        if isinstance(colors, str):
+            colors, key = _lookup(colors)
+            name = name or key
+        copied = isinstance(colors, ColorMap)
+        if copied:
+            varies = colors._recolor is not None
+            colors = colors.in_variant(_variant)
+            stops, default_space = list(colors.stops), colors.space
+            interp = colors.interpolation
+            n = max(len(stops) - 1, 1)
+            even = colors.interpolation != "nearest" and all(
+                abs(p - i / n) < 1e-12 for i, (p, _) in enumerate(stops))
+            even_steps = colors.interpolation == "nearest" and len(stops) > 1 and all(
+                abs(p - i / len(stops)) < 1e-12 for i, (p, _) in enumerate(stops))
+            name = name or colors.name
+            own = (colors.under, colors.over, colors.bad)
+            listed, function, own_kind = colors._colors, colors._function, colors.kind
+        elif callable(colors) and kind == "qualitative":
+            function = _sized(colors, _variant)
+            cols = [_rgba(c) for c in function(FUNCTION_STEPS)]
+            varies = any(_named(c) for c in colors(FUNCTION_STEPS))
+            stops = [(i / len(cols), c) for i, c in enumerate(cols)]
+            interp = "nearest"
+        elif callable(colors):
+            try:
+                stops = [(i / 255, _rgba(colors(i / 255))) for i in range(256)]
+            except TypeError as e:
+                raise ValueError(f"color map function {colors!r}: {e} (a function t -> "
+                                 f"color; one of n -> colors takes kind=\"qualitative\")"
+                                 ) from None
+        else:
+            varies = any(_named(c) for c in colors)
+            cols = _widen([_rgba(c, _variant) for c in colors], widen_colors, widen_sides)
+            if not cols:
+                raise ValueError("a color map needs at least one color")
+            if positions is not None and (widen_colors != 1 or widen_sides != 1.0):
+                raise ValueError("widen_colors and widen_sides take no positions")
+            if positions is None:
+                n = max(len(cols) - 1, 1)
+                stops = [(i / n, c) for i, c in enumerate(cols)]
+                even = True
+            else:
+                pos = [float(p) for p in positions]
+                if len(pos) != len(cols):
+                    raise ValueError("give one position per color")
+                if any(b < a for a, b in zip(pos, pos[1:])) or pos[0] < 0 or pos[-1] > 1:
+                    raise ValueError("positions must increase within [0, 1]")
+                stops = list(zip(pos, cols))
+            if kind in (None, "qualitative"):
+                try:
+                    listed = tuple(_in(color(c), _variant) for c in colors)
+                except (TypeError, ValueError):
+                    listed = tuple(_hex(c) for c in cols)
+        if kind is None:
+            kind = own_kind
+        elif copied and kind != own_kind:
+            listed = function = None      # another kind: its colors come from its stops
+            if mode is None and (interp == "nearest") != (kind == "qualitative"):
+                mode = "nearest" if kind == "qualitative" else "linear"
+        if kind == "qualitative" and is_list and mode is None:
+            mode = "nearest"
+        if even_steps and mode not in (None, "nearest"):
+            n = len(stops) - 1                     # even steps → evenly spaced colors
+            stops = [(i / n, c) for i, (_, c) in enumerate(stops)]
+        if mode is not None:
+            if mode == "nearest" and even:
+                stops = [(i / len(stops), c) for i, (_, c) in enumerate(stops)]
+            interp = mode
+        varies = varies or any(_named(v) for v in (under, over, bad))
+        under, over, bad = (o if v is DEFAULT else v for v, o in zip((under, over, bad), own))
+        self._init(stops, one_of("oklab", "srgb")(space) if space is not None else default_space,
+                   interp, None if under is None else _rgba(under, _variant),
+                   None if over is None else _rgba(over, _variant),
+                   None if bad is None else _rgba(bad, _variant), name, kind, listed, function)
+        if varies and _variant == "base":
+            object.__setattr__(self, "_recolor", lambda v: ColorMap(*args, _variant=v))
+
+    def _init(self, stops: Sequence[tuple[float, RGBA]], space: str, interpolation: str,
+              under: RGBA | None, over: RGBA | None, bad: RGBA | None,
+              name: str | None, kind: str | None = None, colors: tuple[Any, ...] | None = None,
+              function: Callable[[int], tuple[Any, ...]] | None = None) -> None:
+        if len(stops) == 1:
+            stops = [(0.0, stops[0][1]), (1.0, stops[0][1])]
+        frozen = tuple((float(p), tuple(c)) for p, c in stops)
+        put = object.__setattr__
+        for k, v in (("stops", frozen), ("space", space), ("interpolation", interpolation),
+                     ("under", under), ("over", over), ("bad", bad), ("name", name),
+                     ("kind", kind), ("_colors", colors), ("_function", function),
+                     ("_positions", [p for p, _ in frozen]), ("_hash", None), ("_lut", None),
+                     ("_recolor", None), ("_variants", None)):
+            put(self, k, v)
+        put(self, "_key", (frozen, space, interpolation, under, over, bad, kind, function))
+
+    @classmethod
+    def _new(cls, stops: Sequence[tuple[float, RGBA]], space: str, interpolation: str,
+             under: RGBA | None, over: RGBA | None, bad: RGBA | None,
+             name: str | None, kind: str | None = None, colors: tuple[Any, ...] | None = None,
+             function: Callable[[int], tuple[Any, ...]] | None = None) -> "ColorMap":
+        """A map of these fields as they are (colors already RGBA)."""
+        cm = object.__new__(cls)
+        cm._init(stops, space, interpolation, under, over, bad, name, kind, colors, function)
+        return cm
+
+    def in_variant(self, variant: str) -> "ColorMap":
+        """This map with its named colors (those without a variant word) in ``variant``:
+        itself when it has none."""
+        if variant == "base" or self._recolor is None:
+            return self
+        cache = self._variants
+        if cache is None:
+            cache = {}
+            object.__setattr__(self, "_variants", cache)
+        out = cache.get(variant)
+        if out is None:
+            out = cache[variant] = self._recolor(variant)
+        return out
+
+    def _derived(self, out: "ColorMap", f: Any) -> "ColorMap":
+        """``out``, made by ``f`` from this map, following it into each variant."""
+        if self._recolor is not None:
+            object.__setattr__(out, "_recolor", lambda v: f(self.in_variant(v)))
+        return out
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        raise AttributeError("a ColorMap is immutable: with_extremes(), reversed(), "
+                             "truncated(), resampled() or ColorMap(color_map, …) make changed copies")
+
+    def __delattr__(self, key: str) -> None:
+        self.__setattr__(key, None)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ColorMap):
+            return NotImplemented
+        return self is other or self._key == other._key
+
+    def __hash__(self) -> int:
+        h = self._hash
+        if h is None:
+            h = hash(self._key)
+            object.__setattr__(self, "_hash", h)
+        return h
+
+    def __copy__(self) -> "ColorMap":
+        return self
+
+    def __deepcopy__(self, memo: Any) -> "ColorMap":
+        return self
+
+    def __reduce__(self) -> Any:
+        return (ColorMap._new, (self.stops, self.space, self.interpolation, self.under,
+                                self.over, self.bad, self.name, self.kind, self._colors,
+                                self._function))
+
+    def __repr__(self) -> str:
+        """``ColorMap('name')`` for a registered map unchanged, else the arguments that make
+        an equal map."""
+        if self.name:
+            try:
+                if ColorMap(self.name) == self:
+                    return f"ColorMap({self.name!r})"
+            except ValueError:
+                pass
+        stops = self.stops
+        n = len(stops)
+        args = [repr([c for _, c in stops])]
+        even = [i / n for i in range(n)] if self.interpolation == "nearest" \
+            else [i / max(n - 1, 1) for i in range(n)]
+        if self.interpolation != "smooth" and [p for p, _ in stops] != even:
+            args.append(f"positions={[p for p, _ in stops]!r}")
+        for key in ("under", "over", "bad"):
+            if getattr(self, key) is not None:
+                args.append(f"{key}={getattr(self, key)!r}")
+        if self.space != "oklab":
+            args.append(f"space={self.space!r}")
+        if self.interpolation != "linear":
+            args.append(f"interpolation={self.interpolation!r}")
+        if self.name:
+            args.append(f"name={self.name!r}")
+        if self.kind is not None:
+            args.append(f"kind={self.kind!r}")
+        return f"ColorMap({', '.join(args)})"
+
+    def _copy(self, **changes: Any) -> "ColorMap":
+        for key in ("under", "over", "bad"):
+            if changes.get(key) is not None:
+                changes[key] = _rgba(changes[key])
+        fields: dict[str, Any] = dict(
+            stops=self.stops, space=self.space, interpolation=self.interpolation,
+            under=self.under, over=self.over, bad=self.bad, name=self.name, kind=self.kind,
+            colors=self._colors, function=self._function)
+        fields.update(changes)
+        return ColorMap._new(**fields)
+
+    def __call__(self, t: float) -> RGBA:
+        """Color at ``t`` in [0, 1] (``under``/``over`` outside, ``bad`` for NaN)."""
+        t = float(t)
+        if t != t:
+            return self.bad if self.bad is not None else _CLEAR
+        if t < 0 and self.under is not None:
+            return self.under
+        if t > 1 and self.over is not None:
+            return self.over
+        return self._at(t)
+
+    def _at(self, t: float) -> RGBA:
+        """The gradient at ``t`` (clamped to the end colors)."""
+        stops, pos = self.stops, self._positions
+        if self.interpolation == "nearest":       # step k covers [pos[k], pos[k + 1])
+            return stops[max(bisect.bisect_right(pos, t) - 1, 0)][1]
+        c = self._eval([t])
+        return (c[0], c[1], c[2], c[3])
+
+    def _eval(self, ts: Sequence[float]) -> array.array:
+        return _snapped(_native.colormap_eval(self.stops, self.interpolation, self.space,
+                                              array.array("d", ts)))
+
+    def table(self, n: int = 256) -> list[RGBA]:
+        """``n`` colors sampled evenly over [0, 1]."""
+        ts = [i / (n - 1) for i in range(n)] if n > 1 else [0.0]
+        if self.interpolation != "nearest":
+            flat = self._eval(ts)
+            return [(flat[4 * i], flat[4 * i + 1], flat[4 * i + 2], flat[4 * i + 3])
+                    for i in range(len(ts))]
+        return [self._at(t) for t in ts]
+
+    def colors_at(self, ts: Any) -> Any:
+        """Colors at many positions in [0, 1] (an ``(n, 4)`` buffer, or a list): continuous
+        maps through a table of 4,096 entries, steps exactly."""
+        values = kernels.doubles(ts)
+        if self.interpolation == "nearest":
+            steps = array.array("d", self._positions)
+            table = _snapped(array.array("d", [v for _, c in self.stops for v in c]))
+        else:
+            lut = self._lut
+            if lut is None:                # a cache of the value: set once
+                lut = array.array("d", [v for c in self.table(LUT_SIZE) for v in c])
+                object.__setattr__(self, "_lut", lut)
+            steps, table = None, lut
+        out = _native.colors_at(values, table, steps, self.under, self.over, self.bad)
+        n = len(out) // 4
+        return memoryview(out).cast("B").cast("d", (n, 4)) if n else []
+
+    def cells(self, values: Any, lo: float, hi: float, mode: str = "image"
+              ) -> tuple[array.array, list[RGBA], list[float] | None]:
+        """``(fill, colors, bounds)`` of vec_io's ``Canvas.draw_cells`` for ``values`` (an
+        ``array('d')``, through the color scale) over ``[lo, hi]``.  Modes ``image`` and
+        ``cells``: indices into ``table(255)``, or into ``table(253)`` followed by the
+        under and over colors when the map has either.  ``smooth``: positions along
+        ``table(256)``, or for steps along the step colors with ``bounds`` between them.
+        NaN values are bad cells; -inf and +inf are below and above the range."""
+        if mode == "smooth":
+            fill, _ = _native.cells(values, lo, hi, 0, False)
+            if self.interpolation != "nearest":
+                return fill, self.table(256), None
+            ends = self._positions[1:] + [1.0]
+            kept = [(p, c) for (p, c), e in zip(self.stops, ends) if e > p]
+            if not kept:
+                return fill, [self.stops[-1][1]], []
+            return fill, [c for _, c in kept], [p for p, _ in kept[1:]]
+        split = self.under is not None or self.over is not None
+        fill, _ = _native.cells(values, lo, hi, 253 if split else 255, split)
+        table = self.table(253 if split else 255)
+        if split:
+            table += [self.under or table[0], self.over or table[-1]]
+        return fill, table, None
+
+    def reversed(self) -> "ColorMap":
+        stops = _reverse_stops(self.stops, self.interpolation)
+        name = None
+        if self.name:
+            name = self.name[:-2] if self.name.endswith("_r") else self.name + "_r"
+        f = self._function
+        return self._derived(self._copy(
+            stops=stops, under=self.over, over=self.under, name=name,
+            colors=None if self._colors is None else self._colors[::-1],
+            function=None if f is None else lambda n: f(n)[::-1]), ColorMap.reversed)
+
+    def resampled(self, n: int) -> "ColorMap":
+        """``n`` flat steps (a discrete map)."""
+        if n < 1:
+            raise ValueError("resampled() needs at least one step")
+        cols = [self((i + 0.5) / n) for i in range(n)]
+        return self._derived(self._copy(stops=[(i / n, c) for i, c in enumerate(cols)],
+                                        name=None, interpolation="nearest", colors=None,
+                                        function=None),
+                             lambda cm: cm.resampled(n))
+
+    def truncated(self, lo: float, hi: float) -> "ColorMap":
+        """The part between ``lo`` and ``hi``, stretched to [0, 1]."""
+        if not 0 <= lo < hi <= 1:
+            raise ValueError("truncated() needs 0 <= lo < hi <= 1")
+        if self.interpolation == "nearest":       # steps stay steps
+            ends = self._positions[1:] + [1.0]
+            kept = [(max(p, lo), c) for (p, c), e in zip(self.stops, ends) if e > lo and p < hi]
+            out = self._copy(stops=[((p - lo) / (hi - lo), c) for p, c in kept], name=None,
+                             interpolation="nearest", colors=None, function=None)
+        else:
+            n = 256
+            cols = [self(lo + (hi - lo) * i / (n - 1)) for i in range(n)]
+            out = self._copy(stops=[(i / (n - 1), c) for i, c in enumerate(cols)], name=None,
+                             interpolation="linear", colors=None, function=None)
+        return self._derived(out, lambda cm: cm.truncated(lo, hi))
+
+    def colors(self, n: int | None = None) -> tuple[Any, ...]:
+        """The colors categories and series take: of a qualitative map or a map of no kind,
+        its colors in turn (``n`` of them, cycling; all of them when ``n`` is None; a
+        function of n is called with ``n``); of the other kinds, ``n`` colors evenly spaced
+        (end to end; a cyclic map's around its circle; the colors of its stops when ``n``
+        is None)."""
+        if n is not None and (isinstance(n, bool) or not isinstance(n, int) or n < 0):
+            raise ValueError(f"colors() takes a count ≥ 0, got {n!r}")
+        if self._function is not None:
+            return self._function(n or 1)
+        if self.kind in (None, "qualitative") or n is None:
+            cols = self._colors
+            if cols is None:
+                cols = tuple(_hex(c) for _, c in self.stops)
+            return cols if n is None else tuple(cols[i % len(cols)] for i in range(n))
+        if self.kind == "cyclic":
+            ts = [i / n for i in range(n)]
+        else:
+            ts = [i / (n - 1) for i in range(n)] if n > 1 else [0.5]
+        return tuple(_hex(self._at(t)) for t in ts)
+
+    def mix(self, color: Any, k: float = 0.5) -> "ColorMap":
+        """Each color (extremes included, missing values aside) moved by ``k`` (0–1)
+        toward ``color``, in Oklab."""
+        rgba = _rgba(color)
+        k = _fraction(k)
+        out = self._moved(srgb_to_oklab(*rgba[:3]), k)
+        if _named(color):
+            object.__setattr__(out, "_recolor", lambda v: self.in_variant(v).mix(
+                _rgba(color, v), k))
+            return out
+        return self._derived(out, lambda cm: cm.mix(color, k))
+
+    def lighter(self, k: float = 0.25) -> "ColorMap":
+        """Each color moved by ``k`` (0–1) toward white, in Oklab."""
+        k = _fraction(k)
+        return self._derived(self._moved((1.0, 0.0, 0.0), k), lambda cm: cm.lighter(k))
+
+    def darker(self, k: float = 0.25) -> "ColorMap":
+        """Each color moved by ``k`` (0–1) toward black, in Oklab."""
+        k = _fraction(k)
+        return self._derived(self._moved((0.0, 0.0, 0.0), k), lambda cm: cm.darker(k))
+
+    def _moved(self, lab: tuple[float, float, float], k: float) -> "ColorMap":
+        """This map with each color moved by ``k`` toward ``lab``."""
+        f = self._function
+        return self._copy(
+            stops=[(p, _mix_lab(c, lab, k)) for p, c in self.stops], name=None,
+            under=None if self.under is None else _mix_lab(self.under, lab, k),
+            over=None if self.over is None else _mix_lab(self.over, lab, k),
+            colors=None if self._colors is None else tuple(_mix(c, lab, k)
+                                                          for c in self._colors),
+            function=None if f is None else lambda n: tuple(_mix(c, lab, k) for c in f(n)))
+
+    def with_extremes(self, under: Any = DEFAULT, over: Any = DEFAULT,
+                      bad: Any = DEFAULT) -> "ColorMap":
+        """A copy with the extremes given changed (``None``: none)."""
+        given = {k: v for k, v in (("under", under), ("over", over), ("bad", bad))
+                 if v is not DEFAULT}
+        out = self._copy(**given)
+        if any(_named(v) for v in given.values()):
+            object.__setattr__(out, "_recolor", lambda v: ColorMap(self.in_variant(
+                v), under=under, over=over, bad=bad, _variant=v))
+            return out
+        return self._derived(out, lambda cm: cm.with_extremes(under, over, bad))
+
+
+def _with_colors(cm: ColorMap, colors: tuple[str, ...]) -> ColorMap:
+    """``cm`` with the colors it takes in turn written as ``colors``."""
+    object.__setattr__(cm, "_colors", colors)
+    return cm
+
+
+for _name, _spec in MAPS.items():          # hex strings, or ColorMap arguments
+    _REGISTRY[_name] = ColorMap(**_spec, kind=KINDS[_name]) if isinstance(_spec, dict) else \
+        ColorMap._new(_hex_stops("".join(_spec)), "oklab", "linear", None, None, None, _name,
+                      KINDS[_name])
+for _name, _spec in QUALITATIVE.items():   # hex strings, or lists of named colors
+    _cm = _REGISTRY[_name] = ColorMap(
+        _spec if isinstance(_spec, list) else qualitative_colors(_name), name=_name,
+        kind="qualitative")
+    object.__setattr__(_cm, "_colors", qualitative_colors(_name))     # as "#RRGGBB"
+    if isinstance(_spec, list):            # in every variant as "#RRGGBB" too
+        object.__setattr__(_cm, "_recolor", lambda v, cm=_cm._recolor, n=_name: _with_colors(
+            cm(v), qualitative_colors(n, v)))
+_REGISTRY["hue"] = ColorMap(hue, name="hue", kind="qualitative")
+_BUNDLED = frozenset(_REGISTRY)
+
+
+def kind_settings() -> dict[str, Any]:
+    """The inherited settings of the map of each kind."""
+    from ..settings import Setting
+    return dict(
+        qualitative_map=Setting(check_map, inherited=True,
+                                doc="Colors of series and categories, taken in turn (a map "
+                                    "of another kind: evenly spaced): a map name, a "
+                                    "`ColorMap`, colors or a function `n -> colors`."),
+        sequential_map=Setting(check_map, inherited=True,
+                               doc="Map of numbers given as colors (`color_map=\"auto\"`)."),
+        diverging_map=Setting(check_map, inherited=True,
+                              doc="Map of numbers about a `center` (`color_map=\"auto\"`)."),
+        cyclic_map=Setting(check_map, inherited=True,
+                           doc="Map of `color_map=\"cyclic\"`."))
+
+
+#: The error's hint for ``color_map`` on a figure, a plot or in a style.
+COLOR_MAP_HINT = ("use qualitative_map=, sequential_map=, diverging_map= or cyclic_map= "
+                  "(color_map is set on what is colored: a series, a color axis)")
+
+
+def _word(v: Any) -> str | None:
+    """``v`` as a word of :data:`MAP_WORDS`, or ``None``."""
+    if isinstance(v, str):
+        w = v.strip().lower()
+        if w in MAP_WORDS:
+            return w
+    return None
+
+
+def check_color_map(v: Any) -> Any:
+    """A ``color_map``: ``"auto"``, a kind (the map of that kind's setting), or a
+    ``ColorMap`` or anything its ``colors`` accepts (as a ``ColorMap``)."""
+    w = _word(v)
+    return w if w is not None else as_color_map(v)
+
+
+@typed("ColorMap | str | Sequence[ColorLike] | ArrayLike | Callable[..., Any] | "
+       "Mapping[Any, ColorLike]")
+def check_series_map(v: Any) -> Any:
+    """A series' ``color_map``: as :func:`check_color_map`, or a dict level → color."""
+    if isinstance(v, dict):
+        from .values import color
+        return {k: color(c) for k, c in v.items()}
+    return check_color_map(v)
+
+
+def _one_argument(f: Callable[..., Any]) -> None:
+    """Refuse a function that cannot be called with one argument (``n`` or ``t``)."""
+    import inspect
+    try:
+        inspect.signature(f).bind(0)
+    except TypeError:
+        raise ValueError(f"color map function {f!r}: it must take one argument (n -> colors, "
+                         f"or t -> color)") from None
+    except ValueError:                                # no signature (a builtin): try at use
+        pass
+
+
+@typed("ColorMap | str | Sequence[ColorLike] | ArrayLike | Callable[..., Any]")
+def check_map(v: Any) -> Any:
+    """A ``qualitative_map``, ``sequential_map``, ``diverging_map`` or ``cyclic_map``: a map
+    name (kept, lowercase), a ``ColorMap``, colors, or a function (``n -> colors`` for
+    ``qualitative_map``, else ``t -> color``; called when the colors are needed)."""
+    if isinstance(v, ColorMap):
+        return v
+    if callable(v) and not isinstance(v, str):
+        _one_argument(v)
+        return v
+    if _word(v) is not None:
+        raise ValueError(f"{v!r} is a value of color_map only (on what is colored); give "
+                         f"a map name, a ColorMap or colors")
+    if isinstance(v, str) and split_colors(v) is None:
+        ColorMap(v)
+        return " ".join(v.strip().lower().split())
+    return as_color_map(v)
+
+
+def map_of(obj: Any, kind: str, variant: str | None = None) -> ColorMap:
+    """The map of ``obj``'s ``<kind>_map`` setting, in ``variant`` (default: ``obj``'s color
+    variant)."""
+    from .values import variant_of
+    holder = obj
+    while f"{kind}_map" not in holder.SETTINGS:      # a series: its plot's
+        holder = holder._parent()
+    v = holder.resolve(f"{kind}_map")
+    if callable(v) and not isinstance(v, ColorMap):
+        cm = ColorMap(v, kind="qualitative") if kind == "qualitative" else as_color_map(v)
+    else:
+        cm = as_color_map(v)
+    return cm.in_variant(variant_of(obj) if variant is None else variant)
+
+
+def cycle_of(cm: ColorMap, n: int = 1) -> tuple[Any, ...]:
+    """The colors ``n`` series take in turn from ``cm``: every color of a list (cycled), or
+    ``n`` of a function or of a map of another kind (evenly spaced)."""
+    if cm._function is None and cm.kind in (None, "qualitative"):
+        return cm.colors()
+    return cm.colors(max(n, 1))
+
+
+def chosen_map(obj: Any, value: Any, kind: str) -> ColorMap:
+    """The map a ``color_map`` value chooses, in ``obj``'s color variant: a kind word gives
+    ``obj``'s map of that kind, ``"auto"`` the map of ``kind`` (the use: ``"qualitative"``
+    for series and categories, ``"sequential"`` for numbers, ``"diverging"`` for numbers
+    about a centre)."""
+    from .values import variant_of
+    w = _word(value)
+    if w is not None:
+        return map_of(obj, kind if w == "auto" else w)
+    return as_color_map(value).in_variant(variant_of(obj))
+
+
+@functools.lru_cache(maxsize=64)
+def _shared(cm: ColorMap, varies: bool) -> ColorMap:
+    """The first of the equal maps made recently (one table of colors per value)."""
+    return cm
+
+
+def as_color_map(value: Any) -> ColorMap:
+    """``value`` as a ``ColorMap`` (a map given is returned as it is)."""
+    if isinstance(value, ColorMap):
+        return value
+    cm = ColorMap(value)
+    return _shared(cm, cm._recolor is not None)