dymokomi/luce-color
Source of release 0.8.2
0.8.2 / src / aces / module.lucb
#==============================================================================================
#
# aces - The ACES 2.0 Output Transform
#
# DESCRIPTION:
# Scene-referred ACES (AP0, or AP1 through apply_ap1) to display light for a display
# of a given peak luminance and limiting primaries, as the Academy's ACES 2.0 output
# transforms (aces-output) and OpenColorIO's builtin ACES2 transforms compute it:
#
# 1. the input clamped to AP1's positive range below the tonescale's forward limit;
# 2. RGB to Hellwig 2022 JMh (aces/cam);
# 3. the Daniele tonescale on J, and chroma compression (aces/tonescale);
# 4. gamut compression into the limiting gamut (aces/gamut, tables in aces/tables);
# 5. back to RGB in the limiting primaries, clamped to 0..peak/100.
#
# `invert` and `invert_ap1` run the steps backward (OpenColorIO's inverse ACES2
# output transform): display light to the scene light the forward transform
# shows as it, for bringing display-referred pictures (JPEGs, textures, screen
# captures) into a scene so they show unchanged. Display white goes to the scene
# light that reaches the peak, so it shows white, not grey.
#
# The result is display-linear RGB in the limiting primaries with 1.0 = 100 cd/m²
# (so an SDR display's white is 1.0, a 1000-nit display's is 10.0). to_xyz gives the
# matrix to CIE XYZ (D65 for D65 primaries); encoding into other display primaries
# and the transfer function are the caller's (see `space`, `transfer`).
#
# Computed in f64; OpenColorIO computes in f32, and its tables differ from these
# by its search tolerances, so the two agree to about 1e-4 of the peak.
#
# Fragments, in ORDER:
#
# module.lucb OutputTransform: create, apply, apply_ap1, invert, invert_ap1, to_xyz
# linear.lucb 3×3 matrices and primaries matrices
# cam.lucb the JMh model
# tonescale.lucb the tonescale and the chroma compression
# tables.lucb the reach, hue and cusp tables
# gamut.lucb the gamut compression and the upper hull's fit
#
#==============================================================================================
from luce_std import math
import xyz
## A transform's parameters are outside what ACES 2.0 defines.
pub let invalid: ErrorCode = ErrorCode.package(1)
## One display's output transform, its tables precomputed (about 15 KB, built in a few
## milliseconds).
pub struct OutputTransform:
var peak: f64
var input: Cam
var output: Cam
var tones: Tones
var chroma: Chroma
var limit_j: f64
var gamma_inv: f64
var reach: f64[363]
var gamut: Gamut
var to_ap1: f64[9]
var from_ap1: f64[9]
var limiting_to_xyz: f64[9]
## The transform for a display of `peak_nits` (100 for SDR, up to 10000) whose
## colors are limited to `limiting`'s gamut.
pub static func create(peak_nits: f64, limiting: xyz.Primaries) -> OutputTransform!:
if not (peak_nits >= 48.0 and peak_nits <= 10000.0):
error(invalid, "an ACES 2.0 output transform needs a peak of 48 to 10000 nits")
var out = OutputTransform(peak = peak_nits)
out.input = cam_of(xyz.aces_ap0)
out.output = cam_of(limiting)
let reach_cam = cam_of(xyz.aces_ap1)
out.tones = tones_of(peak_nits)
out.chroma = chroma_of(peak_nits, &out.tones)
out.limit_j = y_to_j(peak_nits, &out.input)
out.gamma_inv = 1.0 / model_gamma()
out.reach = fill_reach_table(out.reach, &reach_cam, out.limit_j)
out.gamut.mid_j = y_to_j(out.tones.c_t * reference_luminance, &out.input)
out.gamut.focus_distance = focus_distance + focus_distance * focus_distance_scaling * out.tones.log_peak
out.gamut.lower_gamma_inv = 1.0 / (1.14 + 0.07 * out.tones.log_peak)
let reach_corners_found = reach_corners(&reach_cam, out.limit_j, out.tones.forward_limit)
let limiting_corners_found = limiting_corners(&out.output, peak_nits)
out.gamut.hues = build_hue_table(&reach_corners_found, &limiting_corners_found)
out.gamut.cusps = build_cusp_table(&out.gamut.hues, &limiting_corners_found, &out.output)
out.gamut.search = hue_search_range(&out.gamut.cusps)
fit_upper_hull(&out.gamut, peak_nits, out.limit_j, &out.output)
out.to_ap1 = rgb_to_rgb(xyz.aces_ap0, xyz.aces_ap1)
out.from_ap1 = inverse(out.to_ap1)
out.limiting_to_xyz = to_xyz_of(limiting)
return out
## ACES2065-1 (AP0, scene-linear) to display-linear RGB in the limiting primaries,
## 1.0 = 100 cd/m², clamped to 0..peak/100.
pub func apply(ap0: f64[3]) -> f64[3]:
# The input stays within AP1's positive range below the forward limit.
var ap1 = times(self.to_ap1, ap0)
for at in 0..<(usize)3:
ap1[at] = math.clamp(ap1[at], 0.0, self.tones.forward_limit)
return self.render(times(self.from_ap1, ap1))
## The same from ACEScg (AP1, scene-linear).
pub func apply_ap1(ap1: f64[3]) -> f64[3]:
var clamped: f64[3]
for at in 0..<(usize)3:
clamped[at] = math.clamp(ap1[at], 0.0, self.tones.forward_limit)
return self.render(times(self.from_ap1, clamped))
func render(ap0: f64[3]) -> f64[3]:
let aab = rgb_to_aab(ap0, &self.input)
let jmh = aab_to_jmh(aab, &self.input)
let radians = jmh[2] * math.pi / 180.0
let cos_h = math.cos(radians)
let sin_h = math.sin(radians)
let reach_m = reach_at(&self.reach, jmh[2])
let m_norm = chroma_norm(cos_h, sin_h, self.chroma.scale)
let j_ts = tonescale_a_to_j(aab[0], &self.input, &self.tones)
let toned = chroma_compress(jmh, j_ts, m_norm, self.limit_j, self.gamma_inv, reach_m, &self.chroma)
let compressed = gamut_compress(toned, self.limit_j, self.gamma_inv, reach_m, &self.gamut)
let rgb = aab_to_rgb(jmh_to_aab(compressed, cos_h, sin_h, &self.output), &self.output)
let roof = self.peak / reference_luminance
return [math.clamp(rgb[0], 0.0, roof), math.clamp(rgb[1], 0.0, roof), math.clamp(rgb[2], 0.0, roof)]
## `apply`'s inverse: display-linear RGB in the limiting primaries (1.0 = 100
## cd/m², clamped to 0..peak/100) to ACES2065-1 (AP0, scene-linear).
pub func invert(display: f64[3]) -> f64[3]:
let roof = self.peak / reference_luminance
let rgb: f64[3] = [math.clamp(display[0], 0.0, roof), math.clamp(display[1], 0.0, roof), math.clamp(display[2], 0.0, roof)]
let shown = rgb_to_jmh(rgb, &self.output)
let radians = shown[2] * math.pi / 180.0
let cos_h = math.cos(radians)
let sin_h = math.sin(radians)
let reach_m = reach_at(&self.reach, shown[2])
let toned = gamut_decompress(shown, self.limit_j, self.gamma_inv, reach_m, &self.gamut)
let j = untonescale_j(toned[0], &self.input, &self.tones)
let m_norm = chroma_norm(cos_h, sin_h, self.chroma.scale)
let scene = chroma_decompress(toned, j, m_norm, self.limit_j, self.gamma_inv, reach_m, &self.chroma)
return aab_to_rgb(jmh_to_aab(scene, cos_h, sin_h, &self.input), &self.input)
## The same to ACEScg (AP1, scene-linear).
pub func invert_ap1(display: f64[3]) -> f64[3]:
return times(self.to_ap1, self.invert(display))
## The limiting primaries' RGB to CIE XYZ (their own white at Y = 1), row-major.
pub func to_xyz() -> f64[9]:
return self.limiting_to_xyz
## The peak, in cd/m².
pub func peak_nits() -> f64:
return self.peak
test "grey is neutral, SDR white is 1.0 and the curve rises":
let transform = try OutputTransform.create(100.0, xyz.srgb)
let grey = transform.apply([0.18, 0.18, 0.18])
assert(math.abs(grey[0] - grey[1]) < 1.0e-6 and math.abs(grey[1] - grey[2]) < 1.0e-6)
# 18% grey shows near 10 nits (0.1).
assert(grey[1] > 0.09 and grey[1] < 0.11)
let bright = transform.apply([1000.0, 1000.0, 1000.0])
assert(math.abs(bright[0] - 1.0) < 1.0e-3 and math.abs(bright[2] - 1.0) < 1.0e-3)
var previous = -1.0
for step in 0..<(usize)40:
let v = 0.001 * math.exp2((f64)step * 0.5)
let shown = transform.apply([v, v, v])[1]
assert(shown >= previous)
previous = shown
test "the inverse brings display light back to what the forward transform shows":
let transform = try OutputTransform.create(100.0, xyz.srgb)
# White shows white again, not grey.
let white = transform.apply(transform.invert([1.0, 1.0, 1.0]))
assert(math.abs(white[0] - 1.0) < 2.0e-3 and math.abs(white[1] - 1.0) < 2.0e-3 and math.abs(white[2] - 1.0) < 2.0e-3)
var worst = 0.0
for r in 0..<(usize)9:
for g in 0..<(usize)9:
for b in 0..<(usize)9:
let display: f64[3] = [(f64)r / 8.0 * 0.999, (f64)g / 8.0 * 0.999, (f64)b / 8.0 * 0.999]
let back = transform.apply(transform.invert(display))
for at in 0..<(usize)3:
worst = math.max(worst, math.abs(back[at] - display[at]))
print(f"inverse round trip: worst {worst}")
assert(worst < 2.0e-3)
test "scene light within the gamut comes back through the inverse":
let transform = try OutputTransform.create(100.0, xyz.srgb)
for value in [[0.18, 0.18, 0.18], [0.05, 0.02, 0.01], [0.4, 0.3, 0.2], [1.5, 1.0, 0.6]]:
let scene: f64[3] = value
let back = transform.invert_ap1(transform.apply_ap1(scene))
for at in 0..<(usize)3:
assert(math.abs(back[at] - scene[at]) < 1.0e-3 * (1.0 + scene[at]))