Files
craft-libs/crates/cms/src/lutfile.rs
T
aiongg dffc61a7e0 Merge storytold main 832883b5 (sync 16 Nov)
961 upstream commits since 7bb6c900. Resolutions:
- Test-only conflicts: upstream tests from before the base that our side
  cut stay cut; tests new upstream are kept (audio aac/config, layout,
  encode_format; cms lutfile; media mux; print windows_native, ticket;
  update self_update; xml hostile).
- Code our side moved, with upstream's change carried to the new place:
  craft-media mux roll sample groups (mux/boxes.rs) and writer-start
  offsets with overflow checks (mux/progressive.rs); craft-print's
  shrink-to-fit scale guard (sheets/plan.rs); craft-update's nextest
  archive detection (self_update/detect.rs); craft-vectorcraft-format's
  Tail::write_to_with (container.rs); craft-i18n's pedantic fixes
  (bidi.rs, negotiation.rs).
- craft-ui: the old crate's modules stay removed; gpu_test_lock guarded
  their per-test wgpu renderers, which the snapshot kit does not have.
- New upstream tests in crates that build their integration tests into
  the library's test executable are modules of tests/main.rs (audio
  flac_decode and qoa_oracle, cms, docpath, pcraft-format,
  vectorcraft-format).
- The 22 new crates are optional members of the craft facade.
2026-11-16 01:52:09 +00:00

1367 lines
66 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Creative 3D LUT files for Image › Adjustments › Color Lookup: `.cube` (Adobe/Resolve), `.3dl`
//! (Autodesk Lustre / Flame) and `.look` (SpeedGrade XML), plus a few generated (CC0) looks.
//!
//! Every table is normalised to [`LutFile`]: `size`³ RGB triplets in 0..=1, **red varying
//! fastest** (`((b·size + g)·size + r)·3`). Formats follow their public descriptions: the Adobe
//! "Cube LUT Specification 1.0", the Lustre 3DL layout as documented by OpenColorIO, and the
//! SpeedGrade `.look` XML (hex-encoded little-endian float32 RGB triplets).
/// A parsed 3D LUT.
#[derive(Clone, Debug, PartialEq)]
pub struct LutFile {
/// Title from the file, or empty when it has none.
pub title: String,
/// Edge length of the cube: the table has `size` points per axis.
pub size: usize,
/// `size`³ × 3 values, red fastest.
pub data: Vec<f32>,
/// The input domain the table expects (`.cube` `DOMAIN_MIN`/`DOMAIN_MAX`,
/// `LUT_3D_INPUT_RANGE`): an input `c` samples the table at `(c - min) / (max - min)`,
/// saturating outside. `[0, 1]` is the identity default; applying a table with any other
/// domain is rejected upstream until Color Lookup carries it through.
pub domain_min: [f32; 3],
/// Upper end of the input domain per channel; see [`domain_min`](Self::domain_min).
pub domain_max: [f32; 3],
}
/// Largest edge length accepted (64³ is Photoshop's practical maximum; 129 leaves headroom while
/// keeping the GPU table within texture limits).
pub const MAX_SIZE: usize = 129;
/// Why a LUT file could not be read; the string is a message for the user.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct LutError(pub String);
impl std::fmt::Display for LutError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.0)
}
}
impl std::error::Error for LutError {}
fn err<T>(msg: impl Into<String>) -> Result<T, LutError> {
Err(LutError(msg.into()))
}
fn checked_data_len(size: usize) -> Result<(usize, usize), LutError> {
if !(2..=MAX_SIZE).contains(&size) {
return err(format!("unsupported LUT size {size}"));
}
let entries = size.checked_pow(3).ok_or_else(|| LutError(format!("unsupported LUT size {size}")))?;
let data_len = entries.checked_mul(3).ok_or_else(|| LutError(format!("unsupported LUT size {size}")))?;
Ok((entries, data_len))
}
impl LutFile {
/// The identity table of edge `size` (2 to [`MAX_SIZE`]).
pub fn identity(size: usize) -> Result<Self, LutError> {
Self::from_fn("Identity", size, |c| c)
}
/// Samples `f` on an `size`³ grid, `size` from 2 to [`MAX_SIZE`].
pub fn from_fn(title: &str, size: usize, f: impl Fn([f32; 3]) -> [f32; 3]) -> Result<Self, LutError> {
let (_, data_len) = checked_data_len(size)?;
let m = (size - 1) as f32;
let mut data = Vec::with_capacity(data_len);
for b in 0..size {
for g in 0..size {
for r in 0..size {
let o = f([r as f32 / m, g as f32 / m, b as f32 / m]);
data.extend(o.map(|v| v.clamp(0.0, 1.0)));
}
}
}
Ok(LutFile { title: title.to_string(), size, data, domain_min: [0.0; 3], domain_max: [1.0; 3] })
}
/// Whether the table expects plain 0..1 inputs (the common case; Photoshop's default).
pub fn domain_is_default(&self) -> bool {
self.domain_min == [0.0, 0.0, 0.0] && self.domain_max == [1.0, 1.0, 1.0]
}
fn check(self) -> Result<Self, LutError> {
let (entries, data_len) = checked_data_len(self.size)?;
if self.data.len() != data_len {
return err(format!("expected {entries} entries, found {}", self.data.len() / 3));
}
if self.data.iter().any(|v| !v.is_finite()) {
return err("non-finite LUT value");
}
Ok(self)
}
}
/// A LUT file format.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Format {
Cube,
ThreeDl,
Look,
}
impl Format {
/// The format [`parse`] reads `bytes` as: from `file_name`'s extension, else sniffed
/// (XML is `.look`, anything else `.cube`).
pub fn detect(file_name: &str, bytes: &[u8]) -> Self {
let lower = file_name.to_ascii_lowercase();
if lower.ends_with(".3dl") {
Format::ThreeDl
} else if lower.ends_with(".look") || decode_text(bytes).trim_start().starts_with('<') {
Format::Look
} else {
Format::Cube
}
}
/// The file extension, without the dot.
pub fn extension(self) -> &'static str {
match self {
Format::Cube => "cube",
Format::ThreeDl => "3dl",
Format::Look => "look",
}
}
}
/// Parses a LUT, picking the format from `file_name`'s extension (falls back to sniffing).
pub fn parse(file_name: &str, bytes: &[u8]) -> Result<LutFile, LutError> {
parse_as(Format::detect(file_name, bytes), bytes)
}
/// Parses a LUT in a known format.
pub fn parse_as(format: Format, bytes: &[u8]) -> Result<LutFile, LutError> {
let text = decode_text(bytes);
match format {
Format::Cube => parse_cube(&text),
Format::ThreeDl => parse_3dl(&text),
Format::Look => parse_look(&text),
}
}
/// UTF-16 with a byte-order mark (Photoshop loads such `.look` files, #9118), else UTF-8
/// (a UTF-8 BOM is stripped).
fn decode_text(bytes: &[u8]) -> std::borrow::Cow<'_, str> {
let utf16 = |rest: &[u8], from: fn([u8; 2]) -> u16| {
let units: Vec<u16> = rest.as_chunks::<2>().0.iter().map(|&c| from(c)).collect();
String::from_utf16_lossy(&units).into()
};
match bytes {
[0xFF, 0xFE, rest @ ..] => utf16(rest, u16::from_le_bytes),
[0xFE, 0xFF, rest @ ..] => utf16(rest, u16::from_be_bytes),
[0xEF, 0xBB, 0xBF, rest @ ..] => String::from_utf8_lossy(rest),
_ => String::from_utf8_lossy(bytes),
}
}
/// A bounded, three-dimensional Cube profile with RGB rows in file order.
/// Unlike [`parse_cube`], this preserves the optional title and does not resample 1D curves.
#[derive(Clone, Debug, PartialEq)]
pub struct Cube3d {
pub title: Option<String>,
pub size: usize,
pub data: Vec<[f32; 3]>,
pub domain_min: [f32; 3],
pub domain_max: [f32; 3],
}
/// Read the simple 3D profile dialect used by camera-profile consumers.
///
/// `max_size` must be in 2..=256; the row budget is checked before each allocation.
/// Whole-line comments and literal titles are preserved. Unknown alphabetic directives
/// are ignored; 1D tables are refused. Finite domains are returned unchanged so the
/// consumer retains its existing policy for equal or reversed endpoints.
/// Numeric fields must consist of exactly three finite numbers (never silently skip tokens).
pub fn parse_cube_3d(text: &str, max_size: usize) -> Result<Cube3d, LutError> {
let p = read_cube(text, Some(max_size))?;
if p.size3 == 0 {
return err("not a 3D .cube LUT (no LUT_3D_SIZE)");
}
let expected = p.size3.checked_pow(3).ok_or_else(|| LutError("LUT size overflow".into()))?;
if p.rows.len() != expected {
return err(format!("expected {expected} entries, found {}", p.rows.len()));
}
Ok(Cube3d { title: p.title, size: p.size3, data: p.rows, domain_min: p.min, domain_max: p.max })
}
struct CubeRows {
title: Option<String>,
size3: usize,
size1: usize,
min: [f32; 3],
max: [f32; 3],
rows: Vec<[f32; 3]>,
}
fn cube_triplet(text: &str) -> Result<[f32; 3], LutError> {
let mut it = text.split_whitespace();
let mut row = [0.0; 3];
for value in &mut row {
*value = it.next().and_then(|s| s.parse::<f32>().ok()).filter(|v| v.is_finite()).ok_or_else(|| LutError(format!("bad line `{text}`")))?;
}
if it.next().is_some() {
return err(format!("bad line `{text}`"));
}
Ok(row)
}
fn read_cube(text: &str, profile_max: Option<usize>) -> Result<CubeRows, LutError> {
if profile_max.is_some_and(|n| !(2..=256).contains(&n)) {
return err("3D profile size limit must be in 2..=256");
}
let mut p = CubeRows { title: None, size3: 0, size1: 0, min: [0.0; 3], max: [1.0; 3], rows: Vec::new() };
let row_limit = profile_max.unwrap_or(256).checked_pow(3).ok_or_else(|| LutError("LUT size overflow".into()))?;
for raw in text.lines() {
let profile = profile_max.is_some();
let line = if profile { raw.trim() } else { raw.split('#').next().unwrap_or("").trim() };
// The standard dialect protects '#' inside quoted titles; profile titles are literal.
if !profile
&& let Some(quoted) =
raw.trim_start().strip_prefix("TITLE").filter(|r| r.starts_with(char::is_whitespace)).and_then(|r| r.trim_start().strip_prefix('"'))
{
let Some((title, _)) = quoted.split_once('"') else { return err("unterminated quoted TITLE") };
p.title = Some(title.to_string());
continue;
}
if line.is_empty() || line.starts_with('#') {
continue;
}
let (key, rest) = if profile {
["TITLE", "LUT_3D_SIZE", "LUT_1D_SIZE", "DOMAIN_MIN", "DOMAIN_MAX"]
.into_iter()
.find_map(|key| line.strip_prefix(key).map(|rest| (key, rest.trim())))
.unwrap_or_else(|| line.split_once(char::is_whitespace).unwrap_or((line, "")))
} else {
line.split_once(char::is_whitespace).map_or((line, ""), |(key, rest)| (key, rest.trim()))
};
match key {
"TITLE" => p.title = Some(rest.trim_matches('"').to_string()),
"LUT_3D_SIZE" => {
let value = if profile { rest } else { rest.split_whitespace().next().unwrap_or("") };
p.size3 = value.parse().map_err(|_| LutError(format!("bad LUT_3D_SIZE `{value}`")))?;
let limit = profile_max.unwrap_or(MAX_SIZE);
if !(2..=limit).contains(&p.size3) {
return err(format!("LUT_3D_SIZE {} out of range", p.size3));
}
}
"LUT_1D_SIZE" => {
if profile {
return err("1D LUTs are not supported (only 3D .cube files)");
}
p.size1 = rest.split_whitespace().next().and_then(|s| s.parse().ok()).ok_or_else(|| LutError("bad LUT_1D_SIZE".into()))?;
if p.size1 > row_limit {
return err("1D LUT exceeds row budget");
}
}
"DOMAIN_MIN" => p.min = cube_triplet(rest).map_err(|_| LutError("bad DOMAIN_MIN".into()))?,
"DOMAIN_MAX" => p.max = cube_triplet(rest).map_err(|_| LutError("bad DOMAIN_MAX".into()))?,
"LUT_3D_INPUT_RANGE" | "LUT_1D_INPUT_RANGE" if !profile => {
let mut it = rest.split_whitespace();
let min = it.next().and_then(|s| s.parse::<f32>().ok());
let max = it.next().and_then(|s| s.parse::<f32>().ok());
if let (Some(min), Some(max), None) = (min, max, it.next()) {
p.min = [min; 3];
p.max = [max; 3];
}
}
_ => {
let numeric = key.starts_with(|c: char| c.is_ascii_digit() || c == '-' || c == '+' || c == '.');
let nonfinite = key.parse::<f32>().is_ok();
if numeric || nonfinite || (profile && !key.starts_with(|c: char| c.is_ascii_alphabetic())) {
let row = cube_triplet(line)?;
if p.rows.len() >= row_limit {
return err("LUT exceeds row budget");
}
// Explicit fallible growth prevents capacity growth past the configured budget.
if p.rows.len() == p.rows.capacity() {
let grow = (p.rows.capacity().max(1)).min(row_limit - p.rows.len());
p.rows.try_reserve_exact(grow).map_err(|_| LutError("LUT allocation failed".into()))?;
}
p.rows.push(row);
}
}
}
}
Ok(p)
}
/// Adobe / Resolve `.cube`. 1D LUTs (`LUT_1D_SIZE`) are expanded to a 33³ table.
pub fn parse_cube(text: &str) -> Result<LutFile, LutError> {
let p = read_cube(text, None)?;
let (title, size3, size1, dmin, dmax) = (p.title.unwrap_or_default(), p.size3, p.size1, p.min, p.max);
let rows: Vec<f32> = p.rows.into_iter().flatten().collect();
let domain_ok = (0..3).all(|k| dmin[k] < dmax[k] && dmin[k].is_finite() && dmax[k].is_finite());
if (size3 > 0 || size1 >= 2) && !domain_ok {
return err(format!("DOMAIN_MIN {:?} must lie below DOMAIN_MAX {:?}", dmin, dmax));
}
if size3 > 0 {
return LutFile { title, size: size3, data: rows, domain_min: dmin, domain_max: dmax }.check();
}
if size1 >= 2 {
let expected_rows = size1.checked_mul(3).ok_or_else(|| LutError(format!("unsupported 1D LUT size {size1}")))?;
if rows.len() != expected_rows {
return err("no LUT_3D_SIZE in .cube file");
}
// #8913: the resample below bakes the curve onto a fixed 33-point grid, so a steep
// curve over a narrow domain cannot survive the resample — the baked table silently
// shifts colours (measured 42 RGB8 levels for a two-node ramp over 0.24..0.26, where
// Photoshop renders the ramp exactly). Rather than proxy the risk by domain width (a
// 0.1..0.17 ramp spans two grid cells yet still loses ~28 levels), measure the
// resample's actual error against the exact curve and refuse only tables whose baked
// output shifts by more than a couple of RGB8 levels. Default-domain tables keep the
// existing bake untouched; gentle curves over any domain bake within tolerance and
// stay accepted.
// The 1D table is resampled onto a 0..1 cube anyway, so its input domain
// (`DOMAIN_MIN`/`MAX`, `LUT_1D_INPUT_RANGE`) is baked into the resample: an input `v`
// reads the table at `(v - min) / (max - min)`, saturating outside.
let curve = |ch: usize, v: f32| {
let t = (v - dmin[ch]) / (dmax[ch] - dmin[ch]);
let x = if t.is_finite() { t.clamp(0.0, 1.0) } else { 0.0 } * (size1 - 1) as f32;
let i = (x.floor() as usize).min(size1 - 2);
let f = x - i as f32;
rows[i * 3 + ch] * (1.0 - f) + rows[(i + 1) * 3 + ch] * f
};
let mut l = LutFile::from_fn(&title, 33, |c| [curve(0, c[0]), curve(1, c[1]), curve(2, c[2])])?;
l.title = title;
let non_default = dmin.iter().any(|v| *v != 0.0) || dmax.iter().any(|v| *v != 1.0);
if non_default {
// Worst baked-vs-exact error per channel, in RGB8 levels: the baked cube is read
// by linear interpolation between grid points (red fastest, so channel `ch` sits
// at stride 33^ch), while `curve` is what the file actually says.
const MAX_BAKE_ERROR: f32 = 2.0 / 255.0;
for ch in 0..3 {
let stride = [1usize, 33, 33 * 33][ch];
let mut worst = 0.0f32;
for k in 0..=256 {
let v = k as f32 / 256.0;
let x = v * 32.0;
let i = (x as usize).min(31);
let f = x - i as f32;
let baked = l.data[i * stride * 3 + ch] * (1.0 - f) + l.data[(i + 1).min(32) * stride * 3 + ch] * f;
worst = worst.max((baked - curve(ch, v)).abs());
}
if worst > MAX_BAKE_ERROR {
return err(format!(
"1D LUT domain on {} is {min}..{max}: the curve changes faster than the 33-point grid can \
hold (baking shifts colours by up to {levels:.0} RGB8 levels); export the look as a 3D LUT \
or widen DOMAIN_MIN/DOMAIN_MAX",
["red", "green", "blue"][ch],
min = dmin[ch],
max = dmax[ch],
levels = worst * 255.0,
));
}
}
}
return l.check();
}
err("no LUT_3D_SIZE in .cube file")
}
/// Lustre `.3dl`: an optional `3DMESH` magic and `Mesh <inBits> <outBits>` line, an optional
/// shaper line of input values, then integer RGB rows with **blue** varying fastest. The
/// `Mesh` line declares the cube edge (2^inBits + 1) and the output code range (up to
/// 2^outBits − 1), and Photoshop honours both (#9073, #9078); without it the edge is the cube
/// root of the row count and the range is inferred from the largest value (#9121). A shaper that
/// isn't the even ramp is applied before the table, as Photoshop does (#8982): see `apply_shaper`.
pub fn parse_3dl(text: &str) -> Result<LutFile, LutError> {
let mut mesh: Option<(u32, u32)> = None;
let mut rows: Vec<[f64; 3]> = Vec::new();
// How many numbers the first numeric line carried: a shaper of exactly `n` values (n ≤ 3)
// is otherwise indistinguishable from a node row.
let mut first_len: Option<usize> = None;
// Any text line before the rows is a header: a headerless table peaking at 255 or 1023 is
// on the 12-bit scale, as Photoshop 27.11 reads it (#9121).
let mut header = false;
let mut shaper: Option<Vec<f64>> = None;
for line in text.lines() {
let line = line.split('#').next().unwrap_or("").trim();
// A header is `3DMESH` or starts with a word (`Mesh 4 12`): a letter, and not a number.
// `NaN` and `inf` are numbers, and `0oops` starts like one: those rows are read strictly.
let Some(first) = line.split_whitespace().next() else { continue };
if first.eq_ignore_ascii_case("3DMESH") || first.starts_with(char::is_alphabetic) && first.parse::<f64>().is_err() {
header = true;
// The only header keyword that carries data. A malformed or out-of-range `Mesh`
// line is ignored, as every text line always was.
let mut it = line.split_whitespace();
if it.next().is_some_and(|k| k.eq_ignore_ascii_case("Mesh")) {
// A declaration is exactly two integer fields after the keyword. Anything else
// (a non-numeric field, too few or too many) is not a declaration: `mesh` stays
// unset so headerless inference applies, rather than recovering numbers from
// the wrong positions (#9078).
let fields: Vec<&str> = it.collect();
if let [a, b] = fields.as_slice()
&& let (Ok(n), Ok(bits)) = (a.parse::<u32>(), b.parse::<u32>())
&& (1..=7).contains(&n)
&& (1..=16).contains(&bits)
{
mesh = Some((n, bits));
}
}
continue;
}
// Every token is a number: a malformed one is refused rather than dropped, which could
// turn a shaper into an even ramp and lose it silently.
let v: Vec<f64> = line.split_whitespace().map(str::parse).collect::<Result<_, _>>().map_err(|_| LutError(format!("bad line `{line}`")))?;
first_len.get_or_insert(v.len());
if v.len() == 3 {
rows.push([v[0], v[1], v[2]]);
} else if v.len() >= 2 {
// Two values are a 2-point shaper (a 2³ table's), not something to drop.
// The input shaper: one row of values ahead of the table, and only one.
if shaper.is_some() || !rows.is_empty() {
return err(format!("a second shaper row `{line}`"));
}
shaper = Some(v);
}
}
let (n, nodes, scale) = match mesh {
Some((in_bits, out_bits)) => {
let n = 2usize.pow(in_bits) + 1;
let expected = n.checked_pow(3).ok_or_else(|| LutError(format!("unsupported 3dl cube size {n}")))?;
// One row more than the declared cube, and the first row has exactly `n` values:
// that row is the shaper, not a 28th node of a 3³ cube (#9078).
let nodes = if shaper.is_none() && rows.len() == expected + 1 && first_len == Some(n) {
shaper = rows.first().map(|row| row.to_vec());
&rows[1..]
} else {
&rows[..]
};
if nodes.len() != expected {
return err(format!("expected {expected} rows for the declared {n}³ cube, found {}", nodes.len()));
}
// Under a valid declaration the node codes are integers in the declared range, so
// the declaration wins for every in-range value — including a small max, where 1 is
// 1/declared of full output, not full output itself (#9073). Only a node beyond the
// declared range is a wrong declaration, and the old inference keeps such a file
// loading as before.
let max = nodes.iter().flatten().fold(0.0f64, |a, &b| a.max(b));
let declared = 2f64.powi(i32::try_from(out_bits).unwrap_or(16)) - 1.0;
(n, nodes, if max > declared { inferred_3dl_scale(max, header) } else { declared })
}
None => {
let n = (rows.len() as f64).cbrt().round() as usize;
if n < 2 || n * n * n != rows.len() {
return err(format!("{} rows is not a cube", rows.len()));
}
let max = rows.iter().flatten().fold(0.0f64, |a, &b| a.max(b));
(n, &rows[..], inferred_3dl_scale(max, header))
}
};
let mut data = vec![0.0f32; n * n * n * 3];
for (i, row) in nodes.iter().enumerate() {
let (r, g, b) = (i / (n * n), (i / n) % n, i % n);
let at = ((b * n + g) * n + r) * 3;
for k in 0..3 {
data[at + k] = (row[k] / scale) as f32;
}
}
let lut = LutFile { title: String::new(), size: n, data, domain_min: [0.0; 3], domain_max: [1.0; 3] }.check()?;
Ok(match shaper {
Some(shaper) => apply_shaper(lut, &shaper)?,
None => lut,
})
}
/// Bakes a `.3dl` shaper into the table. Photoshop applies the shaper row as a 1-D curve on each
/// input channel ahead of the 3-D table (input `x` reads the shaper, sampled evenly over 0..1,
/// at `x`, interpolated linearly), so each node of the table becomes the table's own trilinear
/// value at the shaped input. An even ramp (the usual shaper) changes nothing and is skipped.
/// The table is baked on a grid holding both its own nodes and the shaper's knots: exact for an
/// identity table, an approximation at that resolution otherwise. A shaper that would need more
/// than [`MAX_SIZE`] nodes for that, or that holds a value that isn't finite, is refused.
fn apply_shaper(lut: LutFile, shaper: &[f64]) -> Result<LutFile, LutError> {
let m = shaper.len();
if m < 2 {
return Ok(lut);
}
// Apply or refuse: a shaper that can't be applied never leaves the table to render alone.
if shaper.iter().any(|v| !v.is_finite()) {
return err("the .3dl shaper holds a value that isn't finite");
}
// The shaper's own depth, from 10 bits up: a 0..1023 ramp is the even ramp with or without a header.
let scale = inferred_3dl_scale(shaper.iter().fold(0.0f64, |a, &b| a.max(b)), true);
let even = |k: usize| scale * k as f64 / (m - 1) as f64;
// Shapers round their ramp: within one code is still the even ramp. An integer shaper's code
// is 1; a float shaper (0..1) is held to one 10-bit step.
let code = if scale > 1.0 { 1.0 } else { 1.0 / 1023.0 };
if shaper.iter().enumerate().all(|(k, &v)| (v - even(k)).abs() <= code) {
return Ok(lut);
}
// Scaled to 0..1 first, so interpolating between two extreme values can't overflow.
let shaped: Vec<f64> = shaper.iter().map(|v| v / scale).collect();
let curve = |x: f64| -> f32 {
let p = x.clamp(0.0, 1.0) * (m - 1) as f64;
let i = (p.floor() as usize).min(m - 2);
let f = p - i as f64;
let (a, b) = (shaped.get(i).copied().unwrap_or(0.0), shaped.get(i + 1).copied().unwrap_or(0.0));
(a + (b - a) * f).clamp(0.0, 1.0) as f32
};
// The bake grid holds both the table's nodes and the shaper's knots (lcm of their intervals),
// so the curve keeps its breakpoints whatever the table's size: exact on an identity table. A
// grid that would pass MAX_SIZE is refused: sampled more coarsely, a bent shaper could read as
// even and be lost without a word.
let gcd = |mut a: usize, mut b: usize| {
while b != 0 {
(a, b) = (b, a % b);
}
a
};
let (a, k) = (lut.size - 1, m - 1);
let aligned = (a / gcd(a, k)).checked_mul(k).map(|l| l + 1).filter(|&l| l <= MAX_SIZE);
let Some(n) = aligned else {
return err(format!("the .3dl shaper's {m} points can't be kept on a table of at most {MAX_SIZE} nodes"));
};
let step = (n - 1) as f64;
let mut out = LutFile { size: n, data: vec![0.0; n * n * n * 3], ..lut.clone() };
for b in 0..n {
for g in 0..n {
for r in 0..n {
let at = ((b * n + g) * n + r) * 3;
let v = sample(&lut, [curve(r as f64 / step), curve(g as f64 / step), curve(b as f64 / step)]);
if let Some(dst) = out.data.get_mut(at..at + 3) {
dst.copy_from_slice(&v);
}
}
}
}
out.check()
}
/// Trilinear lookup of `rgb` (0..1) in a [`LutFile`] (red fastest).
fn sample(l: &LutFile, rgb: [f32; 3]) -> [f32; 3] {
let n = l.size;
let loc = |v: f32| {
let p = v.clamp(0.0, 1.0) * (n - 1) as f32;
let i = (p as usize).min(n.saturating_sub(2));
(i, p - i as f32)
};
let (r0, fr) = loc(rgb[0]);
let (g0, fg) = loc(rgb[1]);
let (b0, fb) = loc(rgb[2]);
let at = |r: usize, g: usize, b: usize, k: usize| l.data.get(((b * n + g) * n + r) * 3 + k).copied().unwrap_or(0.0);
let mut o = [0.0f32; 3];
for (k, ov) in o.iter_mut().enumerate() {
let c = |r, g, b| at(r, g, b, k);
let x00 = c(r0, g0, b0) + (c(r0 + 1, g0, b0) - c(r0, g0, b0)) * fr;
let x10 = c(r0, g0 + 1, b0) + (c(r0 + 1, g0 + 1, b0) - c(r0, g0 + 1, b0)) * fr;
let x01 = c(r0, g0, b0 + 1) + (c(r0 + 1, g0, b0 + 1) - c(r0, g0, b0 + 1)) * fr;
let x11 = c(r0, g0 + 1, b0 + 1) + (c(r0 + 1, g0 + 1, b0 + 1) - c(r0, g0 + 1, b0 + 1)) * fr;
let y0 = x00 + (x10 - x00) * fg;
let y1 = x01 + (x11 - x01) * fg;
*ov = y0 + (y1 - y0) * fb;
}
o
}
/// The code range a `.3dl` node table without a declared output depth was written with: the
/// smallest common integer depth that covers the largest value; a table of 0..1 floats passes
/// through. A headerless table has no 10-bit reading — 255 and 1023 are on the 12-bit scale, as
/// Photoshop 27.11 reads them (#9121).
fn inferred_3dl_scale(max: f64, header: bool) -> f64 {
if max <= 1.0 {
return 1.0;
}
let depths: &[f64] = if header { &[1023.0, 4095.0, 16383.0, 65535.0] } else { &[4095.0, 16383.0, 65535.0] };
depths.iter().copied().find(|&s| max <= s).unwrap_or(max)
}
/// SpeedGrade `.look`: `<size>` and a hex `<data>` string of little-endian float32 RGB triplets
/// (red fastest).
pub fn parse_look(text: &str) -> Result<LutFile, LutError> {
// Comments may hold tag-like text, so drop them before looking for tags (#9109).
let mut clean = String::with_capacity(text.len());
let mut rest = text;
while let Some(i) = rest.find("<!--") {
clean.push_str(&rest[..i]);
rest = rest[i + 4..].find("-->").map_or("", |e| &rest[i + 4 + e + 3..]);
}
clean.push_str(rest);
let text = clean.as_str();
let tag = |name: &str| -> Option<String> {
let open = format!("<{name}>");
let start = text.find(&open)? + open.len();
let end = text[start..].find(&format!("</{name}>"))? + start;
Some(text[start..end].trim().trim_matches('"').trim().to_string())
};
let size: usize = tag("size").and_then(|s| s.parse().ok()).ok_or_else(|| LutError("no <size> in .look".into()))?;
let (entries, _) = checked_data_len(size)?;
let hex: Vec<u8> = tag("data").ok_or_else(|| LutError("no <data> in .look".into()))?.bytes().filter(|b| !b.is_ascii_whitespace()).collect();
if hex.iter().any(|b| !b.is_ascii_hexdigit()) {
return err("invalid hexadecimal <data> in .look");
}
// Each float needs eight hex digits; as_chunks would silently discard a partial value.
if !hex.len().is_multiple_of(8) {
return err("incomplete float in .look <data>");
}
let nib = |c: u8| (c as char).to_digit(16).unwrap_or(0) as u8;
let bytes: Vec<u8> = hex.as_chunks::<2>().0.iter().map(|p| nib(p[0]) << 4 | nib(p[1])).collect();
let floats: Vec<f32> = bytes.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]])).collect();
let rgba_entries = entries.checked_mul(4).ok_or_else(|| LutError(format!("unsupported LUT size {size}")))?;
let data = if floats.len() == rgba_entries { floats.as_chunks::<4>().0.iter().flat_map(|c| [c[0], c[1], c[2]]).collect() } else { floats };
LutFile { title: tag("title").unwrap_or_default(), size, data, domain_min: [0.0; 3], domain_max: [1.0; 3] }.check()
}
/// Writes a `.cube` file (what Photoshop embeds in a Color Lookup layer).
pub fn write_cube(l: &LutFile) -> String {
let mut s = String::new();
if !l.title.is_empty() {
s.push_str(&format!("TITLE \"{}\"\n", l.title.replace('"', "'")));
}
// The domain is what every row means: a table read with a non-default one must not be
// written back as if it expected inputs in 0..1. `parse_cube` accepts these anywhere.
if !l.domain_is_default() {
s.push_str(&format!("DOMAIN_MIN {} {} {}\n", l.domain_min[0], l.domain_min[1], l.domain_min[2]));
s.push_str(&format!("DOMAIN_MAX {} {} {}\n", l.domain_max[0], l.domain_max[1], l.domain_max[2]));
}
s.push_str(&format!("LUT_3D_SIZE {}\n", l.size));
cube_rows(s, l.data.as_chunks::<3>().0.iter().copied())
}
/// Writes a `.cube` file with a creator comment, section comments and an explicit input domain.
///
/// This layout is useful for exported LUTs; [`write_cube`] keeps its compact layout for embedded
/// tables. Values retain six decimal places, and their order and quantisation belong to the
/// caller. A default domain is written as `0.0` and `1.0` for compatibility with export consumers.
pub fn write_cube_commented(l: &LutFile, creator: &str) -> String {
let mut s = format!("#Created by: {creator}\nTITLE \"{}\"\n\n#LUT size\nLUT_3D_SIZE {}\n\n#data domain\n", l.title.replace('"', "'"), l.size);
if l.domain_is_default() {
s.push_str("DOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n");
} else {
s.push_str(&format!("DOMAIN_MIN {} {} {}\n", l.domain_min[0], l.domain_min[1], l.domain_min[2]));
s.push_str(&format!("DOMAIN_MAX {} {} {}\n", l.domain_max[0], l.domain_max[1], l.domain_max[2]));
}
s.push_str("\n#LUT data points\n");
cube_rows(s, l.data.as_chunks::<3>().0.iter().copied())
}
fn cube_rows(mut s: String, rows: impl Iterator<Item = [f32; 3]>) -> String {
for c in rows {
s.push_str(&format!("{:.6} {:.6} {:.6}\n", c[0], c[1], c[2]));
}
s
}
/// Annotated identity-domain CUBE export, streamed in red-fastest order without a table copy.
/// Callers supply exactly `size³` rows for a valid size (2..=[`MAX_SIZE`]), as with [`write_cube`].
/// Integer-depth exports clamp/round to 1/32768 steps; floating exports clamp without rounding.
pub fn write_cube_export(creator: &str, title: &str, size: usize, integer_depth: bool, rows: impl Iterator<Item = [f32; 3]>) -> String {
let s = format!(
"#Created by: {creator}\nTITLE \"{}\"\n\n#LUT size\nLUT_3D_SIZE {size}\n\n#data domain\nDOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n\n#LUT data points\n",
title.replace('"', "'")
);
cube_rows(
s,
rows.map(|c| {
c.map(|v| {
let v = v.clamp(0.0, 1.0);
if integer_depth { (v * 32768.0).round() / 32768.0 } else { v }
})
}),
)
}
fn luma(c: [f32; 3]) -> f32 {
0.299 * c[0] + 0.587 * c[1] + 0.114 * c[2]
}
fn smooth(x: f32) -> f32 {
let x = x.clamp(0.0, 1.0);
x * x * (3.0 - 2.0 * x)
}
/// Generated looks shipped with this crate (procedural, CC0): `(id, label)`.
pub const BUILTIN: [(&str, &str); 8] = [
("warm", "Warm Filter"),
("cool", "Cool Filter"),
("tealOrange", "Teal & Orange"),
("bleachBypass", "Bleach Bypass"),
("fadedFilm", "Faded Film"),
("dayForNight", "Day for Night"),
("monoContrast", "Mono High Contrast"),
("crossProcess", "Cross Process"),
];
/// A built-in look by id (33³), or None.
pub fn builtin(id: &str) -> Option<LutFile> {
let label = BUILTIN.iter().find(|b| b.0 == id)?.1;
let f: Box<dyn Fn([f32; 3]) -> [f32; 3]> = match id {
"warm" => Box::new(|c: [f32; 3]| [c[0] * 0.92 + 0.08, c[1] * 0.97 + 0.02, c[2] * 0.85]),
"cool" => Box::new(|c: [f32; 3]| [c[0] * 0.86, c[1] * 0.97 + 0.01, c[2] * 0.9 + 0.1]),
"tealOrange" => Box::new(|c: [f32; 3]| {
// Shadows toward teal, highlights toward orange, skin-ish midtones kept.
let l = luma(c);
let t = smooth(l);
let teal = [0.0, 0.5, 0.55];
let orange = [1.0, 0.62, 0.3];
std::array::from_fn(|k| {
let tint = teal[k] * (1.0 - t) + orange[k] * t;
c[k] * 0.75 + (tint * l * 1.1).min(1.0) * 0.25 + (smooth(c[k]) - c[k]) * 0.3
})
}),
"bleachBypass" => Box::new(|c: [f32; 3]| {
let l = luma(c);
let s = smooth(l);
std::array::from_fn(|k| {
let desat = c[k] * 0.45 + l * 0.55;
desat * 0.5 + s * 0.5
})
}),
"fadedFilm" => Box::new(|c: [f32; 3]| {
let l = luma(c);
let tint = [1.0, 0.96, 0.88];
std::array::from_fn(|k| (0.08 + (c[k] * 0.8 + l * 0.2) * 0.84) * tint[k] + 0.02)
}),
"dayForNight" => Box::new(|c: [f32; 3]| {
let l = luma(c);
[l * 0.35, l * 0.45 + c[1] * 0.05, l * 0.65 + c[2] * 0.15]
}),
"monoContrast" => Box::new(|c: [f32; 3]| [smooth(smooth(luma(c))); 3]),
_ /* crossProcess */ => Box::new(|c: [f32; 3]| [smooth(c[0]) * 1.05, c[1] * 1.1 - 0.03, c[2] * 0.7 + 0.15]),
};
LutFile::from_fn(label, 33, f).ok()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn commented_cube_preserves_export_header_and_rows() {
let mut lut = super::LutFile::identity(2).unwrap();
lut.title = "A \"look\"".into();
let text = super::write_cube_commented(&lut, "ExampleCraft");
assert!(text.starts_with("#Created by: ExampleCraft\nTITLE \"A 'look'\"\n\n#LUT size\nLUT_3D_SIZE 2\n\n#data domain\nDOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n\n#LUT data points\n"));
let parsed = super::parse_cube(&text).unwrap();
assert_eq!(parsed.data, lut.data);
assert_eq!(parsed.title, "A 'look'");
assert_eq!(text.lines().count(), 11 + 8);
let rows = |s: &str| s.lines().filter(|line| line.starts_with(|c: char| c.is_ascii_digit())).map(str::to_owned).collect::<Vec<_>>();
assert_eq!(rows(&text), rows(&super::write_cube(&lut)));
}
#[test]
fn commented_cube_keeps_nondefault_domain_and_sample_precision() {
let mut lut = super::LutFile::identity(2).unwrap();
lut.domain_min = [0.125, 0.25, 0.375];
lut.domain_max = [0.625, 0.75, 0.875];
lut.data[0] = 0.833344;
let parsed = super::parse_cube(&super::write_cube_commented(&lut, "ExampleCraft")).unwrap();
assert_eq!(parsed, lut);
}
#[test]
fn cube_title_hashes_and_comment_quotes_are_distinct() {
let rows = "LUT_1D_SIZE 2\n0 0 0 # low\n1 1 1 # high\n";
for (line, title) in [
(r#"TITLE "Look #3" # comment "ignored""#, "Look #3"),
(r#"TITLE Look # "draft""#, "Look"),
(" TITLE\t\"Été #2\"", "Été #2"),
(r#"TITLE "" # empty"#, ""),
] {
assert_eq!(parse_cube(&format!("{line}\n{rows}")).unwrap().title, title);
}
let lut = LutFile::from_fn("Look #3", 2, |c| c).unwrap();
assert_eq!(parse_cube(&write_cube(&lut)).unwrap().title, "Look #3");
assert!(parse_cube(&format!("TITLE \"unterminated # title\n{rows}")).is_err());
}
#[test]
fn cube_rejects_invalid_numeric_fields() {
let text = "LUT_3D_SIZE 2\n0.25 nope 0.5 0.75\n0 0 1\n0 1 0\n0 1 1\n1 0 0\n1 0 1\n1 1 0\n1 1 1\n";
assert!(parse_cube(text).is_err(), "invalid numeric field must not be ignored");
}
#[test]
fn utf8_bom_is_stripped() {
let l = LutFile::identity(3).unwrap();
let mut bytes = vec![0xEF, 0xBB, 0xBF];
bytes.extend_from_slice(write_cube(&l).as_bytes());
let p = parse("a.cube", &bytes).unwrap();
assert_eq!(p.size, l.size);
assert_eq!(p.title, l.title);
let titled = LutFile::from_fn("Look", 3, |c| c).unwrap();
let mut bytes = vec![0xEF, 0xBB, 0xBF];
bytes.extend_from_slice(write_cube(&titled).as_bytes());
assert_eq!(parse("a.cube", &bytes).unwrap().title, "Look");
let mut bytes = vec![0xEF, 0xBB, 0xBF];
bytes.extend_from_slice(b"LUT_3D_SIZE 2\n");
for i in 0..8 {
bytes.extend_from_slice(format!("{} {} {}\n", i & 1, (i >> 1) & 1, i >> 2).as_bytes());
}
assert_eq!(parse("a.cube", &bytes).unwrap().size, 2);
}
/// An identity `.3dl` of edge `n` (12-bit nodes, blue fastest) under `shaper`.
fn identity_3dl(shaper: &[u32], n: usize) -> String {
let mut t = shaper.iter().map(u32::to_string).collect::<Vec<_>>().join(" ") + "\n";
let node = |i: usize| (i * 4095 / (n - 1)).to_string();
for r in 0..n {
for g in 0..n {
for b in 0..n {
t += &format!("{} {} {}\n", node(r), node(g), node(b));
}
}
}
t
}
#[test]
fn three_dl_shaper_applies_before_the_table() {
// #8982: Photoshop applies a .3dl's shaper row as a curve ahead of the 3-D table. On grey
// 128 an identity table with the shaper 0 114 455 1023 gives 71 there, and a 17-point
// squared shaper 64 (reported measurements); even ramps leave grey 128 as it is.
let grey = |l: &LutFile| (sample(l, [128.0 / 255.0; 3])[0] * 255.0).round();
let bent = parse_3dl(&identity_3dl(&[0, 114, 455, 1023], 4)).unwrap();
assert_eq!(grey(&bent), 71.0);
let squared: Vec<u32> = (0..17).map(|i| (1023.0 * (i as f64 / 16.0).powi(2)).round() as u32).collect();
assert_eq!(grey(&parse_3dl(&identity_3dl(&squared, 17)).unwrap()), 64.0);
let even4 = parse_3dl(&identity_3dl(&[0, 341, 682, 1023], 4)).unwrap();
assert_eq!(grey(&even4), 128.0);
assert_eq!(even4, parse_3dl(&identity_3dl(&[0, 341, 682, 1023], 4).lines().skip(1).collect::<Vec<_>>().join("\n")).unwrap());
let even17: Vec<u32> = (0..17).map(|i| (1023.0 * i as f64 / 16.0).round() as u32).collect();
assert_eq!(grey(&parse_3dl(&identity_3dl(&even17, 17)).unwrap()), 128.0);
// The ends stay put, and the shaper bends each channel on its own.
assert_eq!(sample(&bent, [0.0, 1.0, 0.0]), [0.0, 1.0, 0.0]);
let c = sample(&bent, [1.0 / 3.0, 0.0, 2.0 / 3.0]);
assert!((c[0] - 114.0 / 1023.0).abs() < 1e-4 && (c[2] - 455.0 / 1023.0).abs() < 1e-4, "{c:?}");
// A shaper that isn't finite is refused rather than dropped (see
// `three_dl_non_finite_shaper_is_refused`).
assert!(parse_3dl(&identity_3dl(&[0, 341, 682, 1023], 4).replacen("341", "NaN", 1)).is_err());
}
/// #9170 review: a float shaper (values in 0..1) is held to a float ramp, not to one integer
/// code, so a bent float shaper is applied.
#[test]
fn three_dl_float_shaper_is_applied() {
let grey = |l: &LutFile| (sample(l, [128.0 / 255.0; 3])[0] * 255.0).round();
let with = |shaper: &str| {
let table = identity_3dl(&[0, 1, 2, 3], 4);
parse_3dl(&format!("{shaper}\n{}", table.split_once('\n').unwrap().1)).unwrap()
};
// 0.502 lands between 0.1 and 0.3 at 0.506 of the way: 0.2012, so grey 51.
assert_eq!(grey(&with("0 0.1 0.3 1.0")), 51.0);
// An even float ramp, written to three decimals, still changes nothing.
assert_eq!(grey(&with("0 0.333 0.667 1.0")), 128.0);
}
/// #9170 review: a shaper with more points than the table keeps its curve: the table is
/// resampled at the shaper's resolution rather than reading the shaper at its own two nodes.
#[test]
fn three_dl_shaper_finer_than_the_table_keeps_its_curve() {
let grey = |l: &LutFile| (sample(l, [128.0 / 255.0; 3])[0] * 255.0).round();
let small = parse_3dl(&identity_3dl(&[0, 0, 512, 1023], 2)).unwrap();
// 0.502 lands between 0 and 512 at 0.506 of the way: 259 / 1023, so grey 65.
assert_eq!(grey(&small), 65.0);
assert_eq!(sample(&small, [1.0, 0.0, 1.0]), [1.0, 0.0, 1.0], "the ends stay put");
}
/// #9170 review: a finite but extreme shaper can't overflow into NaN when it is baked.
#[test]
fn three_dl_extreme_shaper_bakes_only_finite_values() {
let table = identity_3dl(&[0, 1, 2, 3], 2);
let text = format!("0 1e308 -1e308 0\n{}", table.split_once('\n').unwrap().1);
// Refused or baked, but never a table holding NaN.
if let Ok(l) = parse_3dl(&text) {
assert!(l.data.iter().all(|v| v.is_finite()), "baked a non-finite value");
}
}
/// #9170 review (bommerts): the shaper's breakpoints survive a table whose grid doesn't line
/// up with them. The bake grid holds both the table's nodes and the shaper's knots, so on an
/// identity table the curve is exact: `0 0 512 1023` is 0 at ⅓ over 5³ and 17³ tables.
#[test]
fn three_dl_shaper_knots_survive_a_nonaligned_table() {
for n in [5, 17] {
let l = parse_3dl(&identity_3dl(&[0, 0, 512, 1023], n)).unwrap();
let at = |x: f32| sample(&l, [x, 0.0, 0.0])[0];
assert!(at(1.0 / 3.0).abs() < 1e-6, "{n}³: {}", at(1.0 / 3.0));
// The helper's 12-bit nodes are truncated, so the table itself is within a 12-bit step.
assert!((at(2.0 / 3.0) - 512.0 / 1023.0).abs() < 1.0 / 4095.0, "{n}³: {}", at(2.0 / 3.0));
assert!((at(0.5) - 256.0 / 1023.0).abs() < 1.0 / 4095.0, "{n}³: halfway between the knots");
}
}
/// A two-value shaper row (a 2³ table's) is applied like a longer one, not dropped; the even
/// two-point ramp changes nothing.
#[test]
fn three_dl_two_point_shaper_is_applied() {
let bent = parse_3dl(&identity_3dl(&[0, 512], 2)).unwrap();
let top = sample(&bent, [1.0, 1.0, 1.0]);
assert!(top.iter().all(|v| (v - 512.0 / 1023.0).abs() < 1e-4), "{top:?}");
assert!((sample(&bent, [0.5, 0.0, 0.0])[0] - 256.0 / 1023.0).abs() < 1e-4);
let even = parse_3dl(&identity_3dl(&[0, 1023], 2)).unwrap();
assert_eq!(
even,
parse_3dl(&identity_3dl(&[0, 1023], 2).lines().skip(1).collect::<Vec<_>>().join(
"
"
))
.unwrap()
);
// A second two-value row is a second shaper, refused like a longer one.
let body = identity_3dl(&[0, 512], 2);
assert!(
parse_3dl(&format!(
"{body}0 512
"
))
.is_err()
);
}
/// #9170 review (bommerts): a shaper row with a token that isn't a number, or a second
/// shaper row, is refused rather than silently dropped.
#[test]
fn three_dl_malformed_shaper_rows_are_refused() {
let table = identity_3dl(&[0, 1, 2, 3], 4);
let body = table.split_once('\n').unwrap().1;
assert!(parse_3dl(&format!("0 341 junk 682 1023\n{body}")).is_err(), "a junk token");
assert!(parse_3dl(&format!("0 114 455 1023\n0 114 455 1023\n{body}")).is_err(), "two shaper rows");
assert!(parse_3dl(&format!("0 114 455 1023\n{body}")).is_ok());
}
/// #9170 review (bommerts): the standard `3DMESH` / `Title lut 12` preamble still reads; only
/// the rows after it are parsed strictly.
#[test]
fn three_dl_mesh_preamble_is_accepted() {
let grey = |l: &LutFile| (sample(l, [128.0 / 255.0; 3])[0] * 255.0).round();
let plain = identity_3dl(&[0, 114, 455, 1023], 4);
let headed = parse_3dl(&format!("3DMESH\nTitle lut 12\n{plain}")).unwrap();
assert_eq!(headed, parse_3dl(&plain).unwrap(), "the preamble changes nothing");
assert_eq!(grey(&headed), 71.0, "the bent shaper still applies");
let even = identity_3dl(&[0, 341, 682, 1023], 4);
assert_eq!(grey(&parse_3dl(&format!("3dmesh\nTitle lut 12\n{even}")).unwrap()), 128.0);
assert!(
parse_3dl(&format!("3DMESH\nTitle lut 12\n0 341 junk 682 1023\n{}", even.split_once('\n').unwrap().1)).is_err(),
"still strict after it"
);
}
/// #9170 review: a shaper that isn't finite is refused, not dropped, so a Color Lookup never
/// renders the table alone for a file whose shaper it can't apply.
#[test]
fn three_dl_non_finite_shaper_is_refused() {
let body = identity_3dl(&[0, 1, 2, 3], 4);
let body = body.split_once('\n').unwrap().1;
for shaper in ["0 NaN 682 1023", "0 341 inf 1023", "-inf 341 682 1023"] {
assert!(parse_3dl(&format!("{shaper}\n{body}")).is_err(), "{shaper}");
}
}
/// #9170 review: a shaper row that starts with `NaN` or `inf` is a shaper, not a header, so
/// it reaches the non-finite refusal instead of being skipped.
#[test]
fn three_dl_shaper_starting_non_finite_is_refused() {
let body = identity_3dl(&[0, 1, 2, 3], 4);
let body = body.split_once('\n').unwrap().1;
for shaper in ["NaN 341 682 1023", "inf 341 682 1023", "-inf 341 682 1023"] {
assert!(parse_3dl(&format!("{shaper}\n{body}")).is_err(), "{shaper}");
}
}
/// #9170 review: only a line starting with a word is a header. One whose first token looks
/// like a number but isn't (`0oops`) is read strictly and refused, not skipped with its shaper.
#[test]
fn three_dl_malformed_first_token_is_refused() {
let body = identity_3dl(&[0, 1, 2, 3], 4);
let body = body.split_once('\n').unwrap().1;
for shaper in ["0oops 114 455 1023", "-x 114 455 1023", ".5x 114 455 1023", "+ 114 455 1023"] {
assert!(parse_3dl(&format!("{shaper}\n{body}")).is_err(), "{shaper}");
}
let (first, rest) = body.split_once('\n').unwrap();
assert!(parse_3dl(&format!("0 114 455 1023\n{first}\n1x 0 0\n{rest}")).is_err(), "a table row too");
assert!(parse_3dl(&format!("3DMESH\nTitle lut 12\n0 114 455 1023\n{body}")).is_ok(), "headers still skip");
}
/// #9170 review: a bent shaper whose knots can't all be kept within MAX_SIZE is refused rather
/// than sampled where it may look even (here a 257-point shaper bent only at odd knots, whose
/// 129-node fallback would read the identity).
#[test]
fn three_dl_shaper_too_fine_to_keep_is_refused() {
let shaper: Vec<u32> = (0..257u32).map(|i| (i * 1023 / 256 + if i % 2 == 1 { 40 } else { 0 }).min(1023)).collect();
assert!(parse_3dl(&identity_3dl(&shaper, 2)).is_err());
// As many knots as nodes stays within reach.
let same: Vec<u32> = (0..17u32).map(|i| (1023.0 * (f64::from(i) / 16.0).powi(2)).round() as u32).collect();
assert!(parse_3dl(&identity_3dl(&same, 17)).is_ok());
}
#[test]
fn cube_title_with_hash_round_trips() {
let l = LutFile::from_fn("Look #3", 2, |c| c).unwrap();
assert_eq!(parse_cube(&write_cube(&l)).unwrap().title, "Look #3");
let t = "TITLE \"A #b\" # note\nLUT_3D_SIZE 2 # c\n# comment\n";
let rows = "0 0 0 # x\n1 0 0\n0 1 0\n1 1 0\n0 0 1\n1 0 1\n0 1 1\n1 1 1\n";
let p = parse_cube(&format!("{t}{rows}")).unwrap();
assert_eq!(p.title, "A #b");
}
#[test]
fn write_cube_keeps_non_default_domain() {
let mut l = LutFile::identity(2).unwrap();
l.domain_min = [0.1; 3];
l.domain_max = [0.9; 3];
let back = parse_cube(&write_cube(&l)).unwrap();
assert_eq!(back.domain_min, [0.1; 3]);
assert_eq!(back.domain_max, [0.9; 3]);
l.domain_min = [0.0, 0.0, 0.5];
l.domain_max = [1.0; 3];
let back = parse_cube(&write_cube(&l)).unwrap();
assert_eq!(back.domain_min, [0.0, 0.0, 0.5]);
assert_eq!(back.domain_max, [1.0; 3]);
assert!(!write_cube(&LutFile::identity(2).unwrap()).contains("DOMAIN"));
}
#[test]
fn cube_1d_narrow_domain_is_refused() {
// #8913: the issue's fixture — a two-node ramp over 0.24..0.26. Baking it onto the
// 33-point grid rendered grey-65 as 148 where Photoshop renders 190 (42-level error).
// It must now be an actionable parse error rather than a silently wrong table.
let e = parse_cube("LUT_1D_SIZE 2\nDOMAIN_MIN 0.24 0.24 0.24\nDOMAIN_MAX 0.26 0.26 0.26\n0 0 0\n1 1 1\n").unwrap_err();
assert!(e.0.contains("changes faster than the 33-point grid"), "{e}");
// The same domain via LUT_1D_INPUT_RANGE is refused identically.
let e = parse_cube("LUT_1D_SIZE 2\nLUT_1D_INPUT_RANGE 0.24 0.26\n0 0 0\n1 1 1\n").unwrap_err();
assert!(e.0.contains("changes faster"), "{e}");
// A per-channel narrow domain names the offending channel.
let e = parse_cube("LUT_1D_SIZE 2\nDOMAIN_MIN 0 0 0.24\nDOMAIN_MAX 1 1 0.26\n0 0 0\n1 1 1\n").unwrap_err();
assert!(e.0.contains("blue"), "{e}");
}
#[test]
fn cube_1d_wide_domain_still_bakes() {
// A steep ramp over 0.1..0.17 spans two grid cells but still loses ~28 RGB8 levels
// to the resample, so the measured-error check refuses it even though the old width
// check let it through.
let e = parse_cube("LUT_1D_SIZE 2\nLUT_1D_INPUT_RANGE 0.1 0.17\n0 0 0\n1 1 1\n").unwrap_err();
assert!(e.0.contains("changes faster"), "steep ramp over 0.1..0.17 refused: {e}");
// A gentle (here linear) curve over a grid-aligned domain bakes exactly and stays
// accepted — the check measures the bake's error, not the domain's width. Value
// assertions, not just a successful parse: the baked table must reproduce the curve.
// Table row k sits at t = k/32 of the domain 0.25..0.75; the curve y = 0.4 + 0.4t
// is gentle (a half-level per grid step), so the bake must reproduce it exactly.
let mut table = String::from("LUT_1D_SIZE 33\nLUT_1D_INPUT_RANGE 0.25 0.75\n");
for k in 0..33 {
let y = 0.4 + 0.4 * (k as f32 / 32.0);
table.push_str(&format!("{y} {y} {y}\n"));
}
let l = parse_cube(&table).expect("gentle curve over a non-default domain still bakes");
let at = |r: usize| l.data[r * 3];
// Grid entry r is input r/32: 0.5 is the middle of the domain (t=0.5) -> 0.6.
assert!((at(16) - 0.6).abs() < 1.0 / 255.0, "baked value at 0.5 tracks the curve: {}", at(16));
// Domain top (input 0.75 = grid 24, t=1) -> 0.8.
assert!((at(24) - 0.8).abs() < 1.0 / 255.0, "baked value at the domain top tracks the curve: {}", at(24));
// Below the domain saturates to the first row.
assert!((at(8) - 0.4).abs() < 1.0 / 255.0, "below the domain saturates: {}", at(8));
parse_cube("LUT_1D_SIZE 2\n0 0 0\n1 1 1\n").expect("default domain");
}
#[test]
fn three_dl_without_a_header_reads_low_nodes_as_12_bit() {
let table = |peak: u32| -> String {
let mut text = String::from("0 1023\n");
for i in 0..8 {
let on = |bit: u32| if i & bit != 0 { peak } else { 0 };
text.push_str(&format!("{} {} {}\n", on(4), on(2), on(1)));
}
text
};
for peak in [255, 1023, 4095] {
let white = parse_3dl(&table(peak)).unwrap().data[21..24].to_vec();
assert_eq!(white, [peak as f32 / 4095.0; 3], "peak {peak}");
}
// A header keeps the inferred 10-bit depth. The bare `3DMESH` magic is a header without a
// cube declaration; `Mesh 1 10` would declare a 3³ cube and refuse this 2³ table (#9078).
let white = parse_3dl(&format!("3DMESH\n{}", table(1023))).unwrap().data[21..24].to_vec();
assert_eq!(white, [1.0; 3]);
}
/// A `size`³ inverse-identity `.3dl` (blue fastest): node (r,g,b) outputs `max - max·v/(size-1)`
/// per channel, with a uniform shaper of `size` codes up to 1023.
fn mesh_3dl(n_bits: u32, out_bits: u32, size: usize, max: f64, shaper: bool) -> String {
let mut text = format!("3DMESH\nMesh {n_bits} {out_bits}\n");
if shaper {
for i in 0..size {
if i > 0 {
text.push(' ');
}
text.push_str(&format!("{}", (1023.0 * i as f64 / (size - 1) as f64).round()));
}
text.push('\n');
}
for r in 0..size {
for g in 0..size {
for b in 0..size {
let v = [r, g, b].map(|c| (max - max * c as f64 / (size - 1) as f64).round());
text.push_str(&format!("{} {} {}\n", v[0], v[1], v[2]));
}
}
}
text
}
#[test]
fn three_dl_mesh_three_point_shaper_is_not_a_node() {
// #9078: Photoshop loads a 3³ cube whose shaper line has three values; counting it as a
// 28th node rejected the whole file.
let l = parse_3dl(&mesh_3dl(1, 12, 3, 4095.0, true)).unwrap();
assert_eq!(l.size, 3);
assert_eq!(l.data.len(), 3 * 3 * 3 * 3);
// The inverse identity: node (0,0,0) is full, node (2,2,2) black.
assert!((l.data[0] - 1.0).abs() < 1e-6 && (l.data[1] - 1.0).abs() < 1e-6 && (l.data[2] - 1.0).abs() < 1e-6);
let last = &l.data[l.data.len() - 3..];
assert_eq!(last, [0.0, 0.0, 0.0]);
// The same 27 nodes without the shaper row still load (the node-only control).
assert_eq!(parse_3dl(&mesh_3dl(1, 12, 3, 4095.0, false)).unwrap().data, l.data);
}
#[test]
fn three_dl_mesh_declares_the_output_depth() {
// #9073: identical node codes divide by the declared range, not by the largest value.
let mut text_10 = String::new();
let mut text_12 = String::new();
for (n_bits, out_bits, dst) in [(2, 10, &mut text_10), (2, 12, &mut text_12)] {
// A 5³ identity scaled to 10-bit codes (max 1023).
*dst = format!("3DMESH\nMesh {n_bits} {out_bits}\n0 256 512 768 1023\n");
for r in 0..5 {
for g in 0..5 {
for b in 0..5 {
dst.push_str(&format!("{} {} {}\n", r * 255, g * 255, b * 255));
}
}
}
}
let white_10 = parse_3dl(&text_10).unwrap();
let white_12 = parse_3dl(&text_12).unwrap();
assert_eq!(white_10.size, 5);
let last_10 = &white_10.data[white_10.data.len() - 3..];
let last_12 = &white_12.data[white_12.data.len() - 3..];
assert!((last_10[0] - 1020.0 / 1023.0).abs() < 1e-6, "{last_10:?}");
// 1020/4095 ≈ 0.249: white renders grey, as Photoshop measures it.
assert!((last_12[0] - 1020.0 / 4095.0).abs() < 1e-6, "{last_12:?}");
}
#[test]
fn three_dl_mesh_header_mismatch_is_rejected() {
// A Mesh header that disagrees with the row count is refused, not silently re-inferred.
assert!(parse_3dl("3DMESH\nMesh 1 12\n0 0 0\n0 0 1\n").is_err());
// A node beyond the declared range is a wrong declaration: the old inference from the
// largest value keeps the file loading as it did before the header was honoured.
let mut text = String::from("3DMESH\nMesh 1 10\n");
for r in 0..3 {
for g in 0..3 {
for b in 0..3 {
text.push_str(&format!("{} {} {}\n", r * 2047, g * 2047, b * 2047));
}
}
}
let l = parse_3dl(&text).unwrap();
let last = &l.data[l.data.len() - 3..];
assert!((last[0] - 4094.0 / 4095.0).abs() < 1e-6, "{last:?}");
}
#[test]
fn three_dl_mesh_extra_node_cannot_replace_a_captured_shaper() {
for (bits, size) in [(2, 5), (3, 9)] {
let mut text = mesh_3dl(bits, 12, size, 4095.0, true);
let valid = parse_3dl(&text).unwrap();
assert_eq!(valid.size, size);
assert_eq!(valid.data, parse_3dl(&mesh_3dl(bits, 12, size, 4095.0, false)).unwrap().data);
text.push_str("4095 4095 4095\n");
let error = parse_3dl(&text).unwrap_err().to_string();
assert!(error.contains(&format!("expected {} rows", size * size * size)), "{error}");
}
}
#[test]
fn three_dl_malformed_mesh_header_falls_back_to_inference() {
// A `Mesh` line that is not exactly two integer fields is not a declaration: it is
// ignored and the table is inferred as if headerless, rather than recovering numbers
// from the wrong positions (#9078). A 2³ cube would otherwise be read as a 3³ cube.
for header in ["Mesh invalid 1 12", "Mesh 1 12 13", "Mesh 1 x", "Mesh 1"] {
let mut text = format!("3DMESH\n{header}\n");
for r in 0..2 {
for g in 0..2 {
for b in 0..2 {
text.push_str(&format!("{} {} {}\n", r * 1023, g * 1023, b * 1023));
}
}
}
let l = parse_3dl(&text).unwrap();
assert_eq!(l.size, 2, "{header}");
assert_eq!(l.data, LutFile::identity(2).unwrap().data, "{header}");
}
}
#[test]
fn three_dl_mesh_uses_declared_range_for_small_integer_codes() {
// #9073: under a valid `Mesh` declaration the node codes are integers in the declared
// range, so a max value of 1 is 1/4095 of full output — not full output itself.
let mut text = String::from("3DMESH\nMesh 1 12\n");
for r in 0..3 {
for g in 0..3 {
for b in 0..3 {
let v = u8::from(r == 0 && g == 0 && b == 0);
text.push_str(&format!("{v} {v} {v}\n"));
}
}
}
let l = parse_3dl(&text).unwrap();
assert_eq!(l.size, 3);
// blue fastest: node (0,0,0) is the first entry, code 1 → 1/4095.
assert!((l.data[0] - 1.0 / 4095.0).abs() < 1e-6, "{:?}", &l.data[0..3]);
assert!(l.data[3..].iter().all(|&v| v == 0.0), "{:?}", l.data);
}
#[test]
fn look_data_is_little_endian_float32() {
// Bytes written out by hand rather than by the encoder the parser mirrors, so a wrong byte
// order fails: 0.25, 0.5, 1.0 (3E800000, 3F000000, 3F800000 stored low byte first), then zeros.
let hex = format!("0000803E 0000003F 0000803F {}", "00000000 ".repeat(21));
let xml = format!("<?xml version=\"1.0\"?><look><LUT><size>\"2\"</size><data>\"{hex}\"</data></LUT></look>");
let data = parse("a.look", xml.as_bytes()).unwrap().data;
assert_eq!(data[..3], [0.25, 0.5, 1.0]);
assert!(data[3..].iter().all(|&v| v == 0.0));
}
#[test]
fn look_reads_utf16_with_either_byte_order() {
let id = LutFile::identity(2).unwrap();
let hex: String = id.data.iter().flat_map(|v| v.to_le_bytes()).map(|b| format!("{b:02X}")).collect();
let xml = format!("<?xml version=\"1.0\" encoding=\"UTF-16\"?><look><LUT><size>\"2\"</size><data>\"{hex}\"</data></LUT></look>");
let le: Vec<u8> = [0xFF, 0xFE].into_iter().chain(xml.encode_utf16().flat_map(u16::to_le_bytes)).collect();
let be: Vec<u8> = [0xFE, 0xFF].into_iter().chain(xml.encode_utf16().flat_map(u16::to_be_bytes)).collect();
assert_eq!(parse("a.look", &le).unwrap().data, id.data);
assert_eq!(parse("a.look", &be).unwrap().data, id.data);
// Sniffed as XML through the byte-order mark too, so the recorded format is the one parsed.
assert_eq!(Format::detect("a.lut", &le), Format::Look);
assert_eq!(parse_as(Format::Look, &be).unwrap().data, id.data);
}
#[test]
fn look_ignores_tags_inside_xml_comments() {
let hex = |l: &LutFile| -> String { l.data.iter().flat_map(|v| v.to_le_bytes()).map(|b| format!("{b:02X}")).collect() };
let inverse = LutFile::from_fn("", 2, |[r, g, b]| [1.0 - r, 1.0 - g, 1.0 - b]).unwrap();
let xml = format!(
"<look><!-- <size>\"3\"</size><data>\"{}\"</data> --><LUT><size>\"2\"</size><data>\"{}\"</data></LUT><!-- unterminated <data>00",
hex(&LutFile::identity(2).unwrap()),
hex(&inverse)
);
assert_eq!(parse("commented.look", xml.as_bytes()).unwrap().data, inverse.data);
}
#[test]
fn look_rgb_and_rgba_allow_whitespace_in_hex_data() {
let id = LutFile::identity(2).unwrap();
for channels in [3, 4] {
let mut hex = String::new();
for rgb in id.data.as_chunks::<3>().0 {
for value in rgb.iter().copied().chain((channels == 4).then_some(1.0)) {
for byte in value.to_le_bytes() {
hex.push_str(&format!("{byte:02x} \t\r\n"));
}
}
}
let xml = format!("<look><size>2</size><data>\"{hex}\"</data></look>");
assert_eq!(parse("valid.look", xml.as_bytes()).unwrap().data, id.data);
}
}
#[test]
fn look_rejects_partial_floats_and_invalid_hex() {
let id = LutFile::identity(2).unwrap();
let hex: String = id.data.iter().flat_map(|v| v.to_le_bytes()).map(|b| format!("{b:02X}")).collect();
for suffix in ["0", "00", "0000", "000000", "G", "é"] {
let xml = format!("<look><size>2</size><data>{hex}{suffix}</data></look>");
assert!(parse("bad.look", xml.as_bytes()).is_err(), "accepted malformed suffix {suffix:?}");
}
let invalid = hex.replacen('0', "G", 1);
let xml = format!("<look><size>2</size><data>{invalid}</data></look>");
assert!(parse("bad.look", xml.as_bytes()).unwrap_err().0.contains("invalid hexadecimal"));
let xml = format!("<look><size>2</size><data>{hex}00</data></look>");
assert!(parse("bad.look", xml.as_bytes()).unwrap_err().0.contains("incomplete float"));
}
#[test]
fn format_detection_matches_parse() {
assert_eq!(Format::detect("a.3DL", b"<look>"), Format::ThreeDl);
assert_eq!(Format::detect("a.Look", b""), Format::Look);
assert_eq!(Format::detect("a.cube", b" <look>"), Format::Look, "XML is sniffed as .look");
assert_eq!(Format::detect("a.txt", b"LUT_3D_SIZE 2"), Format::Cube);
assert_eq!(Format::ThreeDl.extension(), "3dl");
let text = write_cube(&LutFile::identity(2).unwrap());
assert_eq!(parse_as(Format::Cube, text.as_bytes()), parse("a.cube", text.as_bytes()));
}
#[test]
fn annotated_cube_export_preserves_header_and_integer_precision() {
let mut lut = LutFile::identity(2).unwrap();
lut.title = "My \"Look\"".into();
lut.data[..3].copy_from_slice(&[1.0 / 6.0, 5.0 / 6.0, 160.0 / 255.0]);
let output = write_cube_export("PhotoCraft", &lut.title, lut.size, true, lut.data.as_chunks::<3>().0.iter().copied());
assert!(output.starts_with("#Created by: PhotoCraft\nTITLE \"My 'Look'\"\n\n#LUT size\nLUT_3D_SIZE 2\n\n#data domain\nDOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n\n#LUT data points\n0.166656 0.833344 0.627441\n"));
assert_eq!(output.lines().count(), 11 + 8);
let parsed = parse_cube(&output).unwrap();
assert_eq!(parsed.size, 2);
assert_eq!(&parsed.data[3..], &lut.data[3..]);
let float = write_cube_export("PhotoCraft", &lut.title, lut.size, false, lut.data.as_chunks::<3>().0.iter().copied());
assert!(float.contains("0.166667 0.833333 0.627451\n"));
}
#[test]
fn annotated_empty_title_and_float_clamping() {
let text = write_cube_export("Exporter", "", 2, false, std::iter::repeat_n([-0.5, 0.25, 1.5], 8));
assert!(text.contains("TITLE \"\"\n"));
let back = parse_cube(&text).unwrap();
assert_eq!(back.data, [0.0, 0.25, 1.0].repeat(8));
}
}
#[cfg(test)]
mod profile_cube_tests {
use super::*;
fn cube(prefix: &str) -> String {
format!("{prefix}\nLUT_3D_SIZE 2\n{}", "0.25 0.5 0.75\n".repeat(8))
}
#[test]
fn profile_preserves_optional_literal_title_and_domains() {
let no_title = parse_cube_3d(&cube(""), 256).unwrap();
assert_eq!(no_title.title, None);
let value = parse_cube_3d(&cube("TITLE \"look # literal\"\nDOMAIN_MIN 1 0 2\nDOMAIN_MAX 0 0 1"), 256).unwrap();
assert_eq!(value.title.as_deref(), Some("look # literal"));
assert_eq!(value.domain_min, [1.0, 0.0, 2.0]);
assert_eq!(value.domain_max, [0.0, 0.0, 1.0]);
assert_eq!(value.data, vec![[0.25, 0.5, 0.75]; 8]);
assert_eq!(parse_cube_3d(&cube("TITLE \"\""), 256).unwrap().title.as_deref(), Some(""));
assert!(parse_cube(&cube("DOMAIN_MIN 1 0 2\nDOMAIN_MAX 0 0 1")).is_err());
}
#[test]
fn profile_limits_are_checked_without_large_allocations() {
assert!(parse_cube_3d("LUT_3D_SIZE 256", 256).unwrap_err().0.contains("16777216"));
assert!(parse_cube_3d("LUT_3D_SIZE 257", 256).unwrap_err().0.contains("out of range"));
assert!(parse_cube_3d("LUT_3D_SIZE 256", 129).unwrap_err().0.contains("out of range"));
assert!(parse_cube_3d(&cube(""), usize::MAX).is_err());
assert!(parse_cube_3d(&cube(""), 1).is_err());
assert!(parse_cube_3d(&format!("{}0 0 0\n", cube("")), 2).unwrap_err().0.contains("budget"));
assert!(parse_cube_3d("LUT_1D_SIZE 2\n0 0 0\n1 1 1", 256).is_err());
}
#[test]
fn every_numeric_token_must_be_valid_and_finite() {
for row in ["0 ignored 0 0", "0 0 0 ignored", "NaN 0 0", "inf 0 0", "0 0 -inf", "1e39 0 0", "0 0", "0 0 0 0"] {
assert!(parse_cube_3d(&format!("LUT_3D_SIZE 2\n{row}\n{}", "0 0 0\n".repeat(7)), 256).is_err(), "{row}");
assert!(parse_cube_3d(&cube(&format!("DOMAIN_MIN {row}")), 256).is_err(), "{row}");
}
}
#[test]
fn standard_reader_keeps_quoted_comments_and_1d_expansion() {
assert_eq!(parse_cube(&cube("TITLE \"look # preserved\" # comment")).unwrap().title, "look # preserved");
let value = parse_cube("LUT_1D_SIZE 2\n0 0 0\n1 1 1").unwrap();
assert_eq!(value.size, 33);
assert!(parse_cube_3d(&cube("DOMAIN_MIN 0 0 0 # not a whole-line comment"), 256).is_err());
}
}