Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-develop

Source of release 0.1.0

0.1.0 / src / scene.lucb

## A photo's scene: its light as the develop starts from it, at a viewer's size,
## upright (the file's orientation applied). A raw is developed once with
## luce-raw's `camera` option (demosaiced, levelled, balanced as shot, no color
## matrix), turned upright, and kept with its file, so a new white
## balance is only a new matrix (luce-raw's `rendering`). Other files are
## display-referred: their pixels come in through the ACES view's inverse
## (view.undisplay), as AP1 scene light the default view shows unchanged, white
## as white. Either way the renderer turns the scene's values into ACES AP1 with
## one matrix that also carries the exposure.
import c
import memory
import strings
from luce_std import files
from luce_std import math
from luce_raw import raw
from luce_exif import exif
from luce_color import temperature
from luce_color import xyz
from luce_color import spectral
from luce_color import camera
from luce_color.camera import Response
import film_exposure
from settings import Settings
from settings import parse as settings_text
import source
import view
from luce_std import parallel
import codes

pub let invalid: ErrorCode = codes.invalid

pub struct Scene:
    ## The raw file's bytes (owned), or empty for other files.
    var data: u8[]
    var columns: usize
    var rows: usize
    ## RGBA half floats, rows packed, top-down, upright: camera values balanced as
    ## shot for raws, AP1 scene light for other files.
    var pixels: f16[]
    ## The as-shot white balance's multipliers, its temperature and tint.
    var as_shot: f64[3]
    pub var shot_temperature: f64
    pub var shot_tint: f64
    ## How long it was exposed (seconds, from EXIF; zero when unknown).
    pub var shot_seconds: f64
    ## A raw camera's spectral sensitivities in the units of `pixels` (its
    ## curves times the as-shot multipliers).
    var response: Response

    pub func width() -> i64:
        return (i64)self.columns

    pub func height() -> i64:
        return (i64)self.rows

    ## Whether the scene is a camera raw, whose white balance the settings choose.
    pub func is_raw() -> bool:
        return self.data.length > 0

    ## The mean of the scene's values, from every 97th pixel (enough for a
    ## mean, cheap enough for every draw).
    pub func average() -> f64[3]:
        var sum: f64[3] = [0.0, 0.0, 0.0]
        var count = 0.0
        var at: usize = 0
        let total = self.columns * self.rows
        while at < total:
            for k in 0..<(usize)3:
                sum[k] += (f64)self.pixels[at * 4 + k]
            count += 1.0
            at += 97
        if count == 0.0:
            return [0.0, 0.0, 0.0]
        return [sum[0] / count, sum[1] / count, sum[2] / count]

    ## The scene values of pixel `at` (rows packed).
    pub func value_at(at: usize) -> f64[3]:
        return [(f64)self.pixels[at * 4], (f64)self.pixels[at * 4 + 1], (f64)self.pixels[at * 4 + 2]]

    ## The scene values at (`u`, `v`), 0..1 of the image, filtered as the GPU
    ## samples a texture: bilinear between texel centers, clamped at the edges.
    pub func sample(u: f64, v: f64) -> f64[3]:
        let x = math.clamp(u * (f64)self.columns - 0.5, 0.0, (f64)(self.columns - 1))
        let y = math.clamp(v * (f64)self.rows - 0.5, 0.0, (f64)(self.rows - 1))
        let x0 = (usize)x
        let y0 = (usize)y
        let x1 = x0 + 1 if x0 + 1 < self.columns else x0
        let y1 = y0 + 1 if y0 + 1 < self.rows else y0
        let fx = x - (f64)x0
        let fy = y - (f64)y0
        let top_left = self.value_at(y0 * self.columns + x0)
        let top_right = self.value_at(y0 * self.columns + x1)
        let bottom_left = self.value_at(y1 * self.columns + x0)
        let bottom_right = self.value_at(y1 * self.columns + x1)
        var out: f64[3]
        for at in 0..<(usize)3:
            let top = top_left[at] + (top_right[at] - top_left[at]) * fx
            let bottom = bottom_left[at] + (bottom_right[at] - bottom_left[at]) * fx
            out[at] = top + (bottom - top) * fy
        return out

    ## A scene of `pixels` (RGBA half floats, `width` × `height`, rows packed),
    ## already scene light in AP1, which it owns: film's output.
    pub static func from_pixels(width: usize, height: usize, pixels: f16[]) -> Scene:
        return Scene(columns = width, rows = height, pixels = pixels, shot_temperature = 6500.0)

    ## The scene `columns` pixels wide (its height in proportion), each pixel the
    ## mean of the light over its area: what a film scanned at that many samples
    ## is filmed from. Only its pixels and as-shot white come along (no raw, no
    ## camera response): it is for filming, through a matrix found on this scene.
    pub func sampled(columns: usize) -> Scene!:
        if columns == 0 or self.columns == 0:
            error(invalid, "a sampled scene needs a size")
        let rows = (usize)math.max(1.0, math.round((f64)self.rows * (f64)columns / (f64)self.columns))
        let pixels = try new f16[columns * rows * 4] --- in memory.heap
        errdefer free(pixels) in memory.heap
        var job = Sampling(source = &self, columns = columns, rows = rows, pixels = pixels)
        try parallel.for_each(rows, (void*)&job, sample_row)
        return Scene(columns = columns, rows = rows, pixels = pixels, as_shot = self.as_shot, shot_temperature = self.shot_temperature,
                     shot_tint = self.shot_tint, shot_seconds = self.shot_seconds)

    ## The pixels as bytes, for a texture upload.
    pub func bytes() -> const u8[]:
        return u8[]((u8*)self.pixels.data, self.pixels.length * 2)

    ## The matrix, row-major, from the scene's values into AP1 for `settings`:
    ## white balance (and camera color for raws), then exposure. Other files are
    ## AP1 already and balanced as shot (a neutral 6500 K): a temperature and tint
    ## re-balance them as if that had been the light, adapting its white (Bradford)
    ## to the as-shot one, so a higher temperature warms them as it warms a raw.
    pub func matrix(settings: const Settings*) -> f64[9]!:
        let exposure = math.exp2(settings.get(.exposure))
        if not self.is_raw():
            var out: f64[9] = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
            let kelvin = settings.get(.temperature)
            if kelvin > 0.0:
                let light = temperature.white(kelvin, settings.get(.tint))
                let shot = temperature.white(self.shot_temperature, self.shot_tint)
                let to_xyz = xyz.rgb_to_xyz(xyz.aces_ap1)
                out = xyz.multiply(xyz.xyz_to_rgb(xyz.aces_ap1), xyz.multiply(xyz.adapt(light, shot), to_xyz)).m
            for at in 0..<(usize)9:
                out[at] *= exposure
            return out
        let to_working = view.display_to_working()
        let look = try raw.rendering(self.data, settings.get(.temperature), settings.get(.tint) if settings.get(.temperature) > 0.0 else 0.0)
        # Values balanced as shot, rebalanced: times the new multipliers over the old.
        var balanced = look.to_srgb
        for row in 0..<(usize)3:
            for column in 0..<(usize)3:
                balanced[row * 3 + column] *= look.balance.multipliers[column] / self.as_shot[column] * look.gain * exposure
        return multiply(to_working, balanced)

    ## What the film needs to expose this scene for `settings` (the settings the
    ## scene's matrix takes: film.camera_settings): the camera, and the way from
    ## the AP1 light the film receives back to the scene's values.
    pub func film_input(settings: const Settings*) -> film_exposure.Input!:
        var out = film_exposure.Input(response = self.response, raw = self.is_raw(), shot_kelvin = self.shot_temperature, shot_tint = self.shot_tint,
                                      shot_seconds = self.shot_seconds if self.shot_seconds > 0.0 else 1.0 / 60.0)
        if self.is_raw():
            var plain = *settings
            plain.set(.exposure, 0.0)
            let m = try self.matrix(&plain)
            out.to_camera = xyz.invert(xyz.Matrix3(m)).m
        return out

    ## Turn the picture `quarters` quarter turns clockwise (the settings'
    ## Turn, geometry_turn): applied before everything else, as the camera's
    ## own orientation is.
    pub func turn(quarters: i64) -> !:
        let wrapped = ((quarters % 4) + 4) % 4
        # As the EXIF orientations that turn a picture by those quarters.
        let orientations: u64[4] = [1, 6, 3, 8]
        try self.orient(orientations[(usize)wrapped])

    ## Turn the pixels upright from EXIF orientation `orientation` (1–8; other
    ## values leave them as they are). 5–8 swap the width and height.
    func orient(orientation: u64) -> !:
        if orientation < 2 or orientation > 8:
            return
        let width = self.columns
        let height = self.rows
        let turned = orientation >= 5
        let columns = height if turned else width
        let rows = width if turned else height
        let pixels = try new f16[columns * rows * 4] --- in memory.heap
        for y in 0..<rows:
            for x in 0..<columns:
                let (sx, sy) = upright_source(orientation, x, y, width, height)
                let from_at = (sy * width + sx) * 4
                let to_at = (y * columns + x) * 4
                for channel in 0..<(usize)4:
                    pixels[to_at + channel] = self.pixels[from_at + channel]
        free(self.pixels) in memory.heap
        self.pixels = pixels
        self.columns = columns
        self.rows = rows

    pub func close():
        if self.data.length > 0:
            free(self.data) in memory.heap
        if self.pixels.length > 0:
            free(self.pixels) in memory.heap
        var no_bytes: u8[]
        var no_pixels: f16[]
        self.data = no_bytes
        self.pixels = no_pixels
        self.columns = 0
        self.rows = 0

## The stored pixel that lands at (`x`, `y`) of the upright picture, for a
## `width` × `height` picture stored with EXIF orientation `orientation`.
func upright_source(orientation: u64, x: usize, y: usize, width: usize, height: usize) -> (usize, usize):
    return match orientation:
        2 => (width - 1 - x, y)
        3 => (width - 1 - x, height - 1 - y)
        4 => (x, height - 1 - y)
        5 => (y, x)
        6 => (y, height - 1 - x)
        7 => (width - 1 - y, height - 1 - x)
        8 => (width - 1 - y, x)
        _ => (x, y)

## A scene being sampled (Scene.sampled): rows of `pixels` from `source`.
struct Sampling:
    var source: const Scene*
    var columns: usize
    var rows: usize
    var pixels: f16[]

## How much of source pixel `at` lies inside [`low`, `high`) (source pixels).
func covered(at: usize, low: f64, high: f64) -> f64:
    return math.max(0.0, math.min((f64)at + 1.0, high) - math.max((f64)at, low))

## Row `y` of a sampled scene: each pixel the area-weighted mean of the source
## pixels its footprint covers, partly covered ones in part.
func sample_row(context: void*, y: usize, worker: usize) -> !:
    let job = (Sampling*)context
    let original = job.source
    let step_x = (f64)original.columns / (f64)job.columns
    let step_y = (f64)original.rows / (f64)job.rows
    let top = (f64)y * step_y
    let bottom = top + step_y
    let first_row = (usize)top
    let last_row = (usize)math.min(math.ceil(bottom), (f64)original.rows)
    for x in 0..<job.columns:
        let left = (f64)x * step_x
        let right = left + step_x
        let first_column = (usize)left
        let last_column = (usize)math.min(math.ceil(right), (f64)original.columns)
        var sum: f64[4] = [0.0, 0.0, 0.0, 0.0]
        var weight = 0.0
        for sy in first_row..<last_row:
            let wy = covered(sy, top, bottom)
            for sx in first_column..<last_column:
                let w = wy * covered(sx, left, right)
                let at = (sy * original.columns + sx) * 4
                for channel in 0..<(usize)4:
                    sum[channel] += w * (f64)original.pixels[at + channel]
                weight += w
        let to = (y * job.columns + x) * 4
        for channel in 0..<(usize)4:
            job.pixels[to + channel] = (f16)(sum[channel] / math.max(weight, 1.0e-12))

test "a sampled scene keeps the mean light":
    # 4 × 2 → 2 × 1: each half its own mean; 3 × 1 → 2 × 1 shares the middle.
    var picture = Scene()
    picture.columns = 4
    picture.rows = 2
    picture.pixels = try new f16[32] --- in memory.heap
    for at in 0..<(usize)32:
        picture.pixels[at] = (f16)(f64)(at // 4 % 4)
    defer picture.close()
    var half = try picture.sampled(2)
    defer half.close()
    assert(half.columns == 2 and half.rows == 1)
    assert((f64)half.pixels[0] == 0.5 and (f64)half.pixels[4] == 2.5)
    var three = Scene()
    three.columns = 3
    three.rows = 1
    three.pixels = try new f16[12] --- in memory.heap
    for at in 0..<(usize)12:
        three.pixels[at] = (f16)(f64)(at // 4)
    defer three.close()
    var two = try three.sampled(2)
    defer two.close()
    # Left: pixel 0 whole and half of pixel 1 (1.5 wide): (0 + 0.5) / 1.5.
    assert(math.abs((f64)two.pixels[0] - 1.0 / 3.0) < 1.0e-3 and math.abs((f64)two.pixels[4] - 5.0 / 3.0) < 1.0e-3)

test "a quarter turn clockwise puts the left column on top":
    # 2 × 1: a dark pixel left of a bright one; turned, 1 × 2 with the dark on top.
    var picture = Scene()
    picture.columns = 2
    picture.rows = 1
    picture.pixels = try new f16[8] --- in memory.heap
    for at in 0..<(usize)8:
        picture.pixels[at] = (f16)(0.0 if at < 4 else 1.0)
    defer picture.close()
    try picture.turn(1)
    assert(picture.columns == 1 and picture.rows == 2)
    assert((f64)picture.pixels[0] == 0.0 and (f64)picture.pixels[4] == 1.0)
    try picture.turn(-1)
    assert(picture.columns == 2 and (f64)picture.pixels[0] == 0.0)

func multiply(a: f64[9], b: f64[9]) -> f64[9]:
    var out: f64[9]
    for row in 0..<(usize)3:
        for column in 0..<(usize)3:
            out[row * 3 + column] = a[row * 3] * b[column] + a[row * 3 + 1] * b[3 + column] + a[row * 3 + 2] * b[6 + column]
    return out

## The photo at `path` as a scene no larger than `edge` on its longer side; 0
## is its full size.
pub func open(path: str, edge: usize) -> Scene!:
    let terminated = try strings.copy(path)
    defer strings.release(terminated)
    let read = try files.read((c.str)terminated)
    defer read.release()
    return try from_bytes(read.value, edge)

## The photo whose file is `data` as a scene (see `open`).
pub func from_bytes(data: const u8[], edge: usize) -> Scene!:
    if edge != 0 and edge < 16:
        error(invalid, "a scene needs a size")
    if raw.detect(data):
        var made = try raw_scene(data, edge)
        made.shot_seconds = shutter_of(data)
        return made
    var picture = try source.preview(data, edge if edge > 0 else 65536)
    defer picture.close()
    var scene = Scene(columns = (usize)picture.width(), rows = (usize)picture.height(), as_shot = [1.0, 1.0, 1.0], shot_temperature = 6500.0)
    scene.pixels = try new f16[scene.columns * scene.rows * 4] --- in memory.heap
    errdefer free(scene.pixels) in memory.heap
    var job = Undisplay(bytes = picture.pixels(), pixels = scene.pixels, columns = scene.columns)
    try parallel.for_each(scene.rows, (void*)&job, undisplay_row)
    scene.shot_seconds = shutter_of(data)
    return scene

## How long the photo in `data` was exposed, in seconds, as its EXIF says (a
## sixtieth when it says nothing).
func shutter_of(data: const u8[]) -> f64:
    let found = exif.read(data) catch failure:
        return 1.0 / 60.0
    defer found.release()
    let seconds = found.value.exposure_time
    return seconds if seconds > 0.0 else 1.0 / 60.0

## A display-referred picture's rows into scene light, in parallel.
struct Undisplay:
    var bytes: const u8[]
    var pixels: f16[]
    var columns: usize

func undisplay_row(context: void*, row: usize, worker: usize) -> !:
    let job = (Undisplay*)context
    for column in 0..<job.columns:
        let at = (row * job.columns + column) * 4
        let scene = view.undisplay((f64)job.bytes[at] / 255.0, (f64)job.bytes[at + 1] / 255.0, (f64)job.bytes[at + 2] / 255.0)
        job.pixels[at] = (f16)scene[0]
        job.pixels[at + 1] = (f16)scene[1]
        job.pixels[at + 2] = (f16)scene[2]
        job.pixels[at + 3] = (f16)1.0f32

## The full-size camera values a develop delivers, gathered from its tiles.
struct Gathered:
    var pixels: f32[]
    var width: usize

func gather(context: void*?, tile: const raw.Tile*) -> !:
    let into = (Gathered*)(context else return)
    for row in 0..<tile.height:
        for column in 0..<tile.width:
            let from_at = (row * tile.width + column) * 3
            let to_at = ((tile.y + row) * into.width + tile.x + column) * 3
            into.pixels[to_at] = tile.pixels[from_at]
            into.pixels[to_at + 1] = tile.pixels[from_at + 1]
            into.pixels[to_at + 2] = tile.pixels[from_at + 2]

func raw_scene(data: const u8[], edge: usize) -> Scene!:
    # Half size when it is large enough: each 2×2 filter cell is a pixel, no
    # demosaic needed, and a viewer's fit is rarely larger. Otherwise the whole
    # sensor, demosaiced at its best (AHD, Markesteijn for X-Trans).
    let half_options = raw.Options(camera = true, half = true, exposure = false, quality = .fast)
    let (half_width, half_height) = try raw.dimensions(data, half_options)
    let half_longer = half_width if half_width > half_height else half_height
    let options = half_options if edge > 0 and half_longer * 20 >= edge * 19 else raw.Options(camera = true, exposure = false, quality = .best)
    let (width, height) = try raw.dimensions(data, options)
    var gathered = Gathered(width = width)
    gathered.pixels = try new f32[width * height * 3] in memory.heap
    defer free(gathered.pixels) in memory.heap
    try raw.develop(data, options, (void*)&gathered, gather)
    let shot = try raw.rendering(data)
    var scene = Scene(as_shot = shot.balance.multipliers, shot_temperature = shot.balance.temperature, shot_tint = shot.balance.tint)
    errdefer scene.close()
    scene.response = (try sensitivities(data)).scaled(shot.balance.multipliers)
    scene.data = try new u8[data.length] --- in memory.heap
    memory.copy(scene.data, data, data.length)
    # Average down to the edge in linear light.
    let longer = width if width > height else height
    let columns = width * edge // longer if edge > 0 and longer > edge else width
    let rows = height * edge // longer if edge > 0 and longer > edge else height
    scene.columns = columns if columns > 0 else 1
    scene.rows = rows if rows > 0 else 1
    scene.pixels = try new f16[scene.columns * scene.rows * 4] --- in memory.heap
    for y in 0..<scene.rows:
        let y0 = y * height // scene.rows
        let y1 = math_above(y0, (y + 1) * height // scene.rows)
        for x in 0..<scene.columns:
            let x0 = x * width // scene.columns
            let x1 = math_above(x0, (x + 1) * width // scene.columns)
            var sum: f32[3]
            for sy in y0..<y1:
                for sx in x0..<x1:
                    let at = (sy * width + sx) * 3
                    sum[0] += gathered.pixels[at]
                    sum[1] += gathered.pixels[at + 1]
                    sum[2] += gathered.pixels[at + 2]
            let weight = 1.0f32 / (f32)((x1 - x0) * (y1 - y0))
            let out = (y * scene.columns + x) * 4
            scene.pixels[out] = (f16)(sum[0] * weight)
            scene.pixels[out + 1] = (f16)(sum[1] * weight)
            scene.pixels[out + 2] = (f16)(sum[2] * weight)
            scene.pixels[out + 3] = (f16)1.0f32
    # luce-raw's develop turned it upright already (its size is the turned one).
    return scene

## The spectral sensitivities of the camera that made raw `data`, in its raw
## values: measured (luce_color's camera module) when the camera is known,
## otherwise estimated from its color matrix for daylight (D65). A measured
## camera's channels are scaled to agree with the matrix, so the raw's own
## white balance holds.
func sensitivities(data: const u8[]) -> Response!:
    # The matrix from XYZ under D65 to raw values: luce-raw's rendering for that
    # light takes values balanced for it to sRGB.
    let look = try raw.rendering(data, 6504.0, 0.0)
    let srgb_to_xyz = xyz.rgb_to_xyz(xyz.srgb)
    let to_balanced = xyz.invert(xyz.multiply(srgb_to_xyz, xyz.Matrix3(look.to_srgb))).m
    var to_raw: f64[9]
    for row in 0..<(usize)3:
        for column in 0..<(usize)3:
            to_raw[row * 3 + column] = to_balanced[row * 3 + column] / look.balance.multipliers[row]
    let info = try raw.info(data)
    let kelvins: f64[1] = [6504.0]
    let found = camera.measured(info.make, info.model)
    if found == none:
        return camera.estimate(to_raw, kelvins)
    let measured = found else return camera.estimate(to_raw, kelvins)
    let d65 = spectral.illuminant(6504.0)
    let white = d65.xyz()
    let seen = measured.of(&d65)
    var gains: f64[3]
    for row in 0..<(usize)3:
        let expected = to_raw[row * 3] * white.x + to_raw[row * 3 + 1] * white.y + to_raw[row * 3 + 2] * white.z
        gains[row] = expected / math.max(seen[row], 1.0e-12)
    return measured.scaled(gains)

func math_above(low: usize, value: usize) -> usize:
    return value if value > low else low + 1

test "orientations turn the stored picture upright":
    # A 3 × 2 picture stored as
    #     a b c
    #     d e f
    # Orientation 6 (turn a quarter clockwise) shows it 2 × 3 as
    #     d a
    #     e b
    #     f c
    assert(upright_source(6, 0, 0, 3, 2) == (0, 1) and upright_source(1 + 5, 1, 0, 3, 2) == (0, 0))
    assert(upright_source(6, 0, 2, 3, 2) == (2, 1) and upright_source(6, 1, 2, 3, 2) == (2, 0))
    # Orientation 8 (a quarter counterclockwise) shows c f / b e / a d.
    assert(upright_source(8, 0, 0, 3, 2) == (2, 0) and upright_source(8, 1, 2, 3, 2) == (0, 1))
    # 3 is a half turn; 2 and 4 mirror; 5 and 7 mirror across a diagonal.
    assert(upright_source(3, 0, 0, 3, 2) == (2, 1) and upright_source(2, 0, 1, 3, 2) == (2, 1))
    assert(upright_source(4, 2, 0, 3, 2) == (2, 1) and upright_source(5, 1, 2, 3, 2) == (2, 1))
    assert(upright_source(7, 0, 0, 3, 2) == (2, 1))

## Mid grey through `scene`'s matrix for settings `text`.
func grey_through(scene: const Scene*, text: str) -> f64[3]!:
    let settings = settings_text(text)
    let m = try scene.matrix(&settings)
    let v = 0.18
    return [(m[0] + m[1] + m[2]) * v, (m[3] + m[4] + m[5]) * v, (m[6] + m[7] + m[8]) * v]

test "white balance turns non-raw scenes as it turns raws: warmer above as shot, cooler below":
    let scene = Scene(as_shot = [1.0, 1.0, 1.0], shot_temperature = 6500.0)
    let same = try grey_through(&scene, "temperature=6500;tint=0")
    assert(math.abs(same[0] - 0.18) < 1.0e-9 and math.abs(same[2] - 0.18) < 1.0e-9)
    let warm = try grey_through(&scene, "temperature=9000")
    assert(warm[0] > warm[1] and warm[1] > warm[2])
    let cool = try grey_through(&scene, "temperature=4000")
    assert(cool[2] > cool[1] and cool[1] > cool[0])
    # A positive tint is magenta: green falls below red and blue.
    let magenta = try grey_through(&scene, "temperature=6500;tint=30")
    assert(magenta[1] < magenta[0] and magenta[1] < magenta[2])