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}