Merge pull request #108 from chrivers/chrivers/api-v1-hs-color-mode

Implement support for converting Hue/Saturation ("HS") light updates to modern XY-based values.

This enables support for receiving Hue/Sat light updates over API V1, specifically for `ApiLightStateUpdate` (`PUT` requests for controlling lights).

When such a request is received, it is converted to XY mode, and handled from there.

Author: chrivers

crates/hue/Cargo.toml

@@ -30,3 +30,4 @@ uuid = { version = "1.13.1", features = ["serde", "v5"] }
 
 [dev-dependencies]
 hex = "0.4.3"
+uuid = { version = "1.13.1", features = ["v4"] }

crates/hue/src/api/light.rs

@@ -5,6 +5,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
 
 use crate::api::{DeviceArchetype, Identify, Metadata, MetadataUpdate, ResourceLink, Stub};
+use crate::hs::HS;
 use crate::xy::XY;
 
 #[derive(Debug, Serialize, Deserialize, Clone)]
@@ -613,7 +614,15 @@ impl LightUpdate {
     #[must_use]
     pub fn with_color_xy(self, xy: impl Into<Option<XY>>) -> Self {
         Self {
-            color: xy.into().map(ColorUpdate::new),
+            color: self.color.or_else(|| xy.into().map(ColorUpdate::new)),
+            ..self
+        }
+    }
+
+    #[must_use]
+    pub fn with_color_hs(self, hs: impl Into<Option<HS>>) -> Self {
+        Self {
+            color: hs.into().map(|hs| XY::from_hs(hs).0).map(ColorUpdate::new),
             ..self
         }
     }

crates/hue/src/hs.rs

@@ -0,0 +1,73 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Copy, Debug, Serialize, Deserialize, Clone)]
+pub struct HS {
+    pub hue: f64,
+    pub sat: f64,
+}
+
+#[derive(Copy, Debug, Serialize, Deserialize, Clone, Eq, PartialEq)]
+pub struct RawHS {
+    pub hue: u16,
+    pub sat: u8,
+}
+
+impl From<RawHS> for HS {
+    fn from(raw: RawHS) -> Self {
+        Self {
+            hue: f64::from(raw.hue) / f64::from(0xFFFF),
+            sat: f64::from(raw.sat) / f64::from(0xFF),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::hs::{RawHS, HS};
+
+    macro_rules! compare {
+        ($expr:expr, $value:expr) => {
+            let a = $expr;
+            let b = $value;
+            eprintln!("{a} vs {b:.4}");
+            assert!((a - b).abs() < 1e-4);
+        };
+    }
+
+    macro_rules! compare_hs {
+        ($a:expr, $b:expr) => {{
+            compare!($a.hue, $b.hue);
+            compare!($a.sat, $b.sat);
+        }};
+    }
+
+    #[test]
+    fn from_rawhs_min() {
+        compare_hs!(
+            HS::from(RawHS { hue: 0, sat: 0 }),
+            HS { hue: 0.0, sat: 0.0 }
+        );
+    }
+
+    #[test]
+    fn from_rawhs_mid() {
+        compare_hs!(
+            HS::from(RawHS {
+                hue: 0xCCCC,
+                sat: 0xCC
+            }),
+            HS { hue: 0.8, sat: 0.8 }
+        );
+    }
+
+    #[test]
+    fn from_rawhs_max() {
+        compare_hs!(
+            HS::from(RawHS {
+                hue: 0xFFFF,
+                sat: 0xFF
+            }),
+            HS { hue: 1.0, sat: 1.0 }
+        );
+    }
+}

crates/hue/src/legacy_api.rs

@@ -8,6 +8,7 @@ use uuid::Uuid;
 
 use crate::api::{ColorGamut, DeviceProductData};
 use crate::date_format;
+use crate::hs::RawHS;
 use crate::version::SwVersion;
 use crate::{api, best_guess_timezone};
 
@@ -489,6 +490,8 @@ pub struct ApiLightStateUpdate {
     pub xy: Option<[f64; 2]>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ct: Option<u16>,
+    #[serde(skip_serializing_if = "Option::is_none", flatten)]
+    pub hs: Option<RawHS>,
 }
 
 #[derive(Debug, Serialize, Deserialize)]
@@ -521,6 +524,7 @@ impl From<api::SceneAction> for ApiLightStateUpdate {
             bri: action.dimming.map(|dim| (dim.brightness * 2.54) as u32),
             xy: action.color.map(|col| col.xy.into()),
             ct: action.color_temperature.map(|ct| ct.mirek),
+            hs: None,
         }
     }
 }

crates/hue/src/lib.rs

@@ -9,6 +9,7 @@ pub mod error;
 pub mod event;
 pub mod flags;
 pub mod gamma;
+pub mod hs;
 pub mod legacy_api;
 pub mod scene_icons;
 pub mod stream;

crates/hue/src/xy.rs

@@ -2,6 +2,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::clamp::Clamp;
 use crate::colorspace::{self, ColorSpace};
+use crate::hs::HS;
 use crate::{WIDE_GAMUT_MAX_X, WIDE_GAMUT_MAX_Y};
 
 #[derive(Copy, Debug, Serialize, Deserialize, Clone, PartialEq)]
@@ -23,18 +24,56 @@ impl XY {
         y: 0.32902,
     };
 
-    #[allow(clippy::many_single_char_names)]
     #[must_use]
     pub fn from_rgb(red: u8, green: u8, blue: u8) -> (Self, f64) {
         let [r, g, b] = [red, green, blue].map(Clamp::unit_from_u8);
+        Self::from_rgb_unit(r, g, b)
+    }
 
+    #[allow(clippy::many_single_char_names)]
+    #[must_use]
+    pub fn from_rgb_unit(r: f64, g: f64, b: f64) -> (Self, f64) {
         let [x, y, b] = Self::COLOR_SPACE.rgb_to_xyy(r, g, b);
 
         let max_y = Self::COLOR_SPACE.find_maximum_y(x, y);
 
         (Self { x, y }, b / max_y * 255.0)
     }
 
+    #[must_use]
+    pub fn from_hs(hs: HS) -> (Self, f64) {
+        let lightness: f64 = 0.5;
+        Self::from_hsl(hs, lightness)
+    }
+
+    #[must_use]
+    pub fn from_hsl(hs: HS, lightness: f64) -> (Self, f64) {
+        let [r, g, b] = Self::rgb_from_hsl(hs, lightness);
+        Self::from_rgb_unit(r, g, b)
+    }
+
+    #[must_use]
+    pub fn rgb_from_hsl(hs: HS, lightness: f64) -> [f64; 3] {
+        let c = (1.0 - (2.0f64.mul_add(lightness, -1.0)).abs()) * hs.sat;
+        let h = hs.hue * 6.0;
+        let x = c * (1.0 - (h % 2.0 - 1.0).abs());
+        let m = lightness - c / 2.0;
+
+        if h < 1.0 {
+            [m + c, m + x, m]
+        } else if h < 2.0 {
+            [m + x, m + c, m]
+        } else if h < 3.0 {
+            [m, m + c, m + x]
+        } else if h < 4.0 {
+            [m, m + x, m + c]
+        } else if h < 5.0 {
+            [m + x, m, m + c]
+        } else {
+            [m + c, m + 0.0, m + x]
+        }
+    }
+
     #[must_use]
     pub fn to_rgb(&self, brightness: f64) -> [u8; 3] {
         Self::COLOR_SPACE
@@ -85,3 +124,50 @@ impl From<XY> for [f64; 2] {
         [value.x, value.y]
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::hs::HS;
+    use crate::xy::XY;
+
+    macro_rules! compare {
+        ($expr:expr, $value:expr) => {
+            let a = $expr;
+            let b = $value;
+            eprintln!("{a} vs {b:.4}");
+            assert!((a - b).abs() < 1e-4);
+        };
+    }
+
+    macro_rules! compare_rgb {
+        ($a:expr, $b:expr) => {{
+            eprintln!("Comparing r");
+            compare!($a[0], $b[0]);
+            eprintln!("Comparing g");
+            compare!($a[1], $b[1]);
+            eprintln!("Comparing b");
+            compare!($a[2], $b[2]);
+        }};
+    }
+
+    macro_rules! compare_hsl_rgb {
+        ($h:expr, $s:expr, $rgb:expr) => {{
+            let sat = $s;
+            compare_rgb!(XY::rgb_from_hsl(HS { hue: $h, sat }, 0.5), $rgb);
+        }};
+    }
+
+    #[test]
+    fn rgb_from_hsl() {
+        const ONE: f64 = 1.0;
+        let sat = 1.0;
+
+        compare_hsl_rgb!(0.0 / 3.0, sat, [ONE, 0.0, 0.0]); // red
+        compare_hsl_rgb!(0.5 / 3.0, sat, [ONE, ONE, 0.0]); // red-green
+        compare_hsl_rgb!(1.0 / 3.0, sat, [0.0, ONE, 0.0]); // green
+        compare_hsl_rgb!(1.5 / 3.0, sat, [0.0, ONE, ONE]); // green-blue
+        compare_hsl_rgb!(2.0 / 3.0, sat, [0.0, 0.0, ONE]); // blue
+        compare_hsl_rgb!(2.5 / 3.0, sat, [ONE, 0.0, ONE]); // blue-red
+        compare_hsl_rgb!(3.0 / 3.0, sat, [ONE, 0.0, 0.0]); // red (wrapped around)
+    }
+}

src/routes/api.rs

@@ -317,6 +317,7 @@ async fn put_api_user_resource_id_path(
                 .with_on(updv1.on.map(On::new))
                 .with_brightness(updv1.bri)
                 .with_color_temperature(updv1.ct)
+                .with_color_hs(updv1.hs.map(Into::into))
                 .with_color_xy(updv1.xy.map(Into::into));
 
             lock.backend_request(BackendRequest::LightUpdate(link, upd))?;