Struct 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 OklabCopy item path

§Characteristics

§Conversions

§Clamping

§Lightening / Darkening

Fields§

Implementations§

impl<T> Oklab<T>

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

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

pub fn from_components(_: (T, T, T)) -> Oklab<T>

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 Oklab<C> as IntoIterator>::IntoIterwhere &'a Oklab<C>: IntoIterator,

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

pub fn get<'a, I, T>( &'a self, index: I, ) -> Option<Oklab<&'a <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<&'a 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) -> Oklab<Vec<T>>

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 as AbsDiffEq>::Epsilon: Clone,

type Epsilon = <T as AbsDiffEq>::Epsilon

fn default_epsilon() -> <Oklab<T> as AbsDiffEq>::Epsilon

fn abs_diff_eq( &self, other: &Oklab<T>, epsilon: <T as AbsDiffEq>::Epsilon, ) -> bool

fn abs_diff_ne( &self, other: &Oklab<T>, epsilon: <T as AbsDiffEq>::Epsilon, ) -> bool

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

type Output = Oklab<T>

fn add(self, c: T) -> <Oklab<T> as Add<T>>::Output

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

type Output = Oklab<T>

fn add(self, other: Oklab<T>) -> <Oklab<T> as Add>::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: Oklab<T>)

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) -> Oklab<T>

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

fn clamp_assign(&mut self)

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

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) -> Oklab<T>

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

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

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

fn default() -> Oklab<T>

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

type Output = Oklab<T>

fn div(self, c: T) -> <Oklab<T> as Div<T>>::Output

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

Struct Oklab

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 Oklab<C> as IntoIterator>::IntoIter
where &'a Oklab<C>: IntoIterator,

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

pub fn get<'a, I, T>( &'a self, index: I, ) -> Option<Oklab<&'a <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<&'a 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 as AbsDiffEq>::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> Clone for Oklab<T>
where T: Clone,

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

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

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

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: Add<Output = T> + Real + Mul<Output = T> + Sub<Output = T> + Clone,

fn distance(self, other: Self) -> Self::Scalar
where Self::Scalar: Sqrt,

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

fn extend<I>(&mut self, iter: I)
where I: IntoIterator<Item = Oklab<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 [Oklab<T>; N]: Default, V: IntoScalarArray<N, Scalar = T>,

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

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

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

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

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

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

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

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

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

impl<T, _S> FromColorUnclamped<Luma<_S, T>> for Oklab<T>
where _S: LumaStandard<WhitePoint = D65>, D65: WhitePoint<T>, Xyz<D65, T>: FromColorUnclamped<Luma<_S, T>> + IntoColorUnclamped<Oklab<T>>,

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