Skip to main content

sightloom_host/
preprocess.rs

1//! Pure-Rust preprocess helpers (no image codec dependency).
2//!
3//! Hosts still own decode (JPEG/PNG → RGB). This module resizes / normalizes
4//! dense RGB8 planes into CHW `f32` tensors for future ONNX adapters.
5
6use crate::error::HostError;
7use serde::{Deserialize, Serialize};
8
9/// ImageNet-style or custom normalize + resize plan.
10#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
11pub struct PreprocessConfig {
12    /// Output width.
13    pub width: u32,
14    /// Output height.
15    pub height: u32,
16    /// Per-channel mean (RGB).
17    pub mean: [f32; 3],
18    /// Per-channel std (RGB).
19    pub std: [f32; 3],
20    /// Scale pixel values by `1/255` before mean/std.
21    #[serde(default = "default_true")]
22    pub scale_1_255: bool,
23    /// Keep aspect ratio and pad (YOLO letterbox) instead of stretching.
24    #[serde(default)]
25    pub letterbox: bool,
26    /// Letterbox pad value in `0..=255` (Ultralytics uses 114).
27    #[serde(default = "default_letterbox_pad")]
28    pub letterbox_pad: u8,
29}
30
31fn default_true() -> bool {
32    true
33}
34
35fn default_letterbox_pad() -> u8 {
36    114
37}
38
39impl Default for PreprocessConfig {
40    fn default() -> Self {
41        Self::imagenet_like(640, 640)
42    }
43}
44
45impl PreprocessConfig {
46    /// Common re-id / classifier input size with `ImageNet` mean/std.
47    ///
48    /// Stretches to `width × height` (no letterbox).
49    #[must_use]
50    pub fn imagenet_like(width: u32, height: u32) -> Self {
51        Self {
52            width: width.max(1),
53            height: height.max(1),
54            mean: [0.485, 0.456, 0.406],
55            std: [0.229, 0.224, 0.225],
56            scale_1_255: true,
57            letterbox: false,
58            letterbox_pad: 114,
59        }
60    }
61
62    /// YOLO-style detector input: `/255`, zero mean, unit std, letterbox pad.
63    #[must_use]
64    pub fn yolo_detect(width: u32, height: u32) -> Self {
65        Self {
66            width: width.max(1),
67            height: height.max(1),
68            mean: [0.0, 0.0, 0.0],
69            std: [1.0, 1.0, 1.0],
70            scale_1_255: true,
71            letterbox: true,
72            letterbox_pad: 114,
73        }
74    }
75}
76
77/// Maps network-space boxes back to the source frame.
78#[derive(Clone, Copy, Debug, PartialEq)]
79pub struct Letterbox {
80    /// `net_x = src_x * scale_x + pad_x`.
81    pub scale_x: f32,
82    /// `net_y = src_y * scale_y + pad_y`.
83    pub scale_y: f32,
84    /// Left pad in network pixels.
85    pub pad_x: f32,
86    /// Top pad in network pixels.
87    pub pad_y: f32,
88    /// Network width.
89    pub net_w: u32,
90    /// Network height.
91    pub net_h: u32,
92    /// Source width.
93    pub src_w: u32,
94    /// Source height.
95    pub src_h: u32,
96}
97
98impl Letterbox {
99    /// Stretch (no pad) from source to network size.
100    #[must_use]
101    pub fn stretch(src_w: u32, src_h: u32, net_w: u32, net_h: u32) -> Self {
102        let src_w = src_w.max(1);
103        let src_h = src_h.max(1);
104        let net_w = net_w.max(1);
105        let net_h = net_h.max(1);
106        Self {
107            scale_x: net_w as f32 / src_w as f32,
108            scale_y: net_h as f32 / src_h as f32,
109            pad_x: 0.0,
110            pad_y: 0.0,
111            net_w,
112            net_h,
113            src_w,
114            src_h,
115        }
116    }
117
118    /// Maps a network-space point onto the source frame (clamped).
119    #[must_use]
120    pub fn to_source(self, x: f32, y: f32) -> (f32, f32) {
121        let sx = ((x - self.pad_x) / self.scale_x.max(1e-6)).clamp(0.0, self.src_w as f32);
122        let sy = ((y - self.pad_y) / self.scale_y.max(1e-6)).clamp(0.0, self.src_h as f32);
123        (sx, sy)
124    }
125}
126
127/// Nearest-neighbor resize of packed RGB8 → packed RGB8 at `out_w × out_h`.
128///
129/// # Errors
130///
131/// Buffer size mismatches.
132pub fn resize_rgb8_nearest(
133    src: &[u8],
134    src_w: u32,
135    src_h: u32,
136    out_w: u32,
137    out_h: u32,
138) -> Result<Vec<u8>, HostError> {
139    let src_w = src_w.max(1) as usize;
140    let src_h = src_h.max(1) as usize;
141    let out_w = out_w.max(1) as usize;
142    let out_h = out_h.max(1) as usize;
143    let need = src_w
144        .checked_mul(src_h)
145        .and_then(|n| n.checked_mul(3))
146        .ok_or_else(|| HostError::Preprocess("src size overflow".into()))?;
147    if src.len() < need {
148        return Err(HostError::Preprocess(format!(
149            "rgb buffer too small: have {} need {need}",
150            src.len()
151        )));
152    }
153    let mut out = vec![0_u8; out_w * out_h * 3];
154    for y in 0..out_h {
155        let sy = y * src_h / out_h;
156        for x in 0..out_w {
157            let sx = x * src_w / out_w;
158            let si = (sy * src_w + sx) * 3;
159            let di = (y * out_w + x) * 3;
160            out[di] = src[si];
161            out[di + 1] = src[si + 1];
162            out[di + 2] = src[si + 2];
163        }
164    }
165    Ok(out)
166}
167
168/// RGB8 packed → CHW `f32` with mean/std (and optional /255).
169///
170/// Layout: `[R plane | G plane | B plane]`, length `3 * W * H`.
171///
172/// # Errors
173///
174/// Size mismatch.
175pub fn rgb8_to_chw_f32(
176    rgb: &[u8],
177    width: u32,
178    height: u32,
179    cfg: &PreprocessConfig,
180) -> Result<Vec<f32>, HostError> {
181    let w = width as usize;
182    let h = height as usize;
183    let n = w
184        .checked_mul(h)
185        .ok_or_else(|| HostError::Preprocess("plane overflow".into()))?;
186    let need = n
187        .checked_mul(3)
188        .ok_or_else(|| HostError::Preprocess("rgb overflow".into()))?;
189    if rgb.len() < need {
190        return Err(HostError::Preprocess("rgb buffer too small".into()));
191    }
192    let mut out = vec![0.0_f32; need];
193    for i in 0..n {
194        let base = i * 3;
195        for c in 0..3 {
196            let mut v = f32::from(rgb[base + c]);
197            if cfg.scale_1_255 {
198                v /= 255.0;
199            }
200            v = (v - cfg.mean[c]) / cfg.std[c].max(1e-6);
201            out[c * n + i] = v;
202        }
203    }
204    Ok(out)
205}
206
207/// Letterbox packed RGB8 into `net_w × net_h` with a constant pad.
208///
209/// # Errors
210///
211/// Buffer size mismatches.
212pub fn letterbox_rgb8(
213    src: &[u8],
214    src_w: u32,
215    src_h: u32,
216    net_w: u32,
217    net_h: u32,
218    pad: u8,
219) -> Result<(Vec<u8>, Letterbox), HostError> {
220    let src_w = src_w.max(1);
221    let src_h = src_h.max(1);
222    let net_w = net_w.max(1);
223    let net_h = net_h.max(1);
224    let scale = (net_w as f32 / src_w as f32).min(net_h as f32 / src_h as f32);
225    let inner_w = ((src_w as f32 * scale).round() as u32).clamp(1, net_w);
226    let inner_h = ((src_h as f32 * scale).round() as u32).clamp(1, net_h);
227    let pad_x = (net_w - inner_w) / 2;
228    let pad_y = (net_h - inner_h) / 2;
229    let resized = resize_rgb8_nearest(src, src_w, src_h, inner_w, inner_h)?;
230    let mut out = vec![pad; (net_w as usize) * (net_h as usize) * 3];
231    let dest_w = net_w as usize;
232    let copy_w = inner_w as usize;
233    let copy_h = inner_h as usize;
234    let ox = pad_x as usize;
235    let oy = pad_y as usize;
236    for y in 0..copy_h {
237        let src_row = y * copy_w * 3;
238        let dst_row = ((oy + y) * dest_w + ox) * 3;
239        out[dst_row..dst_row + copy_w * 3].copy_from_slice(&resized[src_row..src_row + copy_w * 3]);
240    }
241    Ok((
242        out,
243        Letterbox {
244            scale_x: inner_w as f32 / src_w as f32,
245            scale_y: inner_h as f32 / src_h as f32,
246            pad_x: pad_x as f32,
247            pad_y: pad_y as f32,
248            net_w,
249            net_h,
250            src_w,
251            src_h,
252        },
253    ))
254}
255
256/// Resize (or letterbox) then normalize. Returns the mapping used for boxes.
257///
258/// # Errors
259///
260/// Preprocess failures.
261pub fn prepare_rgb8_nchw_with_meta(
262    src: &[u8],
263    src_w: u32,
264    src_h: u32,
265    cfg: &PreprocessConfig,
266) -> Result<(Vec<f32>, Letterbox), HostError> {
267    let (plane, meta) = if cfg.letterbox {
268        letterbox_rgb8(src, src_w, src_h, cfg.width, cfg.height, cfg.letterbox_pad)?
269    } else {
270        let resized = resize_rgb8_nearest(src, src_w, src_h, cfg.width, cfg.height)?;
271        (
272            resized,
273            Letterbox::stretch(src_w, src_h, cfg.width, cfg.height),
274        )
275    };
276    let tensor = rgb8_to_chw_f32(&plane, cfg.width, cfg.height, cfg)?;
277    Ok((tensor, meta))
278}
279
280/// Resize then normalize in one shot.
281///
282/// # Errors
283///
284/// Preprocess failures.
285pub fn prepare_rgb8_nchw(
286    src: &[u8],
287    src_w: u32,
288    src_h: u32,
289    cfg: &PreprocessConfig,
290) -> Result<Vec<f32>, HostError> {
291    Ok(prepare_rgb8_nchw_with_meta(src, src_w, src_h, cfg)?.0)
292}
293
294/// Crops an axis-aligned box from packed RGB8 (clamped to image).
295///
296/// # Errors
297///
298/// Empty crop / buffer issues.
299pub fn crop_rgb8(
300    src: &[u8],
301    src_w: u32,
302    src_h: u32,
303    left: u32,
304    top: u32,
305    right: u32,
306    bottom: u32,
307) -> Result<(Vec<u8>, u32, u32), HostError> {
308    let width = src_w as usize;
309    let height = src_h as usize;
310    let need = width
311        .checked_mul(height)
312        .and_then(|n| n.checked_mul(3))
313        .ok_or_else(|| HostError::Preprocess("crop size overflow".into()))?;
314    if src.len() < need {
315        return Err(HostError::Preprocess(
316            "rgb buffer too small for crop".into(),
317        ));
318    }
319    let left_i = (left as usize).min(width.saturating_sub(1));
320    let top_i = (top as usize).min(height.saturating_sub(1));
321    let right_i = (right as usize).clamp(left_i + 1, width);
322    let bottom_i = (bottom as usize).clamp(top_i + 1, height);
323    let crop_w = right_i - left_i;
324    let crop_h = bottom_i - top_i;
325    let mut out = vec![0_u8; crop_w * crop_h * 3];
326    for y in 0..crop_h {
327        for x in 0..crop_w {
328            let si = ((top_i + y) * width + (left_i + x)) * 3;
329            let di = (y * crop_w + x) * 3;
330            out[di..di + 3].copy_from_slice(&src[si..si + 3]);
331        }
332    }
333    Ok((out, crop_w as u32, crop_h as u32))
334}
335
336#[cfg(test)]
337mod tests {
338    use super::*;
339
340    #[test]
341    fn resize_and_chw_shapes() {
342        let src = vec![10_u8, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120]; // 2x2 RGB
343        let cfg = PreprocessConfig::imagenet_like(4, 4);
344        let t = prepare_rgb8_nchw(&src, 2, 2, &cfg).unwrap();
345        assert_eq!(t.len(), 4 * 4 * 3);
346    }
347
348    #[test]
349    fn crop_center() {
350        // 3x1 RGB row
351        let src = [1, 2, 3, 4, 5, 6, 7, 8, 9];
352        let (crop, w, h) = crop_rgb8(&src, 3, 1, 1, 0, 2, 1).unwrap();
353        assert_eq!((w, h), (1, 1));
354        assert_eq!(crop, vec![4, 5, 6]);
355    }
356
357    #[test]
358    fn letterbox_keeps_aspect_and_inverts() {
359        let src = vec![200_u8; 40 * 20 * 3];
360        let (out, meta) = letterbox_rgb8(&src, 40, 20, 64, 64, 114).unwrap();
361        assert_eq!(out.len(), 64 * 64 * 3);
362        assert!((meta.scale_x - meta.scale_y).abs() < 1e-5);
363        assert!(meta.pad_y > meta.pad_x);
364        let (x, y) = meta.to_source(meta.pad_x, meta.pad_y);
365        assert!(x < 1.0 && y < 1.0);
366        let (x2, y2) = meta.to_source(
367            meta.pad_x + 40.0 * meta.scale_x,
368            meta.pad_y + 20.0 * meta.scale_y,
369        );
370        assert!((x2 - 40.0).abs() < 1.5);
371        assert!((y2 - 20.0).abs() < 1.5);
372    }
373
374    #[test]
375    fn yolo_detect_preset_letterboxes() {
376        let src = vec![10_u8; 8 * 4 * 3];
377        let cfg = PreprocessConfig::yolo_detect(16, 16);
378        let (t, meta) = prepare_rgb8_nchw_with_meta(&src, 8, 4, &cfg).unwrap();
379        assert_eq!(t.len(), 16 * 16 * 3);
380        assert!(cfg.letterbox);
381        assert!(meta.pad_y >= meta.pad_x);
382    }
383}