# 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