qualia_vision/biosense/magnification/
colour_evm_yiq.rs1use 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#[derive(Debug, Clone, Copy)]
12pub struct ColourEvmParams {
13 pub fps: f32,
14 pub f_lo_hz: f32,
15 pub f_hi_hz: f32,
16 pub alpha_chroma: f32,
18 pub alpha_luma: f32,
20 pub min_snr: f32,
21 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
60pub 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}