# Eye - Usage Guide 👁️

## Installation

```bash
cd eye
pip install -e .
```

## Ultra-Simple (3 Lines)

```python
import eye
from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Process video in 3 lines!
for result in model("video.mp4", stream=True):
    dets = eye.detect(result)  # Auto-convert
    tracked = eye.track(dets, use_case="traffic")  # Auto-config
    frame = eye.annotate(result.orig_img, tracked)  # Draw
```

## Model Auto-Conversion

### YOLO (Easiest)
```python
results = model(frame)[0]
detections = eye.detect(results)  # Auto-detects YOLO
```

### TensorFlow
```python
boxes, scores, classes = tf_model.predict(frame)
detections = eye.detect((boxes, scores, classes), "tensorflow")
```

### PyTorch (torchvision)
```python
outputs = torch_model(frame)
detections = eye.detect(outputs, "pytorch")
```

### Manual
```python
detections = eye.Detections.from_numpy(boxes, scores, classes)
```

## Smart Tracking

### Quick Setup
```python
# Let Eye choose for you
tracked = eye.track(detections, use_case="traffic")
tracked = eye.track(detections, use_case="pedestrians")
tracked = eye.track(detections, use_case="sports")
```

### Get Recommendation
```python
rec = eye.get_tracker_recommendation(eye.UseCase.TRAFFIC_DENSE)
print(rec['reason'])
# → "ByteTrack handles occlusions well. Higher inflation (2.0x)..."

tracker = eye.Tracker(**rec['config'])
```

### Manual Control
```python
tracker = eye.Tracker(
    tracker_type=eye.TrackerType.BYTETRACK,
    inflation_factor=2.0,  # 2x box size for matching
    enable_smoothing=True,  # Reduce jitter
    smoothing_alpha=0.3  # Lower = smoother
)

tracked = tracker.update(detections)

# Reset between video clips or scenes
tracker.reset()
```

### BoT-SORT Direct Access
```python
# For appearance features (embeddings)
from eye import BoTSORTTracker
bot = BoTSORTTracker(max_age=30, appearance_thresh=0.25)
result = bot.update(dets_array, features=embeddings)
```

## Jitter Reduction

### Automatic (Built-in)
```python
tracker = eye.Tracker(enable_smoothing=True)  # Set explicitly (default is False)
```

> **Note:** `filterpy` is optional. Exponential smoothing works without it;
> install `filterpy` only if you want Kalman smoothing.

### Manual Control
```python
# Fast smoothing
smoother = eye.ExponentialSmoothing(alpha=0.3)

# Advanced smoothing
smoother = eye.KalmanSmoothing(
    process_noise=0.01,
    measurement_noise=0.1
)

# Apply
for tid, box in zip(tracker_ids, boxes):
    smooth_box = smoother.update(tid, box)
```

## Easy Colors

```python
# Quick access
red = eye.Colors.RED
blue = eye.Colors.BLUE
green = eye.Colors.GREEN

# Palettes
bright = eye.PredefinedPalettes.bright()
pastel = eye.PredefinedPalettes.pastel()
traffic = eye.PredefinedPalettes.traffic()

# Use in annotators
box_ann = eye.BoxAnnotator(color_palette=bright)
```

## Quick Annotation

### One-Liner
```python
frame = eye.annotate(frame, detections)
```

### Custom
```python
# Create annotators
box_ann = eye.BoxAnnotator()
label_ann = eye.LabelAnnotator()
trace_ann = eye.TraceAnnotator(fade=True)

# Apply
frame = box_ann.annotate(frame, detections)
frame = label_ann.annotate(frame, detections, labels)
frame = trace_ann.annotate(frame, detections)
```

## Tracker Recommendations

### Traffic (Clear Roads)
```python
rec = eye.get_tracker_recommendation(eye.UseCase.TRAFFIC_CLEAR)
# → SORT, inflation 1.5x, fast
```

### Traffic (Dense/Crowded)
```python
rec = eye.get_tracker_recommendation(eye.UseCase.TRAFFIC_DENSE)
# → ByteTrack, inflation 2.0x, handles occlusions
```

### Pedestrians
```python
rec = eye.get_tracker_recommendation(eye.UseCase.PEDESTRIANS)
# → ByteTrack, inflation 1.8x, fast response
```

### Sports
```python
rec = eye.get_tracker_recommendation(eye.UseCase.SPORTS)
# → BoT-SORT, inflation 1.5x, handles camera motion
```

### Surveillance
```python
rec = eye.get_tracker_recommendation(eye.UseCase.SURVEILLANCE)
# → SORT, inflation 1.3x, long-term stability
```

## Complete Workflow

```python
import eye
from ultralytics import YOLO

# 1. Setup
model = YOLO("yolo11x.pt")

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

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

# 4. Zones
zone = eye.Zone(
    polygon=np.array([[100, 300], [500, 700]]),
    trigger_type=eye.ZoneType.CENTER
)

# 5. Annotators
box_ann = eye.BoxAnnotator()
trace_ann = eye.TraceAnnotator(fade=True, smooth=True)

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

def process(frame, idx):
    # Detect & convert (auto!)
    dets = eye.detect(model(frame)[0])
    
    # Filter
    dets = filters(dets)
    
    # Track (with smoothing!)
    dets = tracker.update(dets)
    
    # Annotate
    frame = trace_ann.annotate(frame, dets)
    frame = box_ann.annotate(frame, dets)
    
    return frame

video.process(process)
```

## Tips

1. **Use auto-convert** - `eye.detect(results)` works with any model
2. **Get recommendations** - `eye.get_tracker_recommendation()` for best settings
3. **Enable smoothing** - Reduces jitter by 60-80%
4. **Use inflation** - 1.5-2.0x for better tracking
5. **Try one-liners** - `eye.track()` and `eye.annotate()` for quick prototypes

## Performance

- **Inflation**: 1.5x (clear) to 2.0x (crowded); **2.0–3.0x for tiny/fast objects**
- **Smoothing**: α=0.3 (balanced) to 0.1 (very smooth)
- **Tracker**: SORT (fast) → ByteTrack (robust) → BoT-SORT (advanced)
- **Reset**: Call `tracker.reset()` between video clips
- **Optional deps**: `filterpy`/`lap` are optional — core tracking works without them

## Key Features

| Feature | Eye |
|---------|-----|
| Model conversion | Auto |
| Tracker setup | Get recommendation |
| Jitter reduction | Built-in |
| Color API | Simple (Colors.RED) |
| One-liners | Yes (detect/track/annotate) |
| Learning curve | Gentle |

---

**Eye** - Because CV should be simple. 👁️
