Skip to main content

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}