Skip to main content

qualia_vision/
preprocess.rs

1//! Fixed-buffer preprocess helpers (Phase 1/V1).
2//!
3//! Hot path: no heap. Caller supplies workspace and output buffers.
4
5use crate::types::{Detection, ImageView, PixelFormat, VisionError};
6
7/// Nearest-neighbour resize RGB8 → RGB8 into caller buffer (`out_w * out_h * 3` bytes).
8pub fn resize_nearest_rgb8(
9    src: ImageView<'_>,
10    out_w: u32,
11    out_h: u32,
12    out: &mut [u8],
13) -> Result<(), VisionError> {
14    if !src.is_well_formed() || out_w == 0 || out_h == 0 {
15        return Err(VisionError::MalformedImage);
16    }
17    if src.format == PixelFormat::Rgb8 {
18        return etalon_signal::vision::resize_nearest_rgb8_into(
19            src.bytes,
20            src.width,
21            src.height,
22            src.row_stride,
23            out_w,
24            out_h,
25            out,
26        )
27        .map(|_| ())
28        .map_err(|err| match err {
29            etalon_signal::SignalError::LengthMismatch => VisionError::OutputBufferTooSmall,
30            _ => VisionError::MalformedImage,
31        });
32    }
33    let need = (out_w as usize)
34        .saturating_mul(out_h as usize)
35        .saturating_mul(3);
36    if out.len() < need {
37        return Err(VisionError::OutputBufferTooSmall);
38    }
39    let bpp = src.bytes_per_pixel() as usize;
40    for oy in 0..out_h {
41        let sy = ((oy as u64 * src.height as u64) / out_h as u64) as u32;
42        for ox in 0..out_w {
43            let sx = ((ox as u64 * src.width as u64) / out_w as u64) as u32;
44            let soff = (sy as usize)
45                .saturating_mul(src.row_stride as usize)
46                .saturating_add((sx as usize).saturating_mul(bpp));
47            let doff = ((oy * out_w + ox) * 3) as usize;
48            let (r, g, b) = sample_rgb(src, soff, bpp);
49            out[doff] = r;
50            out[doff + 1] = g;
51            out[doff + 2] = b;
52        }
53    }
54    Ok(())
55}
56
57#[inline]
58fn sample_rgb(src: ImageView<'_>, off: usize, bpp: usize) -> (u8, u8, u8) {
59    if off + bpp > src.bytes.len() {
60        return (0, 0, 0);
61    }
62    match src.format {
63        PixelFormat::Gray8 => {
64            let g = src.bytes[off];
65            (g, g, g)
66        }
67        PixelFormat::Rgb8 | PixelFormat::Rgba8 => {
68            (src.bytes[off], src.bytes[off + 1], src.bytes[off + 2])
69        }
70        PixelFormat::Bgr8 => (src.bytes[off + 2], src.bytes[off + 1], src.bytes[off]),
71        PixelFormat::RgbF32 => (0, 0, 0),
72    }
73}
74
75/// Normalize RGB8 to planar f32 CHW in `out` (len ≥ 3 * w * h). Mean/std per channel.
76pub fn normalize_rgb8_to_f32_chw(
77    rgb: &[u8],
78    w: u32,
79    h: u32,
80    mean: [f32; 3],
81    std: [f32; 3],
82    out: &mut [f32],
83) -> Result<(), VisionError> {
84    if w == 0 || h == 0 {
85        return Ok(());
86    }
87    etalon_signal::vision::normalize_rgb8_to_f32_chw_into(rgb, w, h, mean, std, out)
88        .map(|_| ())
89        .map_err(|err| match err {
90            etalon_signal::SignalError::LengthMismatch => VisionError::OutputBufferTooSmall,
91            _ => VisionError::MalformedImage,
92        })
93}
94
95/// IoU of two axis-aligned boxes in normalized u16 coordinates.
96#[inline]
97pub fn iou_u16(a: &Detection, b: &Detection) -> f32 {
98    etalon_signal::vision::iou_xywh_u16(
99        [
100            a.x_min_u16,
101            a.y_min_u16,
102            a.x_max_u16.saturating_sub(a.x_min_u16),
103            a.y_max_u16.saturating_sub(a.y_min_u16),
104        ],
105        [
106            b.x_min_u16,
107            b.y_min_u16,
108            b.x_max_u16.saturating_sub(b.x_min_u16),
109            b.y_max_u16.saturating_sub(b.y_min_u16),
110        ],
111    )
112}
113
114/// Class-agnostic NMS into `out` (copies survivors). Returns count written.
115/// `workspace` must hold at least `n` bool flags as bytes (0/1).
116pub fn nms_class_agnostic(
117    dets: &[Detection],
118    n: usize,
119    iou_thresh: f32,
120    out: &mut [Detection],
121    workspace: &mut [u8],
122) -> Result<usize, VisionError> {
123    let n = n.min(dets.len());
124    if out.is_empty() {
125        return Err(VisionError::OutputBufferTooSmall);
126    }
127    if workspace.len() < n {
128        return Err(VisionError::WorkspaceTooSmall);
129    }
130    // Selection sort by score descending into index order using workspace as suppressed flags.
131    for i in 0..n {
132        workspace[i] = 0;
133    }
134    let mut order = [0u16; 256];
135    let n_ord = n.min(256);
136    for i in 0..n_ord {
137        order[i] = i as u16;
138    }
139    for i in 0..n_ord {
140        let mut best = i;
141        for j in (i + 1)..n_ord {
142            if dets[order[j] as usize].score_u16 > dets[order[best] as usize].score_u16 {
143                best = j;
144            }
145        }
146        order.swap(i, best);
147    }
148    let mut written = 0usize;
149    for oi in 0..n_ord {
150        let i = order[oi] as usize;
151        if workspace[i] != 0 {
152            continue;
153        }
154        if written >= out.len() {
155            break;
156        }
157        out[written] = dets[i];
158        written += 1;
159        for oj in (oi + 1)..n_ord {
160            let j = order[oj] as usize;
161            if workspace[j] != 0 {
162                continue;
163            }
164            if iou_u16(&dets[i], &dets[j]) > iou_thresh {
165                workspace[j] = 1;
166            }
167        }
168    }
169    Ok(written)
170}
171
172/// Workspace bytes for letterbox RGB8 of size `out_w × out_h`.
173pub fn letterbox_workspace_bytes(out_w: u32, out_h: u32) -> usize {
174    (out_w as usize)
175        .saturating_mul(out_h as usize)
176        .saturating_mul(3)
177}
178
179/// Letterbox RGB into square/out buffer with grey pad (114). Returns scale and pad (x,y) as u32 pixels.
180pub fn letterbox_rgb8(
181    src: ImageView<'_>,
182    out_w: u32,
183    out_h: u32,
184    out: &mut [u8],
185) -> Result<(f32, u32, u32), VisionError> {
186    if !src.is_well_formed() || out_w == 0 || out_h == 0 {
187        return Err(VisionError::MalformedImage);
188    }
189    let need = letterbox_workspace_bytes(out_w, out_h);
190    if out.len() < need {
191        return Err(VisionError::OutputBufferTooSmall);
192    }
193    for b in out.iter_mut().take(need) {
194        *b = 114;
195    }
196    let scale = (out_w as f32 / src.width as f32).min(out_h as f32 / src.height as f32);
197    let nw = ((src.width as f32 * scale) as u32).max(1).min(out_w);
198    let nh = ((src.height as f32 * scale) as u32).max(1).min(out_h);
199    let pad_x = (out_w - nw) / 2;
200    let pad_y = (out_h - nh) / 2;
201    // Resize into temp region via nearest into full out then we already padded — write into ROI.
202    let bpp = src.bytes_per_pixel() as usize;
203    for oy in 0..nh {
204        let sy = ((oy as u64 * src.height as u64) / nh as u64) as u32;
205        for ox in 0..nw {
206            let sx = ((ox as u64 * src.width as u64) / nw as u64) as u32;
207            let soff = (sy as usize)
208                .saturating_mul(src.row_stride as usize)
209                .saturating_add((sx as usize).saturating_mul(bpp));
210            let dx = pad_x + ox;
211            let dy = pad_y + oy;
212            let doff = ((dy * out_w + dx) * 3) as usize;
213            let (r, g, b) = sample_rgb(src, soff, bpp);
214            out[doff] = r;
215            out[doff + 1] = g;
216            out[doff + 2] = b;
217        }
218    }
219    Ok((scale, pad_x, pad_y))
220}
221
222#[cfg(test)]
223mod tests {
224    use super::*;
225    use crate::types::Detection;
226
227    #[test]
228    fn resize_preserves_red() {
229        let mut rgb = [0u8; 12];
230        rgb[0] = 255;
231        rgb[1] = 0;
232        rgb[2] = 0;
233        // 2x2: first pixel red
234        let img = ImageView {
235            bytes: &rgb,
236            width: 2,
237            height: 2,
238            row_stride: 6,
239            format: PixelFormat::Rgb8,
240        };
241        let mut out = [0u8; 3];
242        resize_nearest_rgb8(img, 1, 1, &mut out).unwrap();
243        assert_eq!(out[0], 255);
244    }
245
246    #[test]
247    fn iou_identical_is_one() {
248        let d = Detection {
249            class_hash: 1,
250            instance_hash: 2,
251            score_u16: 1000,
252            x_min_u16: 1000,
253            y_min_u16: 1000,
254            x_max_u16: 2000,
255            y_max_u16: 2000,
256            frame_index: 0,
257            track_id: 0,
258            flags: 0,
259        };
260        assert!((iou_u16(&d, &d) - 1.0).abs() < 1e-5);
261    }
262
263    #[test]
264    fn nms_suppresses_overlap() {
265        let mut a = Detection::empty();
266        a.score_u16 = 50000;
267        a.x_min_u16 = 0;
268        a.y_min_u16 = 0;
269        a.x_max_u16 = 30000;
270        a.y_max_u16 = 30000;
271        let mut b = a;
272        b.score_u16 = 40000;
273        b.x_min_u16 = 1000;
274        b.y_min_u16 = 1000;
275        let dets = [a, b];
276        let mut out = [Detection::empty(); 4];
277        let mut ws = [0u8; 8];
278        let n = nms_class_agnostic(&dets, 2, 0.3, &mut out, &mut ws).unwrap();
279        assert_eq!(n, 1);
280        assert_eq!(out[0].score_u16, 50000);
281    }
282}