plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/color/values.py

@@ -0,0 +1,295 @@
+"""Color values: the ``color`` validator, named color scales, references to the plot's colors
+(``"C0"``) and operations on colors (alpha, saturation, luminance).
+
+Named color scales: ``"[variant] name [level]"``: ``"blue"``, ``"blue 0.45"``,
+``"pastel blue"``, ``"pastel blue 45%"``.
+
+Each name has eleven shades: levels 0.05 and 0.1 to 0.9 and 0.95 (Tailwind CSS 4's 50,
+100 to 900 and 950, in OKLCh); level 0 is white and level 1 black.  A level between two
+shades is interpolated in Oklab; the color is then gamut mapped into sRGB as CSS Color 4
+specifies (vec_io's ``oklab()``).  A bare name is its level 0.5.  These names take
+precedence over CSS's (``"red"`` is Red 0.5, not ``#ff0000``; ``"brown"`` is Brown 0.5,
+not ``#a52a2a``); other CSS names (``"navy"``) are vec_io's.
+
+Variants (:data:`VARIANTS`): ``base`` (Tailwind's), ``vivid``, ``pastel``, ``forest``,
+``dim``, ``arctic``, ``desert``, ``dusty``, ``neon``.  A name without a variant word takes
+the ``color_variant`` in effect where it is drawn (:class:`Named`, :func:`variant_of`).
+"""
+
+import colorsys
+import functools
+import re
+from typing import Any
+
+from vec_io.paint import CMYK, as_rgba, oklch_to_oklab, parse_color, srgb_to_oklab, to_rgba
+
+from .. import hints
+from ..units import Fixed
+from ..validators import Color, typed
+from .variants import TABLES, VARIANTS
+
+__all__ = ["SCALES", "VARIANTS", "VARIANT_DOC", "Named", "color", "split_colors", "scale_color", "scale_names",
+           "resolve_color", "variant_of", "check_variant", "with_alpha", "desaturate",
+           "luminance", "ink_for", "nearest_named"]
+
+#: The shades of each scale of the base variant (levels 0.05, 0.1–0.9, 0.95: Tailwind's 50,
+#: 100–900, 950) as OKLCh: lightness in %, chroma, hue in degrees.
+SCALES = {**TABLES["base"], "black": ((0, 0, 0),) * 11, "white": ((100, 0, 0),) * 11}
+_TABLES = {v: {**TABLES[v], "black": SCALES["black"], "white": SCALES["white"]}
+           for v in VARIANTS}
+_ALIASES = {"grey": "gray"}
+_RE = re.compile(r"^\s*(?:([a-z]+)\s+)?([a-z]+)(?:\s+(\d*\.?\d+(?:e[-+]?\d+)?)(%?))?\s*$", re.I)
+#: Stop positions: white, the eleven shades, black.
+_STOPS = (0.0, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.95, 1.0)
+
+
+def scale_names() -> list[str]:
+    return sorted(SCALES)
+
+
+#: The doc of the ``color_variant`` settings.
+VARIANT_DOC = ("Variant of the named colors written without one (`\"red\"`, color maps from names, "
+               "the style's colors): `base`, `vivid`, `pastel`, "
+               "`forest`, `dim`, `arctic`, `desert`, `dusty`, `neon`.")
+
+
+@typed("Literal[" + ", ".join(map(repr, VARIANTS)) + "]")
+def check_variant(v: Any) -> str:
+    """A variant word (``"pastel"``); ``ValueError`` naming the nine otherwise."""
+    if isinstance(v, str) and v.strip().lower() in VARIANTS:
+        return v.strip().lower()
+    raise ValueError(f"unknown color variant {v!r} (variants: {', '.join(VARIANTS)})")
+
+
+def _oklab(name: str, i: int, variant: str = "base") -> tuple[float, float, float]:
+    """Oklab of stop ``i`` of a scale (:data:`_STOPS`): 0 white, 1–11 the shades, 12
+    black."""
+    if i == 0:
+        return (1.0, 0.0, 0.0)
+    if i == 12:
+        return (0.0, 0.0, 0.0)
+    L, C, H = _TABLES[variant][name][i - 1]
+    return oklch_to_oklab(L / 100, C, H)
+
+
+@functools.lru_cache(maxsize=4096)
+def _hex(name: str, level: float, variant: str = "base") -> str:
+    if 0.1 <= level <= 0.9:                       # between shades 100 and 900
+        pos = level * 10
+        i = min(int(pos), 9)
+        t = pos - i
+        i += 1
+    else:                                         # white, 50, 100 or 900, 950, black
+        pos = (level if level < 0.1 else level - 0.9) * 20
+        i = min(int(pos), 1)
+        t = pos - i
+        if level > 0.9:
+            i += 10
+    a, b = _oklab(name, i, variant), _oklab(name, i + 1, variant)
+    if t < 1e-9 or t > 1 - 1e-9:
+        t = round(t)
+    lab = [x + (y - x) * t for x, y in zip(a, b)]
+    color = parse_color("oklab({!r} {!r} {!r})".format(*lab))
+    if color is None:                                     # not reached: valid oklab()
+        raise ValueError(f"no color for {name} {level}")
+    return "#" + "".join(f"{round(v * 255):02x}" for v in as_rgba(color)[:3])
+
+
+def rgba_of(c: Any) -> tuple[float, ...] | None:
+    """``(r, g, b, a)`` of a color (a print color's RGB approximation); ``None`` for none."""
+    r = to_rgba(c)
+    return None if r is None else as_rgba(r)
+
+
+def nearest_named(c: Any, level: float | None = None, variant: str = "base") -> Any:
+    """The named color closest to ``c`` (in Oklab) in ``variant``: the nearest of the
+    shades 100 to 900 (levels 0.1–0.9), or with ``level``, the scale of the nearest shade
+    at that level.  Colors vec_io cannot read (``None``, CMYK) are returned as given; alpha
+    is kept."""
+    if c is None or isinstance(c, CMYK):
+        return c
+    rgba = rgba_of(c)
+    if rgba is None:
+        return c
+    near = _nearest(tuple(round(v, 6) for v in rgba[:3]), level, variant)
+    return near if len(rgba) < 4 or rgba[3] >= 1 else with_alpha(near, rgba[3])
+
+
+@functools.lru_cache(maxsize=4096)
+def _nearest(rgb: tuple[float, ...], level: float | None, variant: str) -> str:
+    lab = srgb_to_oklab(*rgb)
+    best = (float("inf"), "", 0)
+    for name in SCALES:
+        for i in range(1, 10):
+            d = sum((x - y) ** 2 for x, y in zip(lab, _oklab(name, i + 1, variant)))
+            if d < best[0]:
+                best = (d, name, i)
+    _, name, i = best
+    return _hex(name, i / 10 if level is None else level, variant)
+
+
+class Named(Fixed):
+    """A named color as checked: ``source`` the text given, ``value`` its hex in its own
+    variant (``variant``, or base when it has none); a name without a variant word takes
+    the variant in effect where it is drawn (:meth:`in_variant`)."""
+
+    __slots__ = ("name", "level", "variant")
+
+    def __init__(self, source: str, name: str, level: float, variant: str | None) -> None:
+        super().__init__(source, _hex(name, level, variant or "base"))
+        self.name, self.level, self.variant = name, level, variant
+
+    def in_variant(self, variant: str) -> str:
+        """The hex in ``variant``, unless the name has its own."""
+        if self.variant is not None or variant == "base":
+            return self.value
+        return _hex(self.name, self.level, variant)
+
+    def in_context(self, obj: Any) -> str:
+        return self.value if self.variant is not None else self.in_variant(variant_of(obj))
+
+    @property
+    def varies(self) -> bool:
+        return self.variant is None
+
+
+def parse_named(text: Any) -> tuple[str, float, str | None] | None:
+    """``(scale, level, variant or None)`` of a named color (``"pastel blue 0.3"``);
+    ``None`` when ``text`` is not one.  A level outside 0–1 or an unknown variant word
+    before a scale name raises ``ValueError``."""
+    if not isinstance(text, str):
+        return None
+    m = _RE.match(text)
+    if m is None:
+        return None
+    name = m.group(2).lower()
+    name = _ALIASES.get(name, name)
+    if name not in SCALES:
+        return None
+    variant = m.group(1)
+    if variant is not None:
+        variant = variant.lower()
+        if variant not in VARIANTS:
+            raise ValueError(f"{text!r}: unknown color variant {m.group(1)!r} (variants: "
+                             f"{', '.join(VARIANTS)})")
+    level = 0.5 if m.group(3) is None else float(m.group(3)) / (100 if m.group(4) else 1)
+    if not 0 <= level <= 1:
+        raise ValueError(f"{text!r}: the level of a named color is in 0–1, got {level:g}")
+    return name, level, variant
+
+
+def scale_color(text: Any, variant: str = "base") -> str | None:
+    """``"#rrggbb"`` of a named color (``"name"``, ``"name level"``, level 0–1 or a
+    percentage, a variant word first or ``variant``); ``None`` when ``text`` is not a
+    named color.  A level outside 0–1 or an unknown variant word raises ``ValueError``."""
+    p = parse_named(text)
+    if p is None:
+        return None
+    return _hex(p[0], p[1], p[2] or variant)
+
+
+def variant_of(obj: Any) -> str:
+    """The ``color_variant`` in effect for ``obj``: its own setting, else its nearest
+    ancestor's that has the setting; ``"base"`` when none has it."""
+    o = obj
+    while o is not None:
+        settings = getattr(o, "SETTINGS", None)
+        if settings is not None and "color_variant" in settings:
+            return o.resolve("color_variant")
+        parent = getattr(o, "_parent", None)
+        o = parent() if parent is not None else None
+    return "base"
+
+
+def _color(v: Any) -> Any:
+    """A color vec_io accepts, a named color (``"blue"``, ``"pastel blue 0.45"``) or a
+    reference to the plot's colors ``"C0"``, ``"C1"``, …"""
+    if isinstance(v, Fixed):                          # already checked
+        return v
+    if isinstance(v, str) and len(v) >= 2 and v[0] in "Cc" and v[1:].isascii() and v[1:].isdigit():
+        return "C" + v[1:]
+    named = parse_named(v)
+    if named is not None:
+        return Named(v.strip(), *named)
+    try:
+        rgba = to_rgba(v)
+    except (TypeError, ValueError):
+        rgba = None
+    if rgba is None and not (isinstance(v, str) and v.strip().lower() in ("none", "transparent")):
+        raise ValueError(f"invalid color {v!r}{hints.color(v)}")
+    return v
+
+
+#: The validator of colors (``color(v)`` checks ``v``).
+color = Color(_color)
+
+
+def resolve_color(c: Any, cycle: tuple[Any, ...]) -> Any:
+    """A color with ``"C<n>"`` replaced by the plot's color ``n`` (of ``cycle``)."""
+    if isinstance(c, str) and len(c) >= 2 and c[0] == "C" and c[1:].isascii() and c[1:].isdigit():
+        return cycle[int(c[1:]) % len(cycle)]
+    if isinstance(c, str) and c.strip().lower() in ("none", "transparent"):
+        return None
+    return c
+
+
+def with_alpha(c: Any, opacity: float) -> Any:
+    """``c`` with its alpha multiplied by ``opacity`` (as an RGBA tuple)."""
+    if c is None:
+        return None
+    if opacity >= 1:
+        return c
+    if isinstance(c, CMYK):
+        return c.with_alpha(c.alpha * opacity)
+    rgba = rgba_of(c)
+    if rgba is None:
+        return None
+    a = rgba[3] if len(rgba) > 3 else 1.0
+    return (rgba[0], rgba[1], rgba[2], a * opacity)
+
+
+def desaturate(c: Any, k: float) -> Any:
+    """``c`` with its HLS saturation multiplied by ``k`` (as an RGBA tuple)."""
+    rgba = rgba_of(c)
+    if rgba is None:
+        return None
+    h, light, s = colorsys.rgb_to_hls(rgba[0], rgba[1], rgba[2])
+    r, g, b = colorsys.hls_to_rgb(h, light, s * k)
+    return (r, g, b, rgba[3] if len(rgba) > 3 else 1.0)
+
+
+def luminance(c: Any) -> float:
+    """Luma of ``c`` (0–1): Rec. 709 weights of its sRGB components (not linearized),
+    composited over white."""
+    if c is None:
+        return 1.0
+    rgba = rgba_of(c)
+    if rgba is None:
+        return 1.0
+    r, g, b = (float(x) for x in rgba[:3])
+    a = float(rgba[3]) if len(rgba) > 3 else 1.0
+    lum = 0.2126 * r + 0.7152 * g + 0.0722 * b
+    return a * lum + (1.0 - a)            # over a white background
+
+
+def ink_for(fill: Any) -> str:
+    """Black or white, whichever contrasts more with ``fill``."""
+    return "black" if luminance(fill) > 0.45 else "white"
+
+
+def split_colors(text: str) -> list[str] | None:
+    """The colors of a comma-separated list (``"violet 0.4, sky, rgb(1 2 3)"``; commas
+    inside parentheses do not split), or ``None`` when ``text`` has no list comma."""
+    parts, depth, start = [], 0, 0
+    for i, ch in enumerate(text):
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            parts.append(text[start:i])
+            start = i + 1
+    if not parts:
+        return None
+    parts.append(text[start:])
+    return [p.strip() for p in parts]