@camera.ui/rust-postprocessor 0.0.1

package/src/types.rs

@@ -0,0 +1,40 @@
+//! Shared internal types used by NMS and the tracker wrapper.
+//!
+//! These mirror the JS SDK shapes (`BoundingBox`, `Detection`,
+//! `TrackedDetection`) but live entirely on the Rust side. The napi
+//! bindings in `lib.rs` convert to/from these on the boundary.
+
+/// Detection in normalized image coordinates `[0.0, 1.0]`.
+#[derive(Debug, Clone)]
+pub struct Detection {
+  pub x: f32,
+  pub y: f32,
+  pub width: f32,
+  pub height: f32,
+  pub confidence: f32,
+  pub label: String,
+}
+
+/// Tracked detection with stable identity across frames.
+#[derive(Debug, Clone)]
+pub struct TrackedDetection {
+  pub x: f32,
+  pub y: f32,
+  pub width: f32,
+  pub height: f32,
+  pub confidence: f32,
+  pub label: String,
+  /// Globally-unique track id assigned by the tracker. Stable across
+  /// matched frames; resets only on `ObjectTracker::reset()`.
+  pub track_id: u32,
+  /// Number of frames this track has existed (1 on first appearance).
+  pub track_age: u32,
+  /// True when this output frame did not actually match a fresh detection
+  /// — the tracker is keeping the box alive via Kalman extrapolation.
+  pub track_lost: bool,
+  /// Average centroid speed in normalized units/second over a short
+  /// sliding window (~1s of past positions). 0 means the track is
+  /// effectively stationary. Used by consumers to prefer moving tracks
+  /// over static ones (e.g. thumbnail selection).
+  pub track_speed: f32,
+}

package/src/zone_filter.rs

@@ -0,0 +1,567 @@
+//! Detection zone filter — drops detections based on:
+//!   1. Confidence threshold (`min_confidence`).
+//!   2. Whether the detection's label is allowed by any configured zone
+//!      (when at least one zone declares a non-empty `labels` list).
+//!   3. Privacy masks: detections fully contained inside a privacy mask
+//!      are removed.
+//!   4. Active include/exclude zones with intersect/contain semantics.
+//!
+//! Zones are stored normalized to `[0.0, 1.0]` (input coordinates from the
+//! UI come in `[0, 100]` and are scaled by [`prepare_zones`]). Polygons
+//! are auto-closed if the caller didn't repeat the first vertex at the
+//! end.
+//!
+//! Polygon math: the in-polygon test uses the standard ray-casting
+//! algorithm with an extra "point exactly on edge" branch so detections
+//! whose corner sits precisely on a zone boundary still count as inside.
+
+use std::collections::HashSet;
+
+use crate::types::Detection;
+
+/// Where in the polygon the box must sit for the zone to apply.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ZoneMatchType {
+  /// Any overlap with the zone counts.
+  Intersect,
+  /// All four corners of the box must be inside the zone.
+  Contain,
+}
+
+/// How a zone affects matching detections.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ZoneFilterMode {
+  /// Detection passes only if it sits in at least one Include zone.
+  Include,
+  /// Detection is dropped if it sits in any Exclude zone.
+  Exclude,
+}
+
+/// User-supplied zone definition (matches the SDK shape).
+#[derive(Debug, Clone)]
+pub struct ZoneInput {
+  /// Optional label filter — empty means "all labels".
+  pub labels: Vec<String>,
+  pub filter: ZoneFilterMode,
+  pub match_type: ZoneMatchType,
+  pub is_privacy_mask: bool,
+  /// Polygon vertices in `[0, 100]` UI coordinates. Doesn't need to be
+  /// closed — `prepare_zones` will close it automatically.
+  pub points: Vec<[f64; 2]>,
+}
+
+/// Pre-computed zone ready for fast per-frame filtering.
+///
+/// Note: there is no `is_privacy_mask` field — privacy masks live in
+/// `PreparedZones.privacy_masks`, active zones in
+/// `PreparedZones.active_zones`. The bucket the zone sits in tells the
+/// filter how to treat it.
+#[derive(Debug, Clone)]
+pub struct PreparedZone {
+  pub labels: HashSet<String>,
+  pub filter: ZoneFilterMode,
+  pub match_type: ZoneMatchType,
+  /// Closed polygon in normalized `[0.0, 1.0]` coordinates.
+  pub points: Vec<[f32; 2]>,
+}
+
+/// Sorted-into-buckets prepared zones plus the union of all label
+/// restrictions across active zones.
+#[derive(Debug, Clone, Default)]
+pub struct PreparedZones {
+  pub privacy_masks: Vec<PreparedZone>,
+  pub active_zones: Vec<PreparedZone>,
+  /// Union of every active zone's allowed labels (lowercased). Empty
+  /// means "no per-zone label restriction is in effect".
+  pub all_labels: HashSet<String>,
+}
+
+/// Convert UI 0-100 zones into normalized prepared zones bucketed by type.
+pub fn prepare_zones(zones: &[ZoneInput]) -> PreparedZones {
+  let mut privacy_masks = Vec::new();
+  let mut active_zones = Vec::new();
+  let mut all_labels: HashSet<String> = HashSet::new();
+
+  for zone in zones {
+    // Normalize 0..100 to 0..1
+    let mut points: Vec<[f32; 2]> = zone
+      .points
+      .iter()
+      .map(|p| [(p[0] / 100.0) as f32, (p[1] / 100.0) as f32])
+      .collect();
+
+    // Auto-close: append the first vertex if it's not already at the end
+    if points.len() > 1 {
+      let first = points[0];
+      let last = points[points.len() - 1];
+      if (first[0] - last[0]).abs() > 1e-9 || (first[1] - last[1]).abs() > 1e-9 {
+        points.push(first);
+      }
+    }
+
+    let mut labels: HashSet<String> = HashSet::new();
+    for label in &zone.labels {
+      let lc = label.to_lowercase();
+      labels.insert(lc.clone());
+      if !zone.is_privacy_mask {
+        all_labels.insert(lc);
+      }
+    }
+
+    let prepared = PreparedZone {
+      labels,
+      filter: zone.filter,
+      match_type: zone.match_type,
+      points,
+    };
+
+    if zone.is_privacy_mask {
+      privacy_masks.push(prepared);
+    } else {
+      active_zones.push(prepared);
+    }
+  }
+
+  PreparedZones {
+    privacy_masks,
+    active_zones,
+    all_labels,
+  }
+}
+
+/// Standard ray-cast point-in-polygon test, augmented with a "point lies
+/// exactly on an edge" check that returns true when applicable. The
+/// polygon must be closed (first vertex == last vertex).
+fn is_point_in_polygon(px: f32, py: f32, polygon: &[[f32; 2]]) -> bool {
+  if polygon.len() < 3 {
+    return false;
+  }
+  let mut inside = false;
+  let n = polygon.len();
+  let mut j = n - 1;
+  for i in 0..n {
+    let xi = polygon[i][0];
+    let yi = polygon[i][1];
+    let xj = polygon[j][0];
+    let yj = polygon[j][1];
+
+    // Edge containment: point lies exactly on (or very near) the edge.
+    let min_x = xi.min(xj);
+    let max_x = xi.max(xj);
+    let min_y = yi.min(yj);
+    let max_y = yi.max(yj);
+    if px >= min_x && px <= max_x && py >= min_y && py <= max_y {
+      if (xi - xj).abs() < 1e-9 {
+        // Vertical edge
+        if (px - xi).abs() < 1e-9 {
+          return true;
+        }
+      } else {
+        let m = (yj - yi) / (xj - xi);
+        if (py - (m * px + (yi - m * xi))).abs() < 1e-9 {
+          return true;
+        }
+      }
+    }
+
+    // Standard ray-cast: count intersections with horizontal ray to the
+    // left of the test point.
+    let yi_above = yi > py;
+    let yj_above = yj > py;
+    if yi_above != yj_above {
+      let x_intersect = (xj - xi) * (py - yi) / (yj - yi) + xi;
+      if px < x_intersect {
+        inside = !inside;
+      }
+    }
+
+    j = i;
+  }
+  inside
+}
+
+/// Parametric segment-segment intersection check (does not return the
+/// crossing point — only whether the segments cross).
+fn do_lines_intersect(a1: [f32; 2], a2: [f32; 2], b1: [f32; 2], b2: [f32; 2]) -> bool {
+  let denom = (b2[1] - b1[1]) * (a2[0] - a1[0]) - (b2[0] - b1[0]) * (a2[1] - a1[1]);
+  if denom.abs() < 1e-12 {
+    return false;
+  }
+  let ua = ((b2[0] - b1[0]) * (a1[1] - b1[1]) - (b2[1] - b1[1]) * (a1[0] - b1[0])) / denom;
+  let ub = ((a2[0] - a1[0]) * (a1[1] - b1[1]) - (a2[1] - a1[1]) * (a1[0] - b1[0])) / denom;
+  (0.0..=1.0).contains(&ua) && (0.0..=1.0).contains(&ub)
+}
+
+#[inline]
+fn box_corners(det: &Detection) -> [[f32; 2]; 4] {
+  let x2 = det.x + det.width;
+  let y2 = det.y + det.height;
+  [[det.x, det.y], [x2, det.y], [x2, y2], [det.x, y2]]
+}
+
+/// True if the detection box has any overlap with the polygon, or if any
+/// polygon vertex sits inside the box, or if any edges cross.
+fn box_intersects_polygon(det: &Detection, polygon: &[[f32; 2]]) -> bool {
+  let corners = box_corners(det);
+  let x2 = det.x + det.width;
+  let y2 = det.y + det.height;
+
+  // 1) Any corner of the box inside the polygon → overlap.
+  for &[cx, cy] in &corners {
+    if is_point_in_polygon(cx, cy, polygon) {
+      return true;
+    }
+  }
+  // 2) Any vertex of the polygon inside the box → overlap.
+  for &[px, py] in polygon {
+    if px >= det.x && px <= x2 && py >= det.y && py <= y2 {
+      return true;
+    }
+  }
+  // 3) Any edge of the box crosses any edge of the polygon → overlap.
+  let edges = [
+    (corners[0], corners[1]),
+    (corners[1], corners[2]),
+    (corners[2], corners[3]),
+    (corners[3], corners[0]),
+  ];
+  if polygon.len() < 2 {
+    return false;
+  }
+  for i in 0..(polygon.len() - 1) {
+    for &(ea, eb) in &edges {
+      if do_lines_intersect(ea, eb, polygon[i], polygon[i + 1]) {
+        return true;
+      }
+    }
+  }
+  false
+}
+
+/// True if all four corners of the box are inside the polygon.
+fn box_contained_in_polygon(det: &Detection, polygon: &[[f32; 2]]) -> bool {
+  for &[cx, cy] in &box_corners(det) {
+    if !is_point_in_polygon(cx, cy, polygon) {
+      return false;
+    }
+  }
+  true
+}
+
+#[inline]
+fn zone_accepts_label(zone: &PreparedZone, lc_label: &str) -> bool {
+  zone.labels.is_empty() || zone.labels.contains(lc_label)
+}
+
+/// Same predicate as [`filter_detections`] but operates on a borrowed
+/// slice and returns the indices of detections that pass the filter
+/// instead of new owned values. Used by callers that need to project the
+/// filter result back onto a parallel array of richer types (face/lpd
+/// items wrapped as Detection with a substitute label, etc.).
+pub fn filter_indices(
+  detections: &[Detection],
+  zones: &PreparedZones,
+  min_confidence: f32,
+) -> Vec<u32> {
+  let PreparedZones {
+    privacy_masks,
+    active_zones,
+    all_labels,
+  } = zones;
+
+  let mut out: Vec<u32> = Vec::with_capacity(detections.len());
+  for (i, det) in detections.iter().enumerate() {
+    if det.confidence < min_confidence {
+      continue;
+    }
+
+    // Fast path: no zones at all → confidence threshold only.
+    if active_zones.is_empty() && privacy_masks.is_empty() {
+      out.push(i as u32);
+      continue;
+    }
+
+    let label_lc = det.label.to_lowercase();
+    if !all_labels.is_empty() && !all_labels.contains(&label_lc) {
+      continue;
+    }
+
+    let mut dropped = false;
+    for mask in privacy_masks {
+      if box_contained_in_polygon(det, &mask.points) {
+        dropped = true;
+        break;
+      }
+    }
+    if dropped {
+      continue;
+    }
+
+    let mut has_include_zone = false;
+    let mut satisfies_include = false;
+
+    for zone in active_zones {
+      if !zone_accepts_label(zone, &label_lc) {
+        continue;
+      }
+      let intersects = box_intersects_polygon(det, &zone.points);
+      let contained = intersects && box_contained_in_polygon(det, &zone.points);
+
+      match zone.filter {
+        ZoneFilterMode::Exclude => match zone.match_type {
+          ZoneMatchType::Contain => {
+            if intersects {
+              dropped = true;
+              break;
+            }
+          }
+          ZoneMatchType::Intersect => {
+            if intersects || contained {
+              dropped = true;
+              break;
+            }
+          }
+        },
+        ZoneFilterMode::Include => {
+          has_include_zone = true;
+          if !satisfies_include {
+            match zone.match_type {
+              ZoneMatchType::Contain => {
+                if contained {
+                  satisfies_include = true;
+                }
+              }
+              ZoneMatchType::Intersect => {
+                if intersects {
+                  satisfies_include = true;
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    if dropped {
+      continue;
+    }
+    if has_include_zone && !satisfies_include {
+      continue;
+    }
+    out.push(i as u32);
+  }
+  out
+}
+
+/// Apply confidence threshold + zone filter to a list of detections.
+///
+/// Delegates to [`filter_indices`] and extracts the kept detections by
+/// index — single implementation, no duplicated logic.
+#[cfg(test)]
+fn filter_detections(
+  detections: Vec<Detection>,
+  zones: &PreparedZones,
+  min_confidence: f32,
+) -> Vec<Detection> {
+  let indices = filter_indices(&detections, zones, min_confidence);
+  if indices.len() == detections.len() {
+    return detections; // all kept — avoid extra work
+  }
+  let mut slots: Vec<Option<Detection>> = detections.into_iter().map(Some).collect();
+  indices
+    .iter()
+    .filter_map(|&i| slots[i as usize].take())
+    .collect()
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  fn det(x: f32, y: f32, w: f32, h: f32, label: &str) -> Detection {
+    Detection {
+      x,
+      y,
+      width: w,
+      height: h,
+      confidence: 0.9,
+      label: label.to_string(),
+    }
+  }
+
+  fn rect_zone(
+    x1: f64,
+    y1: f64,
+    x2: f64,
+    y2: f64,
+    mode: ZoneFilterMode,
+    mt: ZoneMatchType,
+    labels: Vec<String>,
+  ) -> ZoneInput {
+    ZoneInput {
+      labels,
+      filter: mode,
+      match_type: mt,
+      is_privacy_mask: false,
+      points: vec![[x1, y1], [x2, y1], [x2, y2], [x1, y2]],
+    }
+  }
+
+  #[test]
+  fn confidence_filter_only() {
+    let zones = prepare_zones(&[]);
+    let mut a = det(0.1, 0.1, 0.2, 0.2, "person");
+    a.confidence = 0.4;
+    let mut b = det(0.3, 0.3, 0.2, 0.2, "person");
+    b.confidence = 0.8;
+    let out = filter_detections(vec![a, b], &zones, 0.5);
+    assert_eq!(out.len(), 1);
+    assert!(out[0].confidence >= 0.5);
+  }
+
+  #[test]
+  fn include_zone_contains_box() {
+    // Zone covers the middle 50% of the image
+    let zones = prepare_zones(&[rect_zone(
+      25.0,
+      25.0,
+      75.0,
+      75.0,
+      ZoneFilterMode::Include,
+      ZoneMatchType::Contain,
+      vec![],
+    )]);
+    // Box fully inside
+    let inside = det(0.30, 0.30, 0.20, 0.20, "person");
+    // Box outside the zone
+    let outside = det(0.85, 0.85, 0.10, 0.10, "person");
+    let out = filter_detections(vec![inside, outside], &zones, 0.0);
+    assert_eq!(out.len(), 1);
+  }
+
+  #[test]
+  fn include_intersect_keeps_partial_overlap() {
+    let zones = prepare_zones(&[rect_zone(
+      25.0,
+      25.0,
+      75.0,
+      75.0,
+      ZoneFilterMode::Include,
+      ZoneMatchType::Intersect,
+      vec![],
+    )]);
+    // Box overlaps the zone but isn't fully contained
+    let partial = det(0.70, 0.30, 0.20, 0.20, "person");
+    let out = filter_detections(vec![partial], &zones, 0.0);
+    assert_eq!(out.len(), 1);
+  }
+
+  #[test]
+  fn exclude_zone_drops_box() {
+    let zones = prepare_zones(&[rect_zone(
+      25.0,
+      25.0,
+      75.0,
+      75.0,
+      ZoneFilterMode::Exclude,
+      ZoneMatchType::Intersect,
+      vec![],
+    )]);
+    let inside = det(0.30, 0.30, 0.20, 0.20, "person");
+    let outside = det(0.05, 0.05, 0.10, 0.10, "person");
+    let out = filter_detections(vec![inside, outside], &zones, 0.0);
+    assert_eq!(out.len(), 1);
+    assert!((out[0].x - 0.05).abs() < 1e-6);
+  }
+
+  #[test]
+  fn privacy_mask_drops_contained_box() {
+    let mut mask = rect_zone(
+      0.0,
+      0.0,
+      50.0,
+      50.0,
+      ZoneFilterMode::Include,
+      ZoneMatchType::Intersect,
+      vec![],
+    );
+    mask.is_privacy_mask = true;
+    let zones = prepare_zones(&[mask]);
+    let inside = det(0.10, 0.10, 0.20, 0.20, "person");
+    let outside = det(0.60, 0.60, 0.20, 0.20, "person");
+    let out = filter_detections(vec![inside, outside], &zones, 0.0);
+    assert_eq!(out.len(), 1);
+    assert!((out[0].x - 0.60).abs() < 1e-6);
+  }
+
+  #[test]
+  fn label_filter_restricts_globally() {
+    // Zone is configured for cars only — persons should be dropped even
+    // outside the zone (the union of all zone labels becomes a global
+    // allow-list).
+    let zones = prepare_zones(&[rect_zone(
+      0.0,
+      0.0,
+      100.0,
+      100.0,
+      ZoneFilterMode::Include,
+      ZoneMatchType::Intersect,
+      vec!["car".to_string()],
+    )]);
+    let person = det(0.30, 0.30, 0.20, 0.20, "person");
+    let car = det(0.30, 0.30, 0.20, 0.20, "car");
+    let out = filter_detections(vec![person, car], &zones, 0.0);
+    assert_eq!(out.len(), 1);
+    assert_eq!(out[0].label, "car");
+  }
+
+  #[test]
+  fn label_zone_with_other_label_zone_combined() {
+    // Two zones: one for "person", one for "car". Detections of either
+    // class are allowed; cats get dropped.
+    let zones = prepare_zones(&[
+      rect_zone(
+        0.0,
+        0.0,
+        100.0,
+        100.0,
+        ZoneFilterMode::Include,
+        ZoneMatchType::Intersect,
+        vec!["person".to_string()],
+      ),
+      rect_zone(
+        0.0,
+        0.0,
+        100.0,
+        100.0,
+        ZoneFilterMode::Include,
+        ZoneMatchType::Intersect,
+        vec!["car".to_string()],
+      ),
+    ]);
+    let person = det(0.30, 0.30, 0.20, 0.20, "person");
+    let car = det(0.30, 0.30, 0.20, 0.20, "car");
+    let cat = det(0.30, 0.30, 0.20, 0.20, "cat");
+    let out = filter_detections(vec![person, car, cat], &zones, 0.0);
+    assert_eq!(out.len(), 2);
+  }
+
+  #[test]
+  fn auto_close_polygon() {
+    // Pass a polygon that doesn't end with the start vertex — prepare
+    // should close it for us.
+    let zone = ZoneInput {
+      labels: vec![],
+      filter: ZoneFilterMode::Include,
+      match_type: ZoneMatchType::Intersect,
+      is_privacy_mask: false,
+      points: vec![[0.0, 0.0], [100.0, 0.0], [100.0, 100.0], [0.0, 100.0]],
+    };
+    let zones = prepare_zones(&[zone]);
+    assert_eq!(zones.active_zones[0].points.len(), 5);
+    let first = zones.active_zones[0].points[0];
+    let last = zones.active_zones[0].points[4];
+    assert!((first[0] - last[0]).abs() < 1e-6);
+    assert!((first[1] - last[1]).abs() < 1e-6);
+  }
+}