dymokomi/luce-develop
Source of release 0.1.0
## 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])