Track Objects (OpenCV CSRT)

How it fits

Typical backends

Caveats

• FallbackUnknown tracker values fall back silently to csrt; csrt is the most accurate and slowest; mil is the fastest and weakest under appearance change.
• Parameter interactionHigher max_lost_frames tolerates longer occlusions at the cost of stale boxes lingering after the object has left the scene.
• Parameter interactionWhen reinit_on_new_dets is true, every non-empty detection list clears the entire tracking bank and assigns fresh ids; ids are not stable across detector calls.
• I/O contractThe output is a oneof resolved once by the connected downstream. [Track] (default) carries each alive track's UInt64 id, its CSRT-updated BoundingBox, and a ``[Point<Double>]`` trajectory of box centres. [TrackedObject] carries id and confidence; CSRT has no detection score, so confidence is always 1.0. [BoundingBox] carries the id-less updated boxes, and [UInt64] carries the alive ids only. Every arm reports the same set of alive tracks on each frame.
• I/O contractThe class id on every box-bearing arm is carried from the detection that seeded the track; the visual tracking filter re-positions the box every frame but never re-estimates the class, so it stays frozen at its initialisation value for the life of the track.
• I/O contractThe [Track] trajectory is a bounded ring buffer of the last 128 box centres, oldest first; a freshly seeded track has a single-point trajectory (the init box centre) and it grows by one point per surviving frame up to the cap.
• LimitationCSRT is an appearance-correlation single-object filter with no instance mask and no class/score re-estimation, so there is no mask output arm and no TrackedSegmentation; for instance masks use a segmentation-and-tracking component instead.
• State lifetimeTrack ids are monotonically increasing starting at 1 for the lifetime of the process; restarts reset the counter.
• State lifetimeEach frame, every alive track is advanced (coasted) by its correlation filter; incoming detections are then IoU-matched to tracks of the same class and re-anchor the matched track on the detection box (correcting filter drift). A detection that matches no track births a new track, and a track that goes more than max_lost_frames consecutive frames without a matching detection is dropped. Every alive track is emitted on every frame, so a coasting (detection-less) track keeps appearing until it expires.
• I/O contractOutput cardinality is the number of ALIVE tracks, not the number of detections on the current frame. A detection list shorter than the alive-track set still emits all coasting tracks; an unmatched detection adds one track. The correlation filter (CSRT/KCF/MIL) rarely reports loss, so expiry is driven by detection staleness, not by the filter signalling failure.
• Hard constraintDetection rectangles are clamped to frame bounds before the tracking filter sees them; a box smaller than 16 px on a side (or a frame too small to hold it) is not trackable by the correlation filter and is skipped, so no track is born for it. The tick still emits its (possibly shorter) list.
• LimitationSingle-object trackers do not handle id swaps under heavy occlusion; pair with reidentify_objects_torchreid for crowded scenes.
• AccuracyFor the csrt tracker, the optional spatial-reliability segmentation step is disabled so multiple correlation filters run stably in one worker; the box-only discriminative filter is unaffected for rectangular objects, with a small accuracy cost only on non-rectangular shapes the box model never captured anyway.
• FallbackAn empty Image returns an empty list on whichever arm is resolved without touching the tracking bank; every tick emits exactly one list, never a drop.