eye-cv 1.0.0

Eye - Simple & Powerful Computer Vision. Auto-convert, smart tracking, jitter reduction.

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

# 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/ directory:

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 for the complete list.

💻 Quick Start

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

# 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

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

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

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

# 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

# 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