Improve CAM16 parameters and adjust documentation

Author: Ogeon

palette/src/cam16/math.rs

@@ -23,8 +23,19 @@ use self::{chromaticity::ChromaticityType, luminance::LuminanceType};
 pub(crate) mod chromaticity;
 pub(crate) mod luminance;
 
-// This module is originally based on https://observablehq.com/@jrus/cam16.
-// https://rawpedia.rawtherapee.com/CIECAM02 is also informative.
+// This module is originally based on these sources:
+// - https://observablehq.com/@jrus/cam16
+// - "Comprehensive color solutions: CAM16, CAT16, and CAM16-UCS" by Li C, Li Z,
+//   Wang Z, et al.
+//   (https://www.researchgate.net/publication/318152296_Comprehensive_color_solutions_CAM16_CAT16_and_CAM16-UCS)
+// - "Algorithmic improvements for the CIECAM02 and CAM16 color appearance
+//   models" by Nico Schlömer (https://arxiv.org/pdf/1802.06067.pdf)
+// - https://rawpedia.rawtherapee.com/CIECAM02.
+// - "Usage Guidelines for CIECAM97s" by Nathan Moroney
+//   (https://www.imaging.org/common/uploaded%20files/pdfs/Papers/2000/PICS-0-81/1611.pdf)
+// - "CIECAM02 and Its Recent Developments" by Ming Ronnier Luo and Changjun Li
+//   (https://cielab.xyz/pdf/CIECAM02_and_Its_Recent_Developments.pdf)
+// - https://en.wikipedia.org/wiki/CIECAM02
 
 pub(crate) fn xyz_to_cam16<T>(
     xyz: Xyz<white_point::Any, T>,
@@ -268,9 +279,9 @@ where
     // Compute dependent parameters.
     let xyz_w = parameters.white_point * T::from_f64(100.0); // The reference uses 0.0 to 100.0 instead of 0.0 to 1.0.
     let l_a = parameters.adapting_luminance;
-    let y_b = parameters.background_luminance;
+    let y_b = parameters.background_luminance * T::from_f64(100.0); // The reference uses 0.0 to 100.0 instead of 0.0 to 1.0.
     let y_w = xyz_w.y.clone();
-    let surround = parameters.surround.into_value();
+    let surround = parameters.surround.into_percent() * T::from_f64(0.1);
     let c = lazy_select! {
         if surround.gt_eq(&T::one()) => lerp(
             T::from_f64(0.59),
@@ -306,17 +317,18 @@ where
     let n_bb = T::from_f64(0.725) * n.clone().powf(T::from_f64(-0.2)); // Chromatic induction factors
     let n_cb = n_bb.clone();
     // Illuminant discounting (adaptation). Fully adapted = 1
-    let d = if !parameters.discounting {
-        let d = f
-            * (T::one()
+    let d = match parameters.discounting {
+        super::Discounting::Auto => {
+            // The default D function.
+            f * (T::one()
                 - T::one() / T::from_f64(3.6)
-                    * Exp::exp((-l_a - T::from_f64(42.0)) / T::from_f64(92.0)));
-
-        clamp(d, T::zero(), T::one())
-    } else {
-        T::one()
+                    * Exp::exp((-l_a - T::from_f64(42.0)) / T::from_f64(92.0)))
+        }
+        super::Discounting::Custom(degree) => degree,
     };
 
+    let d = clamp(d, T::zero(), T::one());
+
     let rgb_w = m16(xyz_w); // Cone responses of the white point
     let d_rgb = map3(rgb_w.clone(), |c_w| {
         lerp(T::one(), y_w.clone() / c_w, d.clone())

palette/src/cam16/parameters.rs

@@ -5,7 +5,7 @@ use crate::{
     num::{
         Abs, Arithmetics, Clamp, Exp, FromScalar, One, PartialCmp, Powf, Real, Signum, Sqrt, Zero,
     },
-    white_point::{self, WhitePoint, D65},
+    white_point::{self, WhitePoint},
     Xyz,
 };
 
@@ -56,31 +56,36 @@ pub type ParametersDynamicWp<T> = Parameters<Xyz<white_point::Any, T>, T>;
 #[derive(Clone, Copy)]
 #[non_exhaustive]
 pub struct Parameters<WpParam, T> {
-    /// The reference white point. Defaults to `Wp` when it implements
-    /// [`WhitePoint`], or [`D65`] when `Wp` is [`white_point::Any`]. It can
-    /// also be set to a custom value if `Wp` results in the wrong white point.
+    /// White point of the test illuminant, *X<sub>w</sub>* *Y<sub>w</sub>*
+    /// *Z<sub>w</sub>*. *Y<sub>w</sub>* should be normalized to 1.0.
+    ///
+    /// Defaults to `Wp` when it implements [`WhitePoint`]. It can also be set
+    /// to a custom value if `Wp` results in the wrong white point.
     pub white_point: WpParam,
 
-    /// The average luminance of the environment (*L<sub>A</sub>*) in
-    /// *cd/m<sup>2</sup>* (nits). Under a “gray world” assumption this is 20%
-    /// of the luminance of a white reference. Defaults to `T::default()` (0.0
-    /// for `f32` and `f64`).
+    /// The average luminance of the environment (test adapting field)
+    /// (*L<sub>A</sub>*) in *cd/m<sup>2</sup>* (nits).
+    ///
+    /// Under a “gray world” assumption this is 20% of the luminance of a white
+    /// reference. Defaults to `T::default()` (0.0 for `f32` and `f64`).
     pub adapting_luminance: T,
 
-    /// The relative luminance of the nearby background (*Y<sub>b</sub>*), out
-    /// to 10°, on a scale of 0 to 100. Defaults to `T::default()` (0.0 for
-    /// `f32` and `f64`).
+    /// The luminance factor of the background (*Y<sub>b</sub>*), on a scale
+    /// from `0.0` to `1.0` (relative to *Y<sub>w</sub>* = 1.0). Medium grey
+    /// would be `0.2`.
+    ///
+    /// Defaults to `T::default()` (0.0 for `f32` and `f64`).
     pub background_luminance: T,
 
-    /// A description of the peripheral area, with a value from `0` to `2`. Any
-    /// value outside that range will be clamped to `0` or `2`. It has presets
-    /// for "dark", "dim" and "average". Defaults to "average" (`2`).
+    /// A description of the peripheral area, with a value from 0% to 20%. Any
+    /// value outside that range will be clamped to 0% or 20%. It has presets
+    /// for "dark", "dim" and "average". Defaults to "average" (20%).
     pub surround: Surround<T>,
 
-    /// Set to `true` to assume that the observer's eyes have fully adapted to
-    /// the illuminant. The degree of discounting will be set based on the other
-    /// parameters. Defaults to `false`.
-    pub discounting: bool,
+    /// The degree of discounting of (or adaptation to) the reference
+    /// illuminant. Defaults to `Auto`, making the degree of discounting depend
+    /// on the other parameters, but can be customized if necessary.
+    pub discounting: Discounting<T>,
 }
 
 impl<WpParam, T> Parameters<WpParam, T>
@@ -144,7 +149,7 @@ impl<Wp> Parameters<StaticWp<Wp>, f64> {
         adapting_luminance: 40.0f64,
         background_luminance: 20.0f64,
         surround: Surround::Average,
-        discounting: false,
+        discounting: Discounting::Auto,
     };
 }
 
@@ -159,23 +164,7 @@ where
             adapting_luminance: T::default(),
             background_luminance: T::default(),
             surround: Surround::Average,
-            discounting: false,
-        }
-    }
-}
-
-impl<T> Default for Parameters<Xyz<white_point::Any, T>, T>
-where
-    T: Real + Default,
-{
-    #[inline]
-    fn default() -> Self {
-        Self {
-            white_point: D65::get_xyz(),
-            adapting_luminance: T::default(),
-            background_luminance: T::default(),
-            surround: Surround::Average,
-            discounting: false,
+            discounting: Discounting::Auto,
         }
     }
 }
@@ -235,35 +224,54 @@ where
 #[non_exhaustive]
 pub enum Surround<T> {
     /// Represents a dark room, such as a movie theatre. Corresponds to a
-    /// surround value of `0`.
+    /// surround value of 0%.
     Dark,
 
     /// Represents a dimly lit room with a bright TV or monitor. Corresponds to
-    /// a surround value of `1`.
+    /// a surround value of 10%.
     Dim,
 
-    /// Represents a surface color. Corresponds to a surround value of `2`.
+    /// Represents a surface color, such as a print on a 20% reflective,
+    /// uniformly lit background surface. Corresponds to a surround value of
+    /// 20%.
     Average,
 
-    /// Any custom value from `0` to `2`. Any value outside that range will be
-    /// clamped to either `0` or `2`.
-    Custom(T),
+    /// Any custom value from 0% to 20%. Any value outside that range will be
+    /// clamped to either `0.0` or `20.0`.
+    Percent(T),
 }
 
 impl<T> Surround<T> {
-    pub(crate) fn into_value(self) -> T
+    pub(crate) fn into_percent(self) -> T
     where
         T: Real + Clamp,
     {
         match self {
             Surround::Dark => T::from_f64(0.0),
-            Surround::Dim => T::from_f64(1.0),
-            Surround::Average => T::from_f64(2.0),
-            Surround::Custom(value) => value.clamp(T::from_f64(0.0), T::from_f64(2.0)),
+            Surround::Dim => T::from_f64(10.0),
+            Surround::Average => T::from_f64(20.0),
+            Surround::Percent(value) => value.clamp(T::from_f64(0.0), T::from_f64(20.0)),
         }
     }
 }
 
+/// The degree of discounting of (or adaptation to) the illuminant.
+///
+/// See also: https://en.wikipedia.org/wiki/CIECAM02#CAT02.
+#[derive(Clone, Copy)]
+#[non_exhaustive]
+pub enum Discounting<T> {
+    /// Uses luminance levels and surround conditions to calculate the
+    /// discounting, using the original CIECAM16 *D* function. Ranges from
+    /// `0.65` to `1.0`.
+    Auto,
+
+    /// A value between `0.0` and `1.0`, where `0.0` represents no adaptation,
+    /// and `1.0` represents that the observer's vision is fully adapted to the
+    /// illuminant. Values outside that range will be clamped.
+    Custom(T),
+}
+
 /// A trait for types that can be used as white point parameters in
 /// [`Parameters`].
 pub trait WhitePointParameter<T> {