Luce packages
LuceLuce BaseLuciaOS

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]))