@camera.ui/rust-postprocessor 0.0.1

package/src/line_crossing.rs

@@ -0,0 +1,214 @@
+//! Line-crossing detection.
+//!
+//! Crossing lines are perpendicular to a "handle" segment drawn by the user
+//! in the UI. We compute the perpendicular in visual (aspect-ratio-corrected)
+//! space so the line orientation matches what the user sees, then store both
+//! endpoints normalized in `[0.0, 1.0]`. On every frame the tracker walks
+//! each active track's previous→current centroid segment and checks for
+//! intersection against every prepared line; the sign of the cross product
+//! between the two segments tells us whether the track went A→B or B→A.
+
+use std::collections::HashSet;
+
+/// Direction filter applied to a configured crossing line.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LineDirectionFilter {
+  /// Either A→B or B→A fires an event.
+  Both,
+  AToB,
+  BToA,
+}
+
+/// Direction of an emitted crossing event.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CrossingDirection {
+  AToB,
+  BToA,
+}
+
+/// User-facing line definition (matches the UI shape).
+///
+/// `points` is the two handle endpoints in `[0, 100]` UI coordinates.
+/// `aspect_ratio` (set on `prepare_lines`) is the camera's `width / height`
+/// — used so the perpendicular line ends up visually perpendicular instead
+/// of stretched along the longer axis of the normalized space.
+#[derive(Debug, Clone)]
+pub struct DetectionLineInput {
+  pub name: String,
+  pub direction: LineDirectionFilter,
+  /// Allowed labels (case-insensitive). Empty means "all labels".
+  pub labels: Vec<String>,
+  pub points: [[f64; 2]; 2],
+}
+
+/// Pre-computed crossing line ready for fast per-frame intersection tests.
+#[derive(Debug, Clone)]
+pub struct PreparedLine {
+  pub name: String,
+  pub direction: LineDirectionFilter,
+  /// Lowercased labels — empty set means "all labels allowed".
+  pub labels: HashSet<String>,
+  /// Both endpoints of the perpendicular crossing line in normalized
+  /// `[0.0, 1.0]` coordinates.
+  pub line_a: [f32; 2],
+  pub line_b: [f32; 2],
+}
+
+/// Crossing event emitted by the tracker.
+#[derive(Debug, Clone)]
+pub struct LineCrossingEvent {
+  pub line_name: String,
+  pub direction: CrossingDirection,
+  pub track_id: u32,
+  pub label: String,
+  pub confidence: f32,
+  pub timestamp_ms: f64,
+  pub prev_pos: [f32; 2],
+  pub curr_pos: [f32; 2],
+}
+
+/// Convert raw user-supplied lines (UI 0-100 coordinates) into prepared
+/// lines with the perpendicular crossing segment computed in normalized
+/// space. `aspect_ratio` should be `width / height` of the camera frame.
+pub fn prepare_lines(lines: &[DetectionLineInput], aspect_ratio: f32) -> Vec<PreparedLine> {
+  lines
+    .iter()
+    .map(|line| {
+      // Normalize handle points from 0..100 to 0..1
+      let h1x = (line.points[0][0] / 100.0) as f32;
+      let h1y = (line.points[0][1] / 100.0) as f32;
+      let h2x = (line.points[1][0] / 100.0) as f32;
+      let h2y = (line.points[1][1] / 100.0) as f32;
+
+      let mid_x = (h1x + h2x) * 0.5;
+      let mid_y = (h1y + h2y) * 0.5;
+
+      // Compute the perpendicular in *visual* space (where x is stretched
+      // by aspect_ratio so a square frame is actually square). After
+      // computing the perpendicular we scale x back to normalized space
+      // so the result is a unit-vector-direction perpendicular that
+      // matches what the user drew.
+      let dx_vis = (h2x - h1x) * aspect_ratio;
+      let dy_vis = h2y - h1y;
+      let perp_x_vis = -dy_vis;
+      let perp_y_vis = dx_vis;
+
+      let perp_x_norm = perp_x_vis / aspect_ratio;
+      let perp_y_norm = perp_y_vis;
+      let perp_len = (perp_x_norm * perp_x_norm + perp_y_norm * perp_y_norm)
+        .sqrt()
+        .max(1e-12);
+      let handle_len = ((h2x - h1x).powi(2) + (h2y - h1y).powi(2))
+        .sqrt()
+        .max(1e-12);
+      let scale = handle_len / perp_len;
+      let perp_x = perp_x_norm * scale;
+      let perp_y = perp_y_norm * scale;
+
+      let line_a = [mid_x - perp_x * 0.5, mid_y - perp_y * 0.5];
+      let line_b = [mid_x + perp_x * 0.5, mid_y + perp_y * 0.5];
+
+      let labels: HashSet<String> = line.labels.iter().map(|l| l.to_lowercase()).collect();
+
+      PreparedLine {
+        name: line.name.clone(),
+        direction: line.direction,
+        labels,
+        line_a,
+        line_b,
+      }
+    })
+    .collect()
+}
+
+/// Segment-segment intersection check between `(a, b)` (track motion) and
+/// `(c, d)` (crossing line). Returns the *signed cross product* between the
+/// two direction vectors at the intersection — positive means the track is
+/// going from line side A to side B, negative means B to A. Returns 0 if
+/// the segments do not intersect or are parallel.
+#[inline]
+pub fn segment_intersection(
+  ax: f32,
+  ay: f32,
+  bx: f32,
+  by: f32,
+  cx: f32,
+  cy: f32,
+  dx: f32,
+  dy: f32,
+) -> f32 {
+  let denom = (bx - ax) * (dy - cy) - (by - ay) * (dx - cx);
+  if denom.abs() < 1e-12 {
+    return 0.0;
+  }
+
+  let t = ((cx - ax) * (dy - cy) - (cy - ay) * (dx - cx)) / denom;
+  let u = ((cx - ax) * (by - ay) - (cy - ay) * (bx - ax)) / denom;
+
+  if (0.0..=1.0).contains(&t) && (0.0..=1.0).contains(&u) {
+    let track_dx = bx - ax;
+    let track_dy = by - ay;
+    let line_dx = dx - cx;
+    let line_dy = dy - cy;
+    track_dx * line_dy - track_dy * line_dx
+  } else {
+    0.0
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  fn line(name: &str, p1: [f64; 2], p2: [f64; 2]) -> DetectionLineInput {
+    DetectionLineInput {
+      name: name.to_string(),
+      direction: LineDirectionFilter::Both,
+      labels: Vec::new(),
+      points: [p1, p2],
+    }
+  }
+
+  #[test]
+  fn prepare_horizontal_handle_yields_vertical_line() {
+    // Horizontal handle from (10, 50) to (90, 50) → perpendicular is vertical
+    let prepared = prepare_lines(&[line("h", [10.0, 50.0], [90.0, 50.0])], 16.0 / 9.0);
+    assert_eq!(prepared.len(), 1);
+    let p = &prepared[0];
+    // The perpendicular should be vertical so x of A and B match
+    assert!((p.line_a[0] - p.line_b[0]).abs() < 1e-4);
+    // The midpoint x should be 0.5
+    assert!((p.line_a[0] - 0.5).abs() < 1e-4);
+  }
+
+  #[test]
+  fn segment_intersection_basic() {
+    // Track segment (0,0)→(1,1), line segment (0,1)→(1,0). They cross at (0.5,0.5).
+    let cross = segment_intersection(0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 1.0, 0.0);
+    assert!(cross != 0.0);
+  }
+
+  #[test]
+  fn segment_intersection_no_overlap() {
+    // Parallel
+    let cross = segment_intersection(0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0);
+    assert_eq!(cross, 0.0);
+  }
+
+  #[test]
+  fn segment_intersection_disjoint() {
+    // Skew but disjoint
+    let cross = segment_intersection(0.0, 0.0, 0.1, 0.1, 0.5, 0.5, 0.6, 0.6);
+    assert_eq!(cross, 0.0);
+  }
+
+  #[test]
+  fn cross_sign_indicates_direction() {
+    // Track moves left→right across a vertical line at x=0.5
+    let cross_lr = segment_intersection(0.4, 0.5, 0.6, 0.5, 0.5, 0.0, 0.5, 1.0);
+    assert!(cross_lr > 0.0);
+    // Reverse: right→left should produce opposite sign
+    let cross_rl = segment_intersection(0.6, 0.5, 0.4, 0.5, 0.5, 0.0, 0.5, 1.0);
+    assert!(cross_rl < 0.0);
+  }
+}

package/src/merge.rs

@@ -0,0 +1,312 @@
+//! 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);
+  }
+}