Skip to main content

kallo_core/
interimage.rs

1//! The cyan-sensitive layer's inhibitor, acting on the cyan dye — ADR 0018.
2//!
3//! Fuji's fourth layer is not a second cyan-forming emulsion: the 1989 REALA
4//! paper describes it as sensitive to cyan light (ca. 470–540 nm) and releasing
5//! **development inhibitors** in proportion to exposure, which pull back the
6//! red-sensitive layer and approximate the negative lobe of the colour matching
7//! functions. A layer like that forms no density of its own, so a model built
8//! out of two dye curves cannot hold it — which is what PRO 400H's sheet said,
9//! loudly, by refusing to split its cyan curve.
10//!
11//! ## What is modelled
12//!
13//! The release is proportional to the light the layer absorbed, and it is
14//! compared against **the light that same pixel absorbed**: where the
15//! neighbourhood released more than this pixel did, this pixel's cyan is
16//! suppressed; where the inhibitor diffused away to brighter neighbours, it is
17//! let through.
18//!
19//! That baseline is the whole model, and it is a stronger statement than "the
20//! effect is local". The characteristic curve on the data sheet was measured
21//! with a neutral wedge, which exposes every patch uniformly, so a patch's
22//! uniform inhibition is *already inside the curve* — at every level, not just
23//! at the frame's average. Comparing against the frame mean instead would make
24//! a patch's colour depend on what else is in the frame, which is not an
25//! inter-image effect; comparing against the pixel's own light makes a flat
26//! region come out unchanged however bright it is, and leaves only the
27//! structure: edges, fine detail, the transition across a boundary.
28//!
29//! ## What is not measured
30//!
31//! The strength and the diffusion length are placeholders, the same way the
32//! halation numbers are. A frame rendered with them is a demonstration of a
33//! mechanism, not a prediction for this stock. Measuring them needs patches
34//! that are not uniform — a step or a sinusoid seen through the right filter —
35//! and nothing in a data sheet is.
36
37use crate::psf::gaussian_blur;
38
39/// A cyan-sensitive inhibitor layer for one image.
40#[derive(Debug, Clone, Copy)]
41pub struct InterImage {
42    /// How much cyan density the maximum local excess of exposure takes away,
43    /// as a fraction at full deviation.
44    pub gain: f64,
45    /// How far the inhibitor diffuses on the film, in micrometres.
46    pub sigma_um: f64,
47    /// Size of one pixel on the film, in micrometres across.
48    pub pixel_um: f64,
49}
50
51impl InterImage {
52    /// Placeholder values: a 12 % swing and the same diffusion length the DIR
53    /// couplers use. Neither is measured for any stock.
54    #[must_use]
55    pub fn typical(pixel_um: f64) -> Self {
56        Self {
57            gain: 0.12,
58            sigma_um: 20.0,
59            pixel_um,
60        }
61    }
62
63    /// Whether this would change anything.
64    #[must_use]
65    pub fn is_noop(&self) -> bool {
66        self.gain <= 0.0
67    }
68
69    /// Apply the layer's inhibition to a buffer of densities, in place.
70    ///
71    /// `light` is the fourth layer's relative exposure per pixel — the linear
72    /// quantity, not its logarithm, because the release is a fraction of the
73    /// light absorbed and the log would make the mean meaningless.
74    pub fn apply(&self, density: &mut [[f64; 3]], light: &[f64], width: usize, height: usize) {
75        if self.is_noop() || width == 0 || height == 0 {
76            return;
77        }
78        let pixels = (width * height).min(density.len()).min(light.len());
79        let height = pixels / width;
80        if height == 0 {
81            return;
82        }
83
84        // A scale for the floor below, and the answer to "is there any light".
85        let mean = light[..pixels].iter().sum::<f64>() / pixels as f64;
86        if !mean.is_finite() || mean <= 0.0 {
87            return;
88        }
89        // The inhibitor diffuses before it acts, so a single bright pixel
90        // suppresses its neighbours and not only itself.
91        let sigma_px = self.sigma_um / self.pixel_um.max(1e-9);
92        let diffused = gaussian_blur(&light[..pixels], width, height, sigma_px);
93
94        for (index, pixel) in density[..pixels].iter_mut().enumerate() {
95            // How much more (or less) inhibitor this pixel's neighbourhood made
96            // than the uniform case the curve was measured with. Zero on a flat
97            // region at any brightness; bounded, because a layer cannot be
98            // inhibited by more than "all of it". A pixel that saw nothing next
99            // to one that saw a great deal is the limit case, and it is written
100            // out rather than approached with a floor so that a flat shadow is
101            // exactly unchanged.
102            let local = light[index];
103            let deviation = if local > 0.0 {
104                (diffused[index] / local - 1.0).clamp(-1.0, 1.0)
105            } else if diffused[index] > 0.0 {
106                1.0
107            } else {
108                0.0
109            };
110            // Only the cyan dye: this inhibitor's target is the red-sensitive
111            // layer, which is the one that forms cyan.
112            pixel[0] = (pixel[0] * (1.0 - self.gain * deviation)).max(0.0);
113        }
114    }
115}
116
117#[cfg(test)]
118mod tests {
119    use super::*;
120
121    fn light_from(values: impl Fn(usize) -> f64, count: usize) -> Vec<f64> {
122        (0..count).map(values).collect()
123    }
124
125    /// The invariant the model is built on: a uniform frame comes out
126    /// unchanged, because the uniform inhibition is already in the curve.
127    #[test]
128    fn a_uniform_frame_is_untouched() {
129        let stage = InterImage::typical(6.0);
130        let mut density = vec![[1.0, 0.8, 0.6]; 64];
131        let expected = density.clone();
132        stage.apply(&mut density, &light_from(|_| 3.7, 64), 8, 8);
133        for (left, right) in density.iter().zip(&expected) {
134            assert!((left[0] - right[0]).abs() < 1e-12, "{left:?} vs {right:?}");
135        }
136    }
137
138    /// A step. The bright side's inhibitor diffuses into the dark side, so the
139    /// shadow loses cyan; the bright side keeps less of its own inhibitor than a
140    /// flat patch would, so it gains. Both are bounded by the gain, and both
141    /// fall back to nothing within a few diffusion lengths.
142    #[test]
143    fn a_step_takes_cyan_off_the_shadow_side() {
144        let stage = InterImage {
145            gain: 0.12,
146            sigma_um: 3.0,
147            pixel_um: 1.0,
148        };
149        let mut density = vec![[1.0, 1.0, 1.0]; 64];
150        let light = light_from(|index| if index < 32 { 0.0 } else { 4.0 }, 64);
151        stage.apply(&mut density, &light, 64, 1);
152
153        let shadow = density[31][0];
154        let bright = density[32][0];
155        assert!(shadow < 0.93, "the shadow kept the inhibitor: {shadow:.4}");
156        assert!(
157            bright > 1.01,
158            "the bright side lost instead of gaining: {bright:.4}"
159        );
160        // Bounded by the gain, in both directions.
161        assert!(
162            density
163                .iter()
164                .all(|pixel| (0.88..=1.12).contains(&pixel[0]))
165        );
166        // Far from the boundary both sides are the flat case again.
167        assert!((density[0][0] - 1.0).abs() < 1e-9, "{:?}", density[0]);
168        assert!((density[63][0] - 1.0).abs() < 1e-9, "{:?}", density[63]);
169        // The other two dyes are not this layer's business.
170        assert_eq!([density[31][1], density[31][2]], [1.0, 1.0]);
171    }
172
173    /// A frame with no light anywhere is the uniform case, not a division by
174    /// zero: the layer is dark, so it inhibits nothing below the average and
175    /// there is no average to be below.
176    #[test]
177    fn a_dark_frame_is_untouched() {
178        let stage = InterImage::typical(6.0);
179        let mut density = vec![[0.5, 0.5, 0.5]; 4];
180        stage.apply(&mut density, &[0.0; 4], 2, 2);
181        assert_eq!(density[0], [0.5, 0.5, 0.5]);
182    }
183
184    /// A zero gain is a no-op, so a stock can carry the layer and a flag can
185    /// turn the mechanism off without a second code path.
186    #[test]
187    fn a_zero_gain_changes_nothing() {
188        let stage = InterImage {
189            gain: 0.0,
190            ..InterImage::typical(6.0)
191        };
192        assert!(stage.is_noop());
193        let mut density = vec![[1.0, 1.0, 1.0]; 8];
194        stage.apply(&mut density, &light_from(|index| index as f64, 8), 8, 1);
195        assert_eq!(density[3], [1.0, 1.0, 1.0]);
196    }
197}