Skip to main content

kallo_core/
lut.rs

1//! A baked lookup table for the spectral exposure.
2//!
3//! The hybrid reconstruction costs a non-negative least squares per pixel, which
4//! is fine for a benchmark and hopeless for a 24 MP image. But the expensive part
5//! produces only three numbers: the log exposure of each film layer. So the model
6//! can be *distilled* into a three-dimensional table over RGB and interpolated
7//! per pixel.
8//!
9//! The table is indexed on a **logarithmic** axis. Linear light spans several
10//! decades between a shadow and a highlight, and a linear axis would spend most
11//! of its resolution on values nobody photographs. Uniform steps in log10 give
12//! uniform resolution in stops.
13
14use std::path::{Path, PathBuf};
15
16use crate::spectral::SpectralContext;
17
18/// Magic bytes at the start of a baked table.
19const MAGIC: &[u8; 4] = b"KLUT";
20/// Format version. Bumped when the layout changes.
21const VERSION: u16 = 2;
22/// Channels per sample: the model has always produced three.
23const CHANNELS: u16 = 3;
24/// Largest side accepted on read, to bound allocation from a hostile file.
25const MAX_SIZE: usize = 256;
26
27/// A baked table could not be written or read.
28#[derive(Debug)]
29pub enum LutError {
30    /// The file could not be opened, read or written.
31    Io {
32        /// The path that failed.
33        path: PathBuf,
34        /// The underlying OS error.
35        source: std::io::Error,
36    },
37    /// The file does not start with `KLUT`.
38    Magic,
39    /// The file was written by a future or older layout.
40    Version(u16),
41    /// The declared side length is outside the accepted range.
42    Size(u32),
43    /// The sample count or channel count does not match the header.
44    Layout,
45    /// The payload does not match its checksum.
46    Checksum,
47    /// The table declares a provenance string longer than the header allows.
48    ProvenanceTooLong,
49}
50
51impl std::fmt::Display for LutError {
52    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
53        match self {
54            Self::Io { path, source } => write!(f, "could not access {}: {source}", path.display()),
55            Self::Magic => write!(f, "not a Kallo lookup table"),
56            Self::Version(version) => write!(f, "unsupported table version {version}"),
57            Self::Size(size) => write!(f, "table side {size} is outside 2..={MAX_SIZE}"),
58            Self::Layout => write!(f, "the table's declared layout does not match its size"),
59            Self::Checksum => write!(f, "the table is corrupt (checksum mismatch)"),
60            Self::ProvenanceTooLong => write!(f, "the table's provenance string is too long"),
61        }
62    }
63}
64
65impl std::error::Error for LutError {
66    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
67        match self {
68            Self::Io { source, .. } => Some(source),
69            _ => None,
70        }
71    }
72}
73
74fn crc32(bytes: &[u8]) -> u32 {
75    let mut crc = 0xFFFF_FFFF_u32;
76    for byte in bytes {
77        crc ^= u32::from(*byte);
78        for _ in 0..8 {
79            let mask = (crc & 1).wrapping_neg();
80            crc = (crc >> 1) ^ (0xEDB8_8320 & mask);
81        }
82    }
83    !crc
84}
85
86/// log10 of the smallest input the table covers.
87pub const LOG_RANGE_MIN: f64 = -4.0;
88/// log10 of the largest input the table covers.
89pub const LOG_RANGE_MAX: f64 = 0.602_06; // log10(4.0)
90
91/// A cubed lookup table mapping linear RGB to per-layer log exposure.
92#[derive(Debug, Clone)]
93pub struct ExposureLut {
94    size: usize,
95    /// `size^3` entries, index order `(r, g, b)`.
96    data: Vec<[f32; 3]>,
97    /// Which model baked it: camera, film, grid. Descriptive and checkable.
98    identity: String,
99}
100
101impl ExposureLut {
102    /// Bake a table by sampling `context` on a `size^3` grid.
103    ///
104    /// A size of 33 gives about 36 k samples: a few hundred milliseconds in
105    /// release, half a megabyte on disk as `f32`.
106    ///
107    /// # Panics
108    ///
109    /// Panics if `size < 2`.
110    #[must_use]
111    pub fn bake(size: usize, context: &SpectralContext) -> Self {
112        assert!(
113            size >= 2,
114            "a lookup table needs at least two samples per axis"
115        );
116        let mut data = Vec::with_capacity(size * size * size);
117        for r in 0..size {
118            let red = decode(r, size);
119            for g in 0..size {
120                let green = decode(g, size);
121                for b in 0..size {
122                    let blue = decode(b, size);
123                    let log_e = context
124                        .expose([red, green, blue])
125                        .unwrap_or([LOG_RANGE_MIN; 3]);
126                    data.push([log_e[0] as f32, log_e[1] as f32, log_e[2] as f32]);
127                }
128            }
129        }
130        Self {
131            size,
132            data,
133            identity: context.identity(),
134        }
135    }
136
137    /// The model identity recorded at bake time.
138    #[must_use]
139    pub fn identity(&self) -> &str {
140        &self.identity
141    }
142
143    /// Number of samples per axis.
144    #[must_use]
145    pub fn size(&self) -> usize {
146        self.size
147    }
148
149    /// Bytes the table would occupy on disk as `f32`.
150    #[must_use]
151    pub fn byte_size(&self) -> usize {
152        self.data.len() * 3 * std::mem::size_of::<f32>()
153    }
154
155    /// Write the table to `path` in the `.klut` format.
156    ///
157    /// Layout, little endian: magic (4), version (u16), side (u32),
158    /// channels (u16), `side^3 * 3` f32, crc32 of everything before it.
159    ///
160    /// # Errors
161    ///
162    /// Returns [`LutError::Io`] if the file cannot be written.
163    pub fn write(&self, path: impl AsRef<Path>) -> Result<(), LutError> {
164        let path = path.as_ref();
165        let identity = self.identity.as_bytes();
166        let Ok(identity_len) = u16::try_from(identity.len()) else {
167            return Err(LutError::ProvenanceTooLong);
168        };
169
170        let mut bytes = Vec::with_capacity(14 + identity.len() + self.data.len() * 12 + 4);
171        bytes.extend_from_slice(MAGIC);
172        bytes.extend_from_slice(&VERSION.to_le_bytes());
173        bytes.extend_from_slice(&(self.size as u32).to_le_bytes());
174        bytes.extend_from_slice(&CHANNELS.to_le_bytes());
175        bytes.extend_from_slice(&identity_len.to_le_bytes());
176        bytes.extend_from_slice(identity);
177        for entry in &self.data {
178            for value in entry {
179                bytes.extend_from_slice(&value.to_le_bytes());
180            }
181        }
182        let checksum = crc32(&bytes);
183        bytes.extend_from_slice(&checksum.to_le_bytes());
184
185        std::fs::write(path, bytes).map_err(|source| LutError::Io {
186            path: path.to_path_buf(),
187            source,
188        })
189    }
190
191    /// Read a table written by [`Self::write`].
192    ///
193    /// # Errors
194    ///
195    /// Returns a [`LutError`] for a missing file, a foreign format, a future
196    /// version, a size outside `2..=256`, a layout mismatch, or a bad checksum.
197    pub fn read(path: impl AsRef<Path>) -> Result<Self, LutError> {
198        let path = path.as_ref();
199        let bytes = std::fs::read(path).map_err(|source| LutError::Io {
200            path: path.to_path_buf(),
201            source,
202        })?;
203
204        if bytes.len() < 18 || &bytes[0..4] != MAGIC {
205            return Err(LutError::Magic);
206        }
207        let version = u16::from_le_bytes([bytes[4], bytes[5]]);
208        if version != VERSION {
209            return Err(LutError::Version(version));
210        }
211        let size = u32::from_le_bytes([bytes[6], bytes[7], bytes[8], bytes[9]]) as usize;
212        if !(2..=MAX_SIZE).contains(&size) {
213            return Err(LutError::Size(size as u32));
214        }
215        let channels = u16::from_le_bytes([bytes[10], bytes[11]]);
216        if channels != CHANNELS {
217            return Err(LutError::Layout);
218        }
219
220        let identity_len = u16::from_le_bytes([bytes[12], bytes[13]]) as usize;
221        let payload_start = 14 + identity_len;
222        let expected = payload_start + size * size * size * usize::from(CHANNELS) * 4;
223        if bytes.len() != expected + 4 {
224            return Err(LutError::Layout);
225        }
226        let stored = u32::from_le_bytes([
227            bytes[expected],
228            bytes[expected + 1],
229            bytes[expected + 2],
230            bytes[expected + 3],
231        ]);
232        if crc32(&bytes[..expected]) != stored {
233            return Err(LutError::Checksum);
234        }
235
236        let identity = String::from_utf8_lossy(&bytes[14..payload_start]).into_owned();
237
238        let mut data = Vec::with_capacity(size * size * size);
239        for chunk in bytes[payload_start..expected].chunks_exact(12) {
240            let mut entry = [0.0_f32; 3];
241            for (index, value) in entry.iter_mut().enumerate() {
242                let offset = index * 4;
243                *value = f32::from_le_bytes([
244                    chunk[offset],
245                    chunk[offset + 1],
246                    chunk[offset + 2],
247                    chunk[offset + 3],
248                ]);
249            }
250            data.push(entry);
251        }
252
253        Ok(Self {
254            size,
255            data,
256            identity,
257        })
258    }
259
260    /// Trilinear interpolation, clamped at the edges.
261    #[must_use]
262    pub fn sample(&self, rgb: [f64; 3]) -> [f64; 3] {
263        let positions = rgb.map(|value| encode(value) * (self.size - 1) as f64);
264        let lower = positions.map(|p| (p.floor() as usize).min(self.size - 1));
265        let upper = lower.map(|l| (l + 1).min(self.size - 1));
266        let weights = std::array::from_fn::<f64, 3, _>(|axis| {
267            let p = positions[axis];
268            let base = lower[axis] as f64;
269            (p - base).clamp(0.0, 1.0)
270        });
271
272        let mut out = [0.0_f64; 3];
273        for corner in 0..8 {
274            let pick = |axis: usize| {
275                if (corner >> axis) & 1 == 1 {
276                    upper[axis]
277                } else {
278                    lower[axis]
279                }
280            };
281            let weight = (0..3).fold(1.0, |acc, axis| {
282                acc * if (corner >> axis) & 1 == 1 {
283                    weights[axis]
284                } else {
285                    1.0 - weights[axis]
286                }
287            });
288            let index = (pick(0) * self.size + pick(1)) * self.size + pick(2);
289            let entry = self.data[index];
290            for channel in 0..3 {
291                out[channel] += weight * f64::from(entry[channel]);
292            }
293        }
294        out
295    }
296}
297
298/// Map a linear value to the `[0, 1]` table coordinate.
299fn encode(value: f64) -> f64 {
300    let log = value.max(1e-10).log10();
301    ((log - LOG_RANGE_MIN) / (LOG_RANGE_MAX - LOG_RANGE_MIN)).clamp(0.0, 1.0)
302}
303
304/// Inverse of [`encode`].
305fn decode(index: usize, size: usize) -> f64 {
306    let u = index as f64 / (size - 1) as f64;
307    10.0_f64.powf(LOG_RANGE_MIN + u * (LOG_RANGE_MAX - LOG_RANGE_MIN))
308}
309
310#[cfg(test)]
311mod tests {
312    use super::*;
313
314    #[test]
315    fn encode_decode_round_trip() {
316        for value in [0.0005, 0.01, 0.18, 1.0, 3.0] {
317            let round_trip =
318                10.0_f64.powf(LOG_RANGE_MIN + encode(value) * (LOG_RANGE_MAX - LOG_RANGE_MIN));
319            assert!(
320                (round_trip - value).abs() < 1e-3 * value.max(1.0),
321                "{value} -> {round_trip}"
322            );
323        }
324    }
325
326    #[test]
327    fn the_table_matches_the_model_it_was_baked_from() {
328        let context = SpectralContext::new();
329        let lut = ExposureLut::bake(33, &context);
330
331        // The error is strongly skewed: the mean is tiny and the tail lives in
332        // the extreme corners, where the polynomial reconstruction clamps at
333        // zero and the mapping has a kink. Asserting a single maximum would
334        // either fail on a corner or hide the distribution.
335        let mut errors = Vec::new();
336        for r in 0..10 {
337            for g in 0..10 {
338                for b in 0..10 {
339                    let rgb = [
340                        0.01 + 0.09 * f64::from(r),
341                        0.01 + 0.09 * f64::from(g),
342                        0.01 + 0.09 * f64::from(b),
343                    ];
344                    let direct = context.expose(rgb).unwrap();
345                    let baked = lut.sample(rgb);
346                    for channel in 0..3 {
347                        errors.push((direct[channel] - baked[channel]).abs());
348                    }
349                }
350            }
351        }
352        errors.sort_by(|a, b| a.partial_cmp(b).unwrap());
353        let count = errors.len();
354        let mean = errors.iter().sum::<f64>() / count as f64;
355        let p99 = errors[count * 99 / 100];
356
357        assert!(mean < 0.005, "mean error {mean} decades");
358        assert!(p99 < 0.05, "p99 error {p99} decades");
359    }
360
361    #[test]
362    fn a_written_table_reads_back_identical() {
363        let context = SpectralContext::new();
364        let table = ExposureLut::bake(9, &context);
365
366        let path = std::env::temp_dir().join(format!("klut-test-{}.klut", std::process::id()));
367        table.write(&path).expect("write");
368        let loaded = ExposureLut::read(&path).expect("read");
369        let _ = std::fs::remove_file(&path);
370
371        assert_eq!(loaded.size(), table.size());
372        assert_eq!(loaded.identity(), table.identity());
373        let probe = [0.2, 0.35, 0.05];
374        assert_eq!(loaded.sample(probe), table.sample(probe));
375    }
376
377    #[test]
378    fn the_identity_names_the_model() {
379        let context = SpectralContext::new();
380        let identity = context.identity();
381        assert!(identity.contains("camera="), "{identity}");
382        assert!(identity.contains("film="), "{identity}");
383        assert!(identity.contains("grid="), "{identity}");
384    }
385
386    #[test]
387    fn a_corrupt_table_is_rejected() {
388        let context = SpectralContext::new();
389        let table = ExposureLut::bake(4, &context);
390        let path = std::env::temp_dir().join(format!("klut-bad-{}.klut", std::process::id()));
391        table.write(&path).expect("write");
392
393        let mut bytes = std::fs::read(&path).expect("read back");
394        let last = bytes.len() - 1;
395        bytes[last] ^= 0xFF;
396        std::fs::write(&path, &bytes).expect("rewrite");
397
398        let result = ExposureLut::read(&path);
399        let _ = std::fs::remove_file(&path);
400        assert!(matches!(result, Err(LutError::Checksum)), "{result:?}");
401    }
402
403    #[test]
404    fn the_table_is_bounded_by_its_inputs() {
405        let context = SpectralContext::new();
406        let lut = ExposureLut::bake(9, &context);
407        for rgb in [[0.0; 3], [1.0; 3], [10.0; 3]] {
408            let out = lut.sample(rgb);
409            for value in out {
410                assert!(value.is_finite());
411            }
412        }
413    }
414}