Struct palette::Oklab

source ·

#[repr(C)]
pub struct Oklab<T = f32> {
    pub l: T,
    pub a: T,
    pub b: T,
}

Expand description

The Oklab color space.

§Characteristics

Oklab is a perceptual color space. It does not relate to an output device (a monitor or printer) but instead relates to the CIE standard observer – an averaging of the results of color matching experiments under laboratory conditions.

Oklab is a uniform color space (Compare to the HSV color space). It is useful for things like:

Turning an image grayscale, while keeping the perceived lightness the same
Increasing the saturation of colors, while maintaining perceived hue and lightness
Creating smooth and uniform looking transitions between colors

Oklab’s structure is similar to L*a*b*. It is based on the opponent color model of human vision, where red and green form an opponent pair, and blue and yellow form an opponent pair.

Oklab uses D65’s whitepoint – daylight illumination, which is also used by sRGB, rec2020 and Display P3 color spaces – and assumes normal well-lit viewing conditions, to which the eye is adapted. Thus Oklabs lightness l technically is a measure of relative brightness – a subjective measure – not relative luminance. The lightness is scale/exposure-independend, i.e. independent of the actual luminance of the color, as displayed by some medium, and even for blindingly bright colors or very bright or dark viewing conditions assumes, that the eye is adapted to the color’s luminance and the hue and chroma are perceived linearly.

Oklab’s chroma is unlimited. Thus it can represent colors of any color space (including HDR). l is in the range 0.0 .. 1.0 and a and b are unbounded.

§Conversions

Oklch is a cylindrical form of Oklab.

Oklab colors converted from valid (i.e. clamped) sRGB will be in the sRGB gamut.

Okhsv, Okhwb and Okhsl reference the sRGB gamut. The transformation from Oklab to one of them is based on the assumption, that the transformed Oklab value is within sRGB.

Okhsv, Okhwb and Okhsl are not applicable to HDR, which also come with color spaces with wider gamuts. They require additional research.

When a Oklab color is converted from Srgb or a equivalent color space, e.g. Hsv, Okhsv, Hsl, Okhsl, Hwb, Okhwb, it’s lightness will be relative to the (user controlled) maximum contrast and luminance of the display device, to which the eye is assumed to be adapted.

§Clamping

Clamping will only clamp l. Clamping does not guarantee the color to be inside the perceptible or any display-dependent color space (like sRGB).

To ensure a color is within the sRGB gamut, it can first be converted to Okhsv, clamped there and converted it back to Oklab.

// Display P3 yellow according to https://colorjs.io/apps/convert/?color=color(display-p3%201%201%200)&precision=17
let oklab = Oklab::from_color_unclamped(LinSrgb::new(1.0, 1.0, -0.098273600140966));
let okhsv: Okhsv<f64> = Okhsv::from_color_unclamped(oklab);
assert!(!okhsv.is_within_bounds());
let clamped_okhsv = okhsv.clamp();
assert!(clamped_okhsv.is_within_bounds());
let linsrgb = LinSrgb::from_color_unclamped(clamped_okhsv);
let  expected = LinSrgb::new(1.0, 0.9876530763223166, 0.0);
assert_abs_diff_eq!(expected, linsrgb, epsilon = 0.02);

Since the conversion contains a gamut mapping, it will map the color to one of the perceptually closest locations in the sRGB gamut. Gamut mapping – unlike clamping – is an expensive operation. To get computationally cheaper (and perceptually much worse) results, convert directly to Srgb and clamp there.

§Lightening / Darkening

Lightening and Darkening will change l, as expected. However, either operation may leave an implicit color space (the percetible or a display dependent color space like sRGB).

To ensure a color is within the sRGB gamut, first convert it to Okhsl, lighten/darken it there and convert it back to Oklab.

Fields§

§l: T

l is the lightness of the color. 0 gives absolute black and 1 gives the full white point luminance of the display medium.

D65 (normalized with Y=1, i.e. white according to the adaption of the eye) transforms to L=1,a=0,b=0. However intermediate values differ from those of CIELab non-linearly.

§a: T

a changes the hue from reddish to greenish, when moving from positive to negative values and becomes more intense with larger absolute values.

The exact orientation is determined by b

§b: T

b changes the hue from yellowish to blueish, when moving from positive to negative values and becomes more intense with larger absolute values.

Struct palette::Oklab

§Characteristics

§Conversions

§Clamping

§Lightening / Darkening

Fields§

Implementations§

impl<T> Oklab<T>

pub const fn new(l: T, a: T, b: T) -> Self

pub fn into_components(self) -> (T, T, T)

pub fn from_components((l, a, b): (T, T, T)) -> Self

impl<T> Oklab<T>where T: Zero + One,

pub fn min_l() -> T

pub fn max_l() -> T

impl<T> Oklab<&T>

pub fn copied(&self) -> Oklab<T>where T: Copy,

pub fn cloned(&self) -> Oklab<T>where T: Clone,

impl<T> Oklab<&mut T>

pub fn set(&mut self, value: Oklab<T>)

pub fn as_refs(&self) -> Oklab<&T>

pub fn copied(&self) -> Oklab<T>where T: Copy,

pub fn cloned(&self) -> Oklab<T>where T: Clone,

impl<C> Oklab<C>

pub fn iter<'a>(&'a self) -> <&'a Self as IntoIterator>::IntoIterwhere &'a Self: IntoIterator,

pub fn iter_mut<'a>(&'a mut self) -> <&'a mut Self as IntoIterator>::IntoIterwhere &'a mut Self: IntoIterator,

pub fn get<'a, I, T>( &'a self, index: I ) -> Option<Oklab<&<I as SliceIndex<[T]>>::Output>>where T: 'a, C: AsRef<[T]>, I: SliceIndex<[T]> + Clone,

pub fn get_mut<'a, I, T>( &'a mut self, index: I ) -> Option<Oklab<&mut <I as SliceIndex<[T]>>::Output>>where T: 'a, C: AsMut<[T]>, I: SliceIndex<[T]> + Clone,

impl<T> Oklab<Vec<T>>

pub fn with_capacity(capacity: usize) -> Self

pub fn push(&mut self, value: Oklab<T>)

pub fn pop(&mut self) -> Option<Oklab<T>>

pub fn clear(&mut self)

pub fn drain<R>(&mut self, range: R) -> Iter<Drain<'_, T>> ⓘwhere R: RangeBounds<usize> + Clone,

Trait Implementations§

impl<T> AbsDiffEq for Oklab<T>where T: AbsDiffEq, T::Epsilon: Clone,

type Epsilon = <T as AbsDiffEq>::Epsilon

fn default_epsilon() -> Self::Epsilon

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

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

impl<T> Add<T> for Oklab<T>where T: Add<Output = T> + Clone,

type Output = Oklab<T>

fn add(self, c: T) -> Self::Output

impl<T> Add for Oklab<T>where T: Add<Output = T>,

type Output = Oklab<T>

fn add(self, other: Self) -> Self::Output

impl<T> AddAssign<T> for Oklab<T>where T: AddAssign + Clone,

fn add_assign(&mut self, c: T)

impl<T> AddAssign for Oklab<T>where T: AddAssign,

fn add_assign(&mut self, other: Self)

impl<T> ArrayCast for Oklab<T>

type Array = [T; 3]

impl<T> AsMut<[T]> for Oklab<T>

fn as_mut(&mut self) -> &mut [T]

impl<T> AsMut<[T; 3]> for Oklab<T>

fn as_mut(&mut self) -> &mut [T; 3]

impl<T> AsMut<Oklab<T>> for [T; 3]

fn as_mut(&mut self) -> &mut Oklab<T>

impl<T> AsRef<[T]> for Oklab<T>

fn as_ref(&self) -> &[T]

impl<T> AsRef<[T; 3]> for Oklab<T>

fn as_ref(&self) -> &[T; 3]

impl<T> AsRef<Oklab<T>> for [T; 3]

fn as_ref(&self) -> &Oklab<T>

impl<T> Clamp for Oklab<T>where T: Clamp + Zero + One,

fn clamp(self) -> Self

impl<T> ClampAssign for Oklab<T>where T: ClampAssign + Zero + One,

fn clamp_assign(&mut self)

impl<T: Clone> Clone for Oklab<T>

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

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

impl<T> Complementary for Oklab<T>where T: Neg<Output = T>,

fn complementary(self) -> Self

impl<T: Debug> Debug for Oklab<T>

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

impl<T> Default for Oklab<T>where T: Zero,

fn default() -> Self

impl<'de, T> Deserialize<'de> for Oklab<T>where T: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,

impl<T> Distribution<Oklab<T>> for Standardwhere Standard: Distribution<T>, T: Mul<Output = T> + Add<Output = T> + Sub<Output = T> + One,

fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Oklab<T>

impl<T> Oklab<T>
where T: Zero + One,

pub fn copied(&self) -> Oklab<T>
where T: Copy,

pub fn cloned(&self) -> Oklab<T>
where T: Clone,

pub fn copied(&self) -> Oklab<T>
where T: Copy,

pub fn cloned(&self) -> Oklab<T>
where T: Clone,

pub fn iter<'a>(&'a self) -> <&'a Self as IntoIterator>::IntoIter
where &'a Self: IntoIterator,

pub fn iter_mut<'a>(&'a mut self) -> <&'a mut Self as IntoIterator>::IntoIter
where &'a mut Self: IntoIterator,

pub fn get<'a, I, T>( &'a self, index: I ) -> Option<Oklab<&<I as SliceIndex<[T]>>::Output>>
where T: 'a, C: AsRef<[T]>, I: SliceIndex<[T]> + Clone,

pub fn get_mut<'a, I, T>( &'a mut self, index: I ) -> Option<Oklab<&mut <I as SliceIndex<[T]>>::Output>>
where T: 'a, C: AsMut<[T]>, I: SliceIndex<[T]> + Clone,

pub fn drain<R>(&mut self, range: R) -> Iter<Drain<'_, T>> ⓘ
where R: RangeBounds<usize> + Clone,

impl<T> AbsDiffEq for Oklab<T>
where T: AbsDiffEq, T::Epsilon: Clone,

impl<T> Add<T> for Oklab<T>
where T: Add<Output = T> + Clone,

impl<T> Add for Oklab<T>
where T: Add<Output = T>,

impl<T> AddAssign<T> for Oklab<T>
where T: AddAssign + Clone,

impl<T> AddAssign for Oklab<T>
where T: AddAssign,

impl<T> Clamp for Oklab<T>
where T: Clamp + Zero + One,

impl<T> ClampAssign for Oklab<T>
where T: ClampAssign + Zero + One,

impl<T> Complementary for Oklab<T>
where T: Neg<Output = T>,

impl<T> Default for Oklab<T>
where T: Zero,

impl<'de, T> Deserialize<'de> for Oklab<T>
where T: Deserialize<'de>,

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where __D: Deserializer<'de>,

impl<T> Distribution<Oklab<T>> for Standard
where Standard: Distribution<T>, T: Mul<Output = T> + Add<Output = T> + Sub<Output = T> + One,

fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T>
where R: Rng, Self: Sized,

fn map<F, S>(self, func: F) -> DistMap<Self, F, T, S>
where F: Fn(T) -> S, Self: Sized,

impl<T> Div<T> for Oklab<T>
where T: Div<Output = T> + Clone,

impl<T> Div for Oklab<T>
where T: Div<Output = T>,

impl<T> DivAssign<T> for Oklab<T>
where T: DivAssign + Clone,

impl<T> DivAssign for Oklab<T>
where T: DivAssign,

impl<T> EuclideanDistance for Oklab<T>
where T: Real + Sub<T, Output = T> + Add<T, Output = T> + Mul<T, Output = T> + Clone,

impl<T, C> Extend<Oklab<T>> for Oklab<C>
where C: Extend<T>,

impl<T, V, const N: usize> From<[Oklab<T>; N]> for Oklab<V>
where [T; N]: Default, V: FromScalarArray<N, Scalar = T>,

impl<T, V, const N: usize> From<Oklab<V>> for [Oklab<T>; N]
where Self: Default, V: IntoScalarArray<N, Scalar = T>,

impl<T> From<PreAlpha<Oklab<T>>> for Oklab<T>
where Self: Premultiply<Scalar = T>,

impl<T, _C, _A> FromColorUnclamped<Alpha<_C, _A>> for Oklab<T>
where _C: IntoColorUnclamped<Self>,

impl<T, _S> FromColorUnclamped<Hsl<_S, T>> for Oklab<T>
where _S: RgbStandard, _S::Space: RgbSpace<WhitePoint = D65>, D65: WhitePoint<T>, Rgb<_S, T>: FromColorUnclamped<Hsl<_S, T>> + IntoColorUnclamped<Self>,

impl<T> FromColorUnclamped<Hsluv<D65, T>> for Oklab<T>
where D65: WhitePoint<T>, Xyz<D65, T>: FromColorUnclamped<Hsluv<D65, T>> + IntoColorUnclamped<Self>,

impl<T, _S> FromColorUnclamped<Hsv<_S, T>> for Oklab<T>
where _S: RgbStandard, _S::Space: RgbSpace<WhitePoint = D65>, D65: WhitePoint<T>, Rgb<_S, T>: FromColorUnclamped<Hsv<_S, T>> + IntoColorUnclamped<Self>,

impl<T, _S> FromColorUnclamped<Hwb<_S, T>> for Oklab<T>
where _S: RgbStandard, _S::Space: RgbSpace<WhitePoint = D65>, D65: WhitePoint<T>, Rgb<_S, T>: FromColorUnclamped<Hwb<_S, T>> + IntoColorUnclamped<Self>,

impl<T> FromColorUnclamped<Lab<D65, T>> for Oklab<T>
where D65: WhitePoint<T>, Xyz<D65, T>: FromColorUnclamped<Lab<D65, T>> + IntoColorUnclamped<Self>,

impl<T> FromColorUnclamped<Lch<D65, T>> for Oklab<T>
where D65: WhitePoint<T>, Xyz<D65, T>: FromColorUnclamped<Lch<D65, T>> + IntoColorUnclamped<Self>,

impl<T> FromColorUnclamped<Lchuv<D65, T>> for Oklab<T>
where D65: WhitePoint<T>, Xyz<D65, T>: FromColorUnclamped<Lchuv<D65, T>> + IntoColorUnclamped<Self>,