Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-develop

Source of release 0.1.0

0.1.0 / src / view.lucb

## View transforms: how scene-linear light in the working space (ACES AP1) is
## shown on a display (linear sRGB/Rec.709 primaries, 0..1, D65). Each view is
## evaluated exactly on the CPU (export) and baked into a 3D table the GPU
## samples: per-channel log2 shaper over 24 stops around middle grey, `lut_size`
## nodes a side, tiled into a 2D texture (the blue axis across the slices).
##
## ACES: the ACES 2.0 Output Transform for a 100-nit SDR display limited to Rec.709
## primaries (luce-color's aces): Hellwig JMh, the Daniele tonescale, chroma and gamut
## compression. It shows scene grey near 0.1, as ACES intends, and its table is
## read tetrahedrally on the GPU.
## Standard: a neutral filmic curve on each pixel's largest component, keeping
## its ratios (so hues hold), colors out of the display gamut pulled toward their
## luminance, and highlights that run to white as they pass the shoulder.
## Linear: the scene clipped to the display, for checking.
## Print: the scene printed on Kodak Vision 2383 and projected (film_print.lucb), a
## cinema's release print; its table is read like ACES's.
##
## Display-referred pictures (JPEG, PNG, TIFF, HEIC) come into the scene through
## the ACES view's inverse (`undisplay`, luce-color's inverse output transform,
## with the lift taken off), as textures and screen content enter an ACES
## pipeline: shown through the default view they look as they did, white white,
## and edits act on scene light. Through Standard or Linear they are that scene
## light shown another way.
import memory
import sync
import time
from luce_std import math
from luce_color import xyz
from luce_color import aces
from luce_color import transfer
from luce_color import cam16
from luce_std import parallel
from settings import View
import film_print
import film_paper
from film_paper import PaperSettings

## Nodes per side of the baked table, and the shaper's range in stops from 0.18.
pub let lut_size: usize = 64
pub let shaper_low: f64 = -12.0
pub let shaper_high: f64 = 12.0

## The display a view shows for: its primaries, all with a D65 white and (for
## encoding) sRGB's curve. The viewer shows sRGB; an export may ask for Display P3.
pub enum Output as i64:
    srgb = 0
    display_p3 = 1

func primaries_of(output: Output) -> xyz.Primaries:
    return xyz.display_p3 if output == Output.display_p3 else xyz.srgb

## The working space to display matrix (AP1, D60 → sRGB primaries, D65), row-major.
pub func working_to_display() -> f64[9]:
    return working_to_output(Output.srgb)

## The working space to `output`'s linear RGB (AP1, D60 → its primaries, D65), row-major.
pub func working_to_output(output: Output) -> f64[9]:
    let primaries = primaries_of(output)
    let to_xyz = xyz.rgb_to_xyz(xyz.aces_ap1)
    let adapted = xyz.multiply(xyz.adapt(xyz.aces_ap1.white, primaries.white), to_xyz)
    return xyz.multiply(xyz.xyz_to_rgb(primaries), adapted).m

## `output`'s luminance weights: Y of its red, green and blue.
func luminance_of(output: Output) -> f64[3]:
    let m = xyz.rgb_to_xyz(primaries_of(output)).m
    return [m[3], m[4], m[5]]

## sRGB (D65) to the working space, row-major: what non-raw sources and luce-raw's
## sRGB matrices are turned by.
pub func display_to_working() -> f64[9]:
    let to_xyz = xyz.rgb_to_xyz(xyz.srgb)
    let adapted = xyz.multiply(xyz.adapt(xyz.srgb.white, xyz.aces_ap1.white), to_xyz)
    return xyz.multiply(xyz.xyz_to_rgb(xyz.aces_ap1), adapted).m

## The scene value at shaper coordinate `s` (0..1), and back.
pub func unshape(s: f64) -> f64:
    return 0.18 * math.exp2(shaper_low + s * (shaper_high - shaper_low))

pub func shape(x: f64) -> f64:
    if not (x > 0.0):
        return 0.0
    return math.clamp((math.log2(x / 0.18) - shaper_low) / (shaper_high - shaper_low), 0.0, 1.0)

## The SDR ACES 2.0 transform, built once on first use (its tables take milliseconds).
## How much the ACES view raises scene light first: one stop.
pub let aces_lift: f64 = 2.0

var aces_sdr: aces.OutputTransform
var aces_once: sync.Once
var aces_p3: aces.OutputTransform
var aces_p3_once: sync.Once

func build_aces():
    aces_sdr = aces.OutputTransform.create(100.0, xyz.srgb) catch failure:
        trap("the ACES 2.0 SDR transform could not be built")

func build_aces_p3():
    aces_p3 = aces.OutputTransform.create(100.0, xyz.display_p3) catch failure:
        trap("the ACES 2.0 SDR P3 transform could not be built")

## Nodes per side of the inverse table, over sRGB-encoded display values.
pub let inverse_size: usize = 129

## The ACES view's inverse, baked over sRGB-encoded display values: per node the
## AP1 scene light that view shows as it (red fastest, then green, then blue),
## stored as `squeeze` of it, in which it is nearly linear between nodes: scene
## light grows about exponentially toward the display's white and its edges.
var inverse_table: f32[]
var inverse_once: sync.Once

## The sRGB decode of each node, shared by the threads that build the table.
var inverse_decoded: f64[129]

func build_inverse():
    let n = inverse_size
    aces_once.run(build_aces)
    inverse_table = new f32[n * n * n * 3] --- in memory.heap catch failure:
        trap("the ACES inverse table could not be allocated")
    for at in 0..<n:
        inverse_decoded[at] = transfer.srgb_decode((f64)at / (f64)(n - 1))
    # A slice of blue per work item, on every processor.
    parallel.for_each(n, (void*)&inverse_table, build_inverse_slice) catch failure:
        trap("the ACES inverse table could not be built")

func build_inverse_slice(context: void*, b: usize, worker: usize) -> !:
    let n = inverse_size
    for g in 0..<n:
        for r in 0..<n:
            let scene = aces_sdr.invert_ap1([inverse_decoded[r], inverse_decoded[g], inverse_decoded[b]])
            let at = ((b * n + g) * n + r) * 3
            for channel in 0..<(usize)3:
                inverse_table[at + channel] = (f32)squeeze(scene[channel] / aces_lift)

## The lower node of the table cell holding coordinate `at` (0..n-1).
func cell_of(at: f64, n: usize) -> usize:
    let node = (usize)at
    return node if node < n - 1 else n - 2

## The scene light (AP1) that the ACES view shows as the sRGB-encoded display
## color (`r`, `g`, `b`, each 0..1), read from the inverse table tetrahedrally.
pub func undisplay(r: f64, g: f64, b: f64) -> f64[3]:
    inverse_once.run(build_inverse)
    let n = inverse_size
    let top = (f64)(n - 1)
    let x = math.clamp(r, 0.0, 1.0) * top
    let y = math.clamp(g, 0.0, 1.0) * top
    let z = math.clamp(b, 0.0, 1.0) * top
    let x0 = cell_of(x, n)
    let y0 = cell_of(y, n)
    let z0 = cell_of(z, n)
    let fx = x - (f64)x0
    let fy = y - (f64)y0
    let fz = z - (f64)z0
    # The tetrahedron of the cube holding the point, by the order of its fractions.
    var steps: usize[3] = [1, n, n * n]
    var fractions: f64[3] = [fx, fy, fz]
    for pass in 0..<(usize)2:
        for at in 0..<(usize)(2 - pass):
            if fractions[at] < fractions[at + 1]:
                let f = fractions[at]
                fractions[at] = fractions[at + 1]
                fractions[at + 1] = f
                let s = steps[at]
                steps[at] = steps[at + 1]
                steps[at + 1] = s
    let base = (z0 * n + y0) * n + x0
    let corner_1 = base + steps[0]
    let corner_2 = corner_1 + steps[1]
    let corner_3 = corner_2 + steps[2]
    var out: f64[3]
    for channel in 0..<(usize)3:
        let c0 = (f64)inverse_table[base * 3 + channel]
        let c1 = (f64)inverse_table[corner_1 * 3 + channel]
        let c2 = (f64)inverse_table[corner_2 * 3 + channel]
        let c3 = (f64)inverse_table[corner_3 * 3 + channel]
        out[channel] = unsqueeze(c0 + (c1 - c0) * fractions[0] + (c2 - c1) * fractions[1] + (c3 - c2) * fractions[2])
    return out

## Scene light on a log-like scale that passes through zero (an inverse
## hyperbolic sine), and back.
let squeeze_scale: f64 = 256.0

func squeeze(x: f64) -> f64:
    let v = x * squeeze_scale
    return math.copysign(math.log(math.abs(v) + math.sqrt(v * v + 1.0)), v)

func unsqueeze(y: f64) -> f64:
    let grown = math.exp(math.abs(y))
    return math.copysign(0.5 * (grown - 1.0 / grown), y) / squeeze_scale

## The Standard view's tone curve, set as a camera renders: scene grey (0.18)
## shows at 0.25 (sRGB 136), scene 1.0 at 0.7, and it reaches the display's
## white near 16, with a firm toe.
func filmic(x: f64) -> f64:
    if not (x > 0.0):
        return 0.0
    return math.min(1.0, 1.05 * math.pow(x / (x + 0.3628), 1.3))

func apply(m: f64[9], r: f64, g: f64, b: f64) -> f64[3]:
    return [m[0] * r + m[1] * g + m[2] * b, m[3] * r + m[4] * g + m[5] * b, m[6] * r + m[7] * g + m[8] * b]

## Scene light `rgb` (AP1) shown through `view` on `output`: display-linear in
## its primaries, 0..1. `to_display` is `working_to_output(output)`; `silver` the
## print view's silver kept (0..1).
pub func display(view: View, rgb: f64[3], to_display: f64[9], output: Output = Output.srgb, silver: f64 = 0.0,
                 paper: PaperSettings = PaperSettings(), material: i64 = 0) -> f64[3]:
    if view == View.aces:
        # AP1 in, a stop brighter: ACES shows scene grey at 10 nits, a stop darker
        # than a camera's rendering, and photographs are exposed for cameras. Out:
        # display light in the output's primaries (the transform's limiting
        # primaries), 1.0 the SDR white.
        let lifted: f64[3] = [rgb[0] * aces_lift, rgb[1] * aces_lift, rgb[2] * aces_lift]
        if output == Output.display_p3:
            aces_p3_once.run(build_aces_p3)
            return aces_p3.apply_ap1(lifted)
        aces_once.run(build_aces)
        return aces_sdr.apply_ap1(lifted)
    if view == View.print or view == View.paper:
        # XYZ (D65, the print's white at 1) into the output's primaries, clipped:
        # the print's gamut is mostly inside the display's.
        # Lifted a stop as for ACES: photographs are exposed for cameras.
        let lifted: f64[3] = [rgb[0] * aces_lift, rgb[1] * aces_lift, rgb[2] * aces_lift]
        let made = film_paper.printed(lifted, &paper) if view == View.paper else film_print.projected(lifted, silver, material)
        let shown = as_displayed(made, viewing_of(view))
        let m = xyz.xyz_to_rgb(primaries_of(output)).m
        let c = apply(m, shown.x, shown.y, shown.z)
        return [math.clamp(c[0], 0.0, 1.0), math.clamp(c[1], 0.0, 1.0), math.clamp(c[2], 0.0, 1.0)]
    var c = apply(to_display, rgb[0], rgb[1], rgb[2])
    if view == View.linear:
        return [math.clamp(c[0], 0.0, 1.0), math.clamp(c[1], 0.0, 1.0), math.clamp(c[2], 0.0, 1.0)]
    let weights = luminance_of(output) if output != Output.srgb else [0.2126, 0.7152, 0.0722]
    let y = weights[0] * c[0] + weights[1] * c[1] + weights[2] * c[2]
    if not (y > 0.0):
        return [0.0, 0.0, 0.0]
    # Out of the display's gamut: toward the luminance until no component is negative.
    let least = math.min(c[0], math.min(c[1], c[2]))
    if least < 0.0:
        let t = y / (y - least)
        for at in 0..<(usize)3:
            c[at] = y + (c[at] - y) * t
    let norm = math.max(c[0], math.max(c[1], c[2]))
    let toned = filmic(norm)
    # Past scene white, highlights lose their color as film's do.
    let whiten = math.pow(math.clamp(math.log2(norm) / 5.0, 0.0, 1.0), 1.5)
    var out: f64[3]
    for at in 0..<(usize)3:
        let kept = c[at] * toned / norm
        out[at] = math.clamp(kept + (toned - kept) * whiten, 0.0, 1.0)
    return out

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

## Where a print is seen, and the display that shows it, for CAM16
## (luce_color.cam16): a print appears as its viewing makes it appear, and the
## display shows the color that looks the same in its own (the same lightness
## relative to its white, hue, and colorfulness: colors look more colorful the
## brighter they are lit, the Hunt effect, so a cinema's 48 cd/m² print shows
## a little less saturated on a 100 cd/m² display, a lit wall's a little more). A cinema's screen white is
## SMPTE's 48 cd/m² (14 fL), in a dark surround: images look
## flatter there (Bartleson and Breneman), which release prints' contrast
## makes up for, so a display in a dim room shows them a little flatter. A
## paper print on a wall under 500 lux (white about 143 cd/m²: 90 % reflected,
## over π) is in an average surround: it looks more contrasty than on a
## display, which shows it a little harder. The display: 100 cd/m² white (the
## ACES view's), a dim room. Adapting luminance is a fifth of white (a grey
## world), the background 20 %.
let screen_white: f64 = 48.0
let room_lux: f64 = 500.0
let display_white: f64 = 100.0
let paper_white_reflectance: f64 = 0.9

## The print's viewing conditions and the display's.
pub struct Viewings:
    pub var print: cam16.Viewing
    pub var display: cam16.Viewing

pub func viewing_of(view: View) -> Viewings:
    let white = xyz.XYZ(95.047, 100.0, 108.883)
    let projected = view == View.print
    let luminance = screen_white if projected else room_lux * paper_white_reflectance / math.pi
    return Viewings(print = cam16.viewing(white, 0.2 * luminance, 20.0, 0.0 if projected else 2.0),
                    display = cam16.viewing(white, 0.2 * display_white, 20.0, 1.0))

## `shown` (XYZ, the print's white at Y = 1, adapted to D65) as the display
## shows it.
func as_displayed(shown: xyz.XYZ, seen: Viewings) -> xyz.XYZ:
    let matched = cam16.corresponding(xyz.XYZ(shown.x * 100.0, shown.y * 100.0, shown.z * 100.0), seen.print, seen.display, colorfulness = true)
    return xyz.XYZ(matched.x / 100.0, matched.y / 100.0, matched.z / 100.0)

## The print and paper views' data for the GPU, which computes them per pixel
## (shaders/develop.frag's `printed`) as `display` does: the print's or the
## paper's model (film_print.lucb, film_paper.lucb), then at row 2: 6–8 the
## matrix from XYZ (D65) to `output`'s primaries, by rows; 9's second the lift;
## 15–17 the print's viewing and 18–20 the display's (`put_viewing`).
## `out` is `film_print.print_atlas_width` × `print_atlas_rows` RGBA single floats.
pub func pack(view: View, out: f32[], output: Output = Output.srgb, silver: f64 = 0.0, paper: PaperSettings = PaperSettings(),
              material: i64 = 0):
    for at in 0..<out.length:
        out[at] = 0.0f32
    if view == View.paper:
        film_paper.pack(&paper, out)
    else:
        film_print.pack_projection(silver, material, out)
    let m = xyz.xyz_to_rgb(primaries_of(output)).m
    for row in 0..<(usize)3:
        film_print.put(out, 2, 6 + row, m[row * 3], m[row * 3 + 1], m[row * 3 + 2], 0.0)
    let at = (2 * film_print.print_atlas_width + 9) * 4
    out[at + 1] = (f32)aces_lift
    let seen = viewing_of(view)
    put_viewing(out, 15, &seen.print)
    put_viewing(out, 18, &seen.display)

## CAM16 viewing conditions `v` at row 2 from `column`: the adaptation gains and
## F_L; Nbb (= Ncb), c, z, Nc; A_w and (1.64 − 0.29ⁿ)^0.73.
func put_viewing(out: f32[], column: usize, v: const cam16.Viewing*):
    film_print.put(out, 2, column, v.rgb_d.x, v.rgb_d.y, v.rgb_d.z, v.fl)
    film_print.put(out, 2, column + 1, v.nbb, v.c, v.z, v.nc)
    film_print.put(out, 2, column + 2, v.aw, math.pow(1.64 - math.pow(0.29, v.n), 0.73), 0.0, 0.0)

## Bake `view` into `table`: lut_size³ RGBA half floats laid out as a 2D image
## lut_size² wide and lut_size high, red fastest, blue choosing the slice.
## For the ACES, Standard and Linear views (the print and paper go per pixel).
pub func bake(view: View, table: f16[]):
    let n = lut_size
    let to_display = working_to_display()
    for b in 0..<n:
        for g in 0..<n:
            for r in 0..<n:
                let scene: f64[3] = [unshape((f64)r / (f64)(n - 1)), unshape((f64)g / (f64)(n - 1)), unshape((f64)b / (f64)(n - 1))]
                let shown = display(view, scene, to_display)
                let at = (g * n * n + b * n + r) * 4
                table[at] = (f16)shown[0]
                table[at + 1] = (f16)shown[1]
                table[at + 2] = (f16)shown[2]
                table[at + 3] = (f16)1.0

test "middle grey shows at 0.25; white stays neutral":
    let to_display = working_to_display()
    let grey = display(View.standard, [0.18, 0.18, 0.18], to_display)
    assert(math.abs(grey[0] - 0.25) < 0.002 and math.abs(grey[1] - grey[2]) < 1.0e-6)
    let bright = display(View.standard, [40.0, 40.0, 40.0], to_display)
    assert(bright[0] > 0.99 and math.abs(bright[0] - bright[2]) < 1.0e-6)
    # A saturated scene red past white comes out bright and lighter, not clipped red.
    let hot = display(View.standard, [30.0, 0.5, 0.5], to_display)
    assert(hot[0] > 0.99 and hot[1] > 0.3)
    assert(math.abs(shape(unshape(0.37)) - 0.37) < 1.0e-12)

test "ACES shows grey near 10 nits, neutral, and highlights converge to white":
    let to_display = working_to_display()
    let grey = display(View.aces, [0.09, 0.09, 0.09], to_display)
    assert(grey[1] > 0.09 and grey[1] < 0.11)
    assert(math.abs(grey[0] - grey[1]) < 1.0e-4 and math.abs(grey[2] - grey[1]) < 1.0e-4)
    let white = display(View.aces, [2000.0, 2000.0, 2000.0], to_display)
    assert(white[0] > 0.99 and white[1] > 0.99 and white[2] > 0.99)
    # A saturated red far past white desaturates toward white instead of clipping.
    let hot = display(View.aces, [400.0, 20.0, 20.0], to_display)
    assert(hot[0] > 0.95 and hot[1] > 0.5 and hot[2] > 0.5)
    var previous = -1.0
    for step in 0..<(usize)30:
        let v = 0.001 * math.exp2((f64)step * 0.6)
        let shown = display(View.aces, [v, v, v], to_display)[1]
        assert(shown >= previous)
        previous = shown

test "the ACES table bakes":
    let n = lut_size
    let table = try new f16[n * n * n * 4] --- in memory.heap
    defer free(table) in memory.heap
    let started = time.now()
    bake(View.aces, table)
    print(f"ACES 64³ bake: {(time.now() - started) // 1000000} ms")
    let grey_node = (usize)(shape(0.18) * (f64)(n - 1) + 0.5)
    let at = (grey_node * n * n + grey_node * n + grey_node) * 4
    let node = unshape((f64)grey_node / (f64)(n - 1))
    let expected = display(View.aces, [node, node, node], working_to_display())
    assert(math.abs((f64)table[at + 1] - expected[1]) < 0.002)

test "display pictures come back unchanged through the ACES view":
    let to_display = working_to_display()
    let started = time.now()
    let white = display(View.aces, undisplay(1.0, 1.0, 1.0), to_display)
    print(f"ACES inverse table: {(time.now() - started) // 1000000} ms")
    assert(white[0] > 0.998 and white[1] > 0.998 and white[2] > 0.998)
    # Every 8-bit level of a grid, and colors between the table's nodes, in levels.
    var worst = 0.0
    for r in 0..<(usize)18:
        for g in 0..<(usize)18:
            for b in 0..<(usize)18:
                let encoded: f64[3] = [(f64)(r * 15) / 255.0, (f64)(g * 15) / 255.0, (f64)(b * 15) / 255.0]
                let scene = undisplay(encoded[0], encoded[1], encoded[2])
                let shown = display(View.aces, scene, to_display)
                for at in 0..<(usize)3:
                    worst = math.max(worst, math.abs(transfer.srgb_encode(shown[at]) - encoded[at]) * 255.0)
    print(f"ACES inverse round trip: worst {worst} levels")
    assert(worst < 0.5)

test "a projected print shows a little lighter on a display, a print on a wall a little darker":
    let to_display = working_to_display()
    let grey: f64[3] = [0.18, 0.18, 0.18]
    let lifted: f64[3] = [0.18 * aces_lift, 0.18 * aces_lift, 0.18 * aces_lift]
    let projected = film_print.projected(lifted)
    let shown = display(View.print, grey, to_display)
    let shown_y = 0.2126 * shown[0] + 0.7152 * shown[1] + 0.0722 * shown[2]
    assert(shown_y > projected.y * 1.05 and shown_y < projected.y * 1.4)
    let paper = PaperSettings()
    let on_wall = film_paper.printed(lifted, &paper)
    let seen = display(View.paper, grey, to_display, paper = paper)
    let seen_y = 0.2126 * seen[0] + 0.7152 * seen[1] + 0.0722 * seen[2]
    assert(seen_y < on_wall.y * 0.95 and seen_y > on_wall.y * 0.6)