Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-color

Source of release 0.8.0

0.8.0 / src / cam16.lucb

## CAM16 (Li et al. 2017): what a color looks like under given viewing
## conditions — lightness J, chroma C, hue h, colorfulness M, saturation s,
## brightness Q — and CAM16-UCS, the uniform space built on it, whose Euclidean
## distance is a color difference. XYZ here is on the Y = 100 scale.
from luce_std import math
from xyz import XYZ, Matrix3, apply, invert

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

## The viewing conditions, with everything the model precomputes from them.
pub struct Viewing:
    pub var white: XYZ
    pub var adapting_luminance: f64
    pub var background: f64
    pub var surround: f64
    var n: f64 = 0.0
    var z: f64 = 0.0
    var nbb: f64 = 0.0
    var ncb: f64 = 0.0
    var c: f64 = 0.0
    var nc: f64 = 0.0
    var fl: f64 = 0.0
    var aw: f64 = 0.0
    var rgb_d: XYZ = XYZ(1.0, 1.0, 1.0)

## A color's appearance under some viewing conditions.
pub struct Appearance:
    pub var j: f64
    pub var q: f64
    pub var c: f64
    pub var m: f64
    pub var s: f64
    pub var h: f64

## CAM16-UCS coordinates: J′ and the opponent pair a′, b′.
pub struct UCS:
    pub var j: f64
    pub var a: f64
    pub var b: f64

# mark: Viewing conditions ====================================================

## Conditions for a display: `white` at Y = 100 (D65 by default), the
## adapting field's luminance in cd/m² (a lit office is around 40; a dim room
## 11.7, sRGB's reference), the background's relative luminance out of 100
## (20 is the usual grey), and the surround: 2 average, 1 dim, 0 dark.
pub func viewing(white: XYZ = XYZ(95.047, 100.0, 108.883), adapting_luminance: f64 = 40.0, background: f64 = 20.0, surround: f64 = 2.0) -> Viewing:
    var v = Viewing(white = white, adapting_luminance = adapting_luminance, background = background, surround = surround)
    let rgb_w = apply(m16, white)
    let f = 0.8 + math.clamp(surround, 0.0, 2.0) / 10.0
    v.c = lerp(0.59, 0.69, (f - 0.9) * 10.0) if f >= 0.9 else lerp(0.525, 0.59, (f - 0.8) * 10.0)
    v.nc = f
    let d = math.clamp(f * (1.0 - (1.0 / 3.6) * math.exp((-adapting_luminance - 42.0) / 92.0)), 0.0, 1.0)
    v.rgb_d = XYZ(d * (100.0 / rgb_w.x) + 1.0 - d, d * (100.0 / rgb_w.y) + 1.0 - d, d * (100.0 / rgb_w.z) + 1.0 - d)
    let k = 1.0 / (5.0 * adapting_luminance + 1.0)
    let k4 = k * k * k * k
    v.fl = k4 * adapting_luminance + 0.1 * (1.0 - k4) * (1.0 - k4) * math.cbrt(5.0 * adapting_luminance)
    v.n = background / white.y
    v.z = 1.48 + math.sqrt(v.n)
    v.nbb = 0.725 / math.pow(v.n, 0.2)
    v.ncb = v.nbb
    let adapted = XYZ(adapt_response(v.fl * v.rgb_d.x * rgb_w.x / 100.0), adapt_response(v.fl * v.rgb_d.y * rgb_w.y / 100.0), adapt_response(v.fl * v.rgb_d.z * rgb_w.z / 100.0))
    v.aw = (2.0 * adapted.x + adapted.y + 0.05 * adapted.z) * v.nbb
    return v

func lerp(a: f64, b: f64, t: f64) -> f64:
    return a + (b - a) * t

## The post-adaptation cone response compression, sign-preserving.
func adapt_response(value: f64) -> f64:
    let magnitude = math.pow(math.abs(value), 0.42)
    return math.copysign(400.0 * magnitude / (magnitude + 27.13), value)

let m16: Matrix3 = Matrix3([0.401288, 0.650173, -0.051461, -0.250268, 1.204414, 0.045854, -0.002079, 0.048952, 0.953127])

# mark: Forward ===============================================================

## The appearance of `xyz` (Y = 100 scale) under `v`.
pub func appearance(xyz: XYZ, v: Viewing) -> Appearance:
    let rgb = apply(m16, xyz)
    let ra = adapt_response(v.fl * v.rgb_d.x * rgb.x / 100.0)
    let ga = adapt_response(v.fl * v.rgb_d.y * rgb.y / 100.0)
    let ba = adapt_response(v.fl * v.rgb_d.z * rgb.z / 100.0)
    let a = ra + (-12.0 * ga + ba) / 11.0
    let b = (ra + ga - 2.0 * ba) / 9.0
    let u = (20.0 * ra + 20.0 * ga + 21.0 * ba) / 20.0
    let p2 = (40.0 * ra + 20.0 * ga + ba) / 20.0
    var h = math.atan2(b, a) * 180.0 / math.pi
    if h < 0.0:
        h += 360.0
    let radians = h * math.pi / 180.0
    let e_hue = 0.25 * (math.cos(radians + 2.0) + 3.8)
    let ac = p2 * v.nbb
    let j = 100.0 * math.pow(math.max(ac / v.aw, 0.0), v.c * v.z)
    let q = 4.0 / v.c * math.sqrt(j / 100.0) * (v.aw + 4.0) * math.pow(v.fl, 0.25)
    let p1 = 50000.0 / 13.0 * v.nc * v.ncb * e_hue
    let t = p1 * math.hypot(a, b) / (u + 0.305)
    let alpha = math.pow(t, 0.9) * math.pow(1.64 - math.pow(0.29, v.n), 0.73)
    let c = alpha * math.sqrt(j / 100.0)
    let m = c * math.pow(v.fl, 0.25)
    let s = 50.0 * math.sqrt(alpha * v.c / (v.aw + 4.0))
    return Appearance(j, q, c, m, s, h)

# mark: Inverse ===============================================================

## The XYZ (Y = 100 scale) that appears with lightness `j`, chroma `c` and hue
## `h` degrees under `v`.
pub func from_jch(j: f64, c: f64, h: f64, v: Viewing) -> XYZ:
    if j <= 0.0:
        return XYZ(0.0, 0.0, 0.0)
    let alpha = c / math.sqrt(j / 100.0)
    let t = math.pow(alpha / math.pow(1.64 - math.pow(0.29, v.n), 0.73), 1.0 / 0.9)
    let radians = h * math.pi / 180.0
    let e_hue = 0.25 * (math.cos(radians + 2.0) + 3.8)
    let ac = v.aw * math.pow(j / 100.0, 1.0 / v.c / v.z)
    let p1 = e_hue * (50000.0 / 13.0) * v.nc * v.ncb
    let p2 = ac / v.nbb
    let h_sin = math.sin(radians)
    let h_cos = math.cos(radians)
    let gamma = 23.0 * (p2 + 0.305) * t / (23.0 * p1 + 11.0 * t * h_cos + 108.0 * t * h_sin)
    let a = gamma * h_cos
    let b = gamma * h_sin
    let ra = (460.0 * p2 + 451.0 * a + 288.0 * b) / 1403.0
    let ga = (460.0 * p2 - 891.0 * a - 261.0 * b) / 1403.0
    let ba = (460.0 * p2 - 220.0 * a - 6300.0 * b) / 1403.0
    let rc = inverse_response(ra, v.fl) / v.rgb_d.x
    let gc = inverse_response(ga, v.fl) / v.rgb_d.y
    let bc = inverse_response(ba, v.fl) / v.rgb_d.z
    return apply(invert(m16), XYZ(rc, gc, bc))

func inverse_response(adapted: f64, fl: f64) -> f64:
    let magnitude = math.abs(adapted)
    let base = math.max(0.0, 27.13 * magnitude / (400.0 - magnitude))
    return math.copysign(100.0 / fl * math.pow(base, 1.0 / 0.42), adapted)

# mark: UCS ===================================================================

## CAM16-UCS from an appearance.
pub func to_ucs(app: Appearance) -> UCS:
    let j = 1.7 * app.j / (1.0 + 0.007 * app.j)
    let m = math.log(1.0 + 0.0228 * app.m) / 0.0228
    let radians = app.h * math.pi / 180.0
    return UCS(j, m * math.cos(radians), m * math.sin(radians))

## The lightness J and colorfulness M an UCS point stands for, and its hue.
pub func from_ucs(ucs: UCS, v: Viewing) -> XYZ:
    let j = ucs.j / (1.7 - 0.007 * ucs.j)
    let m = (math.exp(ucs.b * 0.0 + math.hypot(ucs.a, ucs.b) * 0.0228) - 1.0) / 0.0228
    let c = m / math.pow(v.fl, 0.25)
    var h = math.atan2(ucs.b, ucs.a) * 180.0 / math.pi
    if h < 0.0:
        h += 360.0
    return from_jch(j, c, h, v)

## The CAM16-UCS color difference: Euclidean, with ΔE about 1 just noticeable.
pub func delta_e(a: UCS, b: UCS) -> f64:
    return math.sqrt((a.j - b.j) * (a.j - b.j) + (a.a - b.a) * (a.a - b.a) + (a.b - b.b) * (a.b - b.b))

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

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

## Under incomplete adaptation (D = 0.9 at 40 cd/m²) even the white keeps a
## little chroma, as the model intends; complete adaptation would zero it.
test "the white has lightness 100 and almost no chroma; mid grey sits below":
    let v = viewing()
    let white = appearance(XYZ(95.047, 100.0, 108.883), v)
    assert(near(white.j, 100.0, 0.05) and white.c < 3.0)
    let grey = appearance(XYZ(95.047 * 0.18, 18.0, 108.883 * 0.18), v)
    # CAM16 lightness is not L*: an 18 % grey (L* 50) reads J about 39.
    assert(grey.j > 35.0 and grey.j < 45.0 and grey.c < 3.0)

test "appearance inverts back to the same XYZ":
    let v = viewing()
    for sample in [XYZ(41.24, 21.26, 1.93), XYZ(35.76, 71.52, 11.92), XYZ(18.05, 7.22, 95.05), XYZ(30.0, 40.0, 20.0)]:
        let app = appearance(sample, v)
        let back = from_jch(app.j, app.c, app.h, v)
        assert(near(back.x, sample.x, 0.05) and near(back.y, sample.y, 0.05) and near(back.z, sample.z, 0.05))
        let ucs = from_ucs(to_ucs(app), v)
        assert(near(ucs.x, sample.x, 0.05) and near(ucs.y, sample.y, 0.05) and near(ucs.z, sample.z, 0.05))

test "sRGB red under default conditions has the expected hue and a large chroma":
    let red = appearance(XYZ(41.24, 21.26, 1.93), viewing())
    assert(red.h > 20.0 and red.h < 40.0 and red.c > 80.0 and red.j > 40.0 and red.j < 60.0)
    assert(delta_e(to_ucs(red), to_ucs(red)) == 0.0)