> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datamarkin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bytetracker

> Multi-object tracker implementing the ByteTrack algorithm.

## Overview

ByteTrack: Multi-Object Tracking by Associating Every Detection Box

This module implements the ByteTrack algorithm for multi-object tracking, which achieves high performance by associating both high and low confidence detections. ByteTrack uses a multi-stage matching process that recovers true objects from low-confidence detections while filtering out background noise, making it robust for real-world tracking scenarios.

ByteTrack associates every detection box instead of only high-confidence ones, utilizing similarities with existing tracklets to recover true objects from low-confidence detections while filtering out background. Uses a two-stage matching process: first matching high-confidence detections to existing tracks, then matching low-confidence detections to remaining unmatched tracks. This approach significantly improves tracking performance in challenging scenarios with occlusions and detection noise.

## Class Overview

The `ByteTracker` class provides structured data management for bytetracker operations.

## Parameters

<ParamField path="track_activation_threshold" type="float" required>
  Detection confidence threshold for track activation. Range: \[0.0, 1.0]. Default is 0.25 (25% confidence).
</ParamField>

<ParamField path="lost_track_buffer" type="int" required>
  Number of frames to buffer when a track is lost before removal. Range: \[1, 100]. Default is 30 frames (\~1 second at 30fps).
</ParamField>

<ParamField path="minimum_matching_threshold" type="float" required>
  IoU threshold for first-stage matching with high confidence detections. Range: \[0.0, 1.0]. Default is 0.7 (70% overlap required).
</ParamField>

<ParamField path="minimum_consecutive_frames" type="int" required>
  Minimum consecutive frames before considering a track valid. Range: \[1, 10]. Default is 3 frames.
</ParamField>

<ParamField path="second_match_threshold" type="float" required>
  IoU threshold for second-stage matching with low confidence detections. Range: \[0.0, 1.0]. Default is 0.5 (50% overlap required).
</ParamField>

<ParamField path="assignment_threshold" type="float" required>
  IoU threshold for assigning tracker IDs to final detections. Range: \[0.0, 1.0]. Default is 0.3 (30% overlap required).
</ParamField>

## Examples

<CodeGroup>
  ```python Example theme={null}
  import cv2
  import pixelflow as pf
  from ultralytics import YOLO

  # Initialize tracker with default settings
  tracker = pf.tracker.ByteTracker()
  model = YOLO("yolo11n.pt")
  video_path = "path/to/video.mp4"

  # Process video frames
  for frame in pf.video.get_video_frames(video_path):
  ```

  ```python Example theme={null}

  # Configure for high-precision tracking
  precision_tracker = pf.tracker.ByteTracker(
  ```

  ```python Example theme={null}

  # Configure for challenging scenarios
  robust_tracker = pf.tracker.ByteTracker(
  ```

  ```python Example theme={null}

  # Reset tracker between videos
  tracker.reset()
  metrics = tracker.get_metrics()
  print(f"Tracked {metrics['total_tracks']} objects")

  ```
</CodeGroup>

## Error Handling

<Warning>
  This function may raise the following exceptions:

  * **ValueError**: If any threshold parameter is outside valid range \[0.0, 1.0]
  * **ValueError**: If frame or buffer parameters are not positive integers
</Warning>

## Notes

<Note>
  * Uses Kalman filtering for motion prediction
  * Implements two-stage association: high-confidence then low-confidence
  * Automatically handles track state transitions (tracked → lost → removed)
  * Maintains track continuity through temporary occlusions
  * Filters out short-lived false positive tracks
  * All threshold parameters are automatically clamped to valid ranges
  * Optimized for real-time video processing (>30 FPS on modern hardware)
  * Memory usage scales linearly with number of active tracks
  * IoU computation is the primary bottleneck for scenes with many detections
  * Efficient track management prevents memory leaks in long videos
</Note>