Color maths
The bit layout, the byte swap and the HSV conversion behind the numbers a palette returns. Color formats lists what each depth returns.
RGB565 Bit Layout (16-bit Color)
Microcontroller displays (such as ST7789, ILI9341, GC9A01, SSD1351) commonly use 16-bit RGB565, packing 5 bits of red, 6 bits of green, and 5 bits of blue into a single 16-bit integer:
Bit: 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
[ RED ] [ GREEN ] [ BLUE ]
5 bits 6 bits 5 bits
Conversion Formula from 24-bit RGB888:
Given 8-bit values $R, G, B \in [0, 255]$:
$$\text{RGB565} = ((R \gg 3) \ll 11) \mid ((G \gg 2) \ll 5) \mid (B \gg 3)$$
def rgb888_to_rgb565(r: int, g: int, b: int) -> int:
"""Convert 8-bit R, G, B components to a 16-bit RGB565 integer."""
return ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)
SPI Byte Swapping (swapped=True)
Most SPI TFT display controllers expect pixels in Big Endian format (High byte first over SPI), whereas ARM Cortex-M / RISC-V / x86 processors store 16-bit integers in Little Endian format.
If colors appear inverted or garbled on your panel:
from palettes import get_palette
# Without byte swap (native little-endian integers)
p_native = get_palette("wheel", color_depth=16, swapped=False)
# With byte swap (ready for direct SPI transmission)
p_swapped = get_palette("wheel", color_depth=16, swapped=True)
The Byte Swap Operation:
$$\text{swapped} = ((\text{val} \gg 8) & \text{0x00FF}) \mid ((\text{val} \ll 8) & \text{0xFF00})$$
HSV to RGB Interpolation
The WheelPalette computes color sweeps by converting Hue ($H \in [0, 360^\circ]$), Saturation ($S \in [0, 1]$), and Value ($V \in [0, 1]$) to RGB:
$C = V \times S$ (Chroma)
$H’ = \frac{H}{60^\circ}$
$X = C \times (1 - |(H’ \pmod 2) - 1|)$
$m = V - C$
Depending on the sextant $\lfloor H’ \rfloor$, $(R_1, G_1, B_1)$ is assigned:
$H’$ Interval |
$(R_1, G_1, B_1)$ |
|---|---|
$0 \le H’ < 1$ |
$(C, X, 0)$ |
$1 \le H’ < 2$ |
$(X, C, 0)$ |
$2 \le H’ < 3$ |
$(0, C, X)$ |
$3 \le H’ < 4$ |
$(0, X, C)$ |
$4 \le H’ < 5$ |
$(X, 0, C)$ |
$5 \le H’ < 6$ |
$(C, 0, X)$ |
Final 8-bit components: $$R = \lfloor(R_1 + m) \times 255\rfloor, \quad G = \lfloor(G_1 + m) \times 255\rfloor, \quad B = \lfloor(B_1 + m) \times 255\rfloor$$