@camera.ui/rust-postprocessor 0.0.1 → 0.0.3

package/src/merge.rs

@@ -1,312 +0,0 @@
-//! Per-class union-find clustering of nearby/overlapping detections.
-//!
-//! This is a separate dedup pass from NMS: where NMS keeps the highest-
-//! confidence box and discards its rivals, this function **merges** every
-//! cluster of close-or-overlapping same-label boxes into a single union
-//! bounding box covering all members. Useful when an object detector
-//! consistently splits a single physical object into several adjacent
-//! detections (e.g. a person torso + legs becoming two boxes).
-//!
-//! Two boxes are clustered together if either condition holds:
-//!   1. Their top-left corners are within `close_threshold` along both
-//!      axes (cheap proximity check that survives zero IoU), OR
-//!   2. Their IoU exceeds `iou_threshold`.
-//!
-//! Output: one Detection per connected component, with `box` set to the
-//! axis-aligned union of all member boxes (clamped to `[0, 1]`) and
-//! `confidence` set to the maximum confidence in the cluster. The cluster
-//! inherits the label and remaining metadata from the first member of the
-//! group (all members share the same label since we group by label first).
-
-use std::collections::HashMap;
-
-use crate::types::Detection;
-
-/// Merge nearby/overlapping same-label detections via union-find clustering.
-pub fn merge_detections(
-  detections: Vec<Detection>,
-  iou_threshold: f32,
-  close_threshold: f32,
-) -> Vec<Detection> {
-  if detections.is_empty() {
-    return Vec::new();
-  }
-
-  // Fast path: when all detections share the same label (common after NMS
-  // reduces to 1-2 objects of the same class), skip HashMap grouping.
-  let all_same_label = detections.windows(2).all(|w| w[0].label == w[1].label);
-
-  let mut result: Vec<Detection> = Vec::with_capacity(detections.len());
-
-  if all_same_label {
-    let indices: Vec<usize> = (0..detections.len()).collect();
-    merge_cluster(
-      &detections,
-      &indices,
-      iou_threshold,
-      close_threshold,
-      &mut result,
-    );
-    return result;
-  }
-
-  // Group by label so clustering only happens within a class.
-  let mut by_label: HashMap<String, Vec<usize>> = HashMap::new();
-  for (i, det) in detections.iter().enumerate() {
-    by_label.entry(det.label.clone()).or_default().push(i);
-  }
-
-  for (_label, indices) in by_label {
-    merge_cluster(
-      &detections,
-      &indices,
-      iou_threshold,
-      close_threshold,
-      &mut result,
-    );
-  }
-
-  result
-}
-
-/// Cluster a single-label group of detections and append results to `out`.
-fn merge_cluster(
-  detections: &[Detection],
-  indices: &[usize],
-  iou_threshold: f32,
-  close_threshold: f32,
-  out: &mut Vec<Detection>,
-) {
-  let n = indices.len();
-
-  if n == 1 {
-    out.push(detections[indices[0]].clone());
-    return;
-  }
-
-  // Pack box corners + areas into a SoA layout for cache-friendly
-  // pairwise comparison: [x1, y1, x2, y2, area] per detection.
-  let mut boxes = vec![0.0f32; n * 5];
-  for (i, &orig_idx) in indices.iter().enumerate() {
-    let det = &detections[orig_idx];
-    let off = i * 5;
-    boxes[off] = det.x;
-    boxes[off + 1] = det.y;
-    boxes[off + 2] = det.x + det.width;
-    boxes[off + 3] = det.y + det.height;
-    boxes[off + 4] = det.width * det.height;
-  }
-
-  // Union-find with path-compression. `parent[i]` points to the
-  // representative of i's cluster.
-  let mut parent: Vec<usize> = (0..n).collect();
-  fn find(parent: &mut [usize], mut x: usize) -> usize {
-    while parent[x] != x {
-      parent[x] = parent[parent[x]];
-      x = parent[x];
-    }
-    x
-  }
-  fn union(parent: &mut [usize], a: usize, b: usize) {
-    let ra = find(parent, a);
-    let rb = find(parent, b);
-    parent[ra] = rb;
-  }
-
-  for i in 0..n {
-    let off_i = i * 5;
-    let ix1 = boxes[off_i];
-    let iy1 = boxes[off_i + 1];
-    let ix2 = boxes[off_i + 2];
-    let iy2 = boxes[off_i + 3];
-    let i_area = boxes[off_i + 4];
-
-    for j in (i + 1)..n {
-      let off_j = j * 5;
-
-      let close = (ix1 - boxes[off_j]).abs() <= close_threshold
-        && (iy1 - boxes[off_j + 1]).abs() <= close_threshold;
-      if close {
-        union(&mut parent, i, j);
-        continue;
-      }
-
-      let inter_x1 = ix1.max(boxes[off_j]);
-      let inter_y1 = iy1.max(boxes[off_j + 1]);
-      let inter_x2 = ix2.min(boxes[off_j + 2]);
-      let inter_y2 = iy2.min(boxes[off_j + 3]);
-      if inter_x2 <= inter_x1 || inter_y2 <= inter_y1 {
-        continue;
-      }
-      let inter_area = (inter_x2 - inter_x1) * (inter_y2 - inter_y1);
-      let union_area = i_area + boxes[off_j + 4] - inter_area;
-      if union_area <= 0.0 {
-        continue;
-      }
-      let iou = inter_area / union_area;
-      if iou > iou_threshold {
-        union(&mut parent, i, j);
-      }
-    }
-  }
-
-  // Collect cluster members keyed by their representative.
-  let mut clusters: HashMap<usize, Vec<usize>> = HashMap::new();
-  for i in 0..n {
-    let root = find(&mut parent, i);
-    clusters.entry(root).or_default().push(i);
-  }
-
-  for (_root, members) in clusters {
-    if members.len() == 1 {
-      out.push(detections[indices[members[0]]].clone());
-      continue;
-    }
-
-    let mut min_x = 1.0f32;
-    let mut min_y = 1.0f32;
-    let mut max_x = 0.0f32;
-    let mut max_y = 0.0f32;
-    let mut max_conf = 0.0f32;
-
-    for &m in &members {
-      let off = m * 5;
-      if boxes[off] < min_x {
-        min_x = boxes[off];
-      }
-      if boxes[off + 1] < min_y {
-        min_y = boxes[off + 1];
-      }
-      if boxes[off + 2] > max_x {
-        max_x = boxes[off + 2];
-      }
-      if boxes[off + 3] > max_y {
-        max_y = boxes[off + 3];
-      }
-      let conf = detections[indices[m]].confidence;
-      if conf > max_conf {
-        max_conf = conf;
-      }
-    }
-
-    min_x = min_x.max(0.0);
-    min_y = min_y.max(0.0);
-    max_x = max_x.min(1.0);
-    max_y = max_y.min(1.0);
-
-    let w = max_x - min_x;
-    let h = max_y - min_y;
-    if w <= 0.0 || h <= 0.0 {
-      continue;
-    }
-
-    let template = &detections[indices[members[0]]];
-    out.push(Detection {
-      x: min_x,
-      y: min_y,
-      width: w,
-      height: h,
-      confidence: max_conf,
-      label: template.label.clone(),
-    });
-  }
-}
-
-#[cfg(test)]
-mod tests {
-  use super::*;
-
-  fn det(x: f32, y: f32, w: f32, h: f32, conf: f32, label: &str) -> Detection {
-    Detection {
-      x,
-      y,
-      width: w,
-      height: h,
-      confidence: conf,
-      label: label.to_string(),
-    }
-  }
-
-  #[test]
-  fn empty_input() {
-    assert!(merge_detections(Vec::new(), 0.5, 0.1).is_empty());
-  }
-
-  #[test]
-  fn single_detection_unchanged() {
-    let input = vec![det(0.1, 0.1, 0.2, 0.2, 0.9, "person")];
-    let out = merge_detections(input, 0.5, 0.1);
-    assert_eq!(out.len(), 1);
-    assert!((out[0].x - 0.1).abs() < 1e-6);
-    assert!((out[0].confidence - 0.9).abs() < 1e-6);
-  }
-
-  #[test]
-  fn overlapping_boxes_merged_to_union() {
-    // Two boxes with significant overlap should collapse into one
-    // covering the full extent.
-    let input = vec![
-      det(0.1, 0.1, 0.2, 0.2, 0.7, "person"),
-      det(0.15, 0.15, 0.2, 0.2, 0.9, "person"),
-    ];
-    let out = merge_detections(input, 0.01, 0.001);
-    assert_eq!(out.len(), 1);
-    let m = &out[0];
-    // Union covers [0.1..0.35] x [0.1..0.35]
-    assert!((m.x - 0.1).abs() < 1e-6);
-    assert!((m.y - 0.1).abs() < 1e-6);
-    assert!((m.width - 0.25).abs() < 1e-6);
-    assert!((m.height - 0.25).abs() < 1e-6);
-    // Max confidence in the cluster
-    assert!((m.confidence - 0.9).abs() < 1e-6);
-  }
-
-  #[test]
-  fn close_corners_merged_even_without_iou() {
-    // Two non-overlapping boxes whose top-left corners are within
-    // close_threshold should still cluster (the cheap proximity rule).
-    let input = vec![
-      det(0.10, 0.10, 0.05, 0.05, 0.8, "person"),
-      det(0.12, 0.12, 0.05, 0.05, 0.7, "person"),
-    ];
-    let out = merge_detections(input, 0.5, 0.05);
-    assert_eq!(out.len(), 1);
-  }
-
-  #[test]
-  fn different_labels_not_merged() {
-    let input = vec![
-      det(0.1, 0.1, 0.2, 0.2, 0.7, "person"),
-      det(0.1, 0.1, 0.2, 0.2, 0.9, "car"),
-    ];
-    let out = merge_detections(input, 0.01, 0.001);
-    assert_eq!(out.len(), 2);
-  }
-
-  #[test]
-  fn distant_boxes_not_merged() {
-    let input = vec![
-      det(0.1, 0.1, 0.05, 0.05, 0.7, "person"),
-      det(0.8, 0.8, 0.05, 0.05, 0.9, "person"),
-    ];
-    let out = merge_detections(input, 0.5, 0.01);
-    assert_eq!(out.len(), 2);
-  }
-
-  #[test]
-  fn three_box_chain() {
-    // a–b overlap, b–c overlap, a–c don't — union-find should still
-    // collapse all three into one cluster via the chain.
-    let input = vec![
-      det(0.10, 0.10, 0.10, 0.10, 0.5, "person"),
-      det(0.15, 0.15, 0.10, 0.10, 0.6, "person"),
-      det(0.20, 0.20, 0.10, 0.10, 0.7, "person"),
-    ];
-    let out = merge_detections(input, 0.01, 0.001);
-    assert_eq!(out.len(), 1);
-    // Union covers [0.10..0.30] x [0.10..0.30]
-    let m = &out[0];
-    assert!((m.x - 0.1).abs() < 1e-6);
-    assert!((m.width - 0.2).abs() < 1e-6);
-  }
-}

package/src/nms.rs

@@ -1,296 +0,0 @@
-//! Non-Maximum Suppression with SIMD acceleration.
-//!
-//! Greedy NMS over a list of detections, suppressing within the same class
-//! label only. Uses a Structure-of-Arrays layout so the inner IoU loop can
-//! process eight candidate boxes at once via `wide::f32x8`.
-//!
-//! Algorithm steps:
-//!   1. Optional top-k pre-filter — bounds the work for pathological inputs
-//!      with thousands of overlapping detections.
-//!   2. Sort surviving candidates by descending confidence.
-//!   3. Greedy keep-then-suppress: for each kept box compare in `f32x8`
-//!      chunks against all later boxes of the same class, suppressing those
-//!      whose IoU exceeds the threshold.
-//!
-//! Output preserves the original `Detection` order by confidence (descending).
-
-use wide::{f32x8, CmpGt};
-// CmpGt is the trait that provides `simd_gt` on f32x8.
-
-use crate::types::Detection;
-
-/// Run greedy NMS on `detections`.
-///
-/// * `iou_threshold` — boxes with IoU strictly greater than this value
-///   compared to a higher-scoring box of the same class are removed.
-/// * `max_detections` — hard cap on the output length. `None` for no cap.
-///
-/// Detections without overlapping rivals pass through unchanged. Per-class
-/// semantics ensure a `person` and a `car` with overlapping bboxes are both
-/// retained.
-pub fn nms(
-  detections: Vec<Detection>,
-  iou_threshold: f32,
-  max_detections: Option<usize>,
-) -> Vec<Detection> {
-  if detections.is_empty() {
-    return Vec::new();
-  }
-
-  // Pre-filter: keep at most max_detections * 10 by confidence to bound the
-  // O(n²) inner loop on adversarial inputs. The factor 10 leaves headroom for
-  // suppression to still hit the requested final count.
-  let mut candidates = detections;
-  let max_det = max_detections.unwrap_or(candidates.len());
-  let prefilter_cap = max_det.saturating_mul(10).max(64);
-  if candidates.len() > prefilter_cap {
-    candidates.select_nth_unstable_by(prefilter_cap, |a, b| {
-      b.confidence
-        .partial_cmp(&a.confidence)
-        .unwrap_or(std::cmp::Ordering::Equal)
-    });
-    candidates.truncate(prefilter_cap);
-  }
-
-  // Sort by confidence descending so the highest-score box is always picked
-  // first in the greedy pass.
-  candidates.sort_unstable_by(|a, b| {
-    b.confidence
-      .partial_cmp(&a.confidence)
-      .unwrap_or(std::cmp::Ordering::Equal)
-  });
-
-  let n = candidates.len();
-
-  // Structure-of-Arrays for SIMD-friendly access. We store xyxy (corners)
-  // because the IoU intersection math uses min/max over corners directly.
-  let mut x1 = vec![0.0f32; n];
-  let mut y1 = vec![0.0f32; n];
-  let mut x2 = vec![0.0f32; n];
-  let mut y2 = vec![0.0f32; n];
-  let mut areas = vec![0.0f32; n];
-
-  for (i, det) in candidates.iter().enumerate() {
-    x1[i] = det.x;
-    y1[i] = det.y;
-    x2[i] = det.x + det.width;
-    y2[i] = det.y + det.height;
-    areas[i] = det.width * det.height;
-  }
-
-  // Per-class label dispatch: convert label strings to small integer ids so
-  // the inner loop can compare classes via cheap integer equality.
-  let mut label_ids = vec![0u32; n];
-  let mut label_table: Vec<&str> = Vec::new();
-  for (i, det) in candidates.iter().enumerate() {
-    let id = match label_table.iter().position(|l| *l == det.label.as_str()) {
-      Some(idx) => idx as u32,
-      None => {
-        label_table.push(det.label.as_str());
-        (label_table.len() - 1) as u32
-      }
-    };
-    label_ids[i] = id;
-  }
-
-  let mut suppressed = vec![false; n];
-  let mut keep_indices: Vec<usize> = Vec::with_capacity(max_det.min(n));
-
-  let iou_v = f32x8::splat(iou_threshold);
-  let zero_v = f32x8::splat(0.0);
-
-  for i in 0..n {
-    if suppressed[i] {
-      continue;
-    }
-    keep_indices.push(i);
-    if keep_indices.len() >= max_det {
-      break;
-    }
-
-    let ax1 = f32x8::splat(x1[i]);
-    let ay1 = f32x8::splat(y1[i]);
-    let ax2 = f32x8::splat(x2[i]);
-    let ay2 = f32x8::splat(y2[i]);
-    let aa = f32x8::splat(areas[i]);
-    let a_label = label_ids[i];
-
-    let mut j = i + 1;
-    // SIMD chunks of 8 — load 8 boxes at a time, compute IoU vector, build
-    // a suppression mask, then apply it back per-element with class check.
-    while j + 8 <= n {
-      // Skip the chunk entirely if no candidate inside it can be suppressed
-      // (all already suppressed OR all of a different class).
-      let mut chunk_active = false;
-      for k in 0..8 {
-        if !suppressed[j + k] && label_ids[j + k] == a_label {
-          chunk_active = true;
-          break;
-        }
-      }
-
-      if chunk_active {
-        // Safe unaligned reads — Vec<f32> is contiguous and we never index
-        // past the end (the `while` condition guarantees j + 8 <= n).
-        let bx1: f32x8 = unsafe { (x1.as_ptr().add(j) as *const f32x8).read_unaligned() };
-        let by1: f32x8 = unsafe { (y1.as_ptr().add(j) as *const f32x8).read_unaligned() };
-        let bx2: f32x8 = unsafe { (x2.as_ptr().add(j) as *const f32x8).read_unaligned() };
-        let by2: f32x8 = unsafe { (y2.as_ptr().add(j) as *const f32x8).read_unaligned() };
-        let ba: f32x8 = unsafe { (areas.as_ptr().add(j) as *const f32x8).read_unaligned() };
-
-        let ix1 = ax1.fast_max(bx1);
-        let iy1 = ay1.fast_max(by1);
-        let ix2 = ax2.fast_min(bx2);
-        let iy2 = ay2.fast_min(by2);
-
-        let iw = (ix2 - ix1).fast_max(zero_v);
-        let ih = (iy2 - iy1).fast_max(zero_v);
-        let inter = iw * ih;
-        let union = aa + ba - inter;
-        // Avoid divide-by-zero — when union is 0 the IoU is irrelevant
-        // (both boxes have zero area, the candidate would be filtered
-        // elsewhere). Use a sentinel large enough to fail the threshold
-        // check below.
-        let safe_union = union.fast_max(f32x8::splat(f32::MIN_POSITIVE));
-        let iou = inter / safe_union;
-
-        let mask = iou.simd_gt(iou_v);
-        // `to_bitmask` packs the SIMD comparison result into a bitmap where
-        // bit k is set when lane k of `iou` exceeds the threshold.
-        let bits = mask.to_bitmask();
-        if bits != 0 {
-          for k in 0..8 {
-            if (bits & (1 << k)) != 0 && !suppressed[j + k] && label_ids[j + k] == a_label {
-              suppressed[j + k] = true;
-            }
-          }
-        }
-      }
-      j += 8;
-    }
-
-    // Scalar tail — handle the remaining < 8 elements without SIMD.
-    while j < n {
-      if !suppressed[j] && label_ids[j] == a_label {
-        let ix1 = x1[i].max(x1[j]);
-        let iy1 = y1[i].max(y1[j]);
-        let ix2 = x2[i].min(x2[j]);
-        let iy2 = y2[i].min(y2[j]);
-        let iw = (ix2 - ix1).max(0.0);
-        let ih = (iy2 - iy1).max(0.0);
-        let inter = iw * ih;
-        let union = areas[i] + areas[j] - inter;
-        if union > 0.0 && inter / union > iou_threshold {
-          suppressed[j] = true;
-        }
-      }
-      j += 1;
-    }
-  }
-
-  // Move kept detections out of the candidates Vec — no clones, ownership
-  // transfer via take() over a Vec<Option<Detection>> would also work but
-  // an indexed swap_remove pattern is simpler since keep_indices is sorted.
-  let mut kept: Vec<Detection> = Vec::with_capacity(keep_indices.len());
-  // Build a flag vector so we can drain in original order with one pass.
-  let mut keep_flag = vec![false; n];
-  for &idx in &keep_indices {
-    keep_flag[idx] = true;
-  }
-  for (i, det) in candidates.into_iter().enumerate() {
-    if keep_flag[i] {
-      kept.push(det);
-    }
-  }
-  kept
-}
-
-#[cfg(test)]
-mod tests {
-  use super::*;
-
-  fn det(x: f32, y: f32, w: f32, h: f32, conf: f32, label: &str) -> Detection {
-    Detection {
-      x,
-      y,
-      width: w,
-      height: h,
-      confidence: conf,
-      label: label.to_string(),
-    }
-  }
-
-  #[test]
-  fn empty_input() {
-    assert!(nms(Vec::new(), 0.5, None).is_empty());
-  }
-
-  #[test]
-  fn single_box_kept() {
-    let input = vec![det(0.1, 0.1, 0.2, 0.2, 0.9, "person")];
-    let out = nms(input, 0.5, None);
-    assert_eq!(out.len(), 1);
-  }
-
-  #[test]
-  fn duplicate_boxes_suppressed() {
-    let input = vec![
-      det(0.1, 0.1, 0.2, 0.2, 0.9, "person"),
-      det(0.1, 0.1, 0.2, 0.2, 0.8, "person"),
-      det(0.1, 0.1, 0.2, 0.2, 0.7, "person"),
-    ];
-    let out = nms(input, 0.5, None);
-    assert_eq!(out.len(), 1);
-    assert!((out[0].confidence - 0.9).abs() < 1e-6);
-  }
-
-  #[test]
-  fn different_classes_kept() {
-    let input = vec![
-      det(0.1, 0.1, 0.2, 0.2, 0.9, "person"),
-      det(0.1, 0.1, 0.2, 0.2, 0.8, "car"),
-    ];
-    let out = nms(input, 0.5, None);
-    assert_eq!(out.len(), 2);
-  }
-
-  #[test]
-  fn many_overlapping_simd_path() {
-    // Generate 20 nearly-identical person boxes — exercises the SIMD
-    // chunked loop (n - 1 = 19, so multiple f32x8 iterations).
-    let mut input = Vec::new();
-    for i in 0..20 {
-      input.push(det(0.1, 0.1, 0.2, 0.2, 0.9 - i as f32 * 0.001, "person"));
-    }
-    let out = nms(input, 0.5, None);
-    assert_eq!(out.len(), 1);
-  }
-
-  #[test]
-  fn max_detections_cap() {
-    let input = vec![
-      det(0.0, 0.0, 0.1, 0.1, 0.9, "a"),
-      det(0.2, 0.2, 0.1, 0.1, 0.85, "b"),
-      det(0.4, 0.4, 0.1, 0.1, 0.8, "c"),
-      det(0.6, 0.6, 0.1, 0.1, 0.75, "d"),
-    ];
-    let out = nms(input, 0.5, Some(2));
-    assert_eq!(out.len(), 2);
-    // Top two by confidence
-    assert!((out[0].confidence - 0.9).abs() < 1e-6);
-    assert!((out[1].confidence - 0.85).abs() < 1e-6);
-  }
-
-  #[test]
-  fn output_sorted_by_confidence() {
-    let input = vec![
-      det(0.0, 0.0, 0.1, 0.1, 0.5, "a"),
-      det(0.2, 0.2, 0.1, 0.1, 0.9, "b"),
-      det(0.4, 0.4, 0.1, 0.1, 0.7, "c"),
-    ];
-    let out = nms(input, 0.5, None);
-    assert_eq!(out.len(), 3);
-    assert!(out[0].confidence > out[1].confidence);
-    assert!(out[1].confidence > out[2].confidence);
-  }
-}