# Tracker Selection Guide

## Quick Reference

| Use Case | Tracker | Inflation | Why |
|----------|---------|-----------|-----|
| **Clear Roads** | SORT | 1.5x | Fast, sufficient for good visibility |
| **Dense Traffic** | ByteTrack | 2.0x | Handles occlusions, crowded scenes |
| **Pedestrians** | ByteTrack | 1.8x | Fast appearance/disappearance |
| **Sports** | BoT-SORT | 1.5x | Handles camera motion |
| **Surveillance** | SORT | 1.3x | Long-term stability |
| **Warehouse** | ByteTrack | 1.6x | Indoor occlusions |

## Tracker Comparison

### SORT (Simple Online Realtime Tracker)
- **Speed**: ⚡⚡⚡ Very Fast
- **Robustness**: ⭐⭐ Good
- **Best For**: Clear visibility, high FPS, simple scenes
- **Pros**: Minimal overhead, easy to tune
- **Cons**: Loses tracks easily in occlusions
- **Recommended Inflation**: 1.3-1.5x

```python
tracker = eye.Tracker(
    tracker_type=eye.TrackerType.SORT,
    max_age=30,
    min_hits=3,
    iou_threshold=0.3,
    inflation_factor=1.5
)
```

### ByteTrack
- **Speed**: ⚡⚡ Medium
- **Robustness**: ⭐⭐⭐ Excellent
- **Best For**: Occlusions, crowded scenes, varying detection quality
- **Pros**: Recovers tracks after occlusion, handles low-confidence detections
- **Cons**: Slightly slower than SORT
- **Recommended Inflation**: 1.6-2.0x

```python
tracker = eye.Tracker(
    tracker_type=eye.TrackerType.BYTETRACK,
    max_age=50,
    min_hits=3,
    iou_threshold=0.2,
    inflation_factor=2.0
)
```

### BoT-SORT (Bot + Appearance)
- **Speed**: ⚡ Slower
- **Robustness**: ⭐⭐⭐ Excellent
- **Best For**: Camera motion, fast objects, sports
- **Pros**: Appearance features, motion compensation
- **Cons**: Higher computational cost
- **Recommended Inflation**: 1.5–1.7x

```python
# Via Tracker wrapper
tracker = eye.Tracker(
    tracker_type=eye.TrackerType.BOTSORT,
    max_age=30,
    min_hits=3,
    iou_threshold=0.4,
    inflation_factor=1.5
)

# Or use BoTSORTTracker directly for appearance features
from eye import BoTSORTTracker
bot = BoTSORTTracker(max_age=30, appearance_thresh=0.25)
result = bot.update(dets_array, features=embeddings)
```

## Parameters Explained

### max_age
How long to keep "lost" tracks before deletion.
- **Low (20-30)**: Fast cleanup, fewer false tracks
- **Medium (30-50)**: Balanced
- **High (50-80)**: Keep tracks longer, better for intermittent occlusions

### min_hits
Minimum detections before confirming track.
- **Low (2-3)**: Fast confirmation, more false positives
- **Medium (3-5)**: Balanced
- **High (5-10)**: Very stable, slower to confirm

### iou_threshold
IoU threshold for matching detections to tracks.
- **Low (0.1-0.2)**: More lenient matching (crowded scenes)
- **Medium (0.2-0.4)**: Balanced
- **High (0.4-0.6)**: Strict matching (clear scenes)

### inflation_factor
Multiply box size for matching (Eye innovation!).
- **1.0x**: No inflation (not recommended)
- **1.3–1.5x**: Light inflation (clear scenes, large objects)
- **1.6–1.8x**: Medium inflation (balanced)
- **1.9–2.5x**: Heavy inflation (crowded, occlusions)
- **2.5–3.0x**: Maximum inflation (tiny or fast-moving objects — drones, birds, distant vehicles)

> **Tiny / fast objects:** These often have near-zero IoU between frames because
> the box is small relative to the displacement. Use 2.0–3.0x inflation to
> give the matcher enough overlap. Start high, lower only if you get false merges.

## Use Case Examples

### Traffic Analysis (Clear Roads)
```python
rec = eye.get_tracker_recommendation(eye.UseCase.TRAFFIC_CLEAR)
# → SORT, max_age=30, inflation=1.5x
```
**Why**: Fast processing, good visibility, predictable motion.

### Traffic Analysis (Dense/Urban)
```python
rec = eye.get_tracker_recommendation(eye.UseCase.TRAFFIC_DENSE)
# → ByteTrack, max_age=50, inflation=2.0x
```
**Why**: Frequent occlusions, varying speeds, need robustness.

### Pedestrian Tracking
```python
rec = eye.get_tracker_recommendation(eye.UseCase.PEDESTRIANS)
# → ByteTrack, max_age=30, min_hits=2, inflation=1.8x
```
**Why**: Fast appearance/disappearance, occlusions, erratic motion.

### Sports Tracking
```python
rec = eye.get_tracker_recommendation(eye.UseCase.SPORTS)
# → BoT-SORT, inflation=1.5x
```
**Why**: Camera motion, fast objects, similar appearances.

### Surveillance
```python
rec = eye.get_tracker_recommendation(eye.UseCase.SURVEILLANCE)
# → SORT, max_age=60, min_hits=5, inflation=1.3x
```
**Why**: Long-term stability, low false positives, static camera.

### Warehouse/Retail
```python
rec = eye.get_tracker_recommendation(eye.UseCase.WAREHOUSE)
# → ByteTrack, max_age=40, inflation=1.6x
```
**Why**: Shelf occlusions, indoor lighting, moderate density.

## Jitter Reduction

### When to Use Smoothing

**Recommended** (set `enable_smoothing=True`):
- Reduces box jitter by 60–80%
- Minimal performance impact
- Especially important for:
  - Video stabilization
  - Professional-looking output
  - Downstream processing (e.g., cropping faces)

> **Note:** `enable_smoothing` defaults to `False`. Set it explicitly to `True`.

### Smoothing Types

**Exponential Smoothing** (Built-in):
- Fast, lightweight
- `alpha=0.3` (default, balanced)
- Lower alpha = smoother but slower response

```python
tracker = eye.Tracker(
    enable_smoothing=True,
    smoothing_alpha=0.3  # Adjust 0.1-0.5
)
```

**Kalman Smoothing** (Advanced):
- More sophisticated
- Better for non-linear motion
- Slightly slower

```python
smoother = eye.KalmanSmoothing()
smooth_box = smoother.update(tracker_id, box)
```

## Decision Tree

```
Need tracking?
├─ Clear visibility, high FPS?
│  └─ SORT (1.3–1.5x inflation)
│
├─ Crowded, occlusions?
│  └─ ByteTrack (1.8–2.0x inflation)
│
├─ Camera moving?
│  └─ BoT-SORT (1.5–1.7x inflation)
│
├─ Tiny or very fast objects?
│  └─ ByteTrack or BoT-SORT (2.0–3.0x inflation)
│
└─ Not sure?
   └─ Use eye.get_tracker_recommendation()
```

## Performance Tips

1. **Start with recommendation**: `eye.get_tracker_recommendation(use_case)`
2. **Enable smoothing**: `enable_smoothing=True` reduces jitter
3. **Tune inflation**: Higher for crowded scenes (1.8–2.5x); **2.0–3.0x for tiny/fast objects**
4. **Adjust max_age**: Higher for occlusions (40–60)
5. **Monitor FPS**: SORT > ByteTrack > BoT-SORT
6. **Reset between clips**: `tracker.reset()` to clear state
7. **filterpy/lap are optional**: Core tracking (SORT, ByteTrack) works without them

## Example: Tuning for Your Scene

```python
import eye

# Start with recommendation
rec = eye.get_tracker_recommendation(eye.UseCase.TRAFFIC_DENSE)
tracker = eye.Tracker(**rec['config'])

# Test on sample video
# If tracks are lost too quickly → increase max_age
# If too many false tracks → increase min_hits
# If boxes don't match well → increase inflation_factor
# If boxes jitter → decrease smoothing_alpha

# Example adjustments:
tracker = eye.Tracker(
    tracker_type=eye.TrackerType.BYTETRACK,
    max_age=60,  # Increased from 50
    min_hits=4,  # Increased from 3
    iou_threshold=0.2,
    inflation_factor=2.2,  # Increased from 2.0
    smoothing_alpha=0.2  # Decreased for smoother
)
```

---

**Eye** - Smart tracking made simple. 👁️
