input_pipeline/light_sensor/
types.rs

1// Copyright 2022 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use anyhow::{bail, format_err, Context, Error};
6use async_trait::async_trait;
7use futures::{Future, FutureExt as _, TryFutureExt as _};
8use serde::{Deserialize, Serialize};
9use std::collections::HashMap;
10use std::ops::{Add, Div, Mul, Sub};
11
12/// Abstracts over grouping of red, green, blue and clear color channel data.
13#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
14pub struct Rgbc<T> {
15    pub(crate) red: T,
16    pub(crate) green: T,
17    pub(crate) blue: T,
18    pub(crate) clear: T,
19}
20
21impl<T> Rgbc<T> {
22    /// Maps the supplied function to each color channel.
23    ///
24    /// # Example
25    /// ```
26    /// let rgbc = Rgbc { red: 1, green: 2, blue: 3, clear: 4 };
27    /// let rgbc = rgbc.map(|c| c + 1);
28    /// assert_eq!(rgbc, Rgbc { red: 2, green: 3, blue: 4, clear: 5 });
29    /// ```
30    pub(crate) fn map<U>(self, func: impl Fn(T) -> U) -> Rgbc<U> {
31        let Self { red, green, blue, clear } = self;
32        Rgbc { red: func(red), green: func(green), blue: func(blue), clear: func(clear) }
33    }
34
35    /// Maps the supplied function to each color channel, but returns the first error that occurs.
36    pub(crate) fn map_async<U, F>(
37        self,
38        func: impl Fn(T) -> F,
39    ) -> impl Future<Output = Result<Rgbc<U>, Error>>
40    where
41        F: Future<Output = Result<U, Error>>,
42    {
43        let Self { red, green, blue, clear } = self;
44        let red = func(red).map(|result| result.context("map red"));
45        let green = func(green).map(|result| result.context("map green"));
46        let blue = func(blue).map(|result| result.context("map blue"));
47        let clear = func(clear).map(|result| result.context("map clear"));
48        let fut = futures::future::try_join4(red, green, blue, clear);
49        fut.map_ok(|(red, green, blue, clear)| Rgbc { red, green, blue, clear })
50    }
51
52    /// Maps the supplied function to the matching pair of color channels of the inputs.
53    ///
54    /// # Example
55    /// ```
56    /// let left = Rgbc { red: 1, green: 2, blue: 3, clear: 4};
57    /// let right = Rgbc { red: 5, green: 6, blue: 7, clear: 8};
58    /// let rgbc = Rgbc::multi_map(left, right, |l, r| l + r);
59    /// assert_eq!(rgbc, Rgbc { red: 6, green: 8, blue: 10, clear: 12 });
60    /// ```
61    pub(crate) fn multi_map<U>(rgbc1: Self, rgbc2: Self, func: impl Fn(T, T) -> U) -> Rgbc<U> {
62        let Self { red: red1, green: green1, blue: blue1, clear: clear1 } = rgbc1;
63        let Self { red: red2, green: green2, blue: blue2, clear: clear2 } = rgbc2;
64        Rgbc {
65            red: func(red1, red2),
66            green: func(green1, green2),
67            blue: func(blue1, blue2),
68            clear: func(clear1, clear2),
69        }
70    }
71
72    /// Applies a fold operation across each color channel as if the Rgbc struct was a vec with
73    /// order: red, green, blue, clear.
74    ///
75    /// # Example
76    /// ```
77    /// let rgbc = Rgbc { red: 1, green: 2, blue: 3, clear: 4};
78    /// let value = rgbc.fold(0, |acc, v| acc + v);
79    /// assert_eq!(value, 10);
80    /// ```
81    pub(crate) fn fold<U>(self, acc: U, func: impl Fn(U, T) -> U) -> U {
82        let Self { red, green, blue, clear } = self;
83        [red, green, blue, clear].into_iter().fold(acc, func)
84    }
85
86    /// Helper function that ensures all fields of both [Rgbc] structs match according to the supplied
87    /// predicate.
88    #[cfg(test)]
89    pub(crate) fn match_all(left: Self, right: Self, predicate: impl Fn(T, T) -> bool) -> bool {
90        let Rgbc { red, green, blue, clear } = Self::multi_map(left, right, predicate);
91        red && green && blue && clear
92    }
93}
94
95impl<T> Sub for Rgbc<T>
96where
97    T: Sub<Output = T> + Copy,
98{
99    type Output = Rgbc<T::Output>;
100
101    fn sub(self, rhs: Self) -> Self::Output {
102        Rgbc::multi_map(self, rhs, |left, right| left - right)
103    }
104}
105
106impl<T> Add for Rgbc<T>
107where
108    T: Add<Output = T> + Copy,
109{
110    type Output = Rgbc<T::Output>;
111
112    fn add(self, rhs: Self) -> Self::Output {
113        Rgbc::multi_map(self, rhs, |left, right| left + right)
114    }
115}
116
117impl<T> Mul for Rgbc<T>
118where
119    T: Mul<Output = T> + Copy,
120{
121    type Output = Rgbc<T::Output>;
122
123    fn mul(self, rhs: Self) -> Self::Output {
124        Rgbc::multi_map(self, rhs, |left, right| left * right)
125    }
126}
127
128impl<T> Div for Rgbc<T>
129where
130    T: Div<Output = T> + Copy,
131{
132    type Output = Rgbc<T::Output>;
133
134    fn div(self, rhs: Self) -> Self::Output {
135        Rgbc::multi_map(self, rhs, |left, right| left / right)
136    }
137}
138#[derive(Deserialize, Debug)]
139pub struct Configuration {
140    pub calibration: Option<CalibrationConfiguration>,
141    pub sensor: SensorConfiguration,
142}
143
144/// Configuration file format.
145///
146/// Each string in the rgbc structs should be a file path to a file with the following format:
147/// ```no_rust
148/// version sample_count
149///
150/// linear_fit_slope linear_fit_intercept
151///
152/// lux measurement
153/// # repeated multiple times
154/// ```
155/// Only `linear_fit_slope` and `linear_fit_intercept` are used.
156#[derive(Deserialize, Debug)]
157pub struct CalibrationConfiguration {
158    /// A list of [LedConfig]s.
159    pub(crate) leds: Vec<LedConfig>,
160    /// Calibration data collected with all LEDs and backlight off.
161    pub(crate) off: Rgbc<String>,
162    /// Calibration data collection with all LEDs and backlight at maximum brightness.
163    pub(crate) all_on: Rgbc<String>,
164    /// The mean calibration parameters of the fleet of devices matching this product's
165    /// configuration.
166    pub(crate) golden_calibration_params: Rgbc<Parameters>,
167}
168
169/// Light Sensor configuration
170#[derive(Deserialize, Debug)]
171pub struct SensorConfiguration {
172    /// Vendor id of the product, which is used to validate `input_report_path`.
173    pub(crate) vendor_id: u32,
174    /// Product id of the product, which is used to validate `input_report_path`.
175    pub(crate) product_id: u32,
176    /// Coefficients which are multiplied by sensor rgbc results to get lux
177    /// units.
178    pub(crate) rgbc_to_lux_coefficients: Rgbc<f32>,
179    /// Scaling factors which are multiplied by sensor output to get device
180    /// readings in uW/cm^2 SI units (https://en.wikipedia.org/wiki/International_System_of_Units).
181    pub(crate) si_scaling_factors: Rgbc<f32>,
182    /// Range of adjustment settings for low through high sensitivity readings
183    /// from the light sensor.
184    pub(crate) settings: Vec<AdjustmentSetting>,
185}
186
187/// Configuration for a single LED.
188///
189/// Each string in the rgbc struct follows the format specified in [Configuration].
190#[derive(Deserialize, Debug)]
191pub struct LedConfig {
192    /// The name of this LED. It should be a value that matches the names returned in the
193    /// fuchsia.settings.Light FIDL API.
194    name: String,
195    /// Calibration data collected with only this LED on.
196    rgbc: Rgbc<String>,
197}
198
199/// Linear fit parameters for a particular sensor channel. They describe the linear response that a
200/// sensor has to a particular color channel.
201#[derive(Copy, Clone, Serialize, Deserialize, Debug)]
202pub struct Parameters {
203    pub(crate) slope: f32,
204    pub(crate) intercept: f32,
205}
206
207type LedMap = HashMap<String, Rgbc<Parameters>>;
208
209#[async_trait(?Send)]
210pub trait FileLoader {
211    async fn load_file(&self, file_path: &str) -> Result<String, Error>;
212}
213
214#[derive(Clone, Debug, Serialize)]
215/// Calibration data that is used for calibrating light sensor readings.
216pub struct Calibration {
217    /// Map of LED names to the sensor [Parameters] when only the corresponding
218    /// LED was on.
219    leds: LedMap,
220    /// The sensor [Parameters] when all LEDs were off.
221    off: Rgbc<Parameters>,
222    /// The sensor [Parameters] when all LEDs were on.
223    all_on: Rgbc<Parameters>,
224    /// The calibrated slope for the light sensor.
225    calibrated_slope: Rgbc<f32>,
226}
227
228impl Calibration {
229    pub async fn new(
230        configuration: CalibrationConfiguration,
231        file_loader: &impl FileLoader,
232    ) -> Result<Self, Error> {
233        let mut leds = HashMap::new();
234        for led_config in configuration.leds {
235            let name = led_config.name;
236            let config = match led_config
237                .rgbc
238                .map_async(
239                    |file_path| async move { Self::parse_file(&file_path, file_loader).await },
240                )
241                .await
242            {
243                Ok(config) => config,
244                Err(e) => {
245                    log::error!("Failed to map {name:?}'s rgbc field: {e:?}");
246                    log::error!("Will not account for {name:?} in calibration");
247                    continue;
248                }
249            };
250            let _ = leds.insert(name.clone(), config);
251        }
252
253        let off = configuration
254            .off
255            .map_async(|file_path| async move { Self::parse_file(&file_path, file_loader).await })
256            .await
257            .context("Failed to map off rgbc")?;
258        let all_on = configuration
259            .all_on
260            .map_async(|file_path| async move { Self::parse_file(&file_path, file_loader).await })
261            .await
262            .context("Failed to map all_on rgbc")?;
263        let calibrated_slope =
264            configuration.golden_calibration_params.map(|c| c.slope) / off.map(|c| c.slope);
265        Ok(Self { leds, off, all_on, calibrated_slope })
266    }
267
268    #[cfg(test)]
269    pub(crate) fn new_for_test(
270        leds: LedMap,
271        off: Rgbc<Parameters>,
272        all_on: Rgbc<Parameters>,
273        calibrated_slope: Rgbc<f32>,
274    ) -> Self {
275        Self { leds, off, all_on, calibrated_slope }
276    }
277
278    async fn parse_file(path: &str, file_loader: &impl FileLoader) -> Result<Parameters, Error> {
279        let cal_contents = file_loader
280            .load_file(path)
281            .await
282            .with_context(|| format_err!("Could not load {path:?} for parsing"))?;
283
284        // Skip the first 2 words in the file (version and sample count, which are not used).
285        let mut words = cal_contents.trim().split_ascii_whitespace().skip(2);
286        let slope: f32 = words
287            .next()
288            .ok_or_else(|| format_err!("Missing slope"))?
289            .parse()
290            .context("Failed to parse slope")?;
291
292        if !slope.is_finite() {
293            bail!("Slope must not be NaN or Infinity");
294        }
295
296        let intercept: f32 = words
297            .next()
298            .ok_or_else(|| format_err!("Missing intercept"))?
299            .parse()
300            .context("Failed to parse intercept")?;
301
302        if !intercept.is_finite() {
303            bail!("Intercept must not be NaN or Infinity");
304        }
305
306        Ok(Parameters { slope, intercept })
307    }
308
309    pub(crate) fn leds(&self) -> &LedMap {
310        &self.leds
311    }
312
313    pub(crate) fn off(&self) -> Rgbc<Parameters> {
314        self.off
315    }
316
317    pub(crate) fn all_on(&self) -> Rgbc<Parameters> {
318        self.all_on
319    }
320
321    pub(crate) fn calibrated_slope(&self) -> Rgbc<f32> {
322        self.calibrated_slope
323    }
324}
325
326/// Settings used to configure a light sensor.
327#[derive(Copy, Clone, Deserialize, Debug)]
328pub(crate) struct AdjustmentSetting {
329    /// Rgbc integration time.
330    pub(crate) atime: u32,
331    /// Rgbc gain control.
332    pub(crate) gain: u32,
333}
334
335#[cfg(test)]
336mod types_tests;
input_pipeline/light_sensor/types.rs

input_pipeline/light_sensor/
types.rs
