5a24289898fd
light_v3.rs
//! Process V4's Contrast and Blacks on the camera-look path (a raw with its camera's tone
//! curve): pointwise operators fitted to how Lightroom's sliders move a photo's tones, applied
//! after the camera curve with V2 Whites. Method, operator family and the fitted constants' provenance:
//! `docs/light-v3.md`; the constants are in [`crate::light_v3_params`] (generated).
//!
//! Each slider is an operator `F_a` on encoded values `v` (linear ProPhoto RGB, D50, Bradford from
//! the D65 working space, through the sRGB transfer curve), anchored at `F_0` = identity:
//!
//! - `a > 0`: `F_a(v) = v + s(a)·D₊(v)`; `a < 0`: `F_a(v) = max(0, v − s(a)·D₋(v))`, with `D` piecewise
//! linear on 12 fixed knots (`D(1) = 0`, and for Contrast `D(0) = 0`) and the amount law
//! `s(t) = ((1 − e^(−t/τ)) / (1 − e^(−1/τ)))^q`, `t = |a|/100`, one `(τ, q)` per sign;
//! - applied per channel ([`Mode::PerChannel`]), to the encoded ProPhoto luminance with linear RGB
//! scaled by the luminance ratio ([`Mode::Luminance`]), or a blend of the two in linear light
//! ([`Mode::Mix`], one weight per sign).
//!
//! The functions here port `Family.curve`, `Family.apply`, `Family.law` of
//! `fit_pointwise.py` (the fitting tool) exactly; [`Fit::unpack`] is its `Family.unpack`. Each
//! active operator is tabulated once per render ([`LUT_N`] entries over `v` in 0..1, interpolated
//! linearly). High-bit-depth CPU exports and the GPU read these tables ([`LightOps`]); 8-bit CPU
//! renders compose per-channel operations over linear input ([`PreviewOps`]). Luminance operations
//! retain the original evaluation, including any preceding per-channel operation.
use lightcraft_color::{Mat3, PROPHOTO, REC2020};
use lightcraft_develop::{DevelopSettings, Process};
use crate::SourceInfo;
use crate::light_v3_params as fitted;
/// Entries of an operator's table over encoded `v` in 0..=1.
pub const LUT_N: usize = 1024;
/// Linear ProPhoto RGB luminance (the Y row of ProPhoto → XYZ D50), as the fit computes it.
pub const PRO_Y: [f32; 3] = [0.288_040_2, 0.711_874_1, 0.000_085_7];
/// How an operator is applied to a pixel.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Mode {
/// To each encoded ProPhoto channel.
PerChannel,
/// To the encoded ProPhoto luminance; linear RGB is scaled by the luminance ratio.
Luminance,
/// `w·PerChannel + (1 − w)·Luminance` in linear light, with a weight per sign.
Mix,
}
impl Mode {
/// The GPU kernel's code (`LIGHT_MODE` in `crates/gpu/src/params.rs`).
pub fn code(self) -> u32 {
match self {
Mode::PerChannel => 0,
Mode::Luminance => 1,
Mode::Mix => 2,
}
}
}
/// One slider's fitted parameters, laid out as `fit_pointwise.py`'s `Family`: 11 values of `D₊` at
/// the knots but the last (`D(1) = 0`), 11 of `D₋`, then `ln τ₊, ln q₊, ln τ₋, ln q₋`, then two mix
/// logits (positive, negative amounts) in [`Mode::Mix`].
#[derive(Clone, Copy, Debug)]
pub struct Fit {
pub mode: Mode,
/// Contrast moves tones both ways around a pivot: its shapes are anchored at black too (`D(0) = 0`).
pub signed: bool,
pub params: &'static [f64],
}
const KNOTS_N: usize = fitted::KNOTS.len();
/// A [`Fit`] unpacked (`Family.unpack`).
#[derive(Clone, Copy, Debug)]
pub struct Unpacked {
pub d_pos: [f64; KNOTS_N],
pub d_neg: [f64; KNOTS_N],
/// `(τ, q)` of the amount law, positive and negative amounts.
pub law_pos: (f64, f64),
pub law_neg: (f64, f64),
/// Mix weights of the per-channel result for positive and negative amounts (1 outside [`Mode::Mix`]).
pub weights: (f64, f64),
}
fn sigmoid(x: f64) -> f64 {
1.0 / (1.0 + (-x).exp())
}
impl Fit {
/// The parameters unpacked; `None` when their number doesn't fit the layout.
pub fn unpack(&self) -> Option<Unpacked> {
let n = KNOTS_N - 1;
let p = self.params;
let mix = self.mode == Mode::Mix;
let len = 2 * n + 4 + if mix { 2 } else { 0 };
if p.len() != len {
return None;
}
// D(1) = 0 is appended (the last knot stays 0)
let shape = |off: usize| -> Option<[f64; KNOTS_N]> {
let mut d = [0.0; KNOTS_N];
for (k, slot) in d.iter_mut().take(n).enumerate() {
*slot = *p.get(off + k)?;
}
Some(d)
};
let (mut d_pos, mut d_neg) = (shape(0)?, shape(n)?);
if self.signed {
d_pos[0] = 0.0;
d_neg[0] = 0.0;
}
let at = |i: usize| p.get(i).copied();
let i = 2 * n;
let law_pos = (at(i)?.exp(), at(i + 1)?.exp());
let law_neg = (at(i + 2)?.exp(), at(i + 3)?.exp());
let weights = if mix { (sigmoid(at(i + 4)?), sigmoid(at(i + 5)?)) } else { (1.0, 1.0) };
Some(Unpacked { d_pos, d_neg, law_pos, law_neg, weights })
}
}
/// The amount law `s(t)` (`Family.law`): 1 at `|a| = 100`, linear as `τ` grows, saturating as it
/// shrinks.
pub fn law((tau, q): (f64, f64), a: f64) -> f64 {
let t = (a.abs() / 100.0).min(1.0);
let tau = tau.clamp(1e-3, 1e3);
((1.0 - (-t / tau).exp()) / (1.0 - (-1.0 / tau).exp())).powf(q)
}
/// `numpy.interp(v, KNOTS, d)`: piecewise linear, constant beyond the ends.
fn interp(v: f64, d: &[f64; KNOTS_N]) -> f64 {
let k = &fitted::KNOTS;
if v <= k[0] {
return d[0];
}
for i in 1..KNOTS_N {
if v <= k[i] {
let t = (v - k[i - 1]) / (k[i] - k[i - 1]);
return d[i - 1] + t * (d[i] - d[i - 1]);
}
}
d[KNOTS_N - 1]
}
impl Unpacked {
/// `F_a(v)` on an encoded value (`Family.curve`).
pub fn curve(&self, a: f64, v: f64) -> f64 {
if a == 0.0 {
return v;
}
if a > 0.0 {
return v + law(self.law_pos, a) * interp(v, &self.d_pos);
}
(v - law(self.law_neg, a) * interp(v, &self.d_neg)).max(0.0)
}
}
/// One slider's operator at one amount, tabulated: `lut[i]` is the *linear* value of
/// `F_a(i / (LUT_N − 1))` (decoded with the sRGB curve), made non-decreasing (see [`Operator::new`]).
#[derive(Clone, Debug)]
pub struct Operator {
pub mode: Mode,
/// Weight of the per-channel result ([`Mode::Mix`]; 1 for per channel, 0 for luminance).
pub weight: f32,
pub lut: Box<[f32; LUT_N]>,
}
impl Operator {
/// `fit` at `amount` (-100..100); `None` at 0 (the identity) or for parameters that do not unpack.
///
/// The table is the running maximum of `F_a`: where a fitted shape folds back (a `D` rising
/// faster than 1), it is flat instead, so no two tones swap. None of the shipped fits folds.
/// The fitting tool inverts `F` the same way.
pub fn new(fit: &Fit, amount: f64) -> Option<Operator> {
let a = if amount.is_finite() { amount.clamp(-100.0, 100.0) } else { 0.0 };
if a == 0.0 {
return None;
}
let u = fit.unpack()?;
let weight = match fit.mode {
Mode::PerChannel => 1.0,
Mode::Luminance => 0.0,
Mode::Mix => (if a > 0.0 { u.weights.0 } else { u.weights.1 }) as f32,
};
let mut lut = Box::new([0.0f32; LUT_N]);
let mut top = 0.0f64;
for (i, slot) in lut.iter_mut().enumerate() {
let v = i as f64 / (LUT_N - 1) as f64;
top = top.max(u.curve(a, v));
*slot = srgb_decode(top) as f32;
}
// The negative Blacks fit rounds to exactly 1 in f32. Avoid calculating a luminance
// result that contributes nothing, on both CPU and GPU.
let mode = if weight == 1.0 {
Mode::PerChannel
} else if weight == 0.0 {
Mode::Luminance
} else {
Mode::Mix
};
Some(Operator { mode, weight, lut })
}
/// The table at encoded `v` (clamped to 0..=1), interpolated: linear output.
#[inline]
pub fn eval(&self, v: f32) -> f32 {
let f = v.clamp(0.0, 1.0) * (LUT_N - 1) as f32;
let i = (f as usize).min(LUT_N - 2);
let t = f - i as f32;
self.lut[i] + (self.lut[i + 1] - self.lut[i]) * t
}
/// One linear value through the operator: values above 1 (HDR renders) pass unchanged, which
/// is continuous because `F_a(1) = 1`; values below 0 (outside ProPhoto's gamut) keep their
/// distance below the image of 0, `F_a(0) + x` (continuous and increasing). This is the
/// per-channel domain: on luminance ([`Self::apply`]) a component above 1 is scaled with its
/// pixel unless the pixel's luminance is above 1.
#[inline]
pub fn channel(&self, x: f32, encode: &impl Fn(f32) -> f32) -> f32 {
if x > 1.0 {
x
} else if x < 0.0 {
self.lut[0] + x
} else {
self.eval(encode(x))
}
}
/// The luminance mode: linear ProPhoto `p` scaled by `F` of its luminance over its luminance
/// (unchanged when the luminance is at most 1e-6, or above 1).
#[inline]
fn luminance(&self, p: [f32; 3], encode: &impl Fn(f32) -> f32) -> [f32; 3] {
let y = PRO_Y[0] * p[0] + PRO_Y[1] * p[1] + PRO_Y[2] * p[2];
if y.is_nan() || y <= 1e-6 || y > 1.0 {
return p;
}
let r = self.channel(y, encode) / y;
p.map(|c| c * r)
}
/// The operator on a linear ProPhoto pixel (`Family.apply`). Per channel, each component goes
/// through [`Self::channel`] (one above 1 passes unchanged). On luminance, the pixel is scaled
/// by `F(Y) / Y` as a whole, components above 1 included, and passes unchanged only when `Y`
/// itself is above 1 (or at most 1e-6). Mix blends the two results in linear light, so an HDR
/// component of a pixel with `Y ≤ 1` moves by the luminance part's share.
#[inline]
pub fn apply(&self, p: [f32; 3], encode: &impl Fn(f32) -> f32) -> [f32; 3] {
match self.mode {
Mode::PerChannel => p.map(|c| self.channel(c, encode)),
Mode::Luminance => self.luminance(p, encode),
Mode::Mix => {
let (a, b) = (p.map(|c| self.channel(c, encode)), self.luminance(p, encode));
let w = self.weight;
std::array::from_fn(|k| w * a[k] + (1.0 - w) * b[k])
}
}
}
}
/// sRGB decoding in f64 (the tables are built in f64, like the fit).
fn srgb_decode(e: f64) -> f64 {
if e <= 0.04045 { e / 12.92 } else { ((e + 0.055) / 1.055).powf(2.4) }
}
/// Linear Rec.2020 (the working space) → linear ProPhoto RGB (D50, Bradford), and back.
pub fn prophoto_matrices() -> ([[f32; 3]; 3], [[f32; 3]; 3]) {
let to = REC2020.to_space(&PROPHOTO);
let from = to.inverse().unwrap_or(Mat3::IDENTITY);
(to.to_f32(), from.to_f32())
}
/// The active operators of a render, in order (Contrast, Blacks), and the conversions to
/// and from the space they work in. Applied after the tone map, chroma scaling and highlight
/// desaturation, before the colour stage (`finish::finish_with`, the GPU's `finish.wgsl`).
#[derive(Clone, Debug)]
pub struct LightOps {
pub ops: Vec<Operator>,
pub to_pro: [[f32; 3]; 3],
pub from_pro: [[f32; 3]; 3],
}
/// The fits of Contrast and Blacks, in the order they apply.
pub const FITS: [&Fit; 2] = [&fitted::CONTRAST, &fitted::BLACKS];
/// Whether `s` renders `info` with the V4 operators: process V4 or later and a raw with its camera's tone
/// curve (other sources keep the tone map's own Contrast and Blacks).
pub fn applies(s: &DevelopSettings, info: &SourceInfo) -> bool {
let camera_look = info.raw && info.camera_tone.is_some();
match s.process.process() {
Process::V1 | Process::V2 | Process::V3 => false,
Process::V4 | Process::V5 | Process::V6 | Process::V7 | Process::V8 => camera_look,
}
}
impl LightOps {
/// The operators of `s` for `info` (see [`applies`]); `None` when they don't apply or every
/// slider is at 0.
pub fn new(s: &DevelopSettings, info: &SourceInfo) -> Option<LightOps> {
if !applies(s, info) {
return None;
}
let l = &s.light;
let ops: Vec<Operator> = FITS.iter().zip([l.contrast, l.blacks]).filter_map(|(f, a)| Operator::new(f, a)).collect();
if ops.is_empty() {
return None;
}
let (to_pro, from_pro) = prophoto_matrices();
Some(LightOps { ops, to_pro, from_pro })
}
/// The operators on a linear Rec.2020 pixel; `encode`: linear → sRGB-encoded on 0..1 (the
/// exact curve or the shared table, as the render encodes).
#[inline]
pub fn apply(&self, d: [f32; 3], encode: &impl Fn(f32) -> f32) -> [f32; 3] {
let mut p = mul3(&self.to_pro, d);
for op in &self.ops {
p = op.apply(p, encode);
}
mul3(&self.from_pro, p)
}
}
/// Number of intervals over linear input for 8-bit CPU renders. Deep exports retain [`LightOps`]
/// with the exact sRGB encoder; this approximation is not used for U16 or F32 samples.
const PREVIEW_INTERVALS: usize = 16_384;
/// An operator with its sRGB encoding and decoding included in one linear-input table.
struct LinearOperator {
black: f32,
white: f32,
// Each linear interval stores [intercept, slope], so a lookup needs no integer-to-float
// conversion or subtraction of neighbouring samples in the pixel loop.
segments: Box<[[f32; 2]; PREVIEW_INTERVALS]>,
}
impl LinearOperator {
fn new(channel: impl Fn(f32) -> f32) -> Self {
let black = channel(0.0);
let mut previous = black;
let mut segments = Box::new([[0.0; 2]; PREVIEW_INTERVALS]);
for (i, segment) in segments.iter_mut().enumerate() {
let next = channel((i + 1) as f32 / PREVIEW_INTERVALS as f32);
let slope = (next - previous) * PREVIEW_INTERVALS as f32;
let intercept = (previous as f64 - slope as f64 * (i as f64 / PREVIEW_INTERVALS as f64)) as f32;
*segment = [intercept, slope];
previous = next;
}
Self { black, white: previous, segments }
}
#[inline(always)]
fn channel(&self, x: f32) -> f32 {
if x >= 1.0 {
if x == 1.0 { self.white } else { x }
} else if x < 0.0 {
self.black + x
} else {
let f = x * PREVIEW_INTERVALS as f32;
let i = (f as u32).min(PREVIEW_INTERVALS as u32 - 1) as usize;
let [intercept, slope] = self.segments[i];
intercept + slope * x
}
}
}
/// CPU preview tables for per-channel operations, built once per render. Luminance operations
/// use [`LightOps`] instead, so interpolation cannot change a nearly cancelling luminance sum.
pub(crate) struct PreviewOps {
ops: PreviewOperators,
to_pro: [[f32; 4]; 3],
from_pro: [[f32; 4]; 3],
}
enum PreviewOperators {
PerChannel(LinearOperator),
Separate(Vec<LinearOperator>),
}
impl PreviewOps {
pub(crate) fn new(exact: &LightOps, encode: &impl Fn(f32) -> f32) -> Option<Self> {
let ops = &exact.ops;
// Small per-channel errors can cross the luminance cutoff at 1e-6, or be amplified
// by F(Y) / Y. Keep every preceding operation exact too, including Contrast.
if ops.iter().any(|o| o.mode != Mode::PerChannel) {
return None;
}
// A preceding black lift could carry a negative input across zero. Only fuse when
// preceding operators fix zero, so the composed negative extension remains F(0) + x.
// Contrast fixes zero and negative Blacks is per channel, so their usual pair fuses.
let fuse = ops.iter().take(ops.len().saturating_sub(1)).all(|o| o.lut[0] == 0.0);
let ops = if fuse {
PreviewOperators::PerChannel(LinearOperator::new(|x| ops.iter().fold(x, |x, o| o.channel(x, encode))))
} else {
PreviewOperators::Separate(ops.iter().map(|o| LinearOperator::new(|x| o.channel(x, encode))).collect())
};
let columns = |m: [[f32; 3]; 3]| std::array::from_fn(|i| [m[0][i], m[1][i], m[2][i], 0.0]);
Some(Self { ops, to_pro: columns(exact.to_pro), from_pro: columns(exact.from_pro) })
}
// Keep the single-table path in the finish loop. An out-of-line call per pixel saves
// little code here but adds register spills to this otherwise small operation.
#[inline(always)]
pub(crate) fn apply(&self, d: [f32; 3]) -> [f32; 3] {
let mut p = mul_preview(&self.to_pro, d);
match &self.ops {
PreviewOperators::PerChannel(op) => p = [op.channel(p[0]), op.channel(p[1]), op.channel(p[2])],
PreviewOperators::Separate(ops) => {
for op in ops {
p = p.map(|c| op.channel(c));
}
}
}
mul_preview(&self.from_pro, p)
}
}
/// Padded columns let the compiler multiply the RGB rows together in vector registers.
/// The fourth lane is unused; each RGB row keeps the same arithmetic order as `mul3`.
#[inline(always)]
fn mul_preview(m: &[[f32; 4]; 3], d: [f32; 3]) -> [f32; 3] {
let out: [f32; 4] = std::array::from_fn(|i| m[0][i] * d[0] + m[1][i] * d[1] + m[2][i] * d[2]);
[out[0], out[1], out[2]]
}
#[inline]
fn mul3(m: &[[f32; 3]; 3], d: [f32; 3]) -> [f32; 3] {
[
m[0][0] * d[0] + m[0][1] * d[1] + m[0][2] * d[2],
m[1][0] * d[0] + m[1][1] * d[1] + m[1][2] * d[2],
m[2][0] * d[0] + m[2][1] * d[1] + m[2][2] * d[2],
]
}
/// `fit_pointwise.py`'s own values for one fit at one amount (generated into
/// [`crate::light_v3_params`]; the tests check the port against them).
#[cfg(test)]
pub struct Reference {
pub amount: f64,
/// `Family.curve` at `light_v3_params::REF_V`.
pub curve: &'static [f64],
/// `Family.apply` on `light_v3_params::REF_PIX` (encoded ProPhoto), where the curve increases.
pub apply: Option<&'static [[f64; 3]]>,
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.