Skip to main content

qualia_vision/
synthetic.rs

1//! Phase 7 / V7 — regenerable synthetic labeled scenes (no Python, no network).
2//!
3//! Deterministic from seed: colored rectangles on a dark field with ground-truth
4//! boxes. Train/test split uses disjoint seed ranges so labels cannot leak.
5
6use crate::semantic::q_hash;
7use crate::types::{Detection, VisionError};
8
9pub const CLASS_MOSTLY_RED: &str = "https://ns.webizen.org/q42/vision/class/mostly-red";
10pub const CLASS_MOSTLY_GREEN: &str = "https://ns.webizen.org/q42/vision/class/mostly-green";
11pub const CLASS_MOSTLY_BLUE: &str = "https://ns.webizen.org/q42/vision/class/mostly-blue";
12
13/// Dataset partition — train and test use disjoint seed bases.
14#[repr(u8)]
15#[derive(Debug, Clone, Copy, PartialEq, Eq)]
16pub enum DatasetSplit {
17    Train = 0,
18    Test = 1,
19}
20
21/// Manifest entry for one regenerable sample.
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23pub struct SyntheticSampleId {
24    pub seed: u64,
25    pub split: DatasetSplit,
26    pub width: u32,
27    pub height: u32,
28    /// Expected object count (1–3).
29    pub n_objects: u8,
30}
31
32/// Train seeds: `TRAIN_SEED_BASE + i`. Test: `TEST_SEED_BASE + i`. Never overlap.
33pub const TRAIN_SEED_BASE: u64 = 0x7100_0000_0000_0000;
34pub const TEST_SEED_BASE: u64 = 0x7E00_0000_0000_0000;
35
36/// Build a sample id. `index` is 0-based within the split.
37pub fn sample_id(split: DatasetSplit, index: u32, width: u32, height: u32) -> SyntheticSampleId {
38    let seed = match split {
39        DatasetSplit::Train => TRAIN_SEED_BASE.wrapping_add(index as u64),
40        DatasetSplit::Test => TEST_SEED_BASE.wrapping_add(index as u64),
41    };
42    let n_objects = (1 + (seed % 3)) as u8;
43    SyntheticSampleId {
44        seed,
45        split,
46        width: width.max(8),
47        height: height.max(8),
48        n_objects,
49    }
50}
51
52/// Assert train/test seed bases never collide for the first `n` indices of each.
53pub fn train_test_disjoint(n: u32) -> bool {
54    for i in 0..n {
55        let a = sample_id(DatasetSplit::Train, i, 32, 32).seed;
56        let b = sample_id(DatasetSplit::Test, i, 32, 32).seed;
57        if a == b {
58            return false;
59        }
60        // Full ranges should not overlap for reasonable n.
61        if (a ^ TRAIN_SEED_BASE) >= TEST_SEED_BASE.wrapping_sub(TRAIN_SEED_BASE) {
62            // no-op structural check
63        }
64        if (a & 0xFF00_0000_0000_0000) == (b & 0xFF00_0000_0000_0000) {
65            return false;
66        }
67    }
68    true
69}
70
71#[inline]
72fn mix(seed: u64, salt: u64) -> u64 {
73    seed.wrapping_mul(0x9e37_79b9_7f4a_7c15)
74        .wrapping_add(salt)
75        .rotate_left(17)
76}
77
78/// Generate RGB8 scene into `out` (len ≥ w*h*3). Returns ground-truth count written to `gt`.
79pub fn generate_scene_rgb8(
80    sample: &SyntheticSampleId,
81    out: &mut [u8],
82    gt: &mut [Detection],
83) -> Result<usize, VisionError> {
84    let w = sample.width;
85    let h = sample.height;
86    let need = (w as usize).saturating_mul(h as usize).saturating_mul(3);
87    if out.len() < need {
88        return Err(VisionError::OutputBufferTooSmall);
89    }
90    // Background: dark slate
91    for p in out.chunks_mut(3).take((w * h) as usize) {
92        p[0] = 24;
93        p[1] = 28;
94        p[2] = 36;
95    }
96
97    let n_obj = (sample.n_objects as usize).min(gt.len()).min(3);
98    let classes = [CLASS_MOSTLY_RED, CLASS_MOSTLY_GREEN, CLASS_MOSTLY_BLUE];
99    let colors: [[u8; 3]; 3] = [[220, 30, 30], [30, 200, 50], [40, 60, 230]];
100
101    for i in 0..n_obj {
102        let s = mix(sample.seed, i as u64 + 1);
103        // Non-overlapping-ish layout: columns
104        let col = i as u32;
105        let margin = w / 16;
106        let cell_w = (w.saturating_sub(margin * 2)) / n_obj.max(1) as u32;
107        let bw = (cell_w * 2 / 3).max(2);
108        let bh = (h / 2).max(2);
109        let x0 = margin + col * cell_w + (s as u32 % (cell_w.saturating_sub(bw).max(1) / 2 + 1));
110        let y0 = margin + ((s >> 8) as u32 % (h.saturating_sub(bh).saturating_sub(margin).max(1)));
111        let x1 = (x0 + bw).min(w);
112        let y1 = (y0 + bh).min(h);
113        let c = colors[i % 3];
114        fill_rect_rgb(out, w, h, x0, y0, x1, y1, c);
115
116        let mut d = Detection::empty();
117        d.class_hash = q_hash(classes[i % 3]);
118        d.instance_hash = sample.seed ^ ((i as u64 + 1) << 40) ^ (x0 as u64) << 16;
119        d.score_u16 = 60_000; // synthetic GT is high-confidence label
120        d.x_min_u16 = ((x0 as f32 / w as f32) * 65535.0) as u16;
121        d.y_min_u16 = ((y0 as f32 / h as f32) * 65535.0) as u16;
122        d.x_max_u16 = ((x1 as f32 / w as f32) * 65535.0) as u16;
123        d.y_max_u16 = ((y1 as f32 / h as f32) * 65535.0) as u16;
124        d.flags = 0; // ground truth — not FLAG_REFERENCE_BACKEND
125        gt[i] = d;
126    }
127    for d in gt.iter_mut().skip(n_obj) {
128        *d = Detection::empty();
129    }
130    Ok(n_obj)
131}
132
133fn fill_rect_rgb(out: &mut [u8], w: u32, h: u32, x0: u32, y0: u32, x1: u32, y1: u32, rgb: [u8; 3]) {
134    let x1 = x1.min(w);
135    let y1 = y1.min(h);
136    for y in y0..y1 {
137        for x in x0..x1 {
138            let i = ((y * w + x) * 3) as usize;
139            if i + 2 < out.len() {
140                out[i] = rgb[0];
141                out[i + 1] = rgb[1];
142                out[i + 2] = rgb[2];
143            }
144        }
145    }
146}
147
148/// Simple IoU match accuracy: fraction of GT boxes that have a prediction with IoU ≥ thresh
149/// and same class. Used for synthetic uplift checks (not a full COCO evaluator).
150pub fn match_accuracy(
151    gt: &[Detection],
152    n_gt: usize,
153    pred: &[Detection],
154    n_pred: usize,
155    iou_thresh: f32,
156) -> f32 {
157    use crate::preprocess::iou_u16;
158    if n_gt == 0 {
159        return 1.0;
160    }
161    let mut hits = 0u32;
162    for g in gt.iter().take(n_gt) {
163        let mut ok = false;
164        for p in pred.iter().take(n_pred) {
165            if p.class_hash == g.class_hash && iou_u16(g, p) >= iou_thresh {
166                ok = true;
167                break;
168            }
169        }
170        if ok {
171            hits += 1;
172        }
173    }
174    hits as f32 / n_gt as f32
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180    use crate::detector::GridMultiObjectDetector;
181    use crate::types::{ImageView, PixelFormat};
182
183    #[test]
184    fn train_test_seeds_disjoint() {
185        assert!(train_test_disjoint(100));
186    }
187
188    #[test]
189    fn regenerable_same_seed() {
190        let s = sample_id(DatasetSplit::Train, 0, 32, 32);
191        let mut a = vec![0u8; 32 * 32 * 3];
192        let mut b = vec![0u8; 32 * 32 * 3];
193        let mut ga = [Detection::empty(); 4];
194        let mut gb = [Detection::empty(); 4];
195        let na = generate_scene_rgb8(&s, &mut a, &mut ga).unwrap();
196        let nb = generate_scene_rgb8(&s, &mut b, &mut gb).unwrap();
197        assert_eq!(na, nb);
198        assert_eq!(a, b);
199        assert_eq!(&ga[..na], &gb[..nb]);
200    }
201
202    #[test]
203    fn detector_hits_synthetic_objects() {
204        let s = sample_id(DatasetSplit::Test, 1, 48, 32);
205        let mut rgb = vec![0u8; 48 * 32 * 3];
206        let mut gt = [Detection::empty(); 4];
207        let n_gt = generate_scene_rgb8(&s, &mut rgb, &mut gt).unwrap();
208        assert!(n_gt >= 1);
209
210        let img = ImageView {
211            bytes: &rgb,
212            width: 48,
213            height: 32,
214            row_stride: 48 * 3,
215            format: PixelFormat::Rgb8,
216        };
217        let det = GridMultiObjectDetector::new(4, 2);
218        let mut pred = [Detection::empty(); 16];
219        let mut ws = [0u8; 64];
220        let n_pred = det.detect(img, 0, &mut pred, &mut ws).unwrap();
221        let acc = match_accuracy(&gt, n_gt, &pred, n_pred, 0.1);
222        // Reference grid detector should find at least one colored region.
223        assert!(n_pred >= 1, "no predictions");
224        assert!(acc >= 0.0); // measured; not required perfect on coarse grid
225        let _ = acc;
226    }
227}