@camera.ui/rust-postprocessor 0.0.1

package/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [X.X.X] - ???
+
+- Initial Release

package/CONTRIBUTING.md

@@ -0,0 +1 @@
+# Contributing

package/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+edition = "2021"
+name = "cameraui-rust-postprocessor"
+version = "0.0.0"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = { version = "3.8.4", default-features = false, features = ["napi9"] }
+napi-derive = "3.5.3"
+
+# Tracker engine — Rust port of the Python `norfair` library used by Frigate.
+# Same battle-tested algorithm: Kalman filter, IoU/Euclidean distance, ReID lifecycle.
+norfair-rs = { version = "0.4.1", default-features = false }
+
+# Stable nalgebra for the few places we construct DMatrix ourselves
+nalgebra = "0.34.2"
+
+# SIMD primitives for our NMS implementation (f32x8 = 8 floats parallel).
+wide = "1.2.0"
+
+[build-dependencies]
+napi-build = "2.3.1"
+
+[profile.release]
+lto = true
+strip = "symbols"
+codegen-units = 1

package/README.md

@@ -0,0 +1,5 @@
+# @camera.ui/rust-postprocessor
+
+---
+
+*Part of the camera.ui ecosystem - A comprehensive camera management solution.*

package/build.rs

@@ -0,0 +1,5 @@
+extern crate napi_build;
+
+fn main() {
+  napi_build::setup();
+}

package/index.d.ts

@@ -0,0 +1,254 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * 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.
+ */
+export declare class ObjectTracker {
+  constructor(options?: ObjectTrackerOptions | undefined | null)
+  /**
+   * 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).
+   */
+  update(detections: Array<Detection>, timestampMs: number): UpdateResult
+  /**
+   * 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.
+   */
+  setLines(lines: Array<DetectionLine>, aspectRatio: number): void
+  /**
+   * 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.
+   */
+  setZones(zones: Array<DetectionZone>): void
+  /**
+   * 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).
+   */
+  setMinConfidence(minConfidence: number): void
+  /**
+   * 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`).
+   */
+  setReidHitCounterMax(frames: number): void
+  /**
+   * 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.
+   */
+  refreshReid(): void
+  /**
+   * 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.
+   */
+  filterIndices(detections: Array<Detection>): Array<number>
+  /**
+   * 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).
+   */
+  reset(): void
+  /** Total number of active tracks across all class buckets. */
+  get trackCount(): number
+}
+
+/** Bounding box used by [`box_iou`]. */
+export interface BoundingBox {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/** Compute IoU between two normalized `[x, y, width, height]` boxes. */
+export declare function boxIou(a: BoundingBox, b: BoundingBox): number
+
+/** Detection in normalized image coordinates `[0.0, 1.0]`. */
+export interface Detection {
+  x: number
+  y: number
+  width: number
+  height: number
+  confidence: number
+  label: string
+}
+
+/**
+ * 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".
+ */
+export interface DetectionLine {
+  name: string
+  direction: LineDirection
+  labels: Array<string>
+  points: Array<Array<number>>
+}
+
+/**
+ * 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.
+ */
+export interface DetectionZone {
+  labels: Array<string>
+  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.
+   */
+  matchType: ZoneMatchType
+  isPrivacyMask: boolean
+  points: Array<Array<number>>
+}
+
+/** Crossing event emitted by [`ObjectTracker::update`]. */
+export interface LineCrossingEvent {
+  lineName: string
+  direction: LineDirection
+  trackId: number
+  label: string
+  confidence: number
+  /** Frame timestamp in milliseconds (forwarded from the `update()` call). */
+  timestampMs: number
+  prevX: number
+  prevY: number
+  currX: number
+  currY: number
+}
+
+/**
+ * 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.
+ */
+export declare const enum LineDirection {
+  Both = 'both',
+  AToB = 'a-to-b',
+  BToA = 'b-to-a'
+}
+
+/**
+ * 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.
+ */
+export declare function merge(detections: Array<Detection>, iouThreshold: number, closeThreshold: number): Array<Detection>
+
+/**
+ * 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.
+ */
+export declare function nms(detections: Array<Detection>, iouThreshold: number, maxDetections?: number | undefined | null): Array<Detection>
+
+/** Constructor options for [`ObjectTracker`]. */
+export interface ObjectTrackerOptions {
+  /**
+   * IoU threshold above which a candidate is matched to an existing track.
+   * Higher = stricter matching. Default 0.3.
+   */
+  iouThreshold?: number
+  /**
+   * Frames a track survives without a fresh detection (Kalman extrapolation
+   * continues during this window). Default 15.
+   */
+  hitCounterMax?: number
+  /**
+   * Frames a new track must be matched before getting a permanent id —
+   * filters one-frame false positives. Default 3.
+   */
+  initializationDelay?: number
+  /**
+   * 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.
+   */
+  reidHitCounterMax?: number
+}
+
+/** Detection with stable identity assigned by [`ObjectTracker`]. */
+export interface TrackedDetection {
+  x: number
+  y: number
+  width: number
+  height: number
+  confidence: number
+  label: string
+  /** Stable id across frames. Resets only on `ObjectTracker::reset()`. */
+  trackId: number
+  /** Number of frames this track has existed (1 on first emit). */
+  trackAge: number
+  /**
+   * True when the box is being kept alive by Kalman extrapolation
+   * instead of a fresh detection match this frame.
+   */
+  trackLost: boolean
+  /**
+   * 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.
+   */
+  trackSpeed: number
+}
+
+/**
+ * Result of [`ObjectTracker::update`] — active tracks plus any crossings
+ * fired this frame.
+ */
+export interface UpdateResult {
+  tracked: Array<TrackedDetection>
+  crossings: Array<LineCrossingEvent>
+}
+
+/** How an active zone affects matching detections. */
+export declare const enum ZoneFilterMode {
+  Include = 'include',
+  Exclude = 'exclude'
+}
+
+/** Where in the polygon the box must sit for the zone to apply. */
+export declare const enum ZoneMatchType {
+  /** Any overlap with the polygon counts. */
+  Intersect = 'intersect',
+  /** All four corners of the box must be inside the polygon. */
+  Contain = 'contain'
+}