kallo-core 0.1.0

Reference film model: characteristic curves and development kinetics
Documentation
//! The digitised spectra the model runs on.
//!
//! These are the measured curves, compiled in rather than loaded. The model does
//! no file I/O at render time, and a `kalo` binary that needs a data directory
//! beside it is not something anyone would install.
//!
//! Every table is 380–730 nm at 5 nm, the grid [`crate::spectral`] uses. Their
//! provenance is the manufacturer's data sheet for the film and the paper — the
//! film's dyes and minimum density from the KODAK VISION3 500T technical
//! information (H-1-5219, page 4), the metallic paper's dyes and layer
//! sensitivities from E-4071 pages 4 and 5, and the E-4021 papers' from page 8.
//! The PDFs are not redistributed; what is here is our digitisation of them.
//!
//! The datasets they came from are not in this repository, so nothing here can be
//! regenerated by a reader. That is a deliberate trade, and the one place it
//! bites is that a transcription error would be invisible. The peak values are
//! the check: three peaks landing on 1.0 for the dyes is what the sheet states,
//! and a mistake in the table moves them.

use kallo_spectral::Spectrum;

use crate::spectral::{GRID_LEN, GRID_START_NM, GRID_STEP_NM};

/// The paper's cyan, magenta and yellow dyes, peak-normalised absorption.
// The shared negative dye and mask set lives with the film data now: it is
// the VISION3 500T digitisation, read from that film's own `.kalofilm`.
pub(crate) use crate::emulsion::{FILM_DYES, FILM_MASK, PAPER_DYES, PAPER_LAYERS};

/// A spectrum on the model's grid, from one of the tables above.
///
/// # Panics
///
/// Cannot panic: the grid is a compile-time constant and the table has its
/// length.
pub(crate) fn spectrum(values: &[f64; GRID_LEN]) -> Spectrum {
    Spectrum::new(GRID_START_NM, GRID_STEP_NM, values.to_vec()).expect("the grid is a constant")
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The film's dye curves were published peak-normalised, so three peaks at
    /// 1.0 is the transcription check the data sheet gives us for free.
    #[test]
    fn the_dye_peaks_land_where_the_data_sheet_says() {
        for (name, table) in ["cyan", "magenta", "yellow"].iter().zip(&FILM_DYES) {
            let peak = table.iter().copied().fold(f64::NEG_INFINITY, f64::max);
            assert!((peak - 1.0).abs() < 0.01, "{name} peaks at {peak}");
        }
    }

    /// The tables have to be on the model's grid, or every dot product silently
    /// disagrees about wavelength.
    #[test]
    fn the_tables_are_on_the_models_grid() {
        let one = spectrum(&FILM_MASK);
        let two = spectrum(&PAPER_DYES[0]);
        assert!(one.shares_grid(&two));
        assert_eq!(one.len(), GRID_LEN);
    }

    /// The model carries the film's minimum density twice — as this spectrum for
    /// the print, and as three status densities on the stock for the scalar path
    /// — because those are the two shapes the two paths need. This is the test
    /// that they are the same quantity.
    ///
    /// Sampled at the status filter peaks, which is the approximation the
    /// model's status-to-analytical unmixing already makes. Green is the loosest
    /// of the three for that reason: 550 nm is the middle of a broad band, not a
    /// wavelength anything is measured at.
    #[test]
    fn the_mask_is_the_measured_minimum_density() {
        // Plateaus of the data sheet's sensitometric curves at -8 stops.
        const MEASURED: [f64; 3] = [0.1867, 0.5782, 0.8319];
        let mask = spectrum(&FILM_MASK);
        for (wavelength, expected) in [650.0, 550.0, 450.0].iter().zip(MEASURED) {
            let at = mask.interpolate(*wavelength);
            assert!(
                (at - expected).abs() < 0.06,
                "{wavelength} nm: mask {at:.4} against measured {expected:.4}"
            );
        }
    }

    /// The mask absorbs blue and passes red: that is the whole reason it exists.
    #[test]
    fn the_mask_is_orange() {
        let at = |wavelength: f64| {
            FILM_MASK[((wavelength - GRID_START_NM) / GRID_STEP_NM).round() as usize]
        };
        assert!(
            at(450.0) > at(650.0),
            "blue {} vs red {}",
            at(450.0),
            at(650.0)
        );
    }
}