Skip to main content

incin_data/transforms/
mod.rs

1//! Data transformation and augmentation pipeline.
2//!
3//! Provides traits and implementations for data preprocessing, batch normalization,
4//! image transformations, and pipeline composition.
5
6use crate::loader::{BatchResult as Result, DataError};
7use alloc::boxed::Box;
8use alloc::vec;
9use alloc::vec::Vec;
10
11/// Rejects a transform input that violates its declared contract.
12fn invalid_input(message: impl Into<String>) -> DataError {
13    DataError::InvalidInput(message.into())
14}
15use rand::RngExt as _;
16
17/// Core trait for a data transformation step.
18pub trait Transform: Send + Sync {
19    /// Input data type.
20    type Input;
21    /// Output data type.
22    type Output;
23
24    /// Applies the transformation to `input`.
25    fn transform(&self, input: Self::Input) -> Result<Self::Output>;
26}
27
28/// Pipeline composing multiple sequential transformations on the same data type.
29pub struct Compose<T> {
30    transforms: Vec<Box<dyn Transform<Input = T, Output = T>>>,
31}
32
33impl<T> Compose<T> {
34    /// Creates a new empty transform pipeline.
35    pub fn new() -> Self {
36        Self {
37            transforms: Vec::new(),
38        }
39    }
40
41    /// Appends a transform step to the pipeline.
42    pub fn push<TR>(mut self, transform: TR) -> Self
43    where
44        TR: Transform<Input = T, Output = T> + 'static,
45    {
46        self.transforms.push(Box::new(transform));
47        self
48    }
49}
50
51impl<T> Default for Compose<T> {
52    fn default() -> Self {
53        Self::new()
54    }
55}
56
57impl<T> Transform for Compose<T> {
58    type Input = T;
59    type Output = T;
60
61    fn transform(&self, mut input: Self::Input) -> Result<Self::Output> {
62        for t in &self.transforms {
63            input = t.transform(input)?;
64        }
65        Ok(input)
66    }
67}
68
69/// Normalizes floating point slice values across channels: `out[c] = (in[c] - mean[c]) / std[c]`.
70#[derive(Debug, Clone)]
71pub struct Normalize {
72    /// Mean value per channel.
73    pub mean: Vec<f32>,
74    /// Standard deviation value per channel.
75    pub std: Vec<f32>,
76}
77
78impl Normalize {
79    /// Creates a new `Normalize` transform for 1 or more channels.
80    pub fn new(mean: Vec<f32>, std: Vec<f32>) -> Self {
81        Self { mean, std }
82    }
83
84    /// Standard ImageNet normalization (3 channels).
85    pub fn imagenet() -> Self {
86        Self {
87            mean: vec![0.485, 0.456, 0.406],
88            std: vec![0.229, 0.224, 0.225],
89        }
90    }
91}
92
93impl Transform for Normalize {
94    type Input = (Vec<f32>, Vec<usize>); // (data, shape [C, H, W] or [C, L])
95    type Output = (Vec<f32>, Vec<usize>);
96
97    fn transform(&self, (mut data, shape): Self::Input) -> Result<Self::Output> {
98        if shape.is_empty() {
99            return Err(invalid_input(
100                "Normalize transform requires a non-empty shape",
101            ));
102        }
103        let channels = shape[0];
104        if channels != self.mean.len() || channels != self.std.len() {
105            return Err(invalid_input(format!(
106                "Normalize channel count mismatch: input has {} channels, mean has {}, std has {}",
107                channels,
108                self.mean.len(),
109                self.std.len()
110            )));
111        }
112
113        let channel_stride = data.len() / channels;
114        for c in 0..channels {
115            let mean_c = self.mean[c];
116            let std_c = self.std[c];
117            if std_c == 0.0 {
118                return Err(invalid_input(format!(
119                    "Normalize std dev cannot be zero for channel {c}"
120                )));
121            }
122            let start = c * channel_stride;
123            let end = start + channel_stride;
124            for val in &mut data[start..end] {
125                *val = (*val - mean_c) / std_c;
126            }
127        }
128        Ok((data, shape))
129    }
130}
131
132/// Multiplies all elements in a flat float buffer by a scaling factor (e.g. `1.0 / 255.0`).
133#[derive(Debug, Clone, Copy)]
134pub struct Scale {
135    /// Scaling factor.
136    pub factor: f32,
137}
138
139impl Scale {
140    /// Creates a new `Scale` transform with the given factor.
141    pub fn new(factor: f32) -> Self {
142        Self { factor }
143    }
144}
145
146impl Transform for Scale {
147    type Input = Vec<f32>;
148    type Output = Vec<f32>;
149
150    fn transform(&self, mut input: Self::Input) -> Result<Self::Output> {
151        for x in &mut input {
152            *x *= self.factor;
153        }
154        Ok(input)
155    }
156}
157
158/// Randomly flips 2D or 3D image data ([C, H, W]) horizontally along the width axis with probability `p`.
159#[derive(Debug, Clone, Copy)]
160pub struct RandomHorizontalFlip {
161    /// Probability of flipping (default 0.5).
162    pub p: f64,
163}
164
165impl RandomHorizontalFlip {
166    /// Creates a new `RandomHorizontalFlip` with probability `p`.
167    pub fn new(p: f64) -> Self {
168        Self { p }
169    }
170}
171
172impl Default for RandomHorizontalFlip {
173    fn default() -> Self {
174        Self { p: 0.5 }
175    }
176}
177
178impl Transform for RandomHorizontalFlip {
179    type Input = (Vec<f32>, Vec<usize>); // (data, shape [C, H, W])
180    type Output = (Vec<f32>, Vec<usize>);
181
182    fn transform(&self, (data, shape): Self::Input) -> Result<Self::Output> {
183        if shape.len() != 3 {
184            return Err(invalid_input(
185                "RandomHorizontalFlip requires 3D shape [C, H, W]",
186            ));
187        }
188        let mut rng = rand::rng();
189        if rng.random_bool(self.p) {
190            let channels = shape[0];
191            let height = shape[1];
192            let width = shape[2];
193
194            let mut flipped = vec![0.0f32; data.len()];
195            for c in 0..channels {
196                for h in 0..height {
197                    for w in 0..width {
198                        let src_idx = c * height * width + h * width + w;
199                        let dst_idx = c * height * width + h * width + (width - 1 - w);
200                        flipped[dst_idx] = data[src_idx];
201                    }
202                }
203            }
204            Ok((flipped, shape))
205        } else {
206            Ok((data, shape))
207        }
208    }
209}
210
211/// Center-crops a 3D tensor ([C, H, W]) to target height `crop_h` and width `crop_w`.
212#[derive(Debug, Clone, Copy)]
213pub struct CenterCrop {
214    /// Target height.
215    pub crop_h: usize,
216    /// Target width.
217    pub crop_w: usize,
218}
219
220impl CenterCrop {
221    /// Creates a new `CenterCrop` with target dimensions.
222    pub fn new(crop_h: usize, crop_w: usize) -> Self {
223        Self { crop_h, crop_w }
224    }
225}
226
227impl Transform for CenterCrop {
228    type Input = (Vec<f32>, Vec<usize>); // (data, shape [C, H, W])
229    type Output = (Vec<f32>, Vec<usize>);
230
231    fn transform(&self, (data, shape): Self::Input) -> Result<Self::Output> {
232        if shape.len() != 3 {
233            return Err(invalid_input("CenterCrop requires 3D shape [C, H, W]"));
234        }
235        let c = shape[0];
236        let h = shape[1];
237        let w = shape[2];
238
239        if self.crop_h > h || self.crop_w > w {
240            return Err(invalid_input(format!(
241                "Crop dimensions [{}, {}] exceed image dimensions [{}, {}]",
242                self.crop_h, self.crop_w, h, w
243            )));
244        }
245
246        let start_h = (h - self.crop_h) / 2;
247        let start_w = (w - self.crop_w) / 2;
248
249        let mut cropped = Vec::with_capacity(c * self.crop_h * self.crop_w);
250        for ch in 0..c {
251            for row in start_h..(start_h + self.crop_h) {
252                let row_start = ch * h * w + row * w + start_w;
253                let row_end = row_start + self.crop_w;
254                cropped.extend_from_slice(&data[row_start..row_end]);
255            }
256        }
257        Ok((cropped, vec![c, self.crop_h, self.crop_w]))
258    }
259}
260
261#[cfg(test)]
262mod tests {
263    use super::*;
264
265    #[test]
266    fn test_scale_transform() {
267        let scale = Scale::new(0.5);
268        let data = vec![1.0, 2.0, 4.0, 8.0];
269        let out = scale.transform(data).unwrap();
270        assert_eq!(out, vec![0.5, 1.0, 2.0, 4.0]);
271    }
272
273    #[test]
274    fn test_normalize_transform() {
275        let norm = Normalize::new(vec![0.5, 1.0], vec![0.5, 2.0]);
276        let data = vec![1.0, 0.5, 5.0, 1.0]; // 2 channels, 2 elements each
277        let (out, shape) = norm.transform((data, vec![2, 2])).unwrap();
278        assert_eq!(shape, vec![2, 2]);
279        // ch0: (1.0-0.5)/0.5 = 1.0, (0.5-0.5)/0.5 = 0.0
280        // ch1: (5.0-1.0)/2.0 = 2.0, (1.0-1.0)/2.0 = 0.0
281        assert_eq!(out, vec![1.0, 0.0, 2.0, 0.0]);
282    }
283
284    #[test]
285    fn test_center_crop_transform() {
286        let crop = CenterCrop::new(2, 2);
287        // 1 channel, 4x4 image
288        let data: Vec<f32> = (0..16).map(|x| x as f32).collect();
289        let (out, shape) = crop.transform((data, vec![1, 4, 4])).unwrap();
290        assert_eq!(shape, vec![1, 2, 2]);
291        // Center 2x2 of 4x4: rows 1..3, cols 1..3 -> [5, 6, 9, 10]
292        assert_eq!(out, vec![5.0, 6.0, 9.0, 10.0]);
293    }
294
295    #[test]
296    fn normalize_rejects_empty_shape_as_invalid_input() {
297        let error = Normalize::new(vec![1.0], vec![1.0])
298            .transform((vec![1.0], Vec::new()))
299            .expect_err("an empty shape has no channel axis");
300        assert!(matches!(error, DataError::InvalidInput(_)));
301    }
302
303    #[test]
304    fn normalize_rejects_channel_count_mismatch_as_invalid_input() {
305        let error = Normalize::new(vec![1.0], vec![1.0])
306            .transform((vec![1.0, 2.0], vec![3]))
307            .expect_err("three channels cannot be normalized by one mean and std");
308        assert!(matches!(error, DataError::InvalidInput(_)));
309    }
310
311    #[test]
312    fn normalize_rejects_zero_std_as_invalid_input() {
313        let error = Normalize::new(vec![1.0], vec![0.0])
314            .transform((vec![1.0], vec![1]))
315            .expect_err("a zero standard deviation divides every value by zero");
316        assert!(matches!(error, DataError::InvalidInput(_)));
317    }
318
319    #[test]
320    fn random_horizontal_flip_rejects_non_3d_shape_as_invalid_input() {
321        let error = RandomHorizontalFlip::default()
322            .transform((vec![1.0, 2.0], vec![2]))
323            .expect_err("the flip kernel indexes channels, height, and width");
324        assert!(matches!(error, DataError::InvalidInput(_)));
325    }
326
327    #[test]
328    fn center_crop_rejects_crop_larger_than_image_as_invalid_input() {
329        let error = CenterCrop::new(8, 8)
330            .transform((vec![0.0; 16], vec![1, 4, 4]))
331            .expect_err("a crop larger than the image has no center");
332        assert!(matches!(error, DataError::InvalidInput(_)));
333    }
334}