Source code for palettes.wheel

# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""HSV and RGB color-wheel palettes.

Build a smooth color wheel or fixed-saturation HSV ramp. Named Windows
16-color attributes (``RED``, ``BLACK``, etc.) are available on each
instance.

Example:
    >>> from palettes import get_palette
    >>> palette = get_palette(name="wheel", length=256, saturation=1.0)
    >>> palette[0]
    >>> palette.RED
"""

from . import Palette as _Palette


[docs] class WheelPalette(_Palette): """Color wheel or HSV ramp palette. This is a good fit for animated gradients, rainbow effects, and other continuous color ramps. The default wheel mode produces a smooth cycling palette that can be sampled across a strip or a full-screen gradient. When either ``saturation`` or ``value`` is set, indices map linearly through hue at a fixed saturation and brightness for more controlled ramps. Args: name (str): Prefix for `name <palettes.Palette.name>` (length suffix is added). color_depth (int): Output format; see `Palette <palettes.Palette>`. swapped (bool): Byte-swap 16-bit colors when ``True``. cached (bool): Memoize index lookups when ``True`` (default). length (int): Number of colors in the wheel (default ``256``). saturation (float): HSV saturation in ``0.0``–``1.0``, or ``None`` for classic wheel mode. value (float): HSV value in ``0.0``–``1.0``, or ``None`` for classic wheel mode. Raises: ValueError: If ``saturation`` or ``value`` is outside ``0``–``1`` in HSV mode. """ def __init__( self, name="", color_depth=16, swapped=False, cached=True, length=256, saturation=1.0, value=None, ): """Create a wheel or fixed-saturation HSV ramp palette. Args: name (str): Prefix for `name <palettes.Palette.name>` (length suffix is added). color_depth (int): Output format; see `Palette <palettes.Palette>`. swapped (bool): Byte-swap 16-bit colors when ``True``. cached (bool): Memoize index lookups when ``True`` (default). length (int): Number of colors in the wheel (default ``256``). saturation (float): HSV saturation in ``0.0``–``1.0``, or ``None`` for classic wheel mode. value (float): HSV value in ``0.0``–``1.0``, or ``None`` for classic wheel mode. Raises: ValueError: If ``saturation`` or ``value`` is outside ``0``–``1`` in HSV mode. """ self._length = length if saturation is None and value is None: self._mode = "wheel" self._one_third = self._length // 3 self._two_thirds = 2 * self._length // 3 self._spacing = 256 * 3 / self._length else: self._mode = "hsv" self._saturation = saturation if saturation is not None else 1.0 self._value = value if value is not None else 1.0 if not 0 <= self._saturation <= 1 or not 0 <= self._value <= 1: raise ValueError("Saturation and value must be in the range of 0-1") from . import WIN16 as NAMES self._names = NAMES super().__init__(name + str(self._length), color_depth, swapped, cached) def _get_rgb(self, index): if self._mode == "wheel": return self._wheel_to_rgb(index) else: return self._hsv_to_rgb(index / self._length, self._saturation, self._value) def _wheel_to_rgb(self, index): # incoming index is in the range of 0-self._length index = self._length - 1 - index # reverse the order if index < self._one_third: return (255 - int(index * self._spacing), 0, int(index * self._spacing)) elif index < self._two_thirds: index -= self._one_third return (0, int(index * self._spacing), 255 - int(index * self._spacing)) else: index -= self._two_thirds return (int(index * self._spacing), 255 - int(index * self._spacing), 0) def _hsv_to_rgb(self, h, s, v): # incoming values are in the range of 0-1 # returns r, g, b values in the range of 0-255 if s == 0: # when s=0, all values are shades of gray return int(v * 255), int(v * 255), int(v * 255) i = int(h * 6.0) f = (h * 6.0) - i p = int(255 * v * (1.0 - s)) q = int(255 * v * (1.0 - s * f)) t = int(255 * v * (1.0 - s * (1.0 - f))) v = int(255 * v) i = i % 6 if i == 0: # red return v, t, p if i == 1: # yellow return q, v, p if i == 2: # green return p, v, t if i == 3: # cyan return p, q, v if i == 4: # blue return t, p, v if i == 5: # magenta return v, p, q return 0, 0, 0