palettes

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 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)
palettes.WIN16

Ordered (0xRRGGBB, name) pairs for the Windows 16 colors, the default name table for Palette and 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.

palettes.get_palette(name='default', **kwargs)[source]

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.

Parameters:
  • name (str) – Palette type. One of "default" (Windows 16-color), "wheel", "cube", "material_design" or "ansi". Unknown names fall back to Palette.

  • **kwargs (Any) – Forwarded to the palette constructor (for example color_depth, length, size, saturation, and swapped).

Returns:

Palette – A Palette subclass instance.

Example

>>> pal = get_palette(name="cube", size=3, color_depth=16)
>>> color = pal[12]
class palettes.Palette(name='', color_depth=16, swapped=False, cached=False)[source]

Bases: object

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.

Parameters:
  • 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.

property name

Human-readable palette label.

color565(r, g=None, b=None)[source]

Convert RGB to a 16-bit RGB565 value.

Parameters:
  • 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.

color332(r, g=None, b=None)[source]

Convert RGB to an 8-bit RGB332 value.

Parameters:
  • 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.

color_rgb(color)[source]

Expand a packed color to an (r, g, b) tuple.

Parameters:

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.

color_name(index)[source]

Return the name of the color at index.

Parameters:

index (int) – Palette index (supports wrapping).

Returns:

str –

A name from the palette name table, or a "#RRGGBB" hex

string when no name matches.

rgb_name(r, g=None, b=None)[source]

Look up a color name from RGB components.

Parameters:
  • 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.

luminance(index)[source]

Perceived brightness of the color at index (ITU-R BT.601).

Parameters:

index (int) – Palette index.

Returns:

float – Luminance in 0.0–255.0.

brightness(index)[source]

Average channel brightness of the color at index.

Parameters:

index (int) – Palette index.

Returns:

float – Normalized brightness in 0.0–1.0.

class palettes.MappedPalette(name, color_depth, swapped, color_map)[source]

Bases: 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 supply a pre-built map and named-color attributes.

Parameters:
  • 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.