f67d38b35cc5
lumetri_cube.rs
//! A clip's Color Grading grade sampled on a 3D lattice, for Color Grading's Export .cube (#4127).
//!
//! The lattice is an image of `size³` pixels holding every grid colour as an encoded (display) RGB
//! value, so that running the grade's own CPU effect on it gives the grade of each colour, and the
//! table applied to an ungraded frame matches the render. What a table cannot hold (the vignette
//! and sharpen, which depend on the pixel's place or its neighbours, and the HSL Secondary
//! denoise and blur) is switched off for the sampling and named in the result.
use filmcraft_color::{ColorPipeline, Lut3d};
use filmcraft_project::{EffectInstance, Param, ParamValue, Project};
use filmcraft_time::Tick;
use crate::effects::{self, FxCtx, dec, enc};
use crate::image::Image;
/// The smallest and largest lattice edge: 65³ is the usual largest `.cube` size.
pub const MIN_SIZE: usize = 2;
pub const MAX_SIZE: usize = 65;
/// The sampled table and the parts of the grade a table cannot hold.
pub struct CubeSample {
pub lut: Lut3d,
pub left_out: Vec<&'static str>,
}
fn param_f(e: &EffectInstance, id: &str, t: Tick) -> f64 {
e.f64_at(id, t)
}
fn set(e: &mut EffectInstance, id: &str, v: ParamValue) {
let p = e.params.entry(id.to_string()).or_insert_with(|| Param::new(v.clone()));
p.keyframes.clear();
p.value = v;
}
/// `e` with what a table cannot hold switched off; adds what was on to `left_out`.
fn tabulable(e: &EffectInstance, t: Tick, left_out: &mut Vec<&'static str>) -> EffectInstance {
let mut e = e.clone();
let on = |e: &EffectInstance, id: &str, default: bool| e.param(id).and_then(|p| p.value.as_bool()).unwrap_or(default);
let mut note = |name: &'static str| {
if !left_out.contains(&name) {
left_out.push(name);
}
};
if on(&e, "vignette_on", true) && param_f(&e, "vignette_amount", t).abs() > 1e-4 {
note("Vignette");
}
set(&mut e, "vignette_on", ParamValue::Bool(false));
if on(&e, "creative_on", true) && param_f(&e, "sharpen", t).abs() > 1e-3 {
note("Sharpen");
}
set(&mut e, "sharpen", ParamValue::Float(0.0));
if on(&e, "hsl_on", false) && (param_f(&e, "hsl_denoise", t) > 0.0 || param_f(&e, "hsl_blur", t) > 0.0) {
note("HSL Secondary Denoise and Blur");
}
set(&mut e, "hsl_denoise", ParamValue::Float(0.0));
set(&mut e, "hsl_blur", ParamValue::Float(0.0));
e
}
/// Sample the Color Grading effects `effects` (in order; disabled ones are skipped) at effect time `t`
/// on a `size³` lattice in the sequence's output encoding. Only Rec. 709 sequences without wide
/// gamut are supported: the HDR and wide-gamut pipelines grade in another signal.
pub fn sample_lumetri(
effects: &[&EffectInstance],
project: Option<&Project>,
t: Tick,
frame_rate: f64,
pipe: &ColorPipeline,
size: usize,
title: &str,
) -> Result<CubeSample, String> {
if !pipe.is_plain() {
return Err("a .cube can be exported from a Rec. 709 sequence without wide gamut; the sequence's color settings use another pipeline".into());
}
if !(MIN_SIZE..=MAX_SIZE).contains(&size) {
return Err(format!("`size` must be between {MIN_SIZE} and {MAX_SIZE}"));
}
if effects.iter().any(|e| e.enabled && e.effect == "lumetri" && !e.masks.is_empty()) {
return Err("Color Grading with masks cannot be exported to a LUT: a LUT has no spatial input".into());
}
let mut left_out = Vec::new();
let graded: Vec<EffectInstance> = effects.iter().filter(|e| e.enabled && e.effect == "lumetri").map(|e| tabulable(e, t, &mut left_out)).collect();
// one row of `size` pixels per (g, b): red runs fastest, as in a .cube
let mut img = Image::new(size, size * size);
if img.px.len() != size * size * size * 4 {
return Err("the lattice is too large".into());
}
let n = (size - 1) as f32;
for (i, px) in img.px.as_chunks_mut::<4>().0.iter_mut().enumerate() {
let (r, g, b) = (i % size, (i / size) % size, i / (size * size));
let lin = dec([r as f32 / n, g as f32 / n, b as f32 / n]);
px.copy_from_slice(&[lin[0], lin[1], lin[2], 1.0]);
}
let cx = FxCtx {
t,
px_scale: 1.0,
mask_scale: 1.0,
seconds: 0.0,
timecode: "",
clip_name: "",
project,
env: None,
frame_rate: if frame_rate.is_finite() && frame_rate > 0.0 { frame_rate } else { 24.0 },
working: pipe.working,
};
for e in &graded {
effects::apply(&mut img, e, &cx);
}
let mut data = Vec::with_capacity(size * size * size);
for p in img.px.as_chunks::<4>().0 {
if !p.iter().all(|v| v.is_finite()) {
return Err("the grade gives a value that is not a number".into());
}
data.push(enc([p[0], p[1], p[2]]).map(|v| v.clamp(0.0, 1.0)));
}
Ok(CubeSample { lut: Lut3d { title: title.to_string(), size, domain_min: [0.0; 3], domain_max: [1.0; 3], data }, left_out })
}
#[cfg(test)]
mod tests {
use super::*;
use filmcraft_project::find_effect;
fn lumetri(params: &[(&str, ParamValue)]) -> EffectInstance {
let mut e = find_effect("lumetri").expect("lumetri").instance();
for (k, v) in params {
set(&mut e, k, v.clone());
}
e
}
fn sample(e: &[&EffectInstance], size: usize) -> CubeSample {
sample_lumetri(e, None, Tick::ZERO, 24.0, &ColorPipeline::REC709, size, "t").expect("sample")
}
#[test]
fn an_ungraded_lumetri_is_the_identity_table() {
let e = lumetri(&[]);
let s = sample(&[&e], 9);
let id = Lut3d::identity(9);
let worst = s.lut.data.iter().zip(&id.data).flat_map(|(a, b)| (0..3).map(move |k| (a[k] - b[k]).abs())).fold(0.0, f32::max);
assert!(worst < 1.0 / 255.0, "worst error {worst}");
assert!(s.left_out.is_empty());
}
/// The table applied to a colour gives what the effect gives it.
#[test]
fn the_table_applied_to_a_frame_gives_the_render() {
let e = lumetri(&[
("exposure", ParamValue::Float(0.6)),
("contrast", ParamValue::Float(25.0)),
("saturation", ParamValue::Float(130.0)),
("temperature", ParamValue::Float(20.0)),
]);
let s = sample(&[&e], 33);
let cx = FxCtx {
t: Tick::ZERO,
px_scale: 1.0,
mask_scale: 1.0,
seconds: 0.0,
timecode: "",
clip_name: "",
project: None,
env: None,
frame_rate: 24.0,
working: ColorPipeline::REC709.working,
};
let mut worst = 0.0f32;
for c in [[0.1, 0.2, 0.3], [0.5, 0.5, 0.5], [0.9, 0.4, 0.2], [0.25, 0.75, 0.6], [0.05, 0.05, 0.9]] {
let lin = dec(c);
let mut img = Image::filled(1, 1, [lin[0], lin[1], lin[2], 1.0]);
effects::apply(&mut img, &e, &cx);
let want = enc([img.px[0], img.px[1], img.px[2]]);
let got = s.lut.apply(c);
worst = (0..3).map(|k| (want[k].clamp(0.0, 1.0) - got[k]).abs()).fold(worst, f32::max);
}
assert!(worst < 3.0 / 255.0, "worst error {worst}");
// and it is a real grade: the table is not the identity
assert!((s.lut.apply([0.5, 0.5, 0.5])[0] - 0.5).abs() > 0.02);
}
#[test]
fn what_a_table_cannot_hold_is_left_out_and_named() {
let e = lumetri(&[("vignette_amount", ParamValue::Float(-1.5)), ("sharpen", ParamValue::Float(40.0)), ("exposure", ParamValue::Float(0.5))]);
let s = sample(&[&e], 5);
assert_eq!(s.left_out, ["Vignette", "Sharpen"]);
// the corners are graded like the centre: the vignette is not in the table
let plain = lumetri(&[("exposure", ParamValue::Float(0.5))]);
assert_eq!(s.lut.data, sample(&[&plain], 5).lut.data);
// a vignette that is switched off or at zero is not named
let off = lumetri(&[("vignette_amount", ParamValue::Float(-1.5)), ("vignette_on", ParamValue::Bool(false))]);
assert!(sample(&[&off], 5).left_out.is_empty());
}
#[test]
fn disabled_effects_are_skipped_and_hostile_sizes_are_refused() {
let mut e = lumetri(&[("exposure", ParamValue::Float(2.0))]);
e.enabled = false;
let s = sample(&[&e], 5);
let id = Lut3d::identity(5);
let worst = s.lut.data.iter().zip(&id.data).flat_map(|(a, b)| (0..3).map(move |k| (a[k] - b[k]).abs())).fold(0.0, f32::max);
assert!(worst < 1.0 / 255.0, "a disabled Color Grading grades nothing: {worst}");
for bad in [0, 1, MAX_SIZE + 1, usize::MAX] {
assert!(sample_lumetri(&[&e], None, Tick::ZERO, 24.0, &ColorPipeline::REC709, bad, "t").is_err(), "{bad}");
}
let wide = ColorPipeline { wide_gamut: true, ..ColorPipeline::REC709 };
assert!(sample_lumetri(&[&e], None, Tick::ZERO, 24.0, &wide, 5, "t").is_err());
}
}
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.