Color Utilities¶

def __eq__(self, other: object) -> bool:
    """Two colors are equal if they share the same wire representation.

    Equality is defined at uint16 (protocol) granularity rather than on the
    raw floats. This keeps colors that round-trip through the protocol stable
    under comparison despite sub-uint16 floating-point drift.
    """
    if not isinstance(other, HSBK):
        return NotImplemented
    return self.as_tuple() == other.as_tuple()

def __hash__(self) -> int:
    """Return a hash consistent with uint16 equality."""
    return hash(self.as_tuple())

def __str__(self) -> str:
    """Return a string representation of the HSBK values for this color."""
    string = (
        f"Hue: {self.hue}, Saturation: {self.saturation:.4f}, "
        f"Brightness: {self.brightness:.4f}, Kelvin: {self.kelvin}"
    )
    return string

def __repr__(self) -> str:
    """Return a string representation of the HSBK values for this color."""
    repr = (
        f"HSBK(hue={self.hue}, saturation={self.saturation:.2f}, "
        f"brightness={self.brightness:.2f}, kelvin={self.kelvin})"
    )
    return repr

@classmethod
def from_rgb(cls, red: float, green: float, blue: float) -> HSBK:
    """Create HSBK from RGB values.

    Args:
        red: Red component (0.0-1.0)
        green: Green component (0.0-1.0)
        blue: Blue component (0.0-1.0)

    Returns:
        HSBK instance

    Raises:
        ValueError: If RGB values are out of range (0.0-1.0)

    Example:
        ```python
        # Pure red
        red = HSBK.from_rgb(1.0, 0.0, 0.0)

        # Purple
        purple = HSBK.from_rgb(0.5, 0.0, 0.5)
        ```
    """

    def _validate_rgb_component(value: float, name: str) -> None:
        if not (0.0 <= value <= 1.0):
            raise ValueError(f"{name} must be between 0.0 and 1.0, got {value}")

    _validate_rgb_component(red, "Red")
    _validate_rgb_component(green, "Green")
    _validate_rgb_component(blue, "Blue")

    # Convert to HSV using colorsys (already 0-1 range)
    h, s, v = colorsys.rgb_to_hsv(red, green, blue)

    return cls(
        hue=h * 360,  # 0-1 -> 0-360
        saturation=s,
        brightness=v,
        kelvin=KELVIN_NEUTRAL,
    )

def to_rgb(self) -> tuple[float, float, float]:
    """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:
        Tuple of (red, green, blue) with values 0.0-1.0

    Example:
        ```python
        color = HSBK(hue=120, saturation=1.0, brightness=1.0, kelvin=3500)
        r, g, b = color.to_rgb()  # Returns (0.0, 1.0, 0.0) - green
        ```
    """
    h = self._hue / 360  # 0-360 -> 0-1
    return colorsys.hsv_to_rgb(h, self._saturation, self._brightness)

def to_protocol(self) -> 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:
        LightHsbk instance for packet serialization

    Example:
        ```python
        color = HSBK(hue=180, saturation=0.5, brightness=0.75, kelvin=3500)
        protocol_color = color.to_protocol()
        # Use in packet: LightSetColor(color=protocol_color, ...)
        ```
    """
    hue_u16 = round(0x10000 * self._hue / 360) % 0x10000
    saturation_u16 = round(0xFFFF * self._saturation)
    brightness_u16 = round(0xFFFF * self._brightness)

    return LightHsbk(
        hue=hue_u16,
        saturation=saturation_u16,
        brightness=brightness_u16,
        kelvin=self._kelvin,
    )

@classmethod
def from_protocol(cls, protocol: LightHsbk) -> HSBK:
    """Create HSBK from protocol HSBK.

    Args:
        protocol: LightHsbk instance from packet deserialization

    Returns:
        User-friendly HSBK instance

    Example:
        ```python
        # After receiving LightState packet
        state = await device.get_state()
        color = HSBK.from_protocol(state.color)
        print(f"Hue: {color.hue}°, Brightness: {color.brightness * 100}%")
        ```
    """
    # Convert from uint16 ranges to user-friendly ranges, preserving the
    # full precision of the device value (no rounding). Kelvin is passed
    # through verbatim, including the 0 devices report for a fully
    # saturated colour.
    hue = float(protocol.hue) * 360 / 0x10000
    saturation = float(protocol.saturation) / 0xFFFF
    brightness = float(protocol.brightness) / 0xFFFF

    return cls(
        hue=hue,
        saturation=saturation,
        brightness=brightness,
        kelvin=protocol.kelvin,
    )

def with_hue(self, hue: float) -> HSBK:
    """Create a new HSBK with modified hue.

    Args:
        hue: New hue value (0-360)

    Returns:
        New HSBK instance
    """
    return HSBK(
        hue=hue,
        saturation=self._saturation,
        brightness=self._brightness,
        kelvin=self._kelvin,
    )

def with_saturation(self, saturation: float) -> HSBK:
    """Create a new HSBK with modified saturation.

    Args:
        saturation: New saturation value (0.0-1.0)

    Returns:
        New HSBK instance
    """
    return HSBK(
        hue=self._hue,
        saturation=saturation,
        brightness=self._brightness,
        kelvin=self._kelvin,
    )

def with_brightness(self, brightness: float) -> HSBK:
    """Create a new HSBK with modified brightness.

    Args:
        brightness: New brightness value (0.0-1.0)

    Returns:
        New HSBK instance
    """
    return HSBK(
        hue=self._hue,
        saturation=self._saturation,
        brightness=brightness,
        kelvin=self._kelvin,
    )

def with_kelvin(self, kelvin: int) -> HSBK:
    """Create a new HSBK with modified color temperature.

    Args:
        kelvin: New kelvin value (1500-9000, or 0 for no white component)

    Returns:
        New HSBK instance
    """
    return HSBK(
        hue=self._hue,
        saturation=self._saturation,
        brightness=self._brightness,
        kelvin=kelvin,
    )

def replace(
    self,
    hue: float | None = None,
    saturation: float | None = None,
    brightness: float | None = None,
    kelvin: int | None = None,
) -> HSBK:
    """Create a new HSBK, replacing only the components that were supplied.

    Each component defaults to the value held by this color, so any subset
    can be overridden in a single call rather than chaining ``with_*``
    methods. Supplying nothing returns an equivalent color.

    Args:
        hue: New hue in degrees (0-360), or None to keep the current hue
        saturation: New saturation (0.0-1.0), or None to keep the current
            saturation
        brightness: New brightness (0.0-1.0), or None to keep the current
            brightness
        kelvin: New color temperature (1500-9000, or 0 for no white
            component), or None to keep the current kelvin

    Returns:
        New HSBK instance

    Raises:
        ValueError: If any supplied value is out of range

    Example:
        ```python
        color = HSBK(hue=180, saturation=0.5, brightness=0.75, kelvin=3500)

        # Dim it and shift the hue, keeping saturation and kelvin
        dimmed = color.replace(hue=200, brightness=0.2)
        ```
    """
    return HSBK(
        hue=self._hue if hue is None else hue,
        saturation=self._saturation if saturation is None else saturation,
        brightness=self._brightness if brightness is None else brightness,
        kelvin=self._kelvin if kelvin is None else kelvin,
    )

def lerp_hsb(self, other: HSBK, blend: float) -> HSBK:
    """Interpolate to another color via shortest-path HSB blending.

    Args:
        other: Target color to interpolate towards.
        blend: Blend factor from 0.0 (self) to 1.0 (other), clamped to range.

    Returns:
        New HSBK instance with interpolated values. Kelvin is preserved from self.
    """
    blend = max(0.0, min(1.0, blend))
    diff = other._hue - self._hue
    if diff > 180:
        diff -= 360
    elif diff < -180:
        diff += 360
    hue = (self._hue + diff * blend) % 360
    sat = self._saturation + (other._saturation - self._saturation) * blend
    bri = self._brightness + (other._brightness - self._brightness) * blend
    return HSBK(
        hue=hue,
        saturation=sat,
        brightness=bri,
        kelvin=self._kelvin,
    )

def lerp_oklab(self, other: HSBK, blend: float) -> HSBK:
    """Interpolate to another color through Oklab perceptual color space.

    Oklab produces perceptually uniform transitions without brightness
    dips or muddy intermediates that occur with naive HSB blending.

    Args:
        other: Target color to interpolate towards.
        blend: Blend factor from 0.0 (self) to 1.0 (other), clamped to range.

    Returns:
        New HSBK instance with interpolated values. Kelvin is preserved from self.
    """
    blend = max(0.0, min(1.0, blend))
    r1, g1, b1 = colorsys.hsv_to_rgb(
        self._hue / 360.0, self._saturation, self._brightness
    )
    r2, g2, b2 = colorsys.hsv_to_rgb(
        other._hue / 360.0, other._saturation, other._brightness
    )
    l1, a1, ob1 = _srgb_to_oklab(r1, g1, b1)
    l2, a2, ob2 = _srgb_to_oklab(r2, g2, b2)
    l_interp = l1 + (l2 - l1) * blend
    a_interp = a1 + (a2 - a1) * blend
    ob_interp = ob1 + (ob2 - ob1) * blend
    r, g, b = _oklab_to_srgb(l_interp, a_interp, ob_interp)
    h, s, v = colorsys.rgb_to_hsv(r, g, b)
    return HSBK(
        hue=(h * 360) % 360,
        saturation=s,
        brightness=v,
        kelvin=self._kelvin,
    )

def clone(self) -> HSBK:
    """Create a copy of this color.

    Returns:
        New HSBK instance with the same values
    """
    return HSBK(
        hue=self.hue,
        saturation=self.saturation,
        brightness=self.brightness,
        kelvin=self.kelvin,
    )

def as_tuple(self) -> tuple[int, int, int, int]:
    """Return HSBK values as a tuple of protocol uint16 values.

    Returns:
        Tuple of (hue_u16, saturation_u16, brightness_u16, kelvin)
        where u16 values are in range 0-65535

    Example:
        ```python
        color = HSBK(hue=180, saturation=0.5, brightness=0.75, kelvin=3500)
        hue, sat, bri, kel = color.as_tuple()
        # Use in protocol operations
        ```
    """
    protocol = self.to_protocol()
    return (protocol.hue, protocol.saturation, protocol.brightness, protocol.kelvin)

def limit_distance_to(self, other: HSBK) -> HSBK:
    """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.

    Args:
        other: Reference color to limit distance to

    Returns:
        New HSBK instance with limited hue distance

    Example:
        ```python
        red = HSBK(hue=10, saturation=1.0, brightness=1.0, kelvin=3500)
        blue = HSBK(hue=240, saturation=1.0, brightness=1.0, kelvin=3500)

        # Limit red's hue to be within 90 degrees of blue's hue
        adjusted = red.limit_distance_to(blue)
        # Result: hue is adjusted to be within 90 degrees of 240
        ```
    """
    raw_dist = (
        self.hue - other.hue if self.hue > other.hue else other.hue - self.hue
    )
    dist = 360 - raw_dist if raw_dist > 180 else raw_dist
    if abs(dist) > 90:
        h = self.hue + 90 if (other.hue + dist) % 360 == self.hue else self.hue - 90
        h = h + 360 if h < 0 else h
        return HSBK(h, self.saturation, self.brightness, self.kelvin)
    else:
        return self

@classmethod
def average(cls, colors: list[HSBK]) -> HSBK:
    """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°).

    Args:
        colors: List of HSBK colors to average (must not be empty)

    Returns:
        New HSBK instance with averaged values

    Raises:
        ValueError: If colors list is empty

    Example:
        ```python
        red = HSBK(hue=0, saturation=1.0, brightness=1.0, kelvin=3500)
        green = HSBK(hue=120, saturation=1.0, brightness=1.0, kelvin=3500)
        blue = HSBK(hue=240, saturation=1.0, brightness=1.0, kelvin=3500)

        avg_color = HSBK.average([red, green, blue])
        # Result: average of the three primary colors
        ```
    """
    if not colors:
        raise ValueError("Cannot average an empty list of colors")

    hue_x_total = 0.0
    hue_y_total = 0.0
    saturation_total = 0.0
    brightness_total = 0.0
    kelvin_total = 0.0

    for color in colors:
        hue_x_total += math.sin(color.hue * 2.0 * math.pi / 360)
        hue_y_total += math.cos(color.hue * 2.0 * math.pi / 360)
        saturation_total += color.saturation
        brightness_total += color.brightness
        kelvin_total += color.kelvin

    hue = math.atan2(hue_x_total, hue_y_total) / (2.0 * math.pi)
    if hue < 0.0:
        hue += 1.0
    hue *= 360
    saturation = saturation_total / len(colors)
    brightness = brightness_total / len(colors)
    kelvin = round(kelvin_total / len(colors))

    return cls(hue, saturation, brightness, kelvin)