Struct Cam16

#[repr(C)]
pub struct Cam16<T> {
    pub lightness: T,
    pub chroma: T,
    pub hue: Cam16Hue<T>,
    pub brightness: T,
    pub colorfulness: T,
    pub saturation: T,
}

The CIE CAM16 color appearance model.

It’s a set of six technically defined attributes that describe the appearance of a color under certain viewing conditions, and it’s a successor of CIECAM02. The viewing conditions are defined using Parameters, and two sets of parameters can be used to translate the appearance of a color from one set of viewing conditions to another.

The use of the viewing conditions parameters sets Cam16 and its derived types apart from most other color types in this library. It’s, for example, not possible to use FromColor and friends to convert to and from other types, since that would require default viewing conditions to exist. Instead, the explicit Cam16::from_xyz and Cam16::into_xyz are there to bridge the gap.

Not all attributes are used when converting from CAM16, since they are correlated and derived from each other. This library also provides partial versions of this struct, to make it easier to correctly specify a minimum attribute set.

The full list of partial CAM16 variants is:

• Cam16Jch: lightness and chroma.
• Cam16Jmh: lightness and colorfulness.
• Cam16Jsh: lightness and saturation.
• Cam16Qch: brightness and chroma.
• Cam16Qmh: brightness and colorfulness.
• Cam16Qsh: brightness and saturation.

CAM16-UCS

While CIE CAM16 is a model of color appearance, it’s not necessarily suitable as a color space. Instead, there is the CAM16-UCS (CAM16 uniform color space), that’s based off of the lightness, colorfulness and hue attributes. This colorspace is represented by the Cam16UcsJmh and Cam16UcsJab types.

Creating a Value

A Cam16 value would typically come from another color space, or one of the partial sets of CAM16 attributes. All of which require known viewing conditions.

use palette::{
    Srgb, FromColor, IntoColor,
    cam16::{Cam16, Parameters, Cam16Jmh, Cam16UcsJmh},
};

// Customize these according to the viewing conditions:
let mut example_parameters = Parameters::default_static_wp(40.0);

// CAM16 from sRGB, or most other color spaces:
let rgb = Srgb::new(0.3f32, 0.8, 0.1);
let cam16_from_rgb = Cam16::from_xyz(rgb.into_color(), example_parameters);

// Full CAM16 from a partial set (any partial set can be used):
let partial = Cam16Jmh::new(50.0f32, 80.0, 120.0);
let cam16_from_partial = partial.into_full(example_parameters);

// Full CAM16 from CAM16-UCS J'M'h':
let ucs = Cam16UcsJmh::new(50.0f32, 80.0, 120.0);
let cam16_from_ucs = Cam16Jmh::from_color(ucs).into_full(example_parameters);

Fields

lightness: T

The lightness (J) of the color.

It’s a perception of the color’s luminance, but not linear to it, and is relative to the reference white. The lightness of black is 0.0 and the lightness of white is 100.0.

Lightness behaves similarly to L* in Lch or lightness in Hsl.

See also https://en.wikipedia.org/wiki/Lightness.

chroma: T

The chroma (C) of the color.

It’s how chromatic the color appears in comparison with a grey color of the same lightness. Changing the perceived chroma doesn’t change the perceived lightness, and vice versa.

Chroma behaves similarly to chroma in Lch or saturation in Hsl.

See also https://en.wikipedia.org/wiki/Colorfulness#Chroma.

hue: Cam16Hue<T>

The hue (h) of the color.

The color’s position around a color circle, in degrees.

See also https://en.wikipedia.org/wiki/Hue.

brightness: T

The brightness (Q) of the color.

It’s the perception of how much light appears to shine from an object. As opposed to lightness, this is not in comparison to a reference white, but in more absolute terms. Lightness and brightness area also not linearly correlated in CAM16.

Brightness behaves similarly to value in Hsv.

See also https://en.wikipedia.org/wiki/Brightness.

colorfulness: T

The colorfulness (M) of the color.

It’s a perception of how chromatic the color is and usually increases with luminance, unless the brightness is very high.

See also https://en.wikipedia.org/wiki/Colorfulness.

saturation: T

The saturation (s) of the color.

It’s the colorfulness of a color in proportion to its own brightness. The perceived saturation should stay the same when the perceived brightness changes, and vice versa.

Saturation behaves similarly to saturation in Hsv.

See also https://en.wikipedia.org/wiki/Colorfulness#Saturation.

Implementations

impl<T> Cam16<T>

pub fn from_xyz<WpParam>( color: Xyz<WpParam::StaticWp, T>, parameters: impl Into<BakedParameters<WpParam, T::Scalar>>, ) -> Self

where Xyz<WpParam::StaticWp, T>: IntoCam16Unclamped<WpParam, Self, Scalar = T::Scalar>, T: FromScalar, WpParam: WhitePointParameter<T::Scalar>,

Derive CIE CAM16 attributes for the provided color, under the provided viewing conditions.

use palette::{Srgb, IntoColor, cam16::{Cam16, Parameters}};

// Customize these according to the viewing conditions:
let mut example_parameters = Parameters::default_static_wp(40.0);

let rgb = Srgb::new(0.3f32, 0.8, 0.1);
let cam16 = Cam16::from_xyz(rgb.into_color(), example_parameters);

It’s also possible to “pre-bake” the parameters, to avoid recalculate some of the derived values when converting multiple color value.

use palette::{Srgb, IntoColor, cam16::{Cam16, Parameters}};

// Customize these according to the viewing conditions:
let mut example_parameters = Parameters::default_static_wp(40.0);

let baked_parameters = example_parameters.bake();

let rgb = Srgb::new(0.3f32, 0.8, 0.1);
let cam16 = Cam16::from_xyz(rgb.into_color(), baked_parameters);

pub fn into_xyz<WpParam>( self, parameters: impl Into<BakedParameters<WpParam, T::Scalar>>, ) -> Xyz<WpParam::StaticWp, T>

where Self: Cam16IntoUnclamped<WpParam, Xyz<WpParam::StaticWp, T>, Scalar = T::Scalar>, WpParam: WhitePointParameter<T>, T: FromScalar,

Construct an XYZ color that matches these CIE CAM16 attributes, under the provided viewing conditions.

This assumes that all of the correlated attributes are consistent, as only some of them are actually used. You may want to use one of the partial CAM16 representations for more control over which set of attributes that should be.

use palette::{Srgb, FromColor, cam16::{Cam16, Parameters}};

// Customize these according to the viewing conditions:
let mut example_parameters = Parameters::default_static_wp(40.0);

let cam16: Cam16<f32> = get_cam16_value();
let rgb = Srgb::from_color(cam16.into_xyz(example_parameters));

It’s also possible to “pre-bake” the parameters, to avoid recalculate some of the derived values when converting multiple color value.

use palette::{Srgb, FromColor, cam16::{Cam16, Parameters}};

// Customize these according to the viewing conditions:
let mut example_parameters = Parameters::default_static_wp(40.0);

let baked_parameters = example_parameters.bake();

let cam16: Cam16<f32> = get_cam16_value();
let rgb = Srgb::from_color(cam16.into_xyz(baked_parameters));

Trait Implementations

impl<T> AbsDiffEq for Cam16<T>

where T: AbsDiffEq, T::Epsilon: Clone, Cam16Hue<T>: AbsDiffEq<Epsilon = T::Epsilon>,

type Epsilon = <T as AbsDiffEq>::Epsilon

Used for specifying relative comparisons.

fn default_epsilon() -> Self::Epsilon

The default tolerance to use when testing values that are close together.

fn abs_diff_eq(&self, other: &Self, epsilon: T::Epsilon) -> bool

A test for equality that uses the absolute difference to compute the approximate equality of two numbers.

fn abs_diff_ne(&self, other: &Self, epsilon: T::Epsilon) -> bool

The inverse of AbsDiffEq::abs_diff_eq.

impl<WpParam, T> Cam16FromUnclamped<WpParam, Cam16Jch<T>> for Cam16<T>

where WpParam: WhitePointParameter<T>, T: Real + FromScalar + Zero + Arithmetics + Sqrt + PartialCmp + Clone, T::Mask: LazySelect<T> + Clone, T::Scalar: Clone,

type Scalar = <T as FromScalar>::Scalar

The number type that’s used in parameters when converting.

fn cam16_from_unclamped( cam16: Cam16Jch<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts color into Self, using the provided parameters.

impl<WpParam, T> Cam16FromUnclamped<WpParam, Cam16Jmh<T>> for Cam16<T>

where WpParam: WhitePointParameter<T>, T: Real + FromScalar + Zero + Arithmetics + Sqrt + PartialCmp + Clone, T::Mask: LazySelect<T> + Clone, T::Scalar: Clone,

type Scalar = <T as FromScalar>::Scalar

The number type that’s used in parameters when converting.

fn cam16_from_unclamped( cam16: Cam16Jmh<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts color into Self, using the provided parameters.

impl<WpParam, T> Cam16FromUnclamped<WpParam, Cam16Jsh<T>> for Cam16<T>

where WpParam: WhitePointParameter<T>, T: Real + FromScalar + Zero + Arithmetics + Sqrt + PartialCmp + Clone, T::Mask: LazySelect<T> + Clone, T::Scalar: Clone,

type Scalar = <T as FromScalar>::Scalar

The number type that’s used in parameters when converting.

fn cam16_from_unclamped( cam16: Cam16Jsh<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts color into Self, using the provided parameters.

impl<WpParam, T> Cam16FromUnclamped<WpParam, Cam16Qch<T>> for Cam16<T>

where WpParam: WhitePointParameter<T>, T: Real + FromScalar + Zero + Arithmetics + Sqrt + PartialCmp + Clone, T::Mask: LazySelect<T> + Clone, T::Scalar: Clone,

type Scalar = <T as FromScalar>::Scalar

The number type that’s used in parameters when converting.

fn cam16_from_unclamped( cam16: Cam16Qch<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts color into Self, using the provided parameters.

impl<WpParam, T> Cam16FromUnclamped<WpParam, Cam16Qmh<T>> for Cam16<T>

where WpParam: WhitePointParameter<T>, T: Real + FromScalar + Zero + Arithmetics + Sqrt + PartialCmp + Clone, T::Mask: LazySelect<T> + Clone, T::Scalar: Clone,

type Scalar = <T as FromScalar>::Scalar

The number type that’s used in parameters when converting.

fn cam16_from_unclamped( cam16: Cam16Qmh<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts color into Self, using the provided parameters.

impl<WpParam, T> Cam16FromUnclamped<WpParam, Cam16Qsh<T>> for Cam16<T>

where WpParam: WhitePointParameter<T>, T: Real + FromScalar + Zero + Arithmetics + Sqrt + PartialCmp + Clone, T::Mask: LazySelect<T> + Clone, T::Scalar: Clone,

type Scalar = <T as FromScalar>::Scalar

The number type that’s used in parameters when converting.

fn cam16_from_unclamped( cam16: Cam16Qsh<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts color into Self, using the provided parameters.

impl<WpParam, T> Cam16FromUnclamped<WpParam, Xyz<<WpParam as WhitePointParameter<<T as FromScalar>::Scalar>>::StaticWp, T>> for Cam16<T>

where WpParam: WhitePointParameter<T::Scalar>, T: Real + FromScalar + Arithmetics + Powf + Sqrt + Abs + Signum + Trigonometry + RealAngle + Clone, T::Scalar: Clone,

type Scalar = <T as FromScalar>::Scalar

The number type that’s used in parameters when converting.

fn cam16_from_unclamped( color: Xyz<WpParam::StaticWp, T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts color into Self, using the provided parameters.

impl<T> Clamp for Cam16<T>

where T: Clamp + Zero,

fn clamp(self) -> Self

Return a new color where out-of-bounds components have been changed to the nearest valid values.

impl<T> ClampAssign for Cam16<T>

where T: ClampAssign + Zero,

fn clamp_assign(&mut self)

Changes out-of-bounds components to the nearest valid values.

impl<T: Clone> Clone for Cam16<T>

fn clone(&self) -> Cam16<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Cam16<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Cam16<T>

fn default() -> Cam16<T>

Returns the “default value” for a type.

impl<T, V, const N: usize> From<[Cam16<T>; N]> for Cam16<V>

where [T; N]: Default, V: FromScalarArray<N, Scalar = T>,

fn from(colors: [Cam16<T>; N]) -> Self

Converts to this type from the input type.

impl<T> From<Cam16<T>> for Cam16Jch<T>

fn from(value: Cam16<T>) -> Self

Converts to this type from the input type.

impl<T> From<Cam16<T>> for Cam16Jmh<T>

fn from(value: Cam16<T>) -> Self

Converts to this type from the input type.

impl<T> From<Cam16<T>> for Cam16Jsh<T>

fn from(value: Cam16<T>) -> Self

Converts to this type from the input type.

impl<T> From<Cam16<T>> for Cam16Qch<T>

fn from(value: Cam16<T>) -> Self

Converts to this type from the input type.

impl<T> From<Cam16<T>> for Cam16Qmh<T>

fn from(value: Cam16<T>) -> Self

Converts to this type from the input type.

impl<T> From<Cam16<T>> for Cam16Qsh<T>

fn from(value: Cam16<T>) -> Self

Converts to this type from the input type.

impl<T, V, const N: usize> From<Cam16<V>> for [Cam16<T>; N]

where Self: Default, V: IntoScalarArray<N, Scalar = T>,

fn from(color: Cam16<V>) -> Self

Converts to this type from the input type.

impl<WpParam, T> FromCam16Unclamped<WpParam, Cam16<T>> for Xyz<WpParam::StaticWp, T>

where WpParam: WhitePointParameter<T>, T: FromScalar, Cam16Jch<T>: Cam16IntoUnclamped<WpParam, Self, Scalar = T::Scalar>,

type Scalar = <T as FromScalar>::Scalar

The number type that’s used in parameters when converting.

fn from_cam16_unclamped( cam16: Cam16<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts cam16 into Self, using the provided parameters.

impl<WpParam, T> FromCam16Unclamped<WpParam, Cam16Jch<T>> for Cam16<T>

where Self: Cam16FromUnclamped<WpParam, Cam16Jch<T>>,

type Scalar = <Cam16<T> as Cam16FromUnclamped<WpParam, Cam16Jch<T>>>::Scalar

The number type that’s used in parameters when converting.

fn from_cam16_unclamped( cam16: Cam16Jch<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts cam16 into Self, using the provided parameters.

impl<WpParam, T> FromCam16Unclamped<WpParam, Cam16Jmh<T>> for Cam16<T>

where Self: Cam16FromUnclamped<WpParam, Cam16Jmh<T>>,

type Scalar = <Cam16<T> as Cam16FromUnclamped<WpParam, Cam16Jmh<T>>>::Scalar

The number type that’s used in parameters when converting.

fn from_cam16_unclamped( cam16: Cam16Jmh<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts cam16 into Self, using the provided parameters.

impl<WpParam, T> FromCam16Unclamped<WpParam, Cam16Jsh<T>> for Cam16<T>

where Self: Cam16FromUnclamped<WpParam, Cam16Jsh<T>>,

type Scalar = <Cam16<T> as Cam16FromUnclamped<WpParam, Cam16Jsh<T>>>::Scalar

The number type that’s used in parameters when converting.

fn from_cam16_unclamped( cam16: Cam16Jsh<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts cam16 into Self, using the provided parameters.

impl<WpParam, T> FromCam16Unclamped<WpParam, Cam16Qch<T>> for Cam16<T>

where Self: Cam16FromUnclamped<WpParam, Cam16Qch<T>>,

type Scalar = <Cam16<T> as Cam16FromUnclamped<WpParam, Cam16Qch<T>>>::Scalar

The number type that’s used in parameters when converting.

fn from_cam16_unclamped( cam16: Cam16Qch<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts cam16 into Self, using the provided parameters.

impl<WpParam, T> FromCam16Unclamped<WpParam, Cam16Qmh<T>> for Cam16<T>

where Self: Cam16FromUnclamped<WpParam, Cam16Qmh<T>>,

type Scalar = <Cam16<T> as Cam16FromUnclamped<WpParam, Cam16Qmh<T>>>::Scalar

The number type that’s used in parameters when converting.

fn from_cam16_unclamped( cam16: Cam16Qmh<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts cam16 into Self, using the provided parameters.

impl<WpParam, T> FromCam16Unclamped<WpParam, Cam16Qsh<T>> for Cam16<T>

where Self: Cam16FromUnclamped<WpParam, Cam16Qsh<T>>,

type Scalar = <Cam16<T> as Cam16FromUnclamped<WpParam, Cam16Qsh<T>>>::Scalar

The number type that’s used in parameters when converting.

fn from_cam16_unclamped( cam16: Cam16Qsh<T>, parameters: BakedParameters<WpParam, Self::Scalar>, ) -> Self

Converts cam16 into Self, using the provided parameters.

impl<T> FromColorUnclamped<Cam16<T>> for Cam16Jch<T>

fn from_color_unclamped(val: Cam16<T>) -> Self

Convert from T. The resulting color might be invalid in its color space.

impl<T> FromColorUnclamped<Cam16<T>> for Cam16Jmh<T>

fn from_color_unclamped(val: Cam16<T>) -> Self

Convert from T. The resulting color might be invalid in its color space.

impl<T> FromColorUnclamped<Cam16<T>> for Cam16Jsh<T>

fn from_color_unclamped(val: Cam16<T>) -> Self

Convert from T. The resulting color might be invalid in its color space.

impl<T> FromColorUnclamped<Cam16<T>> for Cam16Qch<T>

fn from_color_unclamped(val: Cam16<T>) -> Self

Convert from T. The resulting color might be invalid in its color space.

impl<T> FromColorUnclamped<Cam16<T>> for Cam16Qmh<T>

fn from_color_unclamped(val: Cam16<T>) -> Self

Convert from T. The resulting color might be invalid in its color space.

impl<T> FromColorUnclamped<Cam16<T>> for Cam16Qsh<T>

fn from_color_unclamped(val: Cam16<T>) -> Self

Convert from T. The resulting color might be invalid in its color space.

impl<T> FromColorUnclamped<Cam16<T>> for Cam16UcsJab<T>

where Cam16UcsJmh<T>: FromColorUnclamped<Cam16<T>> + IntoColorUnclamped<Self>,

fn from_color_unclamped(color: Cam16<T>) -> Self

Convert from T. The resulting color might be invalid in its color space.

impl<T> FromColorUnclamped<Cam16<T>> for Cam16UcsJmh<T>

where Cam16Jmh<T>: FromColorUnclamped<Cam16<T>> + IntoColorUnclamped<Self>,

fn from_color_unclamped(color: Cam16<T>) -> Self

Convert from T. The resulting color might be invalid in its color space.

impl<T> GetHue for Cam16<T>

where T: Clone,

type Hue = Cam16Hue<T>

The kind of hue unit this color space uses.

fn get_hue(&self) -> Cam16Hue<T>

Calculate a hue if possible.

impl<T> HasBoolMask for Cam16<T>

where T: HasBoolMask,

type Mask = <T as HasBoolMask>::Mask

The mask type to use for selecting Self values.

impl<T> IsWithinBounds for Cam16<T>

where T: PartialCmp + Zero, T::Mask: BitAnd<Output = T::Mask>,

fn is_within_bounds(&self) -> T::Mask

Check if the color’s components are within the expected range bounds.

impl<T> PartialEq for Cam16<T>

where T: PartialEq, Cam16Hue<T>: PartialEq,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> RelativeEq for Cam16<T>

where T: RelativeEq, T::Epsilon: Clone, Cam16Hue<T>: RelativeEq + AbsDiffEq<Epsilon = T::Epsilon>,

fn default_max_relative() -> T::Epsilon

The default relative tolerance for testing values that are far-apart.

fn relative_eq( &self, other: &Self, epsilon: T::Epsilon, max_relative: T::Epsilon, ) -> bool

A test for equality that uses a relative comparison if the values are far apart.

fn relative_ne( &self, other: &Self, epsilon: T::Epsilon, max_relative: T::Epsilon, ) -> bool

The inverse of RelativeEq::relative_eq.

impl<T> UlpsEq for Cam16<T>

where T: UlpsEq, T::Epsilon: Clone, Cam16Hue<T>: UlpsEq + AbsDiffEq<Epsilon = T::Epsilon>,

fn default_max_ulps() -> u32

The default ULPs to tolerate when testing values that are far-apart.

fn ulps_eq(&self, other: &Self, epsilon: T::Epsilon, max_ulps: u32) -> bool

A test for equality that uses units in the last place (ULP) if the values are far apart.

fn ulps_ne(&self, other: &Self, epsilon: T::Epsilon, max_ulps: u32) -> bool

The inverse of UlpsEq::ulps_eq.

impl<T, _A> WithAlpha<_A> for Cam16<T>

where _A: Stimulus,

type Color = Cam16<T>

The opaque color type, without any transparency.

type WithAlpha = Alpha<Cam16<T>, _A>

The color type with transparency applied.

fn with_alpha(self, alpha: _A) -> Self::WithAlpha

Transforms the color into a transparent color with the provided alpha value. If Self already has a transparency, it is overwritten.

fn without_alpha(self) -> Self::Color

Removes the transparency from the color. If Self::Color has an internal transparency field, that field will be set to A::max_intensity() to make it opaque.

fn split(self) -> (Self::Color, _A)

Splits the color into separate color and transparency values.

fn opaque(self) -> Self::WithAlpha

where A: Stimulus,

Transforms the color into a fully opaque color with a transparency field. If Self already has a transparency, it is overwritten.

fn transparent(self) -> Self::WithAlpha

where A: Zero,

Transforms the color into a fully transparent color. If Self already has a transparency, it is overwritten.

impl<T: Copy> Copy for Cam16<T>

impl<T> Eq for Cam16<T>

where T: Eq, Cam16Hue<T>: Eq,