# Eye 👁️ - Quick Reference Card

## 🚀 Installation
```bash
pip install opencv-python numpy matplotlib   # required
pip install filterpy lap                      # optional (advanced tracking/smoothing)
cd eye && pip install -e .
```

## ⚡ 3-Line Quickstart
```python
import eye
dets = eye.detect(yolo_results)  # Auto-convert
tracked = eye.track(dets, use_case="traffic")  # Auto-config
frame = eye.annotate(frame, tracked)  # Draw everything
```

## 🎯 Auto-Convert Models
```python
eye.Detections.from_yolo(results)  # Ultralytics YOLO
eye.Detections.from_tensorflow(boxes, scores, classes)  # TF
eye.Detections.from_pytorch(outputs)  # torchvision
eye.Detections.from_opencv(detections)  # OpenCV DNN
eye.Detections.from_numpy(boxes, scores, classes)  # Raw numpy
eye.detect(results)  # Auto-detect format
```

## 🏁 Smart Tracking
```python
# Get recommendation
rec = eye.get_tracker_recommendation(eye.UseCase.TRAFFIC_DENSE)
tracker = eye.Tracker(**rec['config'])

# Or quick setup
tracked = eye.track(detections, use_case="pedestrians")

# Use cases: TRAFFIC_CLEAR, TRAFFIC_DENSE, PEDESTRIANS, SPORTS, SURVEILLANCE, WAREHOUSE
```

## 🎨 Easy Colors
```python
eye.Colors.RED, .BLUE, .GREEN, .YELLOW, .CYAN, .MAGENTA
eye.PredefinedPalettes.bright()  # 10 vibrant colors
eye.PredefinedPalettes.pastel()  # 6 soft colors
eye.PredefinedPalettes.traffic()  # Vehicle-themed
```

## 🔧 Jitter Reduction
```python
# Built-in (default ON)
tracker = eye.Tracker(enable_smoothing=True, smoothing_alpha=0.3)

# Manual
smoother = eye.ExponentialSmoothing(alpha=0.3)  # Fast
smoother = eye.KalmanSmoothing()  # Advanced
smooth_box = smoother.update(tracker_id, box)
```

## 📦 Tracker Settings

| Use Case | Tracker | Inflation | Max Age |
|----------|---------|-----------|---------|
| Clear roads | SORT | 1.5x | 30 |
| Dense traffic | ByteTrack | 2.0x | 50 |
| Pedestrians | ByteTrack | 1.8x | 30 |
| Sports | BoT-SORT | 1.5x | 30 |
| Surveillance | SORT | 1.3x | 60 |

## 🎬 Full Example
```python
import eye
from ultralytics import YOLO

model = YOLO("yolo11x.pt")
rec = eye.get_tracker_recommendation(eye.UseCase.TRAFFIC_DENSE)
tracker = eye.Tracker(**rec['config'])

filters = eye.FilterPipeline([
    eye.ConfidenceFilter(0.3),
    eye.AreaFilter(min_area=100),
    eye.ClassFilter([0, 2, 5, 7])
])

zone = eye.Zone(polygon, trigger_type=eye.ZoneType.CENTER)
manager = eye.DetectionManager(class_names=model.names)

video = eye.VideoProcessor("input.mp4", "output.mp4")

def process(frame, idx):
    dets = eye.detect(model(frame)[0])
    dets = filters(dets)
    dets = tracker.update(dets)  # With smoothing!
    zone.update(dets)
    manager.update(dets)
    return eye.annotate(frame, dets)

video.process(process)
manager.export_csv("results.csv")
```

## 📊 Cheat Sheet

### Detections
- `.xyxy` - Boxes (N, 4)
- `.confidence` - Scores (N,)
- `.class_id` - Classes (N,)
- `.tracker_id` - IDs (N,)
- `.area` - Cached areas
- `.center` - Cached centers
- `.filter(mask)` - Filter by mask

### Tracker
```python
eye.Tracker(
    tracker_type=eye.TrackerType.BYTETRACK,  # SORT, BYTETRACK, BOTSORT
    max_age=50,  # Frames to keep lost tracks
    min_hits=3,  # Min detections before confirmed
    iou_threshold=0.2,  # IoU for matching
    inflation_factor=2.0,  # Inflate boxes (1.5–2.5x; 2.0–3.0x for tiny/fast)
    enable_smoothing=True,  # Jitter reduction (default: False)
    smoothing_alpha=0.3  # Smoothness (0.1–0.5)
)

# Direct BoT-SORT access (appearance features)
from eye import BoTSORTTracker
bot = BoTSORTTracker(max_age=30, appearance_thresh=0.25)

# Reset between clips
tracker.reset()
```

### Filters
```python
eye.FilterPipeline([
    eye.ConfidenceFilter(min_confidence=0.5),
    eye.AreaFilter(min_area=100, max_area=50000),
    eye.AspectRatioFilter(min_ratio=0.2, max_ratio=5.0),
    eye.ClassFilter(allowed_classes=[0, 2, 5, 7])
])
```

### Annotators
```python
box_ann = eye.BoxAnnotator(thickness=2)
label_ann = eye.LabelAnnotator(text_scale=0.6)
trace_ann = eye.TraceAnnotator(fade=True, smooth=True)
zone_ann = eye.ZoneAnnotator(fill_alpha=0.2)
heatmap_ann = eye.HeatmapAnnotator(decay_factor=0.95)
```

## ⚙️ Parameters

### Inflation Factor
- 1.3x - Light (clear scenes, large objects)
- 1.5x - Medium (balanced)
- 2.0x - Heavy (crowded/occlusions)
- 2.5–3.0x - Maximum (tiny/fast objects: drones, birds, distant vehicles)

### Smoothing Alpha
- 0.1-0.2 - Very smooth (slow response)
- 0.3 - Balanced (default)
- 0.4-0.5 - Fast response (less smooth)

### Max Age
- 20-30 - Fast cleanup
- 40-50 - Balanced
- 60-80 - Long occlusions

### Min Hits
- 2-3 - Fast confirmation
- 4-5 - Balanced
- 6-10 - Very stable

## 💡 Tips
1. Use inflation 1.5-2.0x
2. Enable smoothing (default)
3. Get recommendations
4. Auto-convert models
5. Use one-liners for prototypes

## 🐛 Common Issues
- **ID switches**: Increase `inflation_factor` (2.0–3.0x for tiny/fast objects)
- **Boxes jitter**: Set `enable_smoothing=True`, decrease `smoothing_alpha`
- **Lost tracks**: Increase `max_age`
- **False tracks**: Increase `min_hits`
- **Import error (filterpy)**: It's optional; SORT/ByteTrack work without it

---
**Eye 👁️** - Simple & Powerful CV
