Skip to main content

kallo_core/
scanner.rs

1//! The scan: the optics and the noise between the print and the file.
2//!
3//! The model ends with a scan — dye unmixing, a neutral axis, an observer — and
4//! that scan has no space in it. Everything it reads is a single number per
5//! pixel, so the last stage of the chain is the one stage that could not be
6//! wrong about texture: it had none.
7//!
8//! A negative scan says what belongs there. `lasvegas.dng` (Fuji NPH400,
9//! 3.555 µm per pixel) was measured over its flat patches, and the finding was
10//! uncomfortable: the film's own silver is not what a consumer scan shows. The
11//! scan carries a density texture of 0.60 % through a 48 µm aperture, correlated
12//! over 3.2 µm — half again the film's published granularity at its own peak,
13//! measured where the developed silver contributes a fraction of it.
14//!
15//! Two things say it is not grain. Its amplitude is flat across the densities
16//! the scan has (0.0060 to 0.0067 from D = 0.04 to 0.29, where the curve's slope
17//! is rising steeply and a film's granularity cannot be flat), and the three
18//! channels come out with the same correlation length *and* a common field —
19//! `ρ = 0.69` between red and green, 0.83 between green and blue. Three
20//! emulsions do not share a grain field. What does is something every sample
21//! sees at once: the illumination, the optics, or the base's own texture. Which
22//! of those it is cannot be told from one scan, and the model does not claim
23//! to know.
24//!
25//! So the stage models the texture that was measured and nothing else:
26//!
27//! - a density texture, achromatic in part, with the measured length and
28//!   amplitude. `shared` is the fraction of its variance the channels have in
29//!   common, which is the cross-channel correlation the scan showed;
30//! - an optics blur on the print, in micrometres. **Unmeasured**: the
31//!   measurement above cannot separate the optics from the texture that rides
32//!   on it, so the default is no blur rather than a number that would pretend
33//!   to be a point-spread function.
34//!
35//! Whether the texture is fixed in the scanner (a dust-and-condenser pattern
36//! that would repeat from scan to scan) or redrawn every frame is also not
37//! known, and it matters for the two-scan test that would separate the scan
38//! from the film: a fixed pattern is *not* independent between scans. This
39//! model draws it fresh, and says so here rather than in a footnote.
40
41use crate::psf::{convolve, gaussian_blur, gaussian_kernel};
42
43/// The aperture granularity is quoted through, in micrometres.
44pub const APERTURE_UM: f64 = 48.0;
45
46/// A scan: what the optics and the sensor add to the print.
47#[derive(Debug, Clone, Copy)]
48pub struct Scanner {
49    /// Correlation length of the density texture, in micrometres.
50    pub texture_um: f64,
51    /// Its rms through a [`APERTURE_UM`] aperture, in density.
52    pub texture_density: f64,
53    /// Fraction of the texture's variance the three channels share, `0..=1`.
54    pub shared: f64,
55    /// Gaussian optics on the print, in micrometres. Zero is no blur.
56    pub optics_um: f64,
57    /// Seed: the texture is a fixture, not a different scan every render.
58    pub seed: u64,
59}
60
61impl Scanner {
62    /// The numbers measured from `lasvegas.dng`.
63    ///
64    /// The one thing a single scan cannot do is split what it measures into the
65    /// parts that made it, so this is the whole texture as one number per
66    /// property. It is a scan's, not a film's: a stock must not carry it.
67    #[must_use]
68    pub fn measured() -> Self {
69        Self {
70            texture_um: 3.25,
71            texture_density: 0.0060,
72            shared: 0.70,
73            optics_um: 0.0,
74            seed: 0,
75        }
76    }
77
78    /// Whether the scan would change a pixel at all.
79    #[must_use]
80    pub fn is_idle(&self) -> bool {
81        self.optics_um <= 0.0 && (self.texture_density <= 0.0 || self.texture_um <= 0.0)
82    }
83
84    /// Scan a finished print in place.
85    ///
86    /// `pixels` are linear reflectance, one per channel. The optics blur that
87    /// (light is convolved, not density), then the sensor's texture multiplies
88    /// it back down in density, `R·10^-n`, which is how a density fluctuation
89    /// appears in a linear measurement.
90    pub fn apply(&self, pixels: &mut [[f64; 3]], width: usize, height: usize, pixel_um: f64) {
91        if width == 0 || height == 0 || pixel_um <= 0.0 {
92            return;
93        }
94        if self.optics_um > 0.0 {
95            let sigma_px = self.optics_um / pixel_um;
96            let mut planes = vec![vec![0.0; width * height]; 3];
97            for (index, pixel) in pixels.iter().enumerate() {
98                for (plane, value) in planes.iter_mut().zip(pixel) {
99                    plane[index] = *value;
100                }
101            }
102            let blurred: Vec<Vec<f64>> = planes
103                .iter()
104                .map(|plane| gaussian_blur(plane, width, height, sigma_px))
105                .collect();
106            for (index, pixel) in pixels.iter_mut().enumerate() {
107                for (value, plane) in pixel.iter_mut().zip(&blurred) {
108                    *value = plane[index];
109                }
110            }
111        }
112        if self.texture_density <= 0.0 || self.texture_um <= 0.0 {
113            return;
114        }
115
116        // The texture's shape: a Gaussian of `sigma_px`, normalised to unit L2
117        // so the field keeps the variance it is given, and its `P` — the
118        // autocorrelation summed along one axis, the number of pixels one
119        // feature stands behind. `P²` is what a 48 µm aperture would otherwise
120        // over-count, exactly as the grain's stencil is corrected.
121        let sigma_px = self.texture_um / (std::f64::consts::SQRT_2 * pixel_um);
122        let kernel = l2_normalised(sigma_px);
123        let radius = kernel.len() / 2;
124        let mut per_axis = 0.0;
125        for lag in 0..=radius {
126            let mut pair = 0.0;
127            for tap in 0..(kernel.len() - lag) {
128                pair += kernel[tap] * kernel[tap + lag];
129            }
130            per_axis += if lag == 0 { pair } else { 2.0 * pair };
131        }
132        // Per-pixel sigma that puts `texture_density` through a 48 µm aperture.
133        let sigma =
134            self.texture_density * APERTURE_UM / (pixel_um * per_axis.max(f64::MIN_POSITIVE));
135        let shared = self.shared.clamp(0.0, 1.0);
136        let spread = (1.0 - shared).sqrt();
137        let common_scale = shared.sqrt() * sigma;
138        let own_scale = spread * sigma;
139
140        // One white plane per field, filtered once: hashing the noise inside the
141        // stencil would compute the same numbers `k²` times, and a twelve
142        // megapixel frame then takes a minute instead of a second.
143        let common = convolve(&self.white(width, height, 0), width, height, &kernel);
144        let mut own = Vec::with_capacity(3);
145        for channel in 0..3 {
146            own.push(convolve(
147                &self.white(width, height, 1 + channel),
148                width,
149                height,
150                &kernel,
151            ));
152        }
153        for (index, pixel) in pixels.iter_mut().enumerate() {
154            for (channel, value) in pixel.iter_mut().enumerate() {
155                let density = common_scale * common[index] + own_scale * own[channel][index];
156                *value *= 10.0_f64.powf(-density);
157            }
158        }
159    }
160
161    /// A white field of unit variance, one per texture lane.
162    fn white(&self, width: usize, height: usize, lane: usize) -> Vec<f64> {
163        let mut plane = Vec::with_capacity(width * height);
164        for y in 0..height {
165            for x in 0..width {
166                plane.push(self.unit_normal(x, y, lane));
167            }
168        }
169        plane
170    }
171
172    /// A standard normal, deterministic in the pixel, the layer and the seed.
173    ///
174    /// The same generator the grain uses — SplitMix64 and Box–Muller — because
175    /// two generators in one image is one too many, and because a draw shared
176    /// with the grain is a draw that can be checked against it.
177    fn unit_normal(&self, x: usize, y: usize, lane: usize) -> f64 {
178        let u1 = self.uniform(x, y, lane, 0);
179        let u2 = self.uniform(x, y, lane, 1);
180        (-2.0 * u1.ln()).sqrt() * (std::f64::consts::TAU * u2).cos()
181    }
182
183    /// A uniform in `(0, 1)`, twenty-three bits like the grain's.
184    fn uniform(&self, x: usize, y: usize, lane: usize, draw: usize) -> f64 {
185        let mut state = self.seed.wrapping_mul(0xD6E8_FEB8_6659_FD93)
186            ^ (x as u64).wrapping_mul(0x9E37_79B9_7F4A_7C15)
187            ^ (y as u64).wrapping_mul(0xC2B2_AE3D_27D4_EB4F)
188            ^ (lane as u64).wrapping_mul(0x1656_67B1_9E37_79F9)
189            ^ (draw as u64).wrapping_mul(0x2545_F491_4F6C_DD1D);
190        let bits = splitmix64(&mut state) >> 41;
191        (bits as f64 + 0.5) * (1.0 / 8_388_608.0)
192    }
193}
194
195/// A Gaussian kernel normalised to unit L2 norm, so filtering keeps variance.
196fn l2_normalised(sigma_px: f64) -> Vec<f64> {
197    let mut kernel = gaussian_kernel(sigma_px.max(1e-3));
198    let norm = kernel
199        .iter()
200        .map(|weight| weight * weight)
201        .sum::<f64>()
202        .sqrt();
203    if norm > 0.0 {
204        for weight in &mut kernel {
205            *weight /= norm;
206        }
207    }
208    kernel
209}
210
211/// SplitMix64, the generator the grain already uses.
212fn splitmix64(state: &mut u64) -> u64 {
213    *state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
214    let mut z = *state;
215    z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
216    z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
217    z ^ (z >> 31)
218}
219
220#[cfg(test)]
221mod tests {
222    use super::*;
223
224    /// A 48 µm aperture must read the measured granularity, and one pixel must
225    /// read more: the same fluctuation, spread over the texture's length.
226    #[test]
227    fn a_flat_print_scans_at_the_measured_granularity() {
228        // 4.8 µm per pixel makes a 48 µm aperture ten pixels square.
229        let scanner = Scanner::measured();
230        let mut pixels = vec![[0.5; 3]; 400 * 400];
231        scanner.apply(&mut pixels, 400, 400, 4.8);
232        let mut means = Vec::new();
233        for y in (10..390).step_by(10) {
234            for x in (10..390).step_by(10) {
235                let mut sum = 0.0;
236                for dy in 0..10 {
237                    for dx in 0..10 {
238                        let value = pixels[(y + dy) * 400 + x + dx][1];
239                        sum += -value.log10();
240                    }
241                }
242                means.push(sum / 100.0);
243            }
244        }
245        let mean = means.iter().sum::<f64>() / means.len() as f64;
246        let aperture =
247            (means.iter().map(|m| (m - mean).powi(2)).sum::<f64>() / means.len() as f64).sqrt();
248        assert!(
249            (aperture - scanner.texture_density).abs() < 0.0015,
250            "48 µm granularity {aperture:.4}, expected {:.4}",
251            scanner.texture_density
252        );
253
254        let per_pixel = {
255            let values: Vec<f64> = pixels
256                .iter()
257                .skip(10 * 400)
258                .take(380 * 400)
259                .map(|p| -p[1].log10())
260                .collect();
261            let mean = values.iter().sum::<f64>() / values.len() as f64;
262            (values.iter().map(|v| (v - mean).powi(2)).sum::<f64>() / values.len() as f64).sqrt()
263        };
264        assert!(
265            per_pixel > 2.0 * aperture,
266            "the texture is too smooth: {per_pixel:.4} per pixel against {aperture:.4} at 48 µm"
267        );
268    }
269
270    /// The measured cross-channel correlation is what `shared` means: the
271    /// texture is one field seen three times, not three independent ones.
272    /// Drawing it per channel would make a scan of a flat print look like a
273    /// colour film's grain, which is exactly what the negative was measured
274    /// *not* to be.
275    #[test]
276    fn the_texture_is_shared_by_the_channels() {
277        let scanner = Scanner::measured();
278        let mut pixels = vec![[0.5; 3]; 256 * 256];
279        scanner.apply(&mut pixels, 256, 256, 4.8);
280        let density: Vec<[f64; 3]> = pixels
281            .iter()
282            .map(|p| [0usize, 1, 2].map(|c| -p[c].log10()))
283            .collect();
284        let mean = [
285            density.iter().map(|d| d[0]).sum::<f64>() / density.len() as f64,
286            density.iter().map(|d| d[1]).sum::<f64>() / density.len() as f64,
287            density.iter().map(|d| d[2]).sum::<f64>() / density.len() as f64,
288        ];
289        let mut worst = 0.0_f64;
290        for (a, b) in [(0usize, 1usize), (0, 2), (1, 2)] {
291            let mut cov = 0.0;
292            let mut va = 0.0;
293            let mut vb = 0.0;
294            for d in &density {
295                let da = d[a] - mean[a];
296                let db = d[b] - mean[b];
297                cov += da * db;
298                va += da * da;
299                vb += db * db;
300            }
301            let rho = cov / (va * vb).sqrt();
302            worst = worst.max((rho - scanner.shared).abs());
303        }
304        assert!(
305            worst < 0.1,
306            "cross-channel correlation missed `shared` by {worst:.2}"
307        );
308    }
309
310    /// The optics convolve light, so a step edge becomes a ramp; with no optics
311    /// the print goes through unchanged.
312    #[test]
313    fn the_optics_blur_the_print_and_nothing_else() {
314        let idle = Scanner {
315            texture_density: 0.0,
316            optics_um: 0.0,
317            ..Scanner::measured()
318        };
319        assert!(idle.is_idle());
320        let mut pixels = vec![[0.2; 3]; 32 * 8];
321        for pixel in pixels.iter_mut().skip(16) {
322            *pixel = [0.8; 3];
323        }
324        let original = pixels.clone();
325        idle.apply(&mut pixels, 32, 8, 4.8);
326        assert_eq!(pixels, original, "an idle scan changed the print");
327
328        let mut blurred = original.clone();
329        Scanner {
330            optics_um: 4.8,
331            ..idle
332        }
333        .apply(&mut blurred, 32, 8, 4.8);
334        let ramp = blurred[4 * 32 + 12][0];
335        assert!(ramp > 0.2 && ramp < 0.8, "no ramp: {ramp}");
336        assert!(
337            (blurred[4 * 32 + 24][0] - 0.8).abs() < 0.05,
338            "the flat kept its value"
339        );
340    }
341
342    #[test]
343    fn the_same_seed_scans_the_same_frame() {
344        let scanner = Scanner::measured();
345        let mut a = vec![[0.4; 3]; 64 * 64];
346        let mut b = a.clone();
347        scanner.apply(&mut a, 64, 64, 3.555);
348        scanner.apply(&mut b, 64, 64, 3.555);
349        assert_eq!(a, b);
350        let mut other = vec![[0.4; 3]; 64 * 64];
351        Scanner { seed: 7, ..scanner }.apply(&mut other, 64, 64, 3.555);
352        assert_ne!(a, other);
353    }
354}