Enum Observer 

#[non_exhaustive]
pub enum Observer {
    Cie1931,
    Cie1964,
    Cie2015,
    Cie2015_10,
}

Selects a CIE standard colorimetric observer.

The tag is embedded in every XYZ and Rgb value so that operations across incompatible observers can be detected at runtime. Each variant is a lightweight index; the color-matching function tables are stored in observer_data.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Cie1931

CIE 1931 2° standard observer — the default for most colorimetry.

Used by sRGB, ICC profiles, and CIE CRI Ra.

Cie1964

CIE 1964 10° supplementary standard observer.

Preferred when the viewed area subtends more than ~4° at the eye. Used by CIE 224:2017 / ANSI/IES TM-30 for colour fidelity calculations.

Cie2015

CIE 2015 2° observer — CMFs constructed as linear transforms of the Stockman & Sharpe (2000) cone fundamentals.

More accurate than Cie1931 in the short-wavelength (blue) region.

Cie2015_10

CIE 2015 10° observer — CMFs constructed as linear transforms of the Stockman & Sharpe (2000) cone fundamentals.

Wide-field counterpart of Cie2015.

Implementations

impl Observer

pub fn xyz2rgb_matrix(&self, rgb_space: RgbSpace) -> &'static Matrix3<f64>

Returns the XYZ to Rgb conversion matrix for the given RGB space.

impl Observer

pub fn rgb2xyz_matrix(&self, rgb_space: RgbSpace) -> &'static Matrix3<f64>

Returns the RGB to XYZ conversion matrix for the given RGB space.

impl Observer

pub fn name(&self) -> &'static str

Returns the name of the observer.

pub fn spectral_locus(&self) -> &SpectralLocus

Returns the spectral locus for this observer.

The spectral locus is the boundary of the area of all physical colors in a chromaticity diagram.

pub fn rel_xyz(&self, light: &dyn Light, filter: &dyn Filter) -> RelXYZ

Computes relative XYZ tristimulus values for a filtered light source.

The unfiltered light spectrum sets the white point (normalised to Y = 100); the product of the light and filter spectra is integrated to give the stimulus XYZ. The result is a RelXYZ that carries both the stimulus and the white point, as required by CIELAB and CIECAM calculations.

pub fn xyz(&self, light: &dyn Light, filter: Option<&dyn Filter>) -> XYZ

Calulates Tristimulus values for an object implementing the Light trait, and an optional Filter, filtering the light.

The Light trait is implemented by CieIlluminant and Illuminant.

Colorant implments the Filter trait. Rgb, which represents a display pixel, implements both in this library. As a light, it is the light emitted from the pixel, as a filter it is the RGB-composite filter which is applied to the underlying standard illuminant of color space.

pub fn lab(&self, light: &dyn Light, filter: &dyn Filter) -> CieLab

Computes CIELAB L*a*b* values for a light source and filter combination, normalised so the unfiltered source has Y = 100.

Arguments

• light - A light source implementing Light, such as CieIlluminant.
• filter - A filter implementing Filter, such as Colorant.

Returns

CieLab — the CIELAB representation of the filtered stimulus relative to the white point.

pub fn lab_d65(&self, filter: &dyn Filter) -> CieLab

Calculates the Lab* CIELAB D65 values of a Colorant, using D65 as an illuminant. Convenience method for lab with D65 illuminant, and using an illuminance value of 100.0.

pub fn lab_d50(&self, filter: &dyn Filter) -> CieLab

Calculates the Lab* CIELAB D50 values of a Colorant, using D50 as an illuminant. Convenience method for lab with D50 illuminant, and using an illuminance value of 100.0.

pub fn ciecam16( &self, light: &dyn Light, filter: &dyn Filter, vc: ViewConditions, ) -> CieCam16

Computes CIECAM16 color appearance model values for a light source and filter combination, normalised so the unfiltered source has Y = 100.

Arguments

• light - A light source implementing Light, such as CieIlluminant.
• filter - A filter implementing Filter, such as Colorant.
• vc - Viewing conditions for the CIECAM16 model.

Returns

CieCam16 — CIECAM16 correlates for the filtered stimulus under the given viewing conditions.

pub fn ciecam02( &self, light: &dyn Light, filter: &dyn Filter, vc: ViewConditions, ) -> CieCam02

Computes CIECAM02 color appearance model values for a light source and filter combination, normalised so the unfiltered source has Y = 100.

Arguments

• light - A light source implementing Light, such as CieIlluminant.
• filter - A filter implementing Filter, such as Colorant.
• vc - Viewing conditions for the CIECAM02 model.

Returns

CieCam02 — CIECAM02 correlates for the filtered stimulus under the given viewing conditions.

pub fn xyz_from_spectrum(&self, spectrum: &Spectrum) -> XYZ

Calculates tristimulus values for a general spectrum, returned as an XYZ object.

The spectrum is interpreted as an illuminant SPD. This method produces raw (unnormalised) XYZ data; the Y value is not scaled to 100.

pub fn y_from_spectrum(&self, spectrum: &Spectrum) -> f64

Calculates the luminous value (Y tristimulus value) for a general spectrum.

pub fn xyz_at_wavelength(&self, wavelength: usize) -> Result<XYZ, Error>

Returns the observer’s color matching function (CMF) data as an XYZ tristimulus value for the given wavelength.

This allows access to the underlying data for the entire range of wavelengths, 380-780nm. However, please read the documentation for the spectral_locus_wavelength_range method on situations where you might not want to sample the full range.

pub fn monochromes(&self, ref_white: CieIlluminant) -> Vec<(usize, RelXYZ)>

Calculates the relative XYZ tristimulus values of monochromatic stimuli.

Monochromatic stimuli are pure spectral colors, like those seen when white light is dispersed by a prism. This method computes their XYZ values under a given illuminant.

Details

• Computes XYZ values for wavelengths from 380nm to 780nm in 1nm steps
• Multiplies observer color matching functions by illuminant spectrum
• Normalizes results relative to the illuminant’s white point
• Scales output to 100 lux illuminance

Difference from Spectral Locus

While the spectral locus shows only chromaticity coordinates (x,y) of pure spectral colors, this method provides full XYZ values including luminance information.

Implementation Notes

• Each wavelength is treated as a monochromatic stimulus (delta function)
• Results are typically low in magnitude due to the narrow bandwidth
• Values are normalized relative to the illuminant’s total energy

Arguments

• ref_white: Reference illuminant (e.g., D65, D50) for normalisation.

Returns

A vector of (wavelength_nm, RelXYZ) pairs (380–780 nm), where each RelXYZ is scaled to 100 lux illuminance.

pub fn trimmed_spectral_locus( &self, ref_white: CieIlluminant, ) -> Vec<(usize, RelXYZ)>

Returns relative XYZ values for the spectral locus, restricted to the unique wavelength range.

This is a convenience wrapper around monochromes that discards the endpoints where the locus folds back on itself — see spectral_locus_wavelength_range.

pub fn xyz_cie_table( &self, std_illuminant: &CieIlluminant, illuminance: Option<f64>, ) -> XYZ

Tristimulus values for the Standard Illuminants in this library.

Values are not normalized by default, unless an illuminance value is provided.

Results are not cached. For the common cases of D65 and D50, use the dedicated Observer::xyz_d65 and Observer::xyz_d50 methods, which cache their results.

pub fn xyz_d65(&self) -> XYZ

XYZ tristimulus values for the CIE standard daylight illuminant D65 (buffered).

pub fn xyz_d50(&self) -> XYZ

XYZ tristimulus values for the CIE standard daylight illuminant D50 (buffered).

pub fn xyz_planckian_locus(&self, cct: f64) -> XYZ

Computes XYZ tristimulus values for a Planckian (blackbody) radiator at the given CCT.

The spectral radiance is evaluated from Planck’s law and integrated against the observer’s color-matching functions. Combine with xyz_planckian_locus_slope to follow the Planckian locus in XYZ space.

pub fn planckian_locus(&self) -> Vec<(f64, f64)>

Calculates the chromaticity coordinates (x, y) of the Planckian locus over a range from 1000K to 100_000K.

pub fn xyz_planckian_locus_slope(&self, cct: f64) -> XYZ

The slope of the Plancking locus as a (dX/dT, dY/dT, dZ/dT) contained in a XYZ object.

pub fn calc_rgb2xyz_matrix_with_alt_white( &self, rgbspace: RgbSpace, opt_white: Option<XYZ>, ) -> Matrix3<f64>

Computes the 3×3 RGB-to-XYZ matrix for a color space with an optional alternate white point.

When opt_white is None the color space’s own white point is used, producing the same matrix as rgb2xyz_matrix. Supply a D50 XYZ value to obtain a matrix adapted to D50 — this is required for ICC profile rXYZ/gXYZ/bXYZ tags when the color space is natively D65 (e.g. sRGB).

Notes

• XYZ is used for the white point (rather than a spectrum) to match the ICC profile standard, which specifies primaries as XYZ coordinates.

pub fn calc_rgb2xyz_matrix(&self, rgbspace: RgbSpace) -> Matrix3<f64>

Computes the 3×3 RGB-to-XYZ matrix for a color space from first principles.

Pre-computed, cached matrices for all built-in observer / color space combinations are returned by rgb2xyz_matrix. Use this method only when adding a new color space or regenerating built-in tables via cargo xtask gen.

pub fn calc_xyz2rgb_matrix(&self, rgbspace: RgbSpace) -> Matrix3<f64>

Computes the 3×3 XYZ-to-RGB matrix for a color space (the inverse of calc_rgb2xyz_matrix).

Pre-computed, cached matrices for all built-in combinations are returned by xyz2rgb_matrix. Use this method only when regenerating built-in tables via cargo xtask gen.

pub fn spectral_locus_wavelength_range(&self) -> RangeInclusive<usize>

Returns the wavelength range (in nanometres) over which the spectral locus is monotone.

The spectral locus (the horseshoe boundary of all physical colors in a chromaticity diagram) folds back on itself near the blue and red extremes: consecutive wavelengths can map to the same or a reversed chromaticity coordinate. This causes problems for dominant-wavelength calculations and locus plots.

This method returns the sub-range for which each wavelength maps to a unique chromaticity point distinct from its neighbours. See Wikipedia’s CIE 1931 Color Space.

To get the tristimulus values of the spectral locus, use xyz_at_wavelength.

pub fn xyz_from_fn(&self, f: impl Fn(f64) -> f64) -> XYZ

Calculates the XYZ tristimulus values for a spectrum defined by a function.

The input function f should accept a floating-point value in the range [0.0, 1.0], where 0.0 corresponds to a wavelength of 380 nm and 1.0 to 780 nm. The function will be called once for each wavelength step (401 times at 1 nm intervals).

Arguments

• f - A function that takes a floating-point value in the range [0.0, 1.0] and returns the spectral value at that wavelength, in units of watts per square meter per nanometer (W/m²/nm) for illuminants, or Watts per square meter per steradian per nanometer (W/m²/sr/nm) for stimuli.

Notes

• This method is used in the library to compute the Planckian locus (the color of blackbody radiators), as described by Planck’s law.
• For colorants, use xyz_from_colorant_fn.

pub fn xyz_from_colorant_fn( &self, illuminant: &CieIlluminant, f: impl Fn(f64) -> f64, ) -> XYZ

Calculates XYZ tristimulus values for an analytic representation of a spectral distribution of a filter or a color patch, using a normalized wavelength domain ranging from a value of 0.0 to 1.0, illuminated with a standard illuminant.

The spectral values should be defined within a range from 0.0 to 1.0, and are clamped otherwise. The resulting XYZ value will have relative Y values in the range from 0 to 100.0.

Examples

A linear high pass filter, with a value of 0.0 for a wavelength of 380nm, and a value of 1.0 for 780nm, and converting the resulting value to RGB values.

use colorimetry::{rgb::RgbSpace::SRGB, observer::Observer::Cie1931, illuminant::CieIlluminant};
let rgb: [u8;3] = Cie1931.xyz_from_colorant_fn(&CieIlluminant::D65, |x|x).rgb(SRGB).clamp().into();
assert_eq!(rgb, [212, 171, 109]);

Linear low pass filter, with a value of 1.0 for a wavelength of 380nm, and a value of 0.0 for 780nm, and converting the resulting value to RGB values.

use colorimetry::{rgb::RgbSpace::SRGB, observer::Observer::Cie1931, illuminant::CieIlluminant};
let rgb: [u8;3] = Cie1931.xyz_from_colorant_fn(&CieIlluminant::D65, |x|1.0-x).rgb(SRGB).clamp().into();
assert_eq!(rgb, [158, 202, 237]);

Trait Implementations

impl AsRef<str> for Observer

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Observer

fn clone(&self) -> Observer

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Observer

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

Formats the value using the given formatter.

impl Default for Observer

fn default() -> Observer

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Observer

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Observer

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

Formats the value using the given formatter.

impl EnumCount for Observer

const COUNT: usize = 4usize

impl Hash for Observer

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoEnumIterator for Observer

type Iterator = ObserverIter

fn iter() -> ObserverIter

impl PartialEq for Observer

fn eq(&self, other: &Observer) -> 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 Serialize for Observer

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for Observer

impl Eq for Observer

impl StructuralPartialEq for Observer