1use std::path::{Path, PathBuf};
15
16use crate::spectral::SpectralContext;
17
18const MAGIC: &[u8; 4] = b"KLUT";
20const VERSION: u16 = 2;
22const CHANNELS: u16 = 3;
24const MAX_SIZE: usize = 256;
26
27#[derive(Debug)]
29pub enum LutError {
30 Io {
32 path: PathBuf,
34 source: std::io::Error,
36 },
37 Magic,
39 Version(u16),
41 Size(u32),
43 Layout,
45 Checksum,
47 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
86pub const LOG_RANGE_MIN: f64 = -4.0;
88pub const LOG_RANGE_MAX: f64 = 0.602_06; #[derive(Debug, Clone)]
93pub struct ExposureLut {
94 size: usize,
95 data: Vec<[f32; 3]>,
97 identity: String,
99}
100
101impl ExposureLut {
102 #[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 #[must_use]
139 pub fn identity(&self) -> &str {
140 &self.identity
141 }
142
143 #[must_use]
145 pub fn size(&self) -> usize {
146 self.size
147 }
148
149 #[must_use]
151 pub fn byte_size(&self) -> usize {
152 self.data.len() * 3 * std::mem::size_of::<f32>()
153 }
154
155 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 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 #[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
298fn 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
304fn 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 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}