Roboflow Docs

OC-SORT Tracker

Tracks objects through occlusion and unpredictable movement.

Track objects across video frames using the OC-SORT algorithm from the roboflow/trackers package.

OC-SORT extends SORT with two key mechanisms:

  1. Observation-Centric Re-Update (OCR): When a track reappears after occlusion, OC-SORT retroactively corrects the Kalman filter using the real observations before and after the gap, reducing accumulated drift.
  2. Observation-Centric Momentum (OCM): A direction-consistency cost is blended with IoU during association, penalising matches where the candidate detection lies in a direction inconsistent with the track's recent motion.

This makes OC-SORT significantly more robust than SORT in scenes with heavy occlusion, erratic motion, and uniform appearance.

When to use OC-SORT:

  • Crowded scenes with frequent and prolonged occlusions (e.g. pedestrians, warehouse workers).
  • Non-linear or erratic motion patterns (e.g. dancing, sports with abrupt direction changes).
  • When identity consistency over long sequences is more important than raw speed.

When to consider alternatives:

  • For general-purpose tracking with mixed-confidence detections, try ByteTrack.
  • For maximum simplicity and speed with a strong detector, try SORT.

Outputs three detection sets:

  • tracked_detections: All confirmed tracked detections with assigned track IDs.
  • new_instances: Detections whose track ID appears for the first time.
  • already_seen_instances: Detections whose track ID has been seen in a prior frame.

The block maintains separate tracker state and instance cache per video_identifier, enabling multi-stream tracking within a single workflow.

Type identifier

Use the following identifier in step "type" field: roboflow_core/trackers_ocsort@v1 to add the block as a step in your workflow.

Properties

NameTypeDescriptionRefs
namestrEnter a unique identifier for this step..❌
minimum_iou_thresholdfloatMinimum IoU required to associate a detection with an existing track. Default: 0.3..✅
minimum_consecutive_framesintNumber of consecutive frames a track must be matched before it is emitted as a confirmed track (tracker_id != -1). Default: 3..✅
lost_track_bufferintNumber of frames to keep a track alive after it loses its matched detection. Higher values improve occlusion recovery. Default: 30..✅
high_conf_det_thresholdfloatConfidence threshold for high-confidence detections used in association. Default: 0.6..✅
direction_consistency_weightfloatWeight for the direction consistency term in the OC-SORT association cost. Higher values prioritise alignment between historical motion direction and the direction to the candidate detection. Default: 0.2..✅
delta_tintNumber of past frames used by OC-SORT to estimate per-track velocity for direction consistency momentum. Default: 3..✅
instances_cache_sizeintMaximum number of track IDs retained in the instance cache for new/already-seen categorisation. Uses FIFO eviction. Default: 16384..❌

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Runtime compatibility

soft - runtime hosted_serverless, dedicated_deployment; execution remote; input video : Block keeps per-video state in process memory (keyed by video_metadata.video_identifier). With remote step execution on stateless or multi-replica HTTP runtimes, successive requests may be served by different worker processes, so the state resets between calls and the output is meaningless for tracking / counting / aggregation. Use local step execution in a persistent WebRTC session for stable cross-frame results.

soft - input image : Block depends on temporal context from video or repeated-frame workflows. With a still image/photo, there is no meaningful history to track, compare, aggregate, or visualize, so the block provides little or no benefit.

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds OC-SORT Tracker in version v1 has.

Input and output bindings

  • input

    • image (image): Input image with embedded video metadata (fps and video_identifier). Used to initialise and retrieve per-video tracker state..
    • detections (Union[rle_instance_segmentation_prediction, object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction]): Detection predictions for the current frame to track..
    • minimum_iou_threshold (float_zero_to_one): Minimum IoU required to associate a detection with an existing track. Default: 0.3..
    • minimum_consecutive_frames (integer): Number of consecutive frames a track must be matched before it is emitted as a confirmed track (tracker_id != -1). Default: 3..
    • lost_track_buffer (integer): Number of frames to keep a track alive after it loses its matched detection. Higher values improve occlusion recovery. Default: 30..
    • high_conf_det_threshold (float_zero_to_one): Confidence threshold for high-confidence detections used in association. Default: 0.6..
    • direction_consistency_weight (float_zero_to_one): Weight for the direction consistency term in the OC-SORT association cost. Higher values prioritise alignment between historical motion direction and the direction to the candidate detection. Default: 0.2..
    • delta_t (integer): Number of past frames used by OC-SORT to estimate per-track velocity for direction consistency momentum. Default: 3..

  • output

    • tracked_detections (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction, rle_instance_segmentation_prediction]): Prediction with detected bounding boxes in form of sv.Detections(...) object if object_detection_prediction or Prediction with detected bounding boxes and segmentation masks in form of sv.Detections(...) object if instance_segmentation_prediction or Prediction with detected bounding boxes and detected keypoints in form of sv.Detections(...) object if keypoint_detection_prediction or Prediction with detected bounding boxes and RLE-encoded segmentation masks in form of sv.Detections(...) object if rle_instance_segmentation_prediction.
    • new_instances (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction, rle_instance_segmentation_prediction]): Prediction with detected bounding boxes in form of sv.Detections(...) object if object_detection_prediction or Prediction with detected bounding boxes and segmentation masks in form of sv.Detections(...) object if instance_segmentation_prediction or Prediction with detected bounding boxes and detected keypoints in form of sv.Detections(...) object if keypoint_detection_prediction or Prediction with detected bounding boxes and RLE-encoded segmentation masks in form of sv.Detections(...) object if rle_instance_segmentation_prediction.
    • already_seen_instances (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction, rle_instance_segmentation_prediction]): Prediction with detected bounding boxes in form of sv.Detections(...) object if object_detection_prediction or Prediction with detected bounding boxes and segmentation masks in form of sv.Detections(...) object if instance_segmentation_prediction or Prediction with detected bounding boxes and detected keypoints in form of sv.Detections(...) object if keypoint_detection_prediction or Prediction with detected bounding boxes and RLE-encoded segmentation masks in form of sv.Detections(...) object if rle_instance_segmentation_prediction.
Example JSON definition
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/trackers_ocsort@v1",
	    "image": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "minimum_iou_threshold": 0.3,
	    "minimum_consecutive_frames": 3,
	    "lost_track_buffer": 30,
	    "high_conf_det_threshold": 0.6,
	    "direction_consistency_weight": 0.2,
	    "delta_t": 3,
	    "instances_cache_size": "<block_does_not_provide_example>"
	}