Struct prisma::Xyz

#[repr(C)]pub struct Xyz<T> { /* fields omitted */ }

The CIE XYZ device-independent color space

The XYZ color space was defined by the International Commission on Illumination (CIE) in 1931 to be able to describe color human vision. It was developed from a series of experiments to map the human perceptual response to light. A set of "color matching" functions were developed, and from these the XYZ space is defined. XYZ forms an authoritative definition of perceived colors, and is thus used widely in many fields where accurate color representation and conversion are needed.

XYZ is the "parent" device independent color space from which all other color spaces are defined. All device-dependent color spaces are defined by a set of (generally three) primaries defined in XYZ plus a white point defining the viewing conditions. The transformation from RGB to XYZ can be represented in a 3x3 matrix of values, which when multiplied against a vector of (R, G, B) produces a vector of (X, Y, Z).

While XYZ is authoritative, it is not generally the most convenient space to do manipulations in. The Y of XYZ is luminance whereas X and Z are both linearly independent responses to color, but do not map neatly to an observable color. XYZ is also not perceptually uniform.

For perceptual uniformity, CIE defined two further spaces that are transformations of XYZ: LAV and LUV. These are non-linearly derived from XYZ, and both are approximately perceptually uniform, although with different properties. See Lab and Luv for more details on those color spaces.

XYZ coordinates are not technically bounded in any range, and the visible region of the space is not a simple shape. Many combinations of XYZ will correspond to no representable color and are therefore "imaginary" to humans.

Standard Observer

XYZ is actually a family of spaces, each constructed from a set of color matching functions. Currently there are two different "standard observers" defined by the CIE, which are the color matching functions obtained from experiments that represent the average human eye response at a given field of view. The $2^{\circ}$ standard observer is by far the most widely used, and is defined using only the center-most 2 degrees of vision. SRgb and the majority of other used color spaces are defined against this standard observer. A later $10^{\circ}$ standard observer was created representing a larger field of view. These two standard observers differ in their color matching functions by a modest but not insignificant amount, and XYZ using one is not compatible with XYZ using the other. While $10^{\circ}$ standard observer is recommended for use in many applications using more than about $4^{\circ}$ of vision, the $2^{\circ}$ standard observer is still much more widely used in practice.

Implementations

impl<T> Xyz<T> where
    T: FreeChannelScalar, 

pub fn new(x: T, y: T, z: T) -> Self

Construct a new Xyz instance from x, y and z

pub fn color_cast<TOut>(&self) -> Xyz<TOut> where
    T: ChannelFormatCast<TOut>,
    TOut: FreeChannelScalar, 

Convert the internal channel scalar format

pub fn x(&self) -> T

Returns the X value

pub fn y(&self) -> T

Returns the Y value

pub fn z(&self) -> T

Returns the Z value

pub fn x_mut(&mut self) -> &mut T

Returns a mutable reference to the X value

pub fn y_mut(&mut self) -> &mut T

Returns a mutable reference to the Y value

pub fn z_mut(&mut self) -> &mut T

Returns a mutable reference to the Z value

pub fn set_x(&mut self, val: T)

Set the X value

pub fn set_y(&mut self, val: T)

Set the Y value

pub fn set_z(&mut self, val: T)

Set the Z value

Trait Implementations

impl<T> AbsDiffEq<Xyz<T>> for Xyz<T> where
    T: FreeChannelScalar + AbsDiffEq,
    T::Epsilon: Clone, 

type Epsilon = T::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: Self::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: &Rhs, epsilon: Self::Epsilon) -> bool

The inverse of ApproxEq::abs_diff_eq.

impl<T> Bounded for Xyz<T> where
    T: FreeChannelScalar, 

fn normalize(self) -> Self

Return a value clipped inside the normalized range

fn is_normalized(&self) -> bool

Return true if the value is normalized

impl<T> Broadcast for Xyz<T> where
    T: FreeChannelScalar, 

fn broadcast(value: T) -> Self

Construct Self with each channel set to value

impl<T: Clone> Clone for Xyz<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Color for Xyz<T> where
    T: FreeChannelScalar, 

type Tag = XyzTag

The unique tag unit struct identifying the color type

type ChannelsTuple = (T, T, T)

A tuple of types for each channel in the color

fn num_channels() -> u32

Return how many channels the color has

fn to_tuple(self) -> Self::ChannelsTuple

Convert a color into a tuple of channels

impl<T, E> ConvertFromXyz<T, Xyz<T>> for EncodedColorSpace<T, E> where
    T: PosNormalChannelScalar + FreeChannelScalar + ChannelFormatCast<f64>,
    f64: ChannelFormatCast<T>,
    E: ColorEncoding + PartialEq + Clone, 

type OutputColor = Rgb<T>

The color type converted to.

fn convert_from_xyz_raw(&self, color: &Xyz<T>) -> Rgb<T>

Convert color out of the XYZ space, returning a bare color without any wrappers

fn convert_from_xyz(
    &self,
    color: &In
) -> SpacedColor<T, Self::OutputColor, Self::Encoding, Self>

Convert color out of the XYZ space, using the color space's preferred encoding

fn convert_from_xyz_linear(
    &self,
    color: &In
) -> SpacedColor<T, Self::OutputColor, LinearEncoding, Self>

Convert color out of the XYZ space, using a linear encoding

impl<T> ConvertFromXyz<T, Xyz<T>> for SRgb<T> where
    T: Float + FreeChannelScalar + PosNormalChannelScalar + ChannelFormatCast<f64>,
    f64: ChannelFormatCast<T>, 

type OutputColor = Rgb<T>

The color type converted to.

fn convert_from_xyz_raw(&self, color: &Xyz<T>) -> Rgb<T>

Convert color out of the XYZ space, returning a bare color without any wrappers

fn convert_from_xyz(
    &self,
    color: &In
) -> SpacedColor<T, Self::OutputColor, Self::Encoding, Self>

Convert color out of the XYZ space, using the color space's preferred encoding

fn convert_from_xyz_linear(
    &self,
    color: &In
) -> SpacedColor<T, Self::OutputColor, LinearEncoding, Self>

Convert color out of the XYZ space, using a linear encoding

impl<T: Copy> Copy for Xyz<T>

impl<T: Debug> Debug for Xyz<T>

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

Formats the value using the given formatter.

impl<T> Default for Xyz<T> where
    T: FreeChannelScalar, 

fn default() -> Self

Returns the "default value" for a type.

impl<T> Display for Xyz<T> where
    T: FreeChannelScalar + Display, 

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

Formats the value using the given formatter.

impl<T> Flatten for Xyz<T> where
    T: FreeChannelScalar, 

fn as_slice(&self) -> &[Self::ChannelFormat]

Return a slice representation of Self

fn from_slice(vals: &[T]) -> Self

Return Self constructed from values

impl<T, Model> FromColor<Lms<T, Model>> for Xyz<T> where
    T: FreeChannelScalar,
    Model: LmsModel<T>, 

fn from_color(from: &Lms<T, Model>) -> Self

Construct Self from from

impl<T> FromColor<XyY<T>> for Xyz<T> where
    T: FreeChannelScalar + PosNormalChannelScalar + Float, 

fn from_color(from: &XyY<T>) -> Self

Construct Self from from

impl<T, Model> FromColor<Xyz<T>> for Lms<T, Model> where
    T: FreeChannelScalar,
    Model: LmsModel<T>, 

fn from_color(from: &Xyz<T>) -> Self

Construct Self from from

impl<T> FromColor<Xyz<T>> for XyY<T> where
    T: FreeChannelScalar + PosNormalChannelScalar + Float, 

fn from_color(from: &Xyz<T>) -> Self

Construct Self from from

impl<T> FromTuple for Xyz<T> where
    T: FreeChannelScalar, 

fn from_tuple(values: (T, T, T)) -> Self

Construct Self from a tuple of channel values

impl<T> HomogeneousColor for Xyz<T> where
    T: FreeChannelScalar, 

type ChannelFormat = T

The scalar type of each channel

fn clamp(self, min: T, max: T) -> Self

Clamp the value of each channel between min and max

impl<T> Lerp for Xyz<T> where
    T: FreeChannelScalar,
    PosFreeChannel<T>: Lerp, 

type Position = <PosFreeChannel<T> as Lerp>::Position

The type of the pos argument

fn lerp(&self, right: &Self, pos: Self::Position) -> Self

Interpolate between self and right

impl<T: PartialEq> PartialEq<Xyz<T>> for Xyz<T>

fn eq(&self, other: &Xyz<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Xyz<T>) -> bool

This method tests for !=.

impl<T: PartialOrd> PartialOrd<Xyz<T>> for Xyz<T>

fn partial_cmp(&self, other: &Xyz<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Xyz<T>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Xyz<T>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Xyz<T>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Xyz<T>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> RelativeEq<Xyz<T>> for Xyz<T> where
    T: FreeChannelScalar + RelativeEq,
    T::Epsilon: Clone, 

fn default_max_relative() -> Self::Epsilon

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

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

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

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

The inverse of ApproxEq::relative_eq.

impl<T> StructuralPartialEq for Xyz<T>

impl<T> UlpsEq<Xyz<T>> for Xyz<T> where
    T: FreeChannelScalar + UlpsEq,
    T::Epsilon: Clone, 

fn default_max_ulps() -> u32

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

fn ulps_eq(&self, other: &Self, epsilon: Self::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: &Rhs, epsilon: Self::Epsilon, max_ulps: u32) -> bool

The inverse of ApproxEq::ulps_eq.