@camera.ui/rust-postprocessor 0.0.1

package/src/iou.rs

@@ -0,0 +1,83 @@
+//! Intersection-over-Union helpers.
+//!
+//! Boxes are in normalized `[x, y, width, height]` format with coordinates in
+//! `[0.0, 1.0]`. This matches the convention used by the Node SDK
+//! (`BoundingBox`).
+
+/// Compute IoU between two `[x, y, width, height]` boxes.
+///
+/// Returns 0 if either box has non-positive area or there is no overlap.
+#[inline]
+pub fn box_iou(a: &[f32; 4], b: &[f32; 4]) -> f32 {
+  let ax2 = a[0] + a[2];
+  let ay2 = a[1] + a[3];
+  let bx2 = b[0] + b[2];
+  let by2 = b[1] + b[3];
+
+  let ix1 = a[0].max(b[0]);
+  let iy1 = a[1].max(b[1]);
+  let ix2 = ax2.min(bx2);
+  let iy2 = ay2.min(by2);
+
+  if ix2 <= ix1 || iy2 <= iy1 {
+    return 0.0;
+  }
+
+  let inter = (ix2 - ix1) * (iy2 - iy1);
+  let a_area = a[2] * a[3];
+  let b_area = b[2] * b[3];
+  let union = a_area + b_area - inter;
+
+  if union > 0.0 {
+    inter / union
+  } else {
+    0.0
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn perfect_overlap() {
+    let a = [0.1, 0.1, 0.2, 0.2];
+    let b = [0.1, 0.1, 0.2, 0.2];
+    assert!((box_iou(&a, &b) - 1.0).abs() < 1e-6);
+  }
+
+  #[test]
+  fn no_overlap() {
+    let a = [0.0, 0.0, 0.1, 0.1];
+    let b = [0.5, 0.5, 0.1, 0.1];
+    assert_eq!(box_iou(&a, &b), 0.0);
+  }
+
+  #[test]
+  fn half_overlap_horizontal() {
+    // a = [0..0.2] x [0..0.2], b = [0.1..0.3] x [0..0.2]
+    // intersection = 0.1 * 0.2 = 0.02
+    // union = 0.04 + 0.04 - 0.02 = 0.06
+    // iou = 1/3
+    let a = [0.0, 0.0, 0.2, 0.2];
+    let b = [0.1, 0.0, 0.2, 0.2];
+    let v = box_iou(&a, &b);
+    assert!((v - 1.0 / 3.0).abs() < 1e-6, "got {v}");
+  }
+
+  #[test]
+  fn contained() {
+    let a = [0.0, 0.0, 1.0, 1.0];
+    let b = [0.25, 0.25, 0.5, 0.5];
+    // inter = 0.25, union = 1.0
+    let v = box_iou(&a, &b);
+    assert!((v - 0.25).abs() < 1e-6, "got {v}");
+  }
+
+  #[test]
+  fn zero_area() {
+    let a = [0.0, 0.0, 0.0, 0.0];
+    let b = [0.0, 0.0, 0.5, 0.5];
+    assert_eq!(box_iou(&a, &b), 0.0);
+  }
+}

package/src/lib.rs

@@ -0,0 +1,471 @@
+//! camera.ui rust-postprocessor — high-performance NMS, IoU and object
+//! tracking exposed to Node.js via napi-rs.
+//!
+//! - [`nms`] — SIMD greedy NMS over a list of detections (per-class).
+//! - [`box_iou`] — single-pair IoU helper for normalized boxes.
+//! - [`ObjectTracker`] — multi-class IoU+Kalman tracker built on
+//!   `norfair-rs` (Rust port of the Python norfair library used by Frigate).
+//!
+//! All coordinates are normalized to `[0.0, 1.0]` so the tracker is
+//! resolution-independent.
+
+mod iou;
+mod line_crossing;
+mod merge;
+mod nms;
+mod tracker;
+mod types;
+mod zone_filter;
+
+use napi_derive::napi;
+
+use crate::line_crossing::{
+  CrossingDirection as InnerCrossingDirection, DetectionLineInput as InnerDetectionLineInput,
+  LineDirectionFilter as InnerLineDirectionFilter,
+};
+use crate::tracker::{ObjectTracker as InnerObjectTracker, ObjectTrackerConfig};
+use crate::zone_filter::{
+  ZoneFilterMode as InnerZoneFilterMode, ZoneInput as InnerZoneInput,
+  ZoneMatchType as InnerZoneMatchType,
+};
+
+/// Detection in normalized image coordinates `[0.0, 1.0]`.
+#[napi(object)]
+pub struct Detection {
+  pub x: f64,
+  pub y: f64,
+  pub width: f64,
+  pub height: f64,
+  pub confidence: f64,
+  pub label: String,
+}
+
+/// Detection with stable identity assigned by [`ObjectTracker`].
+#[napi(object)]
+pub struct TrackedDetection {
+  pub x: f64,
+  pub y: f64,
+  pub width: f64,
+  pub height: f64,
+  pub confidence: f64,
+  pub label: String,
+  /// Stable id across frames. Resets only on `ObjectTracker::reset()`.
+  pub track_id: u32,
+  /// Number of frames this track has existed (1 on first emit).
+  pub track_age: u32,
+  /// True when the box is being kept alive by Kalman extrapolation
+  /// instead of a fresh detection match this frame.
+  pub track_lost: bool,
+  /// Average centroid speed in normalized units/second over a sliding
+  /// ~1 s window of past positions. Consumers can compare against a
+  /// threshold (typical: 0.05) to distinguish moving from stationary
+  /// tracks. 0 when the track has only one sample so far.
+  pub track_speed: f64,
+}
+
+/// Bounding box used by [`box_iou`].
+#[napi(object)]
+pub struct BoundingBox {
+  pub x: f64,
+  pub y: f64,
+  pub width: f64,
+  pub height: f64,
+}
+
+/// How an active zone affects matching detections.
+#[napi(string_enum = "kebab-case")]
+pub enum ZoneFilterMode {
+  Include,
+  Exclude,
+}
+
+/// Where in the polygon the box must sit for the zone to apply.
+#[napi(string_enum = "kebab-case")]
+pub enum ZoneMatchType {
+  /// Any overlap with the polygon counts.
+  Intersect,
+  /// All four corners of the box must be inside the polygon.
+  Contain,
+}
+
+/// User-facing detection zone definition (matches the SDK shape).
+///
+/// `points` are polygon vertices in `[0, 100]` UI coordinates. The
+/// polygon is auto-closed so the caller does not need to repeat the
+/// first vertex at the end.
+#[napi(object)]
+pub struct DetectionZone {
+  pub labels: Vec<String>,
+  pub filter: ZoneFilterMode,
+  /// Match mode (intersect vs contain). Mapped to `type` on the JS side
+  /// of the SDK — the consumer is responsible for translating that field.
+  pub match_type: ZoneMatchType,
+  pub is_privacy_mask: bool,
+  pub points: Vec<Vec<f64>>,
+}
+
+/// Crossing line direction filter.
+///
+/// `"both"` accepts either direction. `"a-to-b"` and `"b-to-a"` only fire
+/// when the track moves from one specific side to the other.
+#[napi(string_enum = "kebab-case")]
+pub enum LineDirection {
+  Both,
+  AToB,
+  BToA,
+}
+
+/// User-facing crossing line definition.
+///
+/// `points` are the two handle endpoints in `[0, 100]` UI coordinates.
+/// `labels` is the set of allowed detection labels — empty means "any label".
+#[napi(object)]
+pub struct DetectionLine {
+  pub name: String,
+  pub direction: LineDirection,
+  pub labels: Vec<String>,
+  pub points: Vec<Vec<f64>>,
+}
+
+/// Crossing event emitted by [`ObjectTracker::update`].
+#[napi(object)]
+pub struct LineCrossingEvent {
+  pub line_name: String,
+  pub direction: LineDirection,
+  pub track_id: u32,
+  pub label: String,
+  pub confidence: f64,
+  /// Frame timestamp in milliseconds (forwarded from the `update()` call).
+  pub timestamp_ms: f64,
+  pub prev_x: f64,
+  pub prev_y: f64,
+  pub curr_x: f64,
+  pub curr_y: f64,
+}
+
+/// Result of [`ObjectTracker::update`] — active tracks plus any crossings
+/// fired this frame.
+#[napi(object)]
+pub struct UpdateResult {
+  pub tracked: Vec<TrackedDetection>,
+  pub crossings: Vec<LineCrossingEvent>,
+}
+
+/// Constructor options for [`ObjectTracker`].
+#[napi(object)]
+pub struct ObjectTrackerOptions {
+  /// IoU threshold above which a candidate is matched to an existing track.
+  /// Higher = stricter matching. Default 0.3.
+  pub iou_threshold: Option<f64>,
+  /// Frames a track survives without a fresh detection (Kalman extrapolation
+  /// continues during this window). Default 15.
+  pub hit_counter_max: Option<i32>,
+  /// Frames a new track must be matched before getting a permanent id —
+  /// filters one-frame false positives. Default 3.
+  pub initialization_delay: Option<i32>,
+  /// Frames a dead track stays available for ReID re-matching. When a new
+  /// detection appears near a dead track, norfair merges them — the old
+  /// track ID is preserved. Default: disabled.
+  pub reid_hit_counter_max: Option<i32>,
+}
+
+fn to_internal(d: Detection) -> crate::types::Detection {
+  crate::types::Detection {
+    x: d.x as f32,
+    y: d.y as f32,
+    width: d.width as f32,
+    height: d.height as f32,
+    confidence: d.confidence as f32,
+    label: d.label,
+  }
+}
+
+fn from_internal(d: crate::types::Detection) -> Detection {
+  Detection {
+    x: d.x as f64,
+    y: d.y as f64,
+    width: d.width as f64,
+    height: d.height as f64,
+    confidence: d.confidence as f64,
+    label: d.label,
+  }
+}
+
+fn zone_filter_to_internal(m: ZoneFilterMode) -> InnerZoneFilterMode {
+  match m {
+    ZoneFilterMode::Include => InnerZoneFilterMode::Include,
+    ZoneFilterMode::Exclude => InnerZoneFilterMode::Exclude,
+  }
+}
+
+fn zone_match_to_internal(m: ZoneMatchType) -> InnerZoneMatchType {
+  match m {
+    ZoneMatchType::Intersect => InnerZoneMatchType::Intersect,
+    ZoneMatchType::Contain => InnerZoneMatchType::Contain,
+  }
+}
+
+fn detection_zone_to_internal(zone: DetectionZone) -> Option<InnerZoneInput> {
+  let mut points: Vec<[f64; 2]> = Vec::with_capacity(zone.points.len());
+  for p in zone.points {
+    if p.len() != 2 {
+      return None;
+    }
+    points.push([p[0], p[1]]);
+  }
+  Some(InnerZoneInput {
+    labels: zone.labels,
+    filter: zone_filter_to_internal(zone.filter),
+    match_type: zone_match_to_internal(zone.match_type),
+    is_privacy_mask: zone.is_privacy_mask,
+    points,
+  })
+}
+
+fn line_direction_to_internal(d: LineDirection) -> InnerLineDirectionFilter {
+  match d {
+    LineDirection::Both => InnerLineDirectionFilter::Both,
+    LineDirection::AToB => InnerLineDirectionFilter::AToB,
+    LineDirection::BToA => InnerLineDirectionFilter::BToA,
+  }
+}
+
+fn line_direction_from_internal(d: InnerCrossingDirection) -> LineDirection {
+  match d {
+    InnerCrossingDirection::AToB => LineDirection::AToB,
+    InnerCrossingDirection::BToA => LineDirection::BToA,
+  }
+}
+
+fn detection_line_to_internal(line: DetectionLine) -> Option<InnerDetectionLineInput> {
+  // Validate `points` is exactly two `[x, y]` pairs.
+  if line.points.len() != 2 {
+    return None;
+  }
+  let p1 = &line.points[0];
+  let p2 = &line.points[1];
+  if p1.len() != 2 || p2.len() != 2 {
+    return None;
+  }
+  Some(InnerDetectionLineInput {
+    name: line.name,
+    direction: line_direction_to_internal(line.direction),
+    labels: line.labels,
+    points: [[p1[0], p1[1]], [p2[0], p2[1]]],
+  })
+}
+
+fn from_internal_tracked(d: crate::types::TrackedDetection) -> TrackedDetection {
+  TrackedDetection {
+    x: d.x as f64,
+    y: d.y as f64,
+    width: d.width as f64,
+    height: d.height as f64,
+    confidence: d.confidence as f64,
+    label: d.label,
+    track_id: d.track_id,
+    track_age: d.track_age,
+    track_lost: d.track_lost,
+    track_speed: d.track_speed as f64,
+  }
+}
+
+/// Run greedy non-maximum suppression on a list of detections.
+///
+/// Detections are suppressed only against higher-confidence boxes of the
+/// same `label`. Output is sorted by confidence descending. Pass
+/// `maxDetections` to cap the result length.
+#[napi]
+pub fn nms(
+  detections: Vec<Detection>,
+  iou_threshold: f64,
+  max_detections: Option<u32>,
+) -> Vec<Detection> {
+  let internal: Vec<crate::types::Detection> = detections.into_iter().map(to_internal).collect();
+  let max = max_detections.map(|n| n as usize);
+  let kept = crate::nms::nms(internal, iou_threshold as f32, max);
+  kept.into_iter().map(from_internal).collect()
+}
+
+/// Cluster nearby/overlapping same-label detections into single union
+/// boxes via union-find. Two boxes join the same cluster if their
+/// top-left corners are within `closeThreshold` along both axes OR if
+/// their IoU exceeds `iouThreshold`. Each cluster collapses to one
+/// `Detection` whose box covers the axis-aligned union of all members
+/// (clamped to `[0, 1]`) and whose confidence is the maximum in the
+/// cluster. Different labels are never clustered together.
+#[napi]
+pub fn merge(
+  detections: Vec<Detection>,
+  iou_threshold: f64,
+  close_threshold: f64,
+) -> Vec<Detection> {
+  let internal: Vec<crate::types::Detection> = detections.into_iter().map(to_internal).collect();
+  let merged =
+    crate::merge::merge_detections(internal, iou_threshold as f32, close_threshold as f32);
+  merged.into_iter().map(from_internal).collect()
+}
+
+/// Compute IoU between two normalized `[x, y, width, height]` boxes.
+#[napi(js_name = "boxIou")]
+pub fn box_iou(a: BoundingBox, b: BoundingBox) -> f64 {
+  let aa = [a.x as f32, a.y as f32, a.width as f32, a.height as f32];
+  let bb = [b.x as f32, b.y as f32, b.width as f32, b.height as f32];
+  crate::iou::box_iou(&aa, &bb) as f64
+}
+
+/// Multi-class IoU + Kalman object tracker.
+///
+/// Wraps `norfair-rs` with one sub-tracker per class label. Track ids are
+/// stable across frames and globally unique across classes. The tracker is
+/// resolution-independent — feed normalized `[0.0, 1.0]` coordinates.
+#[napi]
+pub struct ObjectTracker {
+  inner: InnerObjectTracker,
+}
+
+#[napi]
+impl ObjectTracker {
+  #[napi(constructor)]
+  pub fn new(options: Option<ObjectTrackerOptions>) -> Self {
+    let mut config = ObjectTrackerConfig::default();
+    if let Some(opts) = options {
+      if let Some(t) = opts.iou_threshold {
+        config.iou_threshold = t as f32;
+      }
+      if let Some(h) = opts.hit_counter_max {
+        config.hit_counter_max = h;
+      }
+      if let Some(i) = opts.initialization_delay {
+        config.initialization_delay = i;
+      }
+      if let Some(r) = opts.reid_hit_counter_max {
+        config.reid_hit_counter_max = if r > 0 { Some(r) } else { None };
+      }
+    }
+    Self {
+      inner: InnerObjectTracker::new(config),
+    }
+  }
+
+  /// Process one frame's detections and return active tracks plus any
+  /// line-crossing events that fired this frame. Detections without
+  /// overlap to existing tracks spawn new ones; existing tracks without a
+  /// matching detection are kept alive via Kalman extrapolation until
+  /// `hitCounterMax` frames have elapsed.
+  ///
+  /// `timestampMs` is forwarded onto emitted crossing events for sequencing
+  /// — pass `Date.now()` (or any monotonic millisecond clock).
+  #[napi]
+  pub fn update(&mut self, detections: Vec<Detection>, timestamp_ms: f64) -> UpdateResult {
+    let internal: Vec<crate::types::Detection> = detections.into_iter().map(to_internal).collect();
+    let result = self.inner.update(internal, timestamp_ms);
+    UpdateResult {
+      tracked: result
+        .tracked
+        .into_iter()
+        .map(from_internal_tracked)
+        .collect(),
+      crossings: result
+        .crossings
+        .into_iter()
+        .map(|c| LineCrossingEvent {
+          line_name: c.line_name,
+          direction: line_direction_from_internal(c.direction),
+          track_id: c.track_id,
+          label: c.label,
+          confidence: c.confidence as f64,
+          timestamp_ms: c.timestamp_ms,
+          prev_x: c.prev_pos[0] as f64,
+          prev_y: c.prev_pos[1] as f64,
+          curr_x: c.curr_pos[0] as f64,
+          curr_y: c.curr_pos[1] as f64,
+        })
+        .collect(),
+    }
+  }
+
+  /// Replace the configured crossing lines. Pass an empty array to disable
+  /// line crossings entirely. The `aspectRatio` is the camera's
+  /// `width / height` so the perpendicular crossing line ends up visually
+  /// perpendicular to the handle the user drew.
+  ///
+  /// Crossing memory is cleared on every reconfigure so existing tracks
+  /// will fire again the moment they cross a freshly-edited line.
+  #[napi]
+  pub fn set_lines(&mut self, lines: Vec<DetectionLine>, aspect_ratio: f64) {
+    let internal: Vec<InnerDetectionLineInput> = lines
+      .into_iter()
+      .filter_map(detection_line_to_internal)
+      .collect();
+    self.inner.set_lines(internal, aspect_ratio as f32);
+  }
+
+  /// Replace the configured detection zones (privacy masks + active
+  /// include/exclude regions). Pass an empty array to disable zone
+  /// filtering entirely. Coordinates are in `[0, 100]` UI space — the
+  /// tracker normalizes them internally and auto-closes polygons.
+  ///
+  /// The filter runs at the start of every `update()` call before
+  /// detections reach the underlying tracker.
+  #[napi]
+  pub fn set_zones(&mut self, zones: Vec<DetectionZone>) {
+    let internal: Vec<InnerZoneInput> = zones
+      .into_iter()
+      .filter_map(detection_zone_to_internal)
+      .collect();
+    self.inner.set_zones(internal);
+  }
+
+  /// Set the minimum detection confidence threshold. Detections below
+  /// this score are dropped at the start of every `update()` call before
+  /// they reach the zone filter or tracker. Default 0.0 (no threshold).
+  #[napi]
+  pub fn set_min_confidence(&mut self, min_confidence: f64) {
+    self.inner.set_min_confidence(min_confidence as f32);
+  }
+
+  /// Set how many frames a dead track stays available for ReID re-matching.
+  /// When a new detection appears near a dead track's last position,
+  /// norfair merges them — the old track ID is preserved with fresh
+  /// Kalman state. Pass 0 to disable ReID. Use to tie track re-ID
+  /// window to an external cascade timeout (e.g. `cascadeTimeout * fps`).
+  #[napi]
+  pub fn set_reid_hit_counter_max(&mut self, frames: i32) {
+    self.inner.set_reid_hit_counter_max(frames);
+  }
+
+  /// Refresh the ReID counter for all dead tracks back to max. Call every
+  /// frame while a cascade is active so dead tracks never expire during
+  /// the cascade window. Stop calling when the cascade ends.
+  #[napi]
+  pub fn refresh_reid(&mut self) {
+    self.inner.refresh_reid();
+  }
+
+  /// Apply the configured zones + confidence threshold to a list of
+  /// detections WITHOUT advancing the tracker state. Returns the indices
+  /// (positions in the input array) of the detections that pass the
+  /// filter. Used for the external-sensor-write path where a plugin
+  /// reports detections directly and we want to apply zone filtering
+  /// without running the full tracker.
+  #[napi]
+  pub fn filter_indices(&self, detections: Vec<Detection>) -> Vec<u32> {
+    let internal: Vec<crate::types::Detection> = detections.into_iter().map(to_internal).collect();
+    self.inner.filter_indices(&internal)
+  }
+
+  /// Drop every active track. The next `update()` starts from a clean
+  /// slate and track ids restart from 1. Use this to align tracker state
+  /// with external segment boundaries (e.g. cascade activate/deactivate).
+  #[napi]
+  pub fn reset(&mut self) {
+    self.inner.reset();
+  }
+
+  /// Total number of active tracks across all class buckets.
+  #[napi(getter)]
+  pub fn track_count(&self) -> u32 {
+    self.inner.track_count() as u32
+  }
+}