Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-color

Source of release 0.8.0

0.8.0 / src / xyz.lucb

## CIE XYZ, the hub every color space meets at, and the RGB spaces defined on
## it by their primaries and white: matrices are derived from chromaticities,
## never typed in, and whites are reconciled by Bradford adaptation.
from luce_std import math
from color import Color

# mark: Types =================================================================

## CIE 1931 tristimulus values. Y is luminance; the library keeps white at Y = 1
## except where a model (CAM16) asks for Y = 100.
pub struct XYZ:
    pub var x: f64
    pub var y: f64
    pub var z: f64

## A CIE xy chromaticity.
pub struct Chromaticity:
    pub var x: f64
    pub var y: f64

## A 3×3 matrix, row-major.
pub struct Matrix3:
    pub var m: f64[9] = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]

## An RGB space's colorimetry: the three primaries and the white they mix to.
pub struct Primaries:
    pub var red: Chromaticity
    pub var green: Chromaticity
    pub var blue: Chromaticity
    pub var white: Chromaticity

# mark: Whites ================================================================

pub let d65: Chromaticity = Chromaticity(0.3127, 0.3290)
pub let d50: Chromaticity = Chromaticity(0.3457, 0.3585)
## ACES's white, near D60.
pub let aces_white: Chromaticity = Chromaticity(0.32168, 0.33767)
## Equal energy.
pub let illuminant_e: Chromaticity = Chromaticity(1.0 / 3.0, 1.0 / 3.0)

## The XYZ of a chromaticity at Y = 1.
pub func white_point(white: Chromaticity) -> XYZ:
    return XYZ(white.x / white.y, 1.0, (1.0 - white.x - white.y) / white.y)

# mark: Spaces ================================================================

## Rec. 709 / sRGB primaries, D65.
pub let srgb: Primaries = Primaries(Chromaticity(0.64, 0.33), Chromaticity(0.30, 0.60), Chromaticity(0.15, 0.06), d65)
## DCI-P3 primaries with a D65 white: Apple's Display P3.
pub let display_p3: Primaries = Primaries(Chromaticity(0.680, 0.320), Chromaticity(0.265, 0.690), Chromaticity(0.150, 0.060), d65)
pub let adobe_rgb: Primaries = Primaries(Chromaticity(0.64, 0.33), Chromaticity(0.21, 0.71), Chromaticity(0.15, 0.06), d65)
pub let rec2020: Primaries = Primaries(Chromaticity(0.708, 0.292), Chromaticity(0.170, 0.797), Chromaticity(0.131, 0.046), d65)
## ACES2065-1's AP0: the whole spectral locus and beyond.
pub let aces_ap0: Primaries = Primaries(Chromaticity(0.7347, 0.2653), Chromaticity(0.0, 1.0), Chromaticity(0.0001, -0.0770), aces_white)
## ACEScg's AP1.
pub let aces_ap1: Primaries = Primaries(Chromaticity(0.713, 0.293), Chromaticity(0.165, 0.830), Chromaticity(0.128, 0.044), aces_white)
## ProPhoto / ROMM RGB, D50.
pub let prophoto: Primaries = Primaries(Chromaticity(0.7347, 0.2653), Chromaticity(0.1596, 0.8404), Chromaticity(0.0366, 0.0001), d50)

# mark: Matrices ==============================================================

pub func multiply(a: Matrix3, b: Matrix3) -> Matrix3:
    var out = Matrix3()
    for row in 0..<(usize)3:
        for column in 0..<(usize)3:
            var sum = 0.0
            for k in 0..<(usize)3:
                sum += a.m[row * 3 + k] * b.m[k * 3 + column]
            out.m[row * 3 + column] = sum
    return out

## `matrix` applied to a column vector.
pub func apply(matrix: Matrix3, v: XYZ) -> XYZ:
    return XYZ(matrix.m[0] * v.x + matrix.m[1] * v.y + matrix.m[2] * v.z,
               matrix.m[3] * v.x + matrix.m[4] * v.y + matrix.m[5] * v.z,
               matrix.m[6] * v.x + matrix.m[7] * v.y + matrix.m[8] * v.z)

## The inverse; a singular matrix returns the identity, which no real set of
## primaries produces.
pub func invert(a: Matrix3) -> Matrix3:
    let m = a.m
    let c0 = m[4] * m[8] - m[5] * m[7]
    let c1 = m[5] * m[6] - m[3] * m[8]
    let c2 = m[3] * m[7] - m[4] * m[6]
    let determinant = m[0] * c0 + m[1] * c1 + m[2] * c2
    if math.abs(determinant) < 1.0e-15:
        return Matrix3()
    let d = 1.0 / determinant
    var out = Matrix3()
    out.m[0] = c0 * d
    out.m[1] = (m[2] * m[7] - m[1] * m[8]) * d
    out.m[2] = (m[1] * m[5] - m[2] * m[4]) * d
    out.m[3] = c1 * d
    out.m[4] = (m[0] * m[8] - m[2] * m[6]) * d
    out.m[5] = (m[2] * m[3] - m[0] * m[5]) * d
    out.m[6] = c2 * d
    out.m[7] = (m[1] * m[6] - m[0] * m[7]) * d
    out.m[8] = (m[0] * m[4] - m[1] * m[3]) * d
    return out

## The matrix taking linear RGB in `primaries` to XYZ (white at Y = 1): the
## primaries' XYZ columns, scaled so that RGB (1, 1, 1) lands on the white.
pub func rgb_to_xyz(primaries: Primaries) -> Matrix3:
    let r = white_point(primaries.red)
    let g = white_point(primaries.green)
    let b = white_point(primaries.blue)
    var columns = Matrix3()
    columns.m = [r.x, g.x, b.x, r.y, g.y, b.y, r.z, g.z, b.z]
    let scale = apply(invert(columns), white_point(primaries.white))
    var out = columns
    out.m[0] *= scale.x
    out.m[3] *= scale.x
    out.m[6] *= scale.x
    out.m[1] *= scale.y
    out.m[4] *= scale.y
    out.m[7] *= scale.y
    out.m[2] *= scale.z
    out.m[5] *= scale.z
    out.m[8] *= scale.z
    return out

pub func xyz_to_rgb(primaries: Primaries) -> Matrix3:
    return invert(rgb_to_xyz(primaries))

# mark: Adaptation ============================================================

## The Bradford chromatic adaptation from one white to another, so a color
## keeps its appearance when the spaces disagree about white (sRGB's D65 against
## ProPhoto's D50, say). Equal whites give the identity.
pub func adapt(source: Chromaticity, target: Chromaticity) -> Matrix3:
    if math.abs(source.x - target.x) < 1.0e-9 and math.abs(source.y - target.y) < 1.0e-9:
        return Matrix3()
    let cone_source = apply(bradford, white_point(source))
    let cone_target = apply(bradford, white_point(target))
    var scale = Matrix3()
    scale.m = [cone_target.x / cone_source.x, 0.0, 0.0, 0.0, cone_target.y / cone_source.y, 0.0, 0.0, 0.0, cone_target.z / cone_source.z]
    return multiply(invert(bradford), multiply(scale, bradford))

let bradford: Matrix3 = Matrix3([0.8951, 0.2664, -0.1614, -0.7502, 1.7135, 0.0367, 0.0389, -0.0685, 1.0296])

# mark: Conversion ============================================================

## Linear RGB in `primaries` to XYZ, in the primaries' own white.
pub func to_xyz(color: Color, primaries: Primaries) -> XYZ:
    return apply(rgb_to_xyz(primaries), XYZ(color.red, color.green, color.blue))

## XYZ (in the primaries' white) to linear RGB, unclamped: a color outside
## the gamut shows as a component outside 0..1.
pub func from_xyz(value: XYZ, primaries: Primaries) -> Color:
    let rgb = apply(xyz_to_rgb(primaries), value)
    return Color(rgb.x, rgb.y, rgb.z)

## Linear RGB from one set of primaries to another, adapting between whites.
pub func convert(color: Color, source: Primaries, target: Primaries) -> Color:
    let value = to_xyz(color, source)
    return from_xyz(apply(adapt(source.white, target.white), value), target)

# mark: Tests =================================================================

func near(a: f64, b: f64, tolerance: f64 = 0.0001) -> bool:
    return math.abs(a - b) < tolerance

test "sRGB's derived matrix matches the published one":
    let m = rgb_to_xyz(srgb)
    assert(near(m.m[0], 0.4124, 0.0005) and near(m.m[1], 0.3576, 0.0005) and near(m.m[2], 0.1805, 0.0005))
    assert(near(m.m[3], 0.2126, 0.0005) and near(m.m[4], 0.7152, 0.0005) and near(m.m[5], 0.0722, 0.0005))
    assert(near(m.m[6], 0.0193, 0.0005) and near(m.m[7], 0.1192, 0.0005) and near(m.m[8], 0.9505, 0.0005))
    let white = to_xyz(Color(1.0, 1.0, 1.0), srgb)
    assert(near(white.x, 0.9505, 0.0005) and near(white.y, 1.0) and near(white.z, 1.0888, 0.0005))

test "a matrix inverts and a color round-trips through XYZ":
    let identity = multiply(rgb_to_xyz(rec2020), xyz_to_rgb(rec2020))
    for index in 0..<(usize)9:
        assert(near(identity.m[index], 1.0 if index % 4 == 0 else 0.0, 0.000001))
    let sample = Color(0.2, 0.66, 0.92)
    let back = from_xyz(to_xyz(sample, display_p3), display_p3)
    assert(near(back.red, sample.red) and near(back.green, sample.green) and near(back.blue, sample.blue))

test "conversion widens into P3 and adaptation moves white to white":
    let red = convert(Color(1.0, 0.0, 0.0), srgb, display_p3)
    # Linear: sRGB red is (0.8225, 0.0332, 0.0171) in P3.
    assert(near(red.red, 0.8225, 0.001) and near(red.green, 0.0332, 0.001) and near(red.blue, 0.0171, 0.001))
    let white = convert(Color(1.0, 1.0, 1.0), srgb, prophoto)
    assert(near(white.red, 1.0, 0.001) and near(white.green, 1.0, 0.001) and near(white.blue, 1.0, 0.001))
    let d50_white = apply(adapt(d65, d50), white_point(d65))
    let expected = white_point(d50)
    assert(near(d50_white.x, expected.x, 0.001) and near(d50_white.y, expected.y, 0.001) and near(d50_white.z, expected.z, 0.001))