mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-18 00:05:08 +00:00
* 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
348 lines
13 KiB
Rust
348 lines
13 KiB
Rust
//! 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);
|
||
}
|
||
}
|