> ## 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

**track\_activation\_threshold** `float` *required*

Detection confidence threshold for track activation. Range: \[0.0, 1.0]. Default is 0.25 (25% confidence).

**lost\_track\_buffer** `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).

**minimum\_matching\_threshold** `float` *required*

IoU threshold for first-stage matching with high confidence detections. Range: \[0.0, 1.0]. Default is 0.7 (70% overlap required).

**minimum\_consecutive\_frames** `int` *required*

Minimum consecutive frames before considering a track valid. Range: \[1, 10]. Default is 3 frames.

**second\_match\_threshold** `float` *required*

IoU threshold for second-stage matching with low confidence detections. Range: \[0.0, 1.0]. Default is 0.5 (50% overlap required).

**assignment\_threshold** `float` *required*

IoU threshold for assigning tracker IDs to final detections. Range: \[0.0, 1.0]. Default is 0.3 (30% overlap required).

## Examples

```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")

```

## 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

## 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.