Skip to main content

qualia_vision/biosense/magnification/
colour_evm_yiq.rs

1//! Colour Eulerian magnification in YIQ-class chrominance (I/Q), not raw RGB.
2//!
3//! Pipeline: RGB→YIQ → temporal band-pass on I and Q → amplify → YIQ→RGB.
4//! Default path uses global-mean chrominance (Tier-2 series); optional full
5//! per-pixel planes when `band_i`/`band_q` are large enough.
6
7use super::evm_snr_gate::{evm_snr_gate_trace, EvmRefuse, DEFAULT_EVM_MIN_SNR};
8use super::temporal_bandpass::{design_bandpass_iir, temporal_bandpass_series, BandpassIir};
9
10/// Parameters for colour EVM (Wu-style chrominance band amplify).
11#[derive(Debug, Clone, Copy)]
12pub struct ColourEvmParams {
13    pub fps: f32,
14    pub f_lo_hz: f32,
15    pub f_hi_hz: f32,
16    /// Chrominance gain (I/Q).
17    pub alpha_chroma: f32,
18    /// Luma gain (usually 0).
19    pub alpha_luma: f32,
20    pub min_snr: f32,
21    /// If true, gate on global mean-I temporal series SNR and refuse invent.
22    pub require_snr: bool,
23}
24
25impl Default for ColourEvmParams {
26    fn default() -> Self {
27        Self {
28            fps: 30.0,
29            f_lo_hz: 0.7,
30            f_hi_hz: 4.0,
31            alpha_chroma: 50.0,
32            alpha_luma: 0.0,
33            min_snr: DEFAULT_EVM_MIN_SNR,
34            require_snr: true,
35        }
36    }
37}
38
39#[inline]
40fn rgb_to_yiq(r: f32, g: f32, b: f32) -> (f32, f32, f32) {
41    let y = 0.299 * r + 0.587 * g + 0.114 * b;
42    let i = 0.596 * r - 0.274 * g - 0.322 * b;
43    let q = 0.211 * r - 0.523 * g + 0.312 * b;
44    (y, i, q)
45}
46
47#[inline]
48fn yiq_to_rgb(y: f32, i: f32, q: f32) -> (f32, f32, f32) {
49    let r = y + 0.956 * i + 0.621 * q;
50    let g = y - 0.272 * i - 0.647 * q;
51    let b = y - 1.106 * i + 1.703 * q;
52    (r, g, b)
53}
54
55#[inline]
56fn clamp_u8(v: f32) -> u8 {
57    v.clamp(0.0, 255.0) as u8
58}
59
60/// Amplify chrominance temporal band of an RGB frame stack into `out`.
61///
62/// `frames` / `out`: packed `n_frames * width * height * 3` RGB8.
63///
64/// Scratch (caller-owned, Tier-2 OK):
65/// - `trace_scratch`: ≥ `n_frames`
66/// - `band_i`, `band_q`: ≥ `n_frames * px` for pixel path; shorter → mean path
67pub fn colour_evm_yiq(
68    frames: &[u8],
69    n_frames: usize,
70    width: u32,
71    height: u32,
72    params: ColourEvmParams,
73    out: &mut [u8],
74    trace_scratch: &mut [f32],
75    band_i: &mut [f32],
76    band_q: &mut [f32],
77) -> Result<f32, EvmRefuse> {
78    let w = width as usize;
79    let h = height as usize;
80    let px = w * h;
81    let frame_bytes = px * 3;
82    if n_frames < 8 || width == 0 || height == 0 {
83        return Err(EvmRefuse::InsufficientFrames {
84            got: n_frames,
85            need: 8,
86        });
87    }
88    if frames.len() < n_frames * frame_bytes || out.len() < n_frames * frame_bytes {
89        return Err(EvmRefuse::BufferTooSmall);
90    }
91    if trace_scratch.len() < n_frames {
92        return Err(EvmRefuse::BufferTooSmall);
93    }
94
95    let bp = design_bandpass_iir(params.fps, params.f_lo_hz, params.f_hi_hz)?;
96
97    for t in 0..n_frames {
98        let base = t * frame_bytes;
99        let mut si = 0.0f32;
100        for p in 0..px {
101            let o = base + p * 3;
102            let (_y, i, _q) =
103                rgb_to_yiq(frames[o] as f32, frames[o + 1] as f32, frames[o + 2] as f32);
104            si += i;
105        }
106        trace_scratch[t] = si / px as f32;
107    }
108
109    let mut snr = 0.0f32;
110    if params.require_snr {
111        let mut snr_scratch = vec![0.0f32; n_frames];
112        snr = evm_snr_gate_trace(
113            &trace_scratch[..n_frames],
114            params.fps,
115            params.f_lo_hz,
116            params.f_hi_hz,
117            params.min_snr,
118            &mut snr_scratch,
119        )?;
120    }
121
122    let a_c = params.alpha_chroma.clamp(0.0, 200.0);
123    let a_y = params.alpha_luma.clamp(0.0, 50.0);
124    let use_pixel = band_i.len() >= n_frames * px && band_q.len() >= n_frames * px;
125
126    if use_pixel {
127        colour_evm_pixel_path(
128            frames,
129            n_frames,
130            px,
131            frame_bytes,
132            &bp,
133            a_c,
134            a_y,
135            out,
136            band_i,
137            band_q,
138        )?;
139    } else {
140        colour_evm_mean_path(
141            frames,
142            n_frames,
143            px,
144            frame_bytes,
145            &bp,
146            a_c,
147            trace_scratch,
148            out,
149        )?;
150    }
151    Ok(snr)
152}
153
154fn colour_evm_mean_path(
155    frames: &[u8],
156    n_frames: usize,
157    px: usize,
158    frame_bytes: usize,
159    bp: &BandpassIir,
160    alpha: f32,
161    mean_i: &[f32],
162    out: &mut [u8],
163) -> Result<(), EvmRefuse> {
164    let mut band = vec![0.0f32; n_frames];
165    temporal_bandpass_series(&mean_i[..n_frames], bp, &mut band)?;
166    let mut mean_q = vec![0.0f32; n_frames];
167    for t in 0..n_frames {
168        let base = t * frame_bytes;
169        let mut sq = 0.0f32;
170        for p in 0..px {
171            let o = base + p * 3;
172            let (_y, _i, q) =
173                rgb_to_yiq(frames[o] as f32, frames[o + 1] as f32, frames[o + 2] as f32);
174            sq += q;
175        }
176        mean_q[t] = sq / px as f32;
177    }
178    let mut band_q = vec![0.0f32; n_frames];
179    temporal_bandpass_series(&mean_q, bp, &mut band_q)?;
180
181    for t in 0..n_frames {
182        let base = t * frame_bytes;
183        let di = alpha * band[t];
184        let dq = alpha * band_q[t];
185        for p in 0..px {
186            let o = base + p * 3;
187            let (y, i, q) =
188                rgb_to_yiq(frames[o] as f32, frames[o + 1] as f32, frames[o + 2] as f32);
189            let (r, g, b) = yiq_to_rgb(y, i + di, q + dq);
190            out[o] = clamp_u8(r);
191            out[o + 1] = clamp_u8(g);
192            out[o + 2] = clamp_u8(b);
193        }
194    }
195    Ok(())
196}
197
198fn colour_evm_pixel_path(
199    frames: &[u8],
200    n_frames: usize,
201    px: usize,
202    frame_bytes: usize,
203    bp: &BandpassIir,
204    a_c: f32,
205    a_y: f32,
206    out: &mut [u8],
207    band_i: &mut [f32],
208    band_q: &mut [f32],
209) -> Result<(), EvmRefuse> {
210    let plane_need = n_frames * px;
211    for t in 0..n_frames {
212        let base = t * frame_bytes;
213        let pbase = t * px;
214        for p in 0..px {
215            let o = base + p * 3;
216            let (_y, i, q) =
217                rgb_to_yiq(frames[o] as f32, frames[o + 1] as f32, frames[o + 2] as f32);
218            band_i[pbase + p] = i;
219            band_q[pbase + p] = q;
220        }
221    }
222
223    let i_src: Vec<f32> = band_i[..plane_need].to_vec();
224    let q_src: Vec<f32> = band_q[..plane_need].to_vec();
225
226    for p in 0..px {
227        let mut state_lo_i = i_src[p];
228        let mut state_hi_i = i_src[p];
229        let mut state_lo_q = q_src[p];
230        let mut state_hi_q = q_src[p];
231        for t in 0..n_frames {
232            let idx = t * px + p;
233            band_i[idx] = super::temporal_bandpass::bandpass_step(
234                i_src[idx],
235                bp,
236                &mut state_lo_i,
237                &mut state_hi_i,
238            );
239            band_q[idx] = super::temporal_bandpass::bandpass_step(
240                q_src[idx],
241                bp,
242                &mut state_lo_q,
243                &mut state_hi_q,
244            );
245        }
246    }
247
248    for t in 0..n_frames {
249        let base = t * frame_bytes;
250        let pbase = t * px;
251        for p in 0..px {
252            let o = base + p * 3;
253            let (y, i, q) =
254                rgb_to_yiq(frames[o] as f32, frames[o + 1] as f32, frames[o + 2] as f32);
255            let (r, g, b) = yiq_to_rgb(
256                y + a_y * 0.0,
257                i + a_c * band_i[pbase + p],
258                q + a_c * band_q[pbase + p],
259            );
260            out[o] = clamp_u8(r);
261            out[o + 1] = clamp_u8(g);
262            out[o + 2] = clamp_u8(b);
263        }
264    }
265    Ok(())
266}
267
268#[cfg(test)]
269mod tests {
270    use super::*;
271
272    #[test]
273    fn colour_evm_runs_on_pulsing_chroma() {
274        let n = 60usize;
275        let w = 4u32;
276        let h = 4u32;
277        let px = (w * h) as usize;
278        let fb = px * 3;
279        let fps = 30.0f32;
280        let mut frames = vec![128u8; n * fb];
281        for t in 0..n {
282            let phase = (core::f32::consts::TAU * 1.2 * t as f32 / fps).sin();
283            let r = (128.0 + 8.0 * phase).clamp(0.0, 255.0) as u8;
284            let g = 120u8;
285            let b = (128.0 - 6.0 * phase).clamp(0.0, 255.0) as u8;
286            for p in 0..px {
287                let o = t * fb + p * 3;
288                frames[o] = r;
289                frames[o + 1] = g;
290                frames[o + 2] = b;
291            }
292        }
293        let mut out = vec![0u8; n * fb];
294        let mut trace = vec![0.0f32; n];
295        let mut bi = Vec::new();
296        let mut bq = Vec::new();
297        let params = ColourEvmParams {
298            fps,
299            f_lo_hz: 0.7,
300            f_hi_hz: 4.0,
301            alpha_chroma: 20.0,
302            alpha_luma: 0.0,
303            min_snr: 0.05,
304            require_snr: true,
305        };
306        let snr = colour_evm_yiq(
307            &frames, n, w, h, params, &mut out, &mut trace, &mut bi, &mut bq,
308        )
309        .unwrap();
310        assert!(snr >= 0.0);
311        let mut diff = 0u32;
312        for i in 0..frames.len() {
313            diff = diff.saturating_add(frames[i].abs_diff(out[i]) as u32);
314        }
315        assert!(diff > 0, "expected magnification change");
316    }
317}