# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Color palette toolkit for PyDevices.
Use this package when a UI or graphics routine needs a predictable set of
colors rather than hard-coded values. The public API is small: call
`get_palette <palettes.get_palette>` to create a palette, then index it to get display-ready
colors for fills, gradients, labels, progress bars, and other visual states.
A common pattern is to create one palette per display or scene and reuse it
across multiple draw calls. For example, a 16-bit RGB565 display will usually
want ``color_depth=16`` and may also need ``swapped=True`` when the driver
expects byte-swapped colors.
Example:
>>> from palettes import get_palette
>>> palette = get_palette(name="wheel", length=256, saturation=1.0)
>>> palette[0]
>>> palette.color_name(0)
Attributes:
WIN16: Ordered ``(0xRRGGBB, name)`` pairs for the Windows 16 colors, the
default name table for `Palette <palettes.Palette>` and
`WheelPalette <palettes.wheel.WheelPalette>`. A pair's position is its palette
index. This is a tuple rather than a dict on purpose: MicroPython and
CircuitPython do not preserve dict insertion order, so a dict would
give a different index order on each interpreter.
"""
__all__ = ["WIN16", "get_palette", "Palette", "MappedPalette"]
WIN16 = (
(0x000000, "Black"),
(0x000080, "Navy"),
(0x0000FF, "Blue"),
(0x008000, "Green"),
(0x008080, "Teal"),
(0x00FF00, "Lime"),
(0x00FFFF, "Cyan"),
(0x800000, "Maroon"),
(0x800080, "Purple"),
(0x808000, "Olive"),
(0x808080, "Grey"),
(0xC0C0C0, "Silver"),
(0xFF0000, "Red"),
(0xFF00FF, "Magenta"),
(0xFFFF00, "Yellow"),
(0xFFFFFF, "White"),
)
[docs]
def get_palette(name="default", **kwargs):
"""Construct a palette by logical name.
This is the easiest entry point for most applications. Select a palette
family once, then reuse the returned object as a color source across the
rest of the UI.
Args:
name (str): Palette type. One of ``"default"`` (Windows 16-color),
``"wheel"``, ``"cube"``, ``"material_design"`` or ``"ansi"``. Unknown names
fall back to `Palette <palettes.Palette>`.
**kwargs (Any): Forwarded to the palette constructor (for example
``color_depth``, ``length``, ``size``, ``saturation``, and
``swapped``).
Returns:
Palette: A `Palette <palettes.Palette>` subclass instance.
Example:
>>> pal = get_palette(name="cube", size=3, color_depth=16)
>>> color = pal[12]
"""
if name == "wheel":
from .wheel import WheelPalette as MyPalette
elif name == "material_design":
from .material_design import MDPalette as MyPalette
elif name == "cube":
from .cube import CubePalette as MyPalette
elif name == "ansi":
from .ansi import AnsiPalette as MyPalette
else:
MyPalette = Palette
return MyPalette(name, **kwargs)
[docs]
class Palette:
"""Indexed color palette with optional named color attributes.
Subclasses override `_get_rgb` to define how each index maps to red,
green, and blue components. The resulting color can then be used for fills,
gradients, status indicators, and other display operations. A subclass may
also set ``_names`` to its own ordered sequence of ``(0xRRGGBB, name)``
pairs before calling ``__init__``; pair position is palette index.
In practice, applications usually create one palette for a screen or view and
then reuse it for many draw calls rather than generating colors inline. Named
colors from the palette's name table (for example ``palette.RED``) are
attached as attributes during initialization.
Args:
name (str): Optional label stored in `name`.
color_depth (int): Output format for `__getitem__`: `4` (the palette
index itself, for 4-bit indexed/grayscale framebuffers), `8`
(RGB332), `16` (RGB565), or `24` (`0xRRGGBB`).
swapped (bool): If ``True``, byte-swap 16-bit colors (little-endian displays).
cached (bool): If ``True``, memoize computed index colors in an internal dict.
"""
def __init__(self, name="", color_depth=16, swapped=False, cached=False):
"""Create a palette from the default Windows 16-color name table.
Args:
name (str): Optional label stored in `name`.
color_depth (int): Output format for `__getitem__`: ``4``, ``8``,
``16``, or ``24``.
swapped (bool): If ``True``, byte-swap 16-bit colors.
cached (bool): If ``True``, memoize computed index colors.
"""
self._name = name
self._color_depth = color_depth
self._swapped = swapped
self._cache = {} if cached else None
if not hasattr(self, "_names"):
self._names = WIN16
if not hasattr(self, "_length"):
self._length = len(self._names)
# Reverse lookup for rgb_name(); index order is still defined by _names.
self._names_by_value = dict(self._names)
self._define_named_colors()
def _define_named_colors(self):
for index, (color, name) in enumerate(self._names):
if self._color_depth == 16:
color = self.color565(color)
elif self._color_depth == 8:
color = self.color332(color)
elif self._color_depth == 4:
color = index
setattr(self, name.replace(" ", "_").upper(), color)
@property
def name(self):
"""Human-readable palette label."""
return self._name
def __iter__(self):
"""Yield each palette entry in index order."""
for i in range(len(self)):
yield self[i]
def __len__(self):
"""Number of colors in the palette."""
return self._length
def __getitem__(self, index):
"""Return the color at ``index`` in the configured bit depth.
Negative indices and indices beyond the palette length wrap around.
Args:
index (int): Color index (supports negative and out-of-range values).
Returns:
int: Color value (format depends on ``color_depth``).
Raises:
ValueError: If ``color_depth`` is not 4, 8, 16, or 24.
"""
index = self._normalize(index)
# At depth 4 the index *is* the value: a GS4 framebuffer stores a
# nibble per pixel, and the named attributes have always returned the
# index (see _define_named_colors). Returning packed RGB here made the
# two halves of the surface disagree -- and pdwidgets passes a driver's
# color_depth straight through, so an ssd1327 got a 24-bit value where
# a nibble belongs.
if self._color_depth == 4:
return index
if self._cache is not None and index in self._cache:
return self._cache[index]
r, g, b = self._get_rgb(index)
if self._color_depth == 24:
return r << 16 | g << 8 | b
elif self._color_depth == 16:
return self.color565(r, g, b)
elif self._color_depth == 8:
return self.color332(r, g, b)
raise ValueError("Invalid color depth")
def _normalize(self, index):
while index < 0:
index += len(self)
if index >= len(self):
index %= len(self)
return index
[docs]
def color565(self, r, g=None, b=None):
"""Convert RGB to a 16-bit RGB565 value.
Args:
r (int): Red component (0–255), a 24-bit ``0xRRGGBB`` integer, or an
``(r, g, b)`` sequence.
g (int): Green component when ``r`` is passed separately.
b (int): Blue component when ``r`` is passed separately.
Returns:
int: 16-bit color, optionally byte-swapped when ``swapped`` is ``True``.
"""
if isinstance(r, (tuple, list)):
# r is a tuple or list
r, g, b = r
elif g is None:
# r is a 24-bit color
r, g, b = r >> 16 & 0xFF, r >> 8 & 0xFF, r & 0xFF
color = (r & 0xF8) << 8 | (g & 0xFC) << 3 | b >> 3
if self._swapped:
return (color & 0xFF) << 8 | (color & 0xFF00) >> 8
else:
return color
[docs]
def color332(self, r, g=None, b=None):
"""Convert RGB to an 8-bit RGB332 value.
Args:
r (int): Red component (0–255), a 24-bit ``0xRRGGBB`` integer, or an
``(r, g, b)`` sequence.
g (int): Green component when ``r`` is passed separately.
b (int): Blue component when ``r`` is passed separately.
Returns:
int: 8-bit RGB332 color.
"""
# Convert r, g, b to 8-bit
if isinstance(r, (tuple, list)):
# r is a tuple or list
r, g, b = r
elif g is None:
# r is a 24-bit color
r, g, b = r >> 16 & 0xFF, r >> 8 & 0xFF, r & 0xFF
color = (r & 0xE0) | (g & 0xE0) >> 3 | (b & 0xC0) >> 6
return color
[docs]
def color_rgb(self, color):
"""Expand a packed color to an ``(r, g, b)`` tuple.
Args:
color (int): A 16-bit integer, or a 2- or 3-byte sequence in display
byte order.
Returns:
tuple: ``(red, green, blue)`` with each component in ``0``–``255``.
"""
if isinstance(color, int):
# convert 16-bit int color to 2 bytes
color = (color & 0xFF, color >> 8)
if len(color) == 2:
r = color[1] & 0xF8 | (color[1] >> 5) & 0x7 # 5 bit to 8 bit red
g = color[1] << 5 & 0xE0 | (color[0] >> 3) & 0x1F # 6 bit to 8 bit green
b = color[0] << 3 & 0xF8 | (color[0] >> 2) & 0x7 # 5 bit to 8 bit blue
else:
r, g, b = color
return (r, g, b)
[docs]
def color_name(self, index):
"""Return the name of the color at ``index``.
Args:
index (int): Palette index (supports wrapping).
Returns:
str: A name from the palette name table, or a ``"#RRGGBB"`` hex
string when no name matches.
"""
return self.rgb_name(self._get_rgb(self._normalize(index)))
[docs]
def rgb_name(self, r, g=None, b=None):
"""Look up a color name from RGB components.
Args:
r (int): Red (0–255), a 24-bit integer, or an ``(r, g, b)`` sequence.
g (int): Green when ``r`` is passed separately.
b (int): Blue when ``r`` is passed separately.
Returns:
str: Matching name from `_names`, or ``"#RRGGBB"`` if unknown.
"""
if isinstance(r, (tuple, list)):
r, g, b = r
value = r << 16 | g << 8 | b
return self._names_by_value.get(value, f"#{r:02X}{g:02X}{b:02X}")
[docs]
def luminance(self, index):
"""Perceived brightness of the color at ``index`` (ITU-R BT.601).
Args:
index (int): Palette index.
Returns:
float: Luminance in ``0.0``–``255.0``.
"""
r, g, b = self._get_rgb(index)
return 0.299 * r + 0.587 * g + 0.114 * b
[docs]
def brightness(self, index):
"""Average channel brightness of the color at ``index``.
Args:
index (int): Palette index.
Returns:
float: Normalized brightness in ``0.0``–``1.0``.
"""
r, g, b = self._get_rgb(index)
return (r + g + b) / 3 / 255
def _get_rgb(self, index):
color = self._names[index][0]
return color >> 16 & 0xFF, color >> 8 & 0xFF, color & 0xFF
[docs]
class MappedPalette(Palette):
"""Palette backed by a flat RGB byte map.
Each color occupies three consecutive bytes ``(r, g, b)`` in
``color_map``. Subclasses such as `MDPalette <palettes.material_design.MDPalette>`
supply a pre-built map and named-color attributes.
Args:
name (str): Optional label stored in `name`.
color_depth (int): Output format for `Palette.__getitem__`.
swapped (bool): Byte-swap 16-bit colors when ``True``.
color_map (bytes): ``bytes`` or buffer of RGB triplets, length ``3 * n_colors``.
"""
def __init__(self, name, color_depth, swapped, color_map):
"""Create a palette from a flat RGB byte map.
Args:
name (str): Optional label stored in `name`.
color_depth (int): Output format for `Palette.__getitem__`.
swapped (bool): Byte-swap 16-bit colors when ``True``.
color_map (bytes): ``bytes`` or buffer of RGB triplets.
"""
self._color_map = color_map
self._length = len(color_map) // 3
super().__init__(name, color_depth, swapped)
def _get_rgb(self, index):
r, g, b = self._color_map[index * 3 : index * 3 + 3]
return r, g, b