colr_types/

primaries.rs

//! RGB primary sets.
//!
//! `Primaries` defines the chromaticity coordinates and native RGB-to-XYZ
//! matrices for one primary set. All matrix values are derived via const fn
//! at compile time.
//!
//! Adding a new primary set:
//!
//! 1. Define the chromaticity constants as [f32; 2] xy pairs.
//! 2. impl Primaries for MyPrimaries.

use crate::illuminant::{AcesWhitePoint, D50, D65, DciWhite, Illuminant};
use crate::math::Mat3;
use crate::observer::Cie1931;

/// Derive the linear RGB to CIE XYZ matrix from chromaticity coordinates
/// and an exact XYZ white point. const fn.
///
/// Takes WHITE_POINT_XYZ directly rather than xy chromaticities to avoid
/// the floating-point drift that occurs when deriving XYZ from rounded xy
/// coordinates. The Y row of the result gives luminance weights directly.
pub const fn derive_rgb_to_xyz(r: [f32; 2], g: [f32; 2], b: [f32; 2], w_xyz: [f32; 3]) -> Mat3 {
    let [xr, yr] = r;
    let zr = 1.0 - xr - yr;
    let [xg, yg] = g;
    let zg = 1.0 - xg - yg;
    let [xb, yb] = b;
    let zb = 1.0 - xb - yb;

    let det = xr * (yg * zb - yb * zg) - xg * (yr * zb - yb * zr) + xb * (yr * zg - yg * zr);

    let inv00 = (yg * zb - yb * zg) / det;
    let inv01 = (xb * zg - xg * zb) / det;
    let inv02 = (xg * yb - xb * yg) / det;
    let inv10 = (yb * zr - yr * zb) / det;
    let inv11 = (xr * zb - xb * zr) / det;
    let inv12 = (xb * yr - xr * yb) / det;
    let inv20 = (yr * zg - yg * zr) / det;
    let inv21 = (xg * zr - xr * zg) / det;
    let inv22 = (xr * yg - xg * yr) / det;

    let [xw, yw, zw] = w_xyz;

    let sr = inv00 * xw + inv01 * yw + inv02 * zw;
    let sg = inv10 * xw + inv11 * yw + inv12 * zw;
    let sb = inv20 * xw + inv21 * yw + inv22 * zw;

    Mat3 {
        col0: [sr * xr, sr * yr, sr * zr, 0.0],
        col1: [sg * xg, sg * yg, sg * zg, 0.0],
        col2: [sb * xb, sb * yb, sb * zb, 0.0],
    }
}

/// The irreducible specification of an RGB primary set.
pub trait Primaries: 'static {
    /// The illuminant these chromaticities are specified relative to.
    type Native: Illuminant<Observer = Cie1931>;

    /// Red primary CIE 1931 xy chromaticity.
    const R: [f32; 2];
    /// Green primary CIE 1931 xy chromaticity.
    const G: [f32; 2];
    /// Blue primary CIE 1931 xy chromaticity.
    const B: [f32; 2];

    /// Linear RGB to CIE XYZ under Self::Native.
    const TO_XYZ_NATIVE: Mat3;
    /// CIE XYZ under Self::Native to linear RGB.
    const FROM_XYZ_NATIVE: Mat3;

    /// Luma coefficients [Kr, Kg, Kb] from the Y row of TO_XYZ_NATIVE.
    const LUMA_WEIGHTS: [f32; 3] = [
        Self::TO_XYZ_NATIVE.col0[1],
        Self::TO_XYZ_NATIVE.col1[1],
        Self::TO_XYZ_NATIVE.col2[1],
    ];
}

/// sRGB and Rec. 709 primaries (D65).
///
/// Both standards share identical chromaticities and differ only in their
/// transfer functions.
///
/// Reference: IEC 61966-2-1:1999, ITU-R BT.709-6.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Srgb;

const SRGB_TO_XYZ: Mat3 = derive_rgb_to_xyz(
    [0.6400, 0.3300],
    [0.3000, 0.6000],
    [0.1500, 0.0600],
    <D65<Cie1931> as Illuminant>::WHITE_POINT_XYZ,
);
const SRGB_FROM_XYZ: Mat3 = Mat3::invert(&SRGB_TO_XYZ);

impl Primaries for Srgb {
    type Native = D65;
    const R: [f32; 2] = [0.6400, 0.3300];
    const G: [f32; 2] = [0.3000, 0.6000];
    const B: [f32; 2] = [0.1500, 0.0600];
    const TO_XYZ_NATIVE: Mat3 = SRGB_TO_XYZ;
    const FROM_XYZ_NATIVE: Mat3 = SRGB_FROM_XYZ;
}

/// Display P3 primaries (D65). Consumer D65 variant; DCI-P3 theatre uses D60.
///
/// Reference: SMPTE EG 432-1:2010.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct P3;

const P3_TO_XYZ: Mat3 = derive_rgb_to_xyz(
    [0.6800, 0.3200],
    [0.2650, 0.6900],
    [0.1500, 0.0600],
    <D65<Cie1931> as Illuminant>::WHITE_POINT_XYZ,
);
const P3_FROM_XYZ: Mat3 = Mat3::invert(&P3_TO_XYZ);

impl Primaries for P3 {
    type Native = D65;
    const R: [f32; 2] = [0.6800, 0.3200];
    const G: [f32; 2] = [0.2650, 0.6900];
    const B: [f32; 2] = [0.1500, 0.0600];
    const TO_XYZ_NATIVE: Mat3 = P3_TO_XYZ;
    const FROM_XYZ_NATIVE: Mat3 = P3_FROM_XYZ;
}

/// Rec. 2020 primaries (D65). Ultra-wide gamut; primaries lie on the spectral
/// locus and are not physically realisable by current displays.
///
/// Reference: ITU-R BT.2020-2.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Rec2020;

const REC2020_TO_XYZ: Mat3 = derive_rgb_to_xyz(
    [0.7080, 0.2920],
    [0.1700, 0.7970],
    [0.1310, 0.0460],
    <D65<Cie1931> as Illuminant>::WHITE_POINT_XYZ,
);
const REC2020_FROM_XYZ: Mat3 = Mat3::invert(&REC2020_TO_XYZ);

impl Primaries for Rec2020 {
    type Native = D65;
    const R: [f32; 2] = [0.7080, 0.2920];
    const G: [f32; 2] = [0.1700, 0.7970];
    const B: [f32; 2] = [0.1310, 0.0460];
    const TO_XYZ_NATIVE: Mat3 = REC2020_TO_XYZ;
    const FROM_XYZ_NATIVE: Mat3 = REC2020_FROM_XYZ;
}

/// ACES AP0 primaries (ACES white point). Full-gamut archival space (ACES 2065-1).
/// The blue primary y-coordinate is negative (an imaginary color), correct per spec.
///
/// Reference: SMPTE ST 2065-1:2021.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct AcesAp0;

const AP0_TO_XYZ: Mat3 = derive_rgb_to_xyz(
    [0.73470, 0.26530],
    [0.00000, 1.00000],
    [0.00010, -0.07700],
    AcesWhitePoint::WHITE_POINT_XYZ,
);
const AP0_FROM_XYZ: Mat3 = Mat3::invert(&AP0_TO_XYZ);

impl Primaries for AcesAp0 {
    type Native = AcesWhitePoint;
    const R: [f32; 2] = [0.73470, 0.26530];
    const G: [f32; 2] = [0.00000, 1.00000];
    const B: [f32; 2] = [0.00010, -0.07700];
    const TO_XYZ_NATIVE: Mat3 = AP0_TO_XYZ;
    const FROM_XYZ_NATIVE: Mat3 = AP0_FROM_XYZ;
}

/// ACES AP1 primaries (ACES white point). VFX rendering working space (ACEScg).
/// All real-world colors have positive values.
///
/// Reference: Academy S-2014-004.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct AcesAp1;

const AP1_TO_XYZ: Mat3 = derive_rgb_to_xyz(
    [0.71300, 0.29300],
    [0.16500, 0.83000],
    [0.12800, 0.04400],
    AcesWhitePoint::WHITE_POINT_XYZ,
);
const AP1_FROM_XYZ: Mat3 = Mat3::invert(&AP1_TO_XYZ);

impl Primaries for AcesAp1 {
    type Native = AcesWhitePoint;
    const R: [f32; 2] = [0.71300, 0.29300];
    const G: [f32; 2] = [0.16500, 0.83000];
    const B: [f32; 2] = [0.12800, 0.04400];
    const TO_XYZ_NATIVE: Mat3 = AP1_TO_XYZ;
    const FROM_XYZ_NATIVE: Mat3 = AP1_FROM_XYZ;
}

/// ProPhoto (ROMM RGB) primaries (D50). Roughly 13% of the gamut is imaginary.
///
/// Reference: ISO 22028-2:2013.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct ProPhoto;

const PRO_PHOTO_TO_XYZ: Mat3 = derive_rgb_to_xyz(
    [0.7347, 0.2653],
    [0.1596, 0.8404],
    [0.0366, 0.0001],
    <D50<Cie1931> as Illuminant>::WHITE_POINT_XYZ,
);
const PRO_PHOTO_FROM_XYZ: Mat3 = Mat3::invert(&PRO_PHOTO_TO_XYZ);

impl Primaries for ProPhoto {
    type Native = D50;
    const R: [f32; 2] = [0.7347, 0.2653];
    const G: [f32; 2] = [0.1596, 0.8404];
    const B: [f32; 2] = [0.0366, 0.0001];
    const TO_XYZ_NATIVE: Mat3 = PRO_PHOTO_TO_XYZ;
    const FROM_XYZ_NATIVE: Mat3 = PRO_PHOTO_FROM_XYZ;
}

/// DCI-P3 primaries (DCI white point) for theatrical projection.
///
/// Same chromaticities as P3Primaries but with the DCI white point
/// instead of D65. Use this for true theatrical DCI-P3. For consumer
/// Display P3 (Apple, Android), use P3Primaries with D65.
///
/// Reference: SMPTE EG 432-1:2010.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct DciP3;

const DCI_P3_TO_XYZ: Mat3 = derive_rgb_to_xyz(
    [0.6800, 0.3200],
    [0.2650, 0.6900],
    [0.1500, 0.0600],
    DciWhite::WHITE_POINT_XYZ,
);
const DCI_P3_FROM_XYZ: Mat3 = Mat3::invert(&DCI_P3_TO_XYZ);

impl Primaries for DciP3 {
    type Native = DciWhite;
    const R: [f32; 2] = [0.6800, 0.3200];
    const G: [f32; 2] = [0.2650, 0.6900];
    const B: [f32; 2] = [0.1500, 0.0600];
    const TO_XYZ_NATIVE: Mat3 = DCI_P3_TO_XYZ;
    const FROM_XYZ_NATIVE: Mat3 = DCI_P3_FROM_XYZ;
}