Metadata-Version: 2.4
Name: eye-cv
Version: 1.0.0
Summary: Eye - Simple & Powerful Computer Vision. Auto-convert, smart tracking, jitter reduction.
Author: Dakar Project
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: tqdm>=4.66.0
Provides-Extra: smooth
Requires-Dist: filterpy>=1.4.5; extra == "smooth"
Provides-Extra: track
Requires-Dist: lap>=0.4.0; extra == "track"
Provides-Extra: web-flask
Requires-Dist: flask>=2.3.0; extra == "web-flask"
Requires-Dist: flask-cors>=4.0.0; extra == "web-flask"
Provides-Extra: web-fastapi
Requires-Dist: fastapi>=0.104.0; extra == "web-fastapi"
Requires-Dist: uvicorn>=0.24.0; extra == "web-fastapi"
Provides-Extra: web
Requires-Dist: flask>=2.3.0; extra == "web"
Requires-Dist: flask-cors>=4.0.0; extra == "web"
Requires-Dist: fastapi>=0.104.0; extra == "web"
Requires-Dist: uvicorn>=0.24.0; extra == "web"
Provides-Extra: all
Requires-Dist: filterpy>=1.4.5; extra == "all"
Requires-Dist: lap>=0.4.0; extra == "all"
Requires-Dist: flask>=2.3.0; extra == "all"
Requires-Dist: flask-cors>=4.0.0; extra == "all"
Requires-Dist: fastapi>=0.104.0; extra == "all"
Requires-Dist: uvicorn>=0.24.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# VisionKit

**Professional Computer Vision Toolkit for Commercial Projects**

A comprehensive, production-ready library for object detection, tracking, and annotation - built as a reusable alternative to Supervision with enhanced features and innovations.

## 🚀 Features

### Core Detection Management
- **Immutable Detections**: Thread-safe, immutable operations
- **Efficient Caching**: Automatic caching of expensive computations (area, center, aspect ratio)
- **Rich Metadata**: Store custom data with detections
- **Flexible Indexing**: Natural slicing and filtering

### Advanced Tracking
- **Multiple Algorithms**: SORT, ByteTrack, BoT-SORT
- **Box Inflation**: Automatic inflation/deflation for robust tracking
- **Unified Interface**: Single API for all tracking methods

### Smart Zone Management
- **Multiple Trigger Types**: Center, bottom center, any corner, all corners
- **Zone Analytics**: Automatic counting and statistics
- **Batch Processing**: Efficient multi-zone operations

### Professional Annotators
- **Box Annotator**: Rounded corners, adaptive thickness, confidence-based styling
- **Label Annotator**: Multiple positions, shadows, auto-sizing
- **Trace Annotator**: Fading trails, smoothing, variable thickness
- **Zone Annotator**: Transparent fills, labels, statistics
- **Heatmap Annotator**: Real-time density maps with decay

### Flexible Filtering
- **Composable Filters**: Chain multiple filters
- **Built-in Filters**: Confidence, area, aspect ratio, class
- **Statistics Tracking**: Monitor filtering performance

### Video Processing
- **Multi-Backend Writers**: OpenCV or FFmpeg
- **Progress Callbacks**: Real-time progress monitoring
- **Frame Generators**: Memory-efficient frame iteration

## 📦 Installation

```bash
# From PyPI (once published)
pip install eye-cv

# Recommended: enable optional features
pip install "eye-cv[all]"      # tracking + smoothing + web

# Or pick what you need
pip install "eye-cv[track]"    # advanced tracking (ByteTrack/BoT-SORT)
pip install "eye-cv[smooth]"   # Kalman smoothing
pip install "eye-cv[web]"      # Flask + FastAPI helpers

# Local dev install
pip install -e .
```

## 📚 Examples

**20+ comprehensive examples** in the [`examples/`](examples/) directory:

```bash
cd examples
python 00_complete_showcase.py  # See ALL features in action!
python 01_quickstart.py         # 3-line usage
python 04_tracker_comparison.py # Compare SORT, ByteTrack, BoT-SORT
python 19_traffic_monitoring.py # Production traffic system
```

See [`examples/README.md`](examples/README.md) for the complete list.

## 💻 Quick Start

```python
import visionkit as vk
from ultralytics import YOLO

# Load model
model = YOLO("yolo11n.pt")

# Create tracker
tracker = vk.Tracker(
    tracker_type=vk.TrackerType.SORT,
    inflation_factor=1.5  # Better tracking
)

# Define zone
zone = vk.Zone(
    polygon=np.array([[100, 300], [200, 300], [200, 400], [100, 400]]),
    trigger_type=vk.ZoneType.CENTER
)

# Create annotators
box_ann = vk.BoxAnnotator()
label_ann = vk.LabelAnnotator()
trace_ann = vk.TraceAnnotator(fade_trail=True)

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

def process_frame(frame, frame_idx):
    # Detect
    results = model(frame)[0]
    detections = vk.Detections.from_yolo(results)
    
    # Track
    detections = tracker.update(detections)
    
    # Filter by zone
    zone_dets = zone.filter(detections)
    
    # Annotate
    annotated = box_ann.annotate(frame, detections)
    annotated = trace_ann.annotate(annotated, detections)
    annotated = label_ann.annotate(annotated, detections, labels)
    
    return annotated

video.process(process_frame)
```

## 🎯 Innovations Over Supervision

1. **Immutable Operations**: Thread-safe, prevents bugs
2. **Automatic Caching**: Faster repeated computations
3. **Box Inflation**: Better tracking without manual tuning
4. **Multi-Backend Video**: FFmpeg for better quality/speed
5. **Fading Trails**: Professional-looking traces
6. **Rounded Corners**: Modern box styling
7. **Heatmap Generation**: Built-in density visualization
8. **Filter Pipeline Stats**: Monitor performance
9. **Zone Analytics**: Built-in counting
10. **Better Type Hints**: Improved IDE support

## 📚 Documentation

### Detections
```python
# Create detections
detections = vk.Detections(
    xyxy=boxes,
    confidence=scores,
    class_id=classes
)

# Cached properties
areas = detections.area  # Fast, cached
centers = detections.center  # Fast, cached
ratios = detections.aspect_ratio

# Filtering
filtered = detections.filter(detections.confidence > 0.5)

# Immutable updates
updated = detections.with_confidence(new_scores)
```

### Tracking
```python
tracker = vk.Tracker(
    tracker_type=vk.TrackerType.SORT,
    max_age=30,
    min_hits=3,
    iou_threshold=0.3,
    inflation_factor=2.0  # Inflate boxes 2x for matching
)

tracked = tracker.update(detections)
```

### Zones
```python
zone = vk.Zone(
    polygon=polygon_points,
    trigger_type=vk.ZoneType.BOTTOM_CENTER,  # Use bottom of box
    name="Entrance"
)

# Check which detections are in zone
inside = zone.filter(detections)

# Get analytics
print(f"Current: {zone.current_count}, Total: {zone.total_count}")
```

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

filtered = pipeline(detections)
stats = pipeline.get_stats()
```

### Video Writing
```python
# OpenCV backend
writer = vk.VideoWriter(
    "output.mp4",
    fps=30,
    resolution=(1920, 1080),
    backend=vk.WriterBackend.OPENCV
)

# FFmpeg backend (better quality)
writer = vk.VideoWriter(
    "output.mp4",
    fps=30,
    resolution=(1920, 1080),
    backend=vk.WriterBackend.FFMPEG,
    crf=18,  # Quality (0-51, lower = better)
    preset="fast"  # Encoding speed
)
```

## 🎨 Color Palettes

```python
# Predefined palettes
colors = vk.PredefinedPalettes.bright()
colors = vk.PredefinedPalettes.pastel()
colors = vk.PredefinedPalettes.traffic()
colors = vk.PredefinedPalettes.monochrome(vk.Color(255, 0, 0), steps=10)

# Custom palette
custom = vk.ColorPalette([
    vk.Color(255, 0, 0),
    vk.Color(0, 255, 0),
    vk.Color.from_hex("#0000FF")
])
```

## 📄 License

MIT License - Free for commercial use

## 🤝 Contributing

This is a production library for your commercial projects. Extend and customize as needed.

## ⚡ Performance Tips

1. Use box inflation (1.5-2.0) for better tracking
2. Enable caching for repeated property access
3. Use FFmpeg backend for video writing
4. Batch zone operations with MultiZone
5. Use filter pipelines instead of manual filtering

## 📊 Example Output

See `example.py` for complete usage with all features.
# eye
