Color Utilities¶
lifx-async provides comprehensive color utilities for working with LIFX's HSBK color model and converting to/from RGB.
HSBK Class¶
The HSBK class represents colors in the Hue, Saturation, Brightness, Kelvin color model used by
LIFX devices.
HSBK
¶
User-friendly HSBK color representation.
LIFX devices use HSBK (Hue, Saturation, Brightness, Kelvin) color space. This class provides a convenient interface with normalized values and conversion to/from RGB.
| ATTRIBUTE | DESCRIPTION |
|---|---|
hue |
Hue value in degrees (0-360)
TYPE:
|
saturation |
Saturation (0.0-1.0, where 0 is white and 1 is fully saturated)
TYPE:
|
brightness |
Brightness (0.0-1.0, where 0 is off and 1 is full brightness)
TYPE:
|
kelvin |
Color temperature in Kelvin (1500-9000, typically 2500-9000 for LIFX)
TYPE:
|
Example
| METHOD | DESCRIPTION |
|---|---|
__eq__ |
Two colors are equal if they have the same HSBK values. |
__hash__ |
Returns a hash of this color as an integer. |
__str__ |
Return a string representation of the HSBK values for this color. |
__repr__ |
Return a string representation of the HSBK values for this color. |
from_rgb |
Create HSBK from RGB values. |
to_rgb |
Convert HSBK to RGB values. |
to_protocol |
Convert to protocol HSBK for packet serialization. |
from_protocol |
Create HSBK from protocol HSBK. |
with_hue |
Create a new HSBK with modified hue. |
with_saturation |
Create a new HSBK with modified saturation. |
with_brightness |
Create a new HSBK with modified brightness. |
with_kelvin |
Create a new HSBK with modified color temperature. |
clone |
Create a copy of this color. |
as_tuple |
Return HSBK values as a tuple of protocol uint16 values. |
as_dict |
Return HSBK values as a dictionary of user-friendly values. |
limit_distance_to |
Return a new color with hue limited to 90 degrees from another color. |
average |
Calculate the average color of a list of HSBK colors. |
Source code in src/lifx/color.py
Attributes¶
Functions¶
__eq__
¶
Two colors are equal if they have the same HSBK values.
Source code in src/lifx/color.py
__str__
¶
__str__() -> str
Return a string representation of the HSBK values for this color.
Source code in src/lifx/color.py
from_rgb
classmethod
¶
Create HSBK from RGB values.
| PARAMETER | DESCRIPTION |
|---|---|
red
|
Red component (0-255)
TYPE:
|
green
|
Green component (0-255)
TYPE:
|
blue
|
Blue component (0-255)
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
HSBK
|
HSBK instance |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If RGB values are out of range (0-255) |
Example
Source code in src/lifx/color.py
to_rgb
¶
Convert HSBK to RGB values.
Color temperature (kelvin) is not considered in this conversion, as it only affects the white point of the device.
| RETURNS | DESCRIPTION |
|---|---|
tuple[int, int, int]
|
Tuple of (red, green, blue) with values 0-255 |
Example
Source code in src/lifx/color.py
to_protocol
¶
to_protocol() -> LightHsbk
Convert to protocol HSBK for packet serialization.
LIFX protocol uses uint16 values for all HSBK components: - Hue: 0-65535 (represents 0-360 degrees) - Saturation: 0-65535 (represents 0-100%) - Brightness: 0-65535 (represents 0-100%) - Kelvin: Direct value in Kelvin
| RETURNS | DESCRIPTION |
|---|---|
LightHsbk
|
LightHsbk instance for packet serialization |
Example
Source code in src/lifx/color.py
from_protocol
classmethod
¶
Create HSBK from protocol HSBK.
| PARAMETER | DESCRIPTION |
|---|---|
protocol
|
LightHsbk instance from packet deserialization
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
HSBK
|
User-friendly HSBK instance |
Example
Source code in src/lifx/color.py
with_hue
¶
with_saturation
¶
with_brightness
¶
with_kelvin
¶
clone
¶
clone() -> HSBK
Create a copy of this color.
| RETURNS | DESCRIPTION |
|---|---|
HSBK
|
New HSBK instance with the same values |
as_tuple
¶
Return HSBK values as a tuple of protocol uint16 values.
| RETURNS | DESCRIPTION |
|---|---|
int
|
Tuple of (hue_u16, saturation_u16, brightness_u16, kelvin) |
int
|
where u16 values are in range 0-65535 |
Example
Source code in src/lifx/color.py
as_dict
¶
Return HSBK values as a dictionary of user-friendly values.
| RETURNS | DESCRIPTION |
|---|---|
dict[str, float | int]
|
Dictionary with keys: hue (float), saturation (float), |
dict[str, float | int]
|
brightness (float), kelvin (int) |
Example
Source code in src/lifx/color.py
limit_distance_to
¶
Return a new color with hue limited to 90 degrees from another color.
This is useful for preventing large hue jumps when interpolating between colors. If the hue difference is greater than 90 degrees, the hue is adjusted to be within 90 degrees of the target hue.
| PARAMETER | DESCRIPTION |
|---|---|
other
|
Reference color to limit distance to
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
HSBK
|
New HSBK instance with limited hue distance |
Example
Source code in src/lifx/color.py
average
classmethod
¶
Calculate the average color of a list of HSBK colors.
Uses circular mean for hue to correctly handle hue wraparound (e.g., average of 10° and 350° is 0°, not 180°).
| PARAMETER | DESCRIPTION |
|---|---|
colors
|
List of HSBK colors to average (must not be empty) |
| RETURNS | DESCRIPTION |
|---|---|
HSBK
|
New HSBK instance with averaged values |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If colors list is empty |
Example
Source code in src/lifx/color.py
Colors Class¶
The Colors class provides convenient color presets for common colors.
Colors
¶
Common color presets for convenience.
Examples¶
Creating Colors¶
from lifx import HSBK, Colors
# Use built-in color presets
color = Colors.BLUE
# Create custom colors
custom = HSBK(hue=180.0, saturation=1.0, brightness=0.8, kelvin=3500)
# Create from RGB
red = HSBK.from_rgb(255, 0, 0, kelvin=3500)
# Convert to RGB
r, g, b = Colors.BLUE.to_rgb()
print(f"RGB: ({r}, {g}, {b})")
Color Components¶
from lifx import HSBK
color = HSBK(hue=240.0, saturation=1.0, brightness=0.5, kelvin=3500)
# Hue: 0-360 degrees (0=red, 120=green, 240=blue)
print(f"Hue: {color.hue}°")
# Saturation: 0.0-1.0 (0=white, 1=full color)
print(f"Saturation: {color.saturation * 100}%")
# Brightness: 0.0-1.0 (0=off, 1=full brightness)
print(f"Brightness: {color.brightness * 100}%")
# Kelvin: 1500-9000 (warm white to cool white)
print(f"Temperature: {color.kelvin}K")
Color Manipulation¶
from lifx import HSBK, Light
async def cycle_hue(light: Light):
"""Cycle through the color spectrum"""
for hue in range(0, 360, 10):
color = HSBK(hue=float(hue), saturation=1.0, brightness=0.8, kelvin=3500)
await light.set_color(color, duration=0.1)
White Balance¶
from lifx import HSBK
# Warm white (sunset, candlelight)
warm = HSBK(hue=0, saturation=0, brightness=1.0, kelvin=2500)
# Neutral white (daylight)
neutral = HSBK(hue=0, saturation=0, brightness=1.0, kelvin=4000)
# Cool white (overcast, shade)
cool = HSBK(hue=0, saturation=0, brightness=1.0, kelvin=6500)
Available Color Presets¶
The Colors class provides these preset colors:
Colors.WHITE- Pure white (3500K)Colors.RED- RedColors.ORANGE- OrangeColors.YELLOW- YellowColors.GREEN- GreenColors.CYAN- CyanColors.BLUE- BlueColors.PURPLE- PurpleColors.PINK- PinkColors.WARM_WHITE- Warm white (2500K)Colors.COOL_WHITE- Cool white (6500K)
Color Conversion Notes¶
RGB to HSBK¶
When converting from RGB to HSBK, note that:
- RGB values are 0-255
- The Kelvin value must be specified (default: 3500K)
- Some RGB colors may not have exact HSBK equivalents
- Conversion uses standard HSV formulas with brightness mapping
HSBK to RGB¶
When converting from HSBK to RGB:
- Returns tuple of (r, g, b) with values 0-255
- Kelvin temperature is not represented in RGB
- White colors (saturation=0) will be pure gray values
- Conversion is lossy - converting back may not yield the same HSBK