kallo_core/spectral.rs
1//! Spectral exposure: linear RGB → spectrum → film layer responses.
2//!
3//! Phase 0 exposed the negative by taking each channel's log exposure directly.
4//! That is a scalar approximation: it assumes the film's three layers see the
5//! same three numbers the camera does. They do not.
6//!
7//! This module inserts the missing step. The camera triple is reconstructed into
8//! a spectrum, and that spectrum is integrated against the film's layer
9//! sensitivities. The result is still three log exposures, but they come from a
10//! physical overlap rather than from an identity.
11//!
12//! The reconstruction used here is the **fast** member of the family: the
13//! polynomial prior, which is a closed-form 3×3 solve per pixel. The dictionary
14//! prior is the target, but it needs a baked lookup table to be usable per
15//! pixel, and that is a separate task.
16
17use kallo_spectral::{DictionaryUpsampler, PolynomialUpsampler, Sensor, Spectrum, Upsampler};
18
19use crate::model::{ExposureModel, inverse3, tables};
20
21/// First wavelength of the internal grid, in nanometres.
22pub const GRID_START_NM: f64 = 380.0;
23/// Wavelength step of the internal grid.
24pub const GRID_STEP_NM: f64 = 5.0;
25/// Number of samples on the internal grid.
26pub const GRID_LEN: usize = 71;
27
28/// Which sensor the RGB triple is assumed to have come from.
29///
30/// This is the assumption the whole spectral path is conditional on, so it is a
31/// named, recorded choice rather than a constant buried in a constructor. The
32/// name reaches `SpectralContext::identity`, which reaches every baked table, so
33/// a table cannot be loaded against a different camera by accident.
34#[derive(Debug, Clone, Default)]
35pub enum CameraProfile {
36 /// The linear sRGB primaries: the triple is an sRGB colour, which is what
37 /// the program is actually handed. The default, because it is the only
38 /// option that is exactly right for the input.
39 #[default]
40 Srgb,
41 /// Three broad Gaussians: the stand-in from before any measured camera
42 /// existed. Kept because it is the assumption the early benchmarks used.
43 Generic,
44 /// The CIE 1931 2 degree observer, for input that is already XYZ.
45 Observer,
46 /// A measured spectral sensitivity, for example an import of the camSPEC
47 /// database.
48 Measured(Sensor),
49}
50
51impl CameraProfile {
52 /// The sensor's name, for the render report and for baked-table identity.
53 #[must_use]
54 pub fn name(&self) -> &str {
55 match self {
56 Self::Srgb => "srgb-primaries",
57 Self::Generic => "generic-camera",
58 Self::Observer => "cie1931-approx",
59 Self::Measured(sensor) => sensor.name(),
60 }
61 }
62
63 /// Build the sensor on `grid`.
64 #[must_use]
65 pub fn sensor(&self, grid: &kallo_spectral::Spectrum) -> Sensor {
66 match self {
67 Self::Srgb => Sensor::srgb(grid),
68 Self::Generic => Sensor::generic_camera(grid),
69 Self::Observer => Sensor::cie1931(grid),
70 Self::Measured(sensor) => sensor.resampled(grid),
71 }
72 }
73}
74
75/// Everything the spectral exposure needs, built once per render.
76#[derive(Debug, Clone)]
77pub struct SpectralContext {
78 grid: Spectrum,
79 camera: Sensor,
80 film: Sensor,
81 upsampler: PolynomialUpsampler,
82 /// When present, the dictionary is tried first and the polynomial is the
83 /// fallback.
84 dictionary: Option<DictionaryUpsampler>,
85 threshold: f64,
86 /// Film response to a correctly exposed 18 % grey, per layer. Dividing by it
87 /// keeps the spectral path anchored to the same grey as the scalar path, so
88 /// that turning spectra on changes colour separation, not overall exposure.
89 reference: [f64; 3],
90 /// The cyan dye's second emulsion, resampled onto the model grid — ADR 0017.
91 ///
92 /// It is a fourth integral rather than a fourth number in `film`: the
93 /// sensitivity is a table, and the layer it belongs to shares its dye with
94 /// the blue-sensitive one instead of owning a channel.
95 extra: Option<[f64; GRID_LEN]>,
96}
97
98impl Default for SpectralContext {
99 fn default() -> Self {
100 Self::new()
101 }
102}
103
104impl SpectralContext {
105 /// Build the context on the internal grid, with the default camera profile
106 /// and the default film's layers.
107 ///
108 /// The film's layers are measured from the manufacturer's data sheet; the
109 /// camera is [`CameraProfile::default`], the input's own definition. Both
110 /// are ordered R, G, B, and getting that order wrong is invisible until a
111 /// red patch comes out blue.
112 ///
113 /// This is the context for whichever stock [`crate::RenderParams::default`]
114 /// uses. A render of any other film wants [`Self::for_stock`], or the
115 /// exposure is computed with VISION3's spectral response and only the curve
116 /// changes.
117 ///
118 /// # Panics
119 ///
120 /// Cannot panic: the grid is a compile-time constant with a valid step.
121 #[must_use]
122 pub fn new() -> Self {
123 Self::for_layers("vision3_500t", &kallo_spectral::layers::CHANNELS)
124 }
125
126 /// The context for a particular film stock: its own layer sensitivities.
127 ///
128 /// This is the difference between "a film with a different curve" and "a
129 /// different film": which wavelengths each layer records decides how the
130 /// scene separates into dyes, and no curve can stand in for it.
131 #[must_use]
132 pub fn for_stock(stock: &crate::emulsion::FilmStock) -> Self {
133 let mut context = Self::for_layers(stock.id, stock.layers);
134 // The three layers are divided by their joint peak when the sensor is
135 // built, so a fourth table has to be divided by the same number or it
136 // would be on a scale of its own and every exposure it reported would
137 // be off by that factor. Normalising it on its *own* peak would be the
138 // other mistake: it would assert that the cyan-sensitive emulsion is
139 // exactly as fast as the blue-sensitive one.
140 let peak = stock
141 .layers
142 .iter()
143 .flat_map(|table| table.iter())
144 .fold(0.0_f64, |a, &b| a.max(b));
145 // Either kind of fourth layer integrates the same way; what differs is
146 // what the number is used for — a dye's density, or an inhibitor's
147 // release (ADR 0017 and ADR 0018).
148 context.extra = stock
149 .extra_cyan
150 .and_then(|emulsion| sensitivity_table(&context.grid, emulsion.sensitivity, peak))
151 .or_else(|| stock.cl_layer.map(|layer| *layer.sensitivity));
152 context
153 }
154
155 /// # Panics
156 ///
157 /// Cannot panic: the grid is a compile-time constant with a valid step.
158 #[must_use]
159 fn for_layers(name: &str, layers: &[[f64; GRID_LEN]; 3]) -> Self {
160 let grid = Spectrum::uniform(GRID_START_NM, GRID_STEP_NM, GRID_LEN)
161 .expect("the internal grid is a valid constant");
162 let camera = CameraProfile::default().sensor(&grid);
163 let film = Sensor::film_layers_from(&grid, name, layers);
164 let upsampler = PolynomialUpsampler;
165
166 let mut context = Self {
167 grid,
168 camera,
169 film,
170 upsampler,
171 dictionary: None,
172 threshold: 0.02,
173 reference: [1.0; 3],
174 extra: None,
175 };
176 context.refresh_reference();
177 context
178 }
179
180 /// Recompute the grey anchor with whatever reconstruction is now active.
181 ///
182 /// This matters: the anchor must be measured through the same path that
183 /// renders, or enabling the dictionary would silently re-balance every print.
184 fn refresh_reference(&mut self) {
185 let grey = self
186 .reconstruct([0.18; 3])
187 .unwrap_or_else(|| Spectrum::filled(self.grid.clone(), 0.0));
188 self.reference = self.film.respond(&grey);
189 }
190
191 /// Use a dictionary prior, with the polynomial as the fallback.
192 ///
193 /// Atoms are resampled onto the internal grid, so callers can pass spectra
194 /// measured on any uniform grid.
195 #[must_use]
196 pub fn with_atoms(mut self, atoms: &[Spectrum]) -> Self {
197 let resampled: Vec<Spectrum> = atoms
198 .iter()
199 .map(|atom| atom.resampled(&self.grid))
200 .collect();
201 if !resampled.is_empty() {
202 self.dictionary = Some(DictionaryUpsampler::new(resampled));
203 self.refresh_reference();
204 }
205 self
206 }
207
208 /// Replace the camera assumption.
209 ///
210 /// The grey anchor is recomputed, because it is the film's response to the
211 /// spectrum this camera reconstructs for mid grey. Changing the camera
212 /// without that would silently re-balance every print.
213 #[must_use]
214 pub fn with_camera(mut self, camera: CameraProfile) -> Self {
215 self.camera = camera.sensor(&self.grid);
216 self.refresh_reference();
217 self
218 }
219
220 /// Relative camera-response residual above which the hybrid falls back.
221 #[must_use]
222 pub fn with_threshold(mut self, threshold: f64) -> Self {
223 self.threshold = threshold.max(0.0);
224 self
225 }
226
227 /// Whether a dictionary prior is active.
228 #[must_use]
229 pub fn has_dictionary(&self) -> bool {
230 self.dictionary.is_some()
231 }
232
233 /// A stable description of the model this context implements.
234 ///
235 /// Recorded in baked tables so that loading a table baked for a different
236 /// camera or film fails loudly instead of silently producing wrong colour.
237 #[must_use]
238 pub fn identity(&self) -> String {
239 format!(
240 "camera={};film={};grid={}:{}:{}",
241 self.camera.name(),
242 self.film.name(),
243 self.grid.start_nm(),
244 self.grid.step_nm(),
245 self.grid.len()
246 )
247 }
248
249 /// The wavelength grid.
250 #[must_use]
251 pub fn grid(&self) -> &Spectrum {
252 &self.grid
253 }
254
255 /// The camera assumption this context was built with.
256 #[must_use]
257 pub fn camera(&self) -> &Sensor {
258 &self.camera
259 }
260
261 /// The film's three layer sensitivities.
262 #[must_use]
263 pub fn film(&self) -> &Sensor {
264 &self.film
265 }
266
267 /// The film's response to a reconstructed 18 % grey, per layer.
268 ///
269 /// The anchor [`Self::expose`] divides by: an integrator that wants the
270 /// same anchor needs this number rather than a second reconstruction.
271 #[must_use]
272 pub fn reference(&self) -> [f64; 3] {
273 self.reference
274 }
275
276 /// The constants this context integrates with, flattened for another backend.
277 ///
278 /// `None` when a dictionary prior is active, or when a table is not on the
279 /// model's grid. Both mean the closed form below is not what this context
280 /// computes, and a backend that rendered anyway would be rendering a
281 /// different model without saying so.
282 #[must_use]
283 pub fn model(&self) -> Option<ExposureModel> {
284 if self.has_dictionary() {
285 return None;
286 }
287 let basis = PolynomialUpsampler::basis(&self.grid);
288 let system = self.upsampler.system(&self.camera, &self.grid).ok()?;
289 Some(ExposureModel {
290 // The CPU's own fallback for a singular system is zero
291 // coefficients, which is exactly the zero matrix for every input.
292 reconstruct: inverse3(system).unwrap_or([[0.0; 3]; 3]),
293 basis: tables(&basis)?,
294 film: tables(self.film.channels())?,
295 reference: self.reference,
296 })
297 }
298
299 /// Per-layer log10 exposure for a linear-light pixel.
300 ///
301 /// Returns `None` if the reconstruction fails, which can only happen on a
302 /// grid mismatch that [`Self::new`] rules out.
303 #[must_use]
304 pub fn expose(&self, linear: [f64; 3]) -> Option<[f64; 3]> {
305 self.expose_with_extra(linear).map(|(layers, _)| layers)
306 }
307
308 /// The same exposure, plus the fourth layer when the film has one.
309 ///
310 /// One reconstruction feeds all four integrals: the second cyan emulsion
311 /// sits in the same stack and sees the same light, so rebuilding the
312 /// spectrum for it would be the same arithmetic twice.
313 ///
314 /// The fourth layer is normalised on the **blue** layer's grey response,
315 /// not on its own. The data sheet plots every emulsion on one log H axis,
316 /// so the distance between the blue-sensitive curve and the cyan-sensitive
317 /// one is a speed difference; anchoring each on its own grey would divide
318 /// that difference out and make the fourth layer a copy of the third.
319 #[must_use]
320 pub fn expose_with_extra(&self, linear: [f64; 3]) -> Option<([f64; 3], Option<f64>)> {
321 let spectrum = self.reconstruct(linear)?;
322 let radiance = spectrum.values();
323 let response = self.film.respond(&spectrum);
324 let layers = std::array::from_fn(|channel| {
325 let normalised = response[channel] * 0.18 / self.reference[channel].max(1e-12);
326 normalised.max(1e-10).log10()
327 });
328 let extra = self.extra.map(|sensitivity| {
329 let total = sensitivity
330 .iter()
331 .zip(radiance)
332 .map(|(sensitivity, radiance)| sensitivity * radiance)
333 .sum::<f64>()
334 * self.grid.step_nm();
335 let normalised = total * 0.18 / self.reference[2].max(1e-12);
336 normalised.max(1e-10).log10()
337 });
338 Some((layers, extra))
339 }
340}
341
342/// A sensitivity table on its own grid, resampled onto the model's.
343///
344/// `peak` is the divisor that puts it on the same relative scale as the film's
345/// three layers — see [`SpectralContext::for_stock`].
346///
347/// `None` for an empty table, which is an emulsion that records nothing — a
348/// layer with no sensitivity would develop only base, and pretending it does is
349/// worse than saying the stock has no fourth emulsion.
350fn sensitivity_table(grid: &Spectrum, sensitivity: &[f32], peak: f64) -> Option<[f64; GRID_LEN]> {
351 if sensitivity.is_empty() || peak <= 0.0 {
352 return None;
353 }
354 let mut table = Spectrum::uniform(
355 crate::dye::SENSITIVITY_START_NM,
356 crate::dye::SENSITIVITY_STEP_NM,
357 sensitivity.len(),
358 )
359 .ok()?;
360 for (slot, value) in table.values_mut().iter_mut().zip(sensitivity) {
361 *slot = f64::from(*value) / peak;
362 }
363 crate::model::table(&table.resampled(grid))
364}
365
366impl SpectralContext {
367 /// Pick a reconstruction: the dictionary if it can explain the measurement,
368 /// the polynomial otherwise.
369 fn reconstruct(&self, linear: [f64; 3]) -> Option<Spectrum> {
370 if let Some(dictionary) = &self.dictionary {
371 let candidate = dictionary
372 .reconstruct(&linear, &self.camera, &self.grid)
373 .ok()?;
374 let measured = self.camera.respond(&candidate);
375 let residual: f64 = (0..3)
376 .map(|index| (measured[index] - linear[index]).powi(2))
377 .sum::<f64>()
378 .sqrt();
379 let scale: f64 = (0..3)
380 .map(|index| linear[index].powi(2))
381 .sum::<f64>()
382 .sqrt()
383 .max(1e-9);
384 if residual / scale <= self.threshold {
385 return Some(candidate);
386 }
387 }
388 self.upsampler
389 .reconstruct(&linear, &self.camera, &self.grid)
390 .ok()
391 }
392}
393
394#[cfg(test)]
395mod tests {
396 use super::*;
397
398 #[test]
399 fn mid_grey_stays_at_mid_grey() {
400 let context = SpectralContext::new();
401 let log_e = context.expose([0.18, 0.18, 0.18]).unwrap();
402 let expected = 0.18_f64.log10();
403 for channel in log_e {
404 assert!((channel - expected).abs() < 1e-6, "{channel} vs {expected}");
405 }
406 }
407
408 /// The default camera is the input's own definition, so the reconstruction
409 /// has to give the colour back exactly — as long as the prior can hold it.
410 #[test]
411 fn the_default_camera_gives_back_the_colour_it_was_handed() {
412 let context = SpectralContext::new();
413 for linear in [
414 [0.18, 0.18, 0.18],
415 [0.9, 0.1, 0.1],
416 [0.1, 0.1, 0.9],
417 [0.4, 0.3, 0.2],
418 ] {
419 let spectrum = context.reconstruct(linear).expect("polynomial solves");
420 let back = context.camera().respond(&spectrum);
421 for channel in 0..3 {
422 assert!(
423 (back[channel] - linear[channel]).abs() < 1e-6,
424 "{linear:?} came back as {back:?}"
425 );
426 }
427 }
428 }
429
430 /// Where the smooth prior cannot hold the colour, the clamp is what gives it
431 /// away: the quadratic goes negative and the reflectance floor lifts the
432 /// response. This is the polynomial's floor, not the camera's — the solve
433 /// before the clamp is exact — and it is why the dictionary exists.
434 #[test]
435 fn a_saturated_green_exceeds_what_the_smooth_prior_can_hold() {
436 let context = SpectralContext::new();
437 let linear = [0.1, 0.9, 0.1];
438 let spectrum = context.reconstruct(linear).expect("polynomial solves");
439 let back = context.camera().respond(&spectrum);
440 assert!(spectrum.min() >= 0.0, "reflectance went negative");
441 assert!(
442 back[0] > 0.2,
443 "expected the clamp to lift red above 0.2, got {back:?}"
444 );
445 }
446
447 #[test]
448 fn a_saturated_colour_separates_the_layers() {
449 let context = SpectralContext::new();
450 let log_e = context.expose([0.9, 0.1, 0.1]).unwrap();
451 // The red layer must see more than the blue one.
452 assert!(log_e[0] > log_e[2], "{log_e:?}");
453 // The magnitude is a property of the placeholder film sensor, so only
454 // the direction and the presence of separation are asserted here.
455 assert!((log_e[0] - log_e[2]) > 0.05, "no separation: {log_e:?}");
456 }
457
458 #[test]
459 fn a_dictionary_is_used_when_it_covers_the_colour() {
460 let context = SpectralContext::new();
461 let atoms: Vec<Spectrum> = [0.18_f64, 0.4, 0.05]
462 .iter()
463 .map(|level| {
464 context
465 .upsampler
466 .reconstruct(&[*level; 3], context.camera(), context.grid())
467 .unwrap()
468 })
469 .collect();
470 let with_dictionary = context.with_atoms(&atoms);
471 assert!(with_dictionary.has_dictionary());
472
473 let neutral = with_dictionary.expose([0.18; 3]).unwrap();
474 assert!((neutral[0] - 0.18_f64.log10()).abs() < 1e-6);
475 }
476
477 #[test]
478 fn exposure_is_monotonic() {
479 let context = SpectralContext::new();
480 let mut previous = f64::NEG_INFINITY;
481 for step in 0..40 {
482 let value = 0.001 * 1.2_f64.powi(step);
483 let log_e = context.expose([value; 3]).unwrap()[1];
484 assert!(log_e > previous, "not monotonic at {value}");
485 previous = log_e;
486 }
487 }
488}