Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-color

Source of release 0.8.2

0.8.2 / src / camera.lucb

## Cameras as spectral instruments: how strongly each of a camera's three
## channels responds to light at each wavelength (its spectral sensitivities),
## so that what a camera recorded can be turned into what something else with
## its own spectral response, such as a film emulsion, would have recorded of
## the same scene.
##
## Measured curves come from the Academy's rawtoaces-data (Apache-2.0; 52
## cameras, most measured by Weta Digital in 2025–26; camera_data.lucb, made by
## tools/cameras.py). For any other camera, `estimate` finds plausible curves
## from what every raw file carries: its color matrices, which say how the
## camera responds to colors under one or two lights. The curves are fitted in
## a prior over the measured cameras (each channel's mean shape and its first
## principal components, gains free), following Solomatov and Akkaynak,
## "Spectral Sensitivity Estimation Without a Camera" (ICCP 2023): about 10% of
## the peak off a measured curve, about what two labs measuring one camera
## disagree by. The fit's data are the 190 training reflectances rawtoaces fits
## its matrices to, also here for anyone fitting a mapping from camera values.
from luce_std import math
import xyz
from xyz import XYZ
import spectral
from spectral import Spectrum, samples
import camera_data

## A camera's red, green and blue spectral sensitivities, 81 samples each (380
## to 780 nm every 5 nm), red first.
pub struct Response:
    pub var curves: f64[243]

    ## The camera's three values for light `spectrum`.
    pub func of(spectrum: const Spectrum*) -> f64[3]:
        var out: f64[3] = [0.0, 0.0, 0.0]
        for channel in 0..<(usize)3:
            for at in 0..<samples:
                out[channel] += spectrum.values[at] * self.curves[channel * 81 + at]
        return out

    ## Each channel scaled by `gains`: the same camera with its values
    ## multiplied, as a white balance multiplies them.
    pub func scaled(gains: f64[3]) -> Response:
        var out = Response(curves = self.curves)
        for channel in 0..<(usize)3:
            for at in 0..<samples:
                out.curves[channel * 81 + at] *= gains[channel]
        return out

## The CIE 1931 standard observer as a camera: its values are XYZ.
pub func observer() -> Response:
    var out: Response
    for channel in 0..<(usize)3:
        for at in 0..<samples:
            out.curves[channel * 81 + at] = spectral.observer[at * 3 + channel]
    return out

## The measured curves of camera `make` `model` as raw files name it (EXIF's
## Make and Model), or none. Names are compared ignoring case, spaces, hyphens,
## the maker repeated in the model and the maker's company suffix, with "Mark
## II" and "M2" the same.
pub func measured(make: str, model: str) -> Response?:
    var wanted: u8[64]
    let length = key(make, model, &wanted)
    for at in 0..<camera_data.measured_count:
        var here: u8[64]
        let n = key(camera_data.measured_makes[at], camera_data.measured_models[at], &here)
        if n != length:
            continue
        var same = true
        for k in 0..<n:
            same = same and here[k] == wanted[k]
        if same:
            var out: Response
            for k in 0..<(usize)243:
                out.curves[k] = camera_data.measured_curves[at * 243 + k]
            return out
    return none

## A matching key for `make` and `model` into `out`: the maker's first word,
## then the model's letters and digits without the maker's name, lower case,
## "markii" as "m2" (to "markiv" as "m4"). Its length.
func key(make: str, model: str, out: u8[64]*) -> usize:
    var n: usize = 0
    let maker = make.bytes
    for b in maker:
        if b == ' ' or n >= 16:
            break
        (*out)[n] = lower(b)
        n += 1
    let start = n
    let bytes = model.bytes
    var at: usize = 0
    while at < bytes.length and n < 64:
        let b = lower(bytes[at])
        if (b >= 'a' and b <= 'z') or (b >= '0' and b <= '9'):
            (*out)[n] = b
            n += 1
        at += 1
    # The model repeating the maker ("NIKON D850", "Canon EOS R5"): drop it.
    if n - start >= start and start > 0:
        var repeats = true
        for k in 0..<start:
            repeats = repeats and (*out)[start + k] == (*out)[k]
        if repeats:
            for k in start..<n - start:
                (*out)[k] = (*out)[k + start]
            n -= start
    # "markii" (and iii, iv) as "m2" (m3, m4).
    for (long, short) in [("markiv", "m4"), ("markiii", "m3"), ("markii", "m2")]:
        n = replace(out, n, long, short)
    return n

func lower(b: u8) -> u8:
    return b | 32 if b >= 'A' and b <= 'Z' else b

## `text` (first `n` bytes) with the first `long` replaced by `short`; its length.
func replace(text: u8[64]*, n: usize, long: str, short: str) -> usize:
    let a = long.bytes
    let b = short.bytes
    if n < a.length:
        return n
    for at in 0..<n - a.length + 1:
        var here = true
        for k in 0..<a.length:
            here = here and (*text)[at + k] == a[k]
        if here:
            for k in 0..<b.length:
                (*text)[at + k] = b[k]
            for k in at + a.length..<n:
                (*text)[k - a.length + b.length] = (*text)[k]
            return n - a.length + b.length
    return n

## A camera's curves estimated from its color matrices: `to_camera`'s k-th nine
## values, a matrix row major, take XYZ (its white at Y = 1) to the camera's raw values under light
## `kelvins[k]` (as `spectral.illuminant` makes it). One matrix is enough; two, at
## lights far apart (a DNG's A and D65), pin the curves down better. Each
## channel is its mean shape and principal components, with free weights,
## fitted so the training reflectances under each light give the values the
## matrix says, the components' weights held back a little (ridge) so the
## curves stay camera-like; negative samples are cut to zero.
pub func estimate(to_camera: const f64[], kelvins: const f64[]) -> Response:
    let n = camera_data.basis_size
    var out: Response
    for channel in 0..<(usize)3:
        # Normal equations of the least squares, n × n, accumulated.
        var normal: f64[16]
        var right: f64[4]
        for k in 0..<(usize)16:
            normal[k] = 0.0
        for k in 0..<(usize)4:
            right[k] = 0.0
        var column_norm = 0.0
        for light_at in 0..<kelvins.length:
            let light = spectral.illuminant(kelvins[light_at])
            let m = to_camera[light_at * 9..<light_at * 9 + 9]
            for patch in 0..<camera_data.training_count:
                var lit: Spectrum
                for at in 0..<samples:
                    lit.values[at] = light.values[at] * camera_data.training[patch * 81 + at]
                let seen = lit.xyz()
                let target = m[channel * 3] * seen.x + m[channel * 3 + 1] * seen.y + m[channel * 3 + 2] * seen.z
                var row: f64[4]
                for j in 0..<n:
                    row[j] = lit.dot(basis_row(channel, j))
                for a in 0..<n:
                    for b in 0..<n:
                        normal[a * 4 + b] += row[a] * row[b]
                    right[a] += row[a] * target
        for a in 0..<n:
            column_norm += math.sqrt(normal[a * 4 + a])
        column_norm /= (f64)n
        # Ridge on the components (not the mean shape's weight).
        for j in 1..<n:
            normal[j * 4 + j] += 1.0e-3 * column_norm * column_norm
        let weights = solve(normal, right, n)
        for at in 0..<samples:
            var value = 0.0
            for j in 0..<n:
                value += weights[j] * camera_data.basis[(channel * n + j) * 81 + at]
            out.curves[channel * 81 + at] = math.max(value, 0.0)
    return out

## Basis vector `j` (0 the mean shape) of channel `channel`, as a response.
func basis_row(channel: usize, j: usize) -> f64[81]:
    var out: f64[81]
    let first = (channel * camera_data.basis_size + j) * 81
    for at in 0..<samples:
        out[at] = camera_data.basis[first + at]
    return out

## The solution of the `n` × `n` system (row stride 4) by Gaussian elimination
## with partial pivoting; zeros where it is singular.
func solve(m: f64[16], v: f64[4], n: usize) -> f64[4]:
    var a = m
    var b = v
    for col in 0..<n:
        var pivot = col
        for row in col + 1..<n:
            if math.abs(a[row * 4 + col]) > math.abs(a[pivot * 4 + col]):
                pivot = row
        if math.abs(a[pivot * 4 + col]) < 1.0e-300:
            return [0.0, 0.0, 0.0, 0.0]
        if pivot != col:
            for k in 0..<n:
                let held = a[col * 4 + k]
                a[col * 4 + k] = a[pivot * 4 + k]
                a[pivot * 4 + k] = held
            let held = b[col]
            b[col] = b[pivot]
            b[pivot] = held
        for row in col + 1..<n:
            let f = a[row * 4 + col] / a[col * 4 + col]
            for k in col..<n:
                a[row * 4 + k] -= f * a[col * 4 + k]
            b[row] -= f * b[col]
    var out: f64[4] = [0.0, 0.0, 0.0, 0.0]
    var row = n
    while row > 0:
        row -= 1
        var sum = b[row]
        for k in row + 1..<n:
            sum -= a[row * 4 + k] * out[k]
        out[row] = sum / a[row * 4 + row]
    return out

## How many training reflectances there are, and reflectance `at`.
pub func training_count() -> usize:
    return camera_data.training_count

pub func training(at: usize) -> Spectrum:
    var out: Spectrum
    for k in 0..<samples:
        out.values[k] = camera_data.training[at * 81 + k]
    return out

# mark: Tests =================================================================

test "measured cameras are found under the names their raw files give":
    assert(measured("SONY", "ILCE-7M3") != none)
    assert(measured("NIKON CORPORATION", "NIKON D850") != none)
    assert(measured("Canon", "Canon EOS R5 Mark II") != none)
    assert(measured("Canon", "Canon EOS R5") != none)
    assert(measured("Leica Camera AG", "LEICA M11") == none)

test "a camera estimated from its matrix is close to its measured curves":
    let found = measured("SONY", "ILCE-7M3")
    assert(found != none)
    let truth = found else return
    # The matrix XYZ → camera that the training reflectances under D65 imply
    # (least squares), as a raw converter's profile would give it.
    let light = spectral.illuminant(6504.0)
    var xx: f64[9]
    var xc: f64[9]
    for k in 0..<(usize)9:
        xx[k] = 0.0
        xc[k] = 0.0
    for patch in 0..<training_count():
        var lit = training(patch)
        for at in 0..<samples:
            lit.values[at] *= light.values[at]
        let seen = lit.xyz()
        let values = truth.of(&lit)
        let v: f64[3] = [seen.x, seen.y, seen.z]
        for a in 0..<(usize)3:
            for b in 0..<(usize)3:
                xx[a * 3 + b] += v[a] * v[b]
                xc[a * 3 + b] += v[a] * values[b]
    let inverse = xyz.invert(xyz.Matrix3(xx)).m
    var m: f64[9]
    for row in 0..<(usize)3:
        for col in 0..<(usize)3:
            var sum = 0.0
            for k in 0..<(usize)3:
                sum += inverse[col * 3 + k] * xc[k * 3 + row]
            m[row * 3 + col] = sum
    let kelvins: f64[1] = [6504.0]
    let guess = estimate(m, kelvins)
    # Each channel within 15% of the peak, root mean square.
    for channel in 0..<(usize)3:
        var peak = 0.0
        var sum = 0.0
        for at in 0..<samples:
            peak = math.max(peak, truth.curves[channel * 81 + at])
        for at in 0..<samples:
            let d = guess.curves[channel * 81 + at] - truth.curves[channel * 81 + at]
            sum += d * d
        assert(math.sqrt(sum / (f64)samples) < 0.15 * peak)

test "the observer as a camera sees XYZ":
    let light = spectral.planck(3200.0)
    let values = observer().of(&light)
    assert(math.abs(values[1] - 1.0) < 1.0e-9)