Files
craft-libs/crates/cms/src/pipeline.rs
T
Dylan M. Taylor 628a235ae5 craft-cms: the changes PhotoCraft made to its copy since extraction (#858)
* craft-cms: the changes PhotoCraft made to its copy since extraction

PhotoCraft kept editing crates/cms after craft-cms was extracted from it at
storytold/photocraft@b3222ee8. This ports its 41 commits up to
storytold/photocraft@0143b148 with a three-way merge per file, keeping the
changes craft-cms made on its own (Result-returning API, white preservation,
FOGRA39, named colours, profile ID).

Ported: the .3dl shaper, Mesh header, UTF-16 and .look fixes in lutfile; the
checked ICC offsets and the per-profile curve sample budget; same_bytes and the
byte-confirmed transform cache; the blocked matrix/TRC path and the 8-bit
first-stage table; GpuMatrixShaper; cicp_rgb; the ACEScg and Dot Gain 20 %
built-ins (the latter now the default gray); bisection for a table's flat ends;
PhotoCraft spelled with a capital C in the built-in descriptions, with the
shipped coated CMYK profile's bytes as PhotoCraft regenerated them.

Not taken, because craft-cms already does it another way: Curve::inverse_table
(inverse64_many), the effective-dimension loop in multilinear interpolation,
the curve-count and mluc checks, and the .cube DOMAIN writer.

The 8-bit first-stage table checks device white as the exact path does.

Refs #779

* craft-cms: Lut3d::from_fn

PhotoCraft's proof and HDR display tables are built from a chain of several
transforms, which it wrote into Lut3d's fields. Those are private here, so
from_fn samples any RGB function, with the same size bounds as from_transform.

Refs #779

* craft-cms: README names Lut3d::from_fn
2026-11-11 18:37:23 -05:00

348 lines
13 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.
//! Float evaluation pipelines: a list of stages mapping normalised device values to the
//! profile connection space (or back). This is the exact reference path; [`crate::Transform`]
//! builds faster lookup tables from it.
use crate::clut::Clut;
use crate::curve::Curve;
use crate::{CmsError, check_len, invalid_arg, math};
/// Largest channel count flowing through a pipeline.
pub const MAX: usize = 16;
/// One processing element.
#[derive(Clone, Debug, PartialEq)]
pub enum Stage {
/// Per-channel curves.
Curves(Vec<Curve>),
/// Per-channel inverse curves.
InvCurves(Vec<Curve>),
/// `out[r] = Σ m[r][c]·in[c] + offset[r]`, `rows × cols`.
Matrix {
rows: usize,
cols: usize,
m: Vec<f64>,
offset: Vec<f64>,
},
Clut(Clut),
/// Float CIE Lab (L 0–100) → XYZ (D50, Y = 1).
LabToXyz,
XyzToLab,
/// ICC v4 / 8-bit Lab encoding (normalised) → float Lab, and back.
DecodeLabV4,
EncodeLabV4,
/// ICC v2 legacy 16-bit Lab encoding (used by `lut16Type`) → float Lab, and back.
DecodeLabV2,
EncodeLabV2,
/// u1Fixed15 XYZ encoding (normalised over 0..=0xFFFF) → XYZ, and back.
DecodeXyz,
EncodeXyz,
/// Clamp every channel to `[0, 1]`.
Clamp01,
}
const XYZ_SCALE: f32 = 65535.0 / 32768.0;
const V2_L: f32 = 100.0 * 65535.0 / 65280.0;
const V2_AB: f32 = 255.0 * 65535.0 / 65280.0;
impl Stage {
/// Output channel count given `n` inputs.
pub fn outputs(&self, n: usize) -> usize {
match self {
Stage::Matrix { rows, .. } => *rows,
Stage::Clut(c) => c.outputs,
_ => n,
}
}
/// Checks that the stage can run on `n` channels: matrix shapes match their data and
/// channel counts stay within [`MAX`].
fn check(&self, n: usize) -> Result<(), CmsError> {
if let Stage::Matrix { rows, cols, m, offset } = self
&& (!(1..=MAX).contains(rows) || !(1..=MAX).contains(cols) || m.len() != rows * cols || offset.len() != *rows)
{
return Err(invalid_arg(format!(
"{rows}×{cols} matrix stage with {} coefficients and {} offsets (1 to {MAX} rows and columns)",
m.len(),
offset.len()
)));
}
let out = self.outputs(n);
if !(1..=MAX).contains(&out) {
return Err(invalid_arg(format!("pipeline stage with {out} outputs (1 to {MAX})")));
}
Ok(())
}
pub fn matrix3(m: &math::Mat3) -> Stage {
Stage::Matrix { rows: 3, cols: 3, m: m.iter().flatten().copied().collect(), offset: vec![0.0; 3] }
}
/// Runs the stage on `n` channels. `edges` holds, for inverse curves, each curve's
/// [`Curve::inverse_edges`].
#[inline]
fn run(&self, v: &mut [f32; MAX], n: usize, edges: &[Option<(f32, f32)>]) -> usize {
match self {
Stage::Curves(cs) => {
for (x, c) in v.iter_mut().zip(cs) {
*x = c.eval(*x);
}
n
}
Stage::InvCurves(cs) => {
for (i, (x, c)) in v.iter_mut().zip(cs).enumerate() {
*x = c.eval_inverse_with(*x, edges.get(i).copied().flatten());
}
n
}
Stage::Matrix { rows, cols, m, offset } => {
let mut o = [0.0f32; MAX];
for r in 0..*rows {
let mut s = offset[r];
for c in 0..*cols {
s += m[r * cols + c] * v[c] as f64;
}
o[r] = s as f32;
}
v[..*rows].copy_from_slice(&o[..*rows]);
*rows
}
Stage::Clut(c) => {
let mut o = [0.0f32; MAX];
let mut inp = [0.0f32; MAX];
inp[..n].copy_from_slice(&v[..n]);
c.interp(&inp[..c.inputs], &mut o[..c.outputs]);
v[..c.outputs].copy_from_slice(&o[..c.outputs]);
c.outputs
}
Stage::LabToXyz => {
let x = math::lab_to_xyz_f32([v[0], v[1], v[2]]);
v[..3].copy_from_slice(&x);
3
}
Stage::XyzToLab => {
let l = math::xyz_to_lab_f32([v[0].max(0.0), v[1].max(0.0), v[2].max(0.0)]);
v[..3].copy_from_slice(&l);
3
}
Stage::DecodeLabV4 => {
v[0] *= 100.0;
v[1] = v[1] * 255.0 - 128.0;
v[2] = v[2] * 255.0 - 128.0;
3
}
Stage::EncodeLabV4 => {
v[0] = (v[0] / 100.0).clamp(0.0, 1.0);
v[1] = ((v[1] + 128.0) / 255.0).clamp(0.0, 1.0);
v[2] = ((v[2] + 128.0) / 255.0).clamp(0.0, 1.0);
3
}
Stage::DecodeLabV2 => {
v[0] *= V2_L;
v[1] = v[1] * V2_AB - 128.0;
v[2] = v[2] * V2_AB - 128.0;
3
}
Stage::EncodeLabV2 => {
v[0] = (v[0] / V2_L).clamp(0.0, 1.0);
v[1] = ((v[1] + 128.0) / V2_AB).clamp(0.0, 1.0);
v[2] = ((v[2] + 128.0) / V2_AB).clamp(0.0, 1.0);
3
}
Stage::DecodeXyz => {
for x in &mut v[..3] {
*x *= XYZ_SCALE;
}
3
}
Stage::EncodeXyz => {
for x in &mut v[..3] {
*x = (*x / XYZ_SCALE).clamp(0.0, 1.0);
}
3
}
Stage::Clamp01 => {
for x in &mut v[..n] {
*x = x.clamp(0.0, 1.0);
}
n
}
}
}
}
/// A sequence of stages with fixed input and output channel counts.
#[derive(Clone, Debug, PartialEq)]
pub struct Pipeline {
inputs: usize,
outputs: usize,
stages: Vec<Stage>,
/// For each stage, the flat-run ends of its inverse curves ([`Curve::inverse_edges`]), so
/// evaluating a long, flat sampled curve does not scan it again for every pixel. Empty for
/// other stages.
edges: Vec<Vec<Option<(f32, f32)>>>,
}
/// The [`Pipeline::edges`] entry for `stage`.
fn stage_edges(stage: &Stage) -> Vec<Option<(f32, f32)>> {
match stage {
Stage::InvCurves(cs) => cs.iter().map(Curve::inverse_edges).collect(),
_ => Vec::new(),
}
}
impl Pipeline {
/// A pipeline over `inputs` channels (1 to [`MAX`]). Refuses stages that cannot run on the
/// channels reaching them with [`CmsError::InvalidArgument`].
pub fn new(inputs: usize, stages: Vec<Stage>) -> Result<Self, CmsError> {
if !(1..=MAX).contains(&inputs) {
return Err(invalid_arg(format!("pipeline with {inputs} inputs (1 to {MAX})")));
}
let mut p = Pipeline { inputs, outputs: inputs, stages: Vec::with_capacity(stages.len()), edges: Vec::with_capacity(stages.len()) };
p.extend(stages)?;
Ok(p)
}
pub fn inputs(&self) -> usize {
self.inputs
}
pub fn outputs(&self) -> usize {
self.outputs
}
pub fn stages(&self) -> &[Stage] {
&self.stages
}
/// Appends stages, checked as in [`Pipeline::new`]; on error the pipeline is unchanged.
pub fn extend(&mut self, stages: impl IntoIterator<Item = Stage>) -> Result<(), CmsError> {
let mut n = self.outputs;
let mut added = Vec::new();
for s in stages {
s.check(n)?;
n = s.outputs(n);
added.push(s);
}
self.edges.extend(added.iter().map(stage_edges));
self.stages.extend(added);
self.outputs = n;
Ok(())
}
/// Evaluates one pixel: `input` has at least `inputs` values, `out` receives `outputs`
/// values.
pub fn eval(&self, input: &[f32], out: &mut [f32]) -> Result<(), CmsError> {
check_len("pipeline input", input.len(), self.inputs)?;
check_len("pipeline output", out.len(), self.outputs)?;
self.run(input, out);
Ok(())
}
/// [`Pipeline::eval`] for callers that guarantee the slice lengths.
#[inline]
pub(crate) fn run(&self, input: &[f32], out: &mut [f32]) {
let mut v = [0.0f32; MAX];
v[..self.inputs].copy_from_slice(&input[..self.inputs]);
let mut n = self.inputs;
for (s, edges) in self.stages.iter().zip(&self.edges) {
n = s.run(&mut v, n, edges);
}
out[..self.outputs].copy_from_slice(&v[..self.outputs]);
}
/// Evaluates the stages after the first one on values already passed through it.
#[inline]
pub(crate) fn eval_after_first(&self, v: &mut [f32; MAX], out: &mut [f32]) {
let mut n = self.inputs;
for (s, edges) in self.stages.iter().zip(&self.edges).skip(1) {
n = s.run(v, n, edges);
}
out[..self.outputs].copy_from_slice(&v[..self.outputs]);
}
/// Removes no-op stages and cancels adjacent inverse pairs (Lab↔XYZ, encode/decode).
pub fn optimize(&mut self) {
let mut out: Vec<Stage> = Vec::with_capacity(self.stages.len());
for s in self.stages.drain(..) {
let noop = match &s {
Stage::Curves(c) | Stage::InvCurves(c) => c.iter().all(Curve::is_identity),
Stage::Matrix { rows: 3, cols: 3, m, offset } => {
offset.iter().all(|o| o.abs() < 1e-12)
&& m.iter().enumerate().all(|(i, v)| (v - if i % 4 == 0 { 1.0 } else { 0.0 }).abs() < 1e-12)
}
_ => false,
};
if noop {
continue;
}
let cancels = matches!(
(out.last(), &s),
(Some(Stage::LabToXyz), Stage::XyzToLab)
| (Some(Stage::XyzToLab), Stage::LabToXyz)
| (Some(Stage::EncodeLabV4), Stage::DecodeLabV4)
| (Some(Stage::EncodeLabV2), Stage::DecodeLabV2)
| (Some(Stage::EncodeXyz), Stage::DecodeXyz)
);
// Decode→encode of the same encoding is only exact inside the gamut of the encoding,
// which always holds for data coming out of a table, so those pairs cancel too.
let cancels_dec = matches!(
(out.last(), &s),
(Some(Stage::DecodeLabV4), Stage::EncodeLabV4)
| (Some(Stage::DecodeLabV2), Stage::EncodeLabV2)
| (Some(Stage::DecodeXyz), Stage::EncodeXyz)
);
if cancels || cancels_dec {
out.pop();
continue;
}
// Merge consecutive 3×3 matrices.
if let (Some(Stage::Matrix { rows: 3, cols: 3, m: a, offset: oa }), Stage::Matrix { rows: 3, cols: 3, m: b, offset: ob }) =
(out.last(), &s)
{
let mut m = vec![0.0; 9];
let mut off = vec![0.0; 3];
for r in 0..3 {
for c in 0..3 {
m[r * 3 + c] = (0..3).map(|k| b[r * 3 + k] * a[k * 3 + c]).sum();
}
off[r] = (0..3).map(|k| b[r * 3 + k] * oa[k]).sum::<f64>() + ob[r];
}
out.pop();
out.push(Stage::Matrix { rows: 3, cols: 3, m, offset: off });
continue;
}
out.push(s);
}
self.edges = out.iter().map(stage_edges).collect();
self.stages = out;
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn inverse_curves_keep_their_flat_ends_through_extend_and_optimize() {
let mut flat = vec![0.25f32; 300];
flat.extend((0..300).map(|i| 0.25 + i as f32 / 600.0));
flat.extend([0.75f32; 300]);
let curves = vec![Curve::Table(flat.clone()), Curve::Table(flat.iter().rev().copied().collect()), Curve::Table(vec![0.5; 1000])];
let mut p = Pipeline::new(3, vec![Stage::Clamp01]).unwrap();
p.extend([Stage::matrix3(&[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]), Stage::InvCurves(curves.clone())]).unwrap();
let check = |p: &Pipeline| {
assert_eq!(p.edges.len(), p.stages.len());
for i in 0..=200 {
let y = i as f32 / 200.0;
let mut out = [0.0f32; 3];
p.eval(&[y; 3], &mut out).unwrap();
let want: Vec<f32> = curves.iter().map(|c| c.eval_inverse(y)).collect();
assert_eq!(out.to_vec(), want, "{y}");
}
};
check(&p);
// Optimising drops the identity matrix; the cached ends must follow the stages.
p.optimize();
assert_eq!(p.stages().len(), 2);
check(&p);
}
}