Upload 11 files

.gitattributes

@@ -1,35 +1,6 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.avi filter=lfs diff=lfs merge=lfs -text
+*.mov filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "Vehicle Speed Estimation and Counting System"
+version: 1.0.0
+date-released: 2024-12-06
+authors:
+  - family-names: "Gupta"
+    given-names: "Abhay"
+    affiliation: "Student ID: 0205CC221005"
+  - family-names: "Lakhera"
+    given-names: "Aditi"
+    affiliation: "Student ID: 0205CC221011"
+  - family-names: "Patel"
+    given-names: "Balraj"
+    affiliation: "Student ID: 0205CC221049"
+  - family-names: "Patel"
+    given-names: "Bhumika"
+    affiliation: "Student ID: 0205CC221050"
+repository-code: "https://huggingface.co/spaces/YOUR_USERNAME/vehicle-speed-estimation"
+keywords:
+  - computer-vision
+  - object-detection
+  - vehicle-tracking
+  - speed-estimation
+  - yolo
+  - opencv
+  - traffic-analysis
+license: MIT

CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing to Vehicle Speed Estimation System
+
+Thank you for your interest in contributing to this project!
+
+## Development Team
+
+This project was developed by:
+- Abhay Gupta (0205CC221005)
+- Aditi Lakhera (0205CC221011)
+- Balraj Patel (0205CC221049)
+- Bhumika Patel (0205CC221050)
+
+## How to Contribute
+
+### Reporting Issues
+
+If you find a bug or have a suggestion:
+
+1. Check if the issue already exists
+2. Create a new issue with:
+   - Clear description
+   - Steps to reproduce (for bugs)
+   - Expected vs actual behavior
+   - System information (OS, Python version, etc.)
+
+### Code Contributions
+
+1. **Fork the repository**
+2. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Make your changes**
+   - Follow the existing code style
+   - Add docstrings to new functions/classes
+   - Include type hints where appropriate
+   - Add error handling
+
+4. **Test your changes**
+   - Ensure existing functionality still works
+   - Test edge cases
+   - Verify error handling
+
+5. **Commit your changes**
+   ```bash
+   git commit -m "Add: brief description of changes"
+   ```
+
+6. **Push and create a Pull Request**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+## Code Style Guidelines
+
+### Python Style
+
+- Follow PEP 8 guidelines
+- Use meaningful variable names
+- Maximum line length: 100 characters
+- Use type hints for function parameters and returns
+
+### Documentation
+
+- Add docstrings to all functions and classes
+- Use Google-style docstrings
+- Include examples where helpful
+- Update README.md for new features
+
+### Example Docstring
+
+```python
+def calculate_speed(distance: float, time: float) -> float:
+    """
+    Calculate speed from distance and time.
+    
+    Args:
+        distance: Distance traveled in meters
+        time: Time elapsed in seconds
+        
+    Returns:
+        Speed in meters per second
+        
+    Raises:
+        ValueError: If time is zero or negative
+        
+    Example:
+        >>> calculate_speed(100, 10)
+        10.0
+    """
+    if time <= 0:
+        raise ValueError("Time must be positive")
+    return distance / time
+```
+
+## Project Structure
+
+```
+src/
+├── __init__.py          # Package initialization
+├── annotator.py         # Frame annotation
+├── speed_estimator.py   # Speed calculation
+├── view_transformer.py  # Perspective transformation
+└── exceptions.py        # Custom exceptions
+```
+
+## Testing
+
+Before submitting:
+
+1. Test with different video inputs
+2. Verify error handling works
+3. Check that configuration changes work
+4. Ensure Gradio interface functions properly
+
+## Questions?
+
+Feel free to open an issue for any questions or clarifications.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

DEPLOYMENT.md

@@ -0,0 +1,269 @@
+# Hugging Face Deployment Guide
+
+## 📋 Pre-Deployment Checklist
+
+Before uploading to Hugging Face Spaces, ensure:
+
+- [x] All code files are plagiarism-free with original implementations
+- [x] Student attribution is present in all files
+- [x] README.md has HF metadata header
+- [x] requirements.txt includes all dependencies
+- [x] .gitattributes is configured for Git LFS
+- [x] LICENSE file is present
+- [x] Error handling is comprehensive
+- [ ] Sample video is available (optional)
+
+## 🚀 Deployment Steps
+
+### 1. Create a New Space on Hugging Face
+
+1. Go to [Hugging Face Spaces](https://huggingface.co/new-space)
+2. Click "Create new Space"
+3. Fill in the details:
+   - **Space name**: `vehicle-speed-estimation` (or your choice)
+   - **License**: MIT
+   - **SDK**: Gradio
+   - **Visibility**: Public or Private
+
+### 2. Upload Files
+
+You can upload files via:
+
+#### Option A: Web Interface
+
+1. Navigate to your Space
+2. Click "Files and versions"
+3. Upload all files from the project directory:
+   ```
+   app.py
+   main.py
+   config.py
+   requirements.txt
+   README.md
+   LICENSE
+   CITATION.cff
+   CONTRIBUTING.md
+   .gitattributes
+   src/
+   ├── __init__.py
+   ├── annotator.py
+   ├── speed_estimator.py
+   ├── view_transformer.py
+   └── exceptions.py
+   ```
+
+#### Option B: Git Command Line
+
+```bash
+# Clone your Space repository
+git clone https://huggingface.co/spaces/YOUR_USERNAME/vehicle-speed-estimation
+cd vehicle-speed-estimation
+
+# Copy all files from the project
+cp -r /path/to/Vehicle-Speed-Estimation-and-Counting-YOLO-Supervision/* .
+
+# Add and commit
+git add .
+git commit -m "Initial commit: Vehicle Speed Estimation System"
+
+# Push to Hugging Face
+git push
+```
+
+### 3. Configure Git LFS for Large Files
+
+If you have model files or sample videos:
+
+```bash
+# Install Git LFS
+git lfs install
+
+# Track large files
+git lfs track "*.pt"
+git lfs track "*.mp4"
+
+# Add .gitattributes
+git add .gitattributes
+git commit -m "Configure Git LFS"
+git push
+```
+
+### 4. Wait for Build
+
+- Hugging Face will automatically build your Space
+- Check the "Logs" tab for build progress
+- Build typically takes 2-5 minutes
+
+### 5. Test Your Space
+
+Once built:
+1. Upload a test video
+2. Verify processing works
+3. Check output video quality
+4. Test error handling with invalid inputs
+
+## ⚙️ Configuration Notes
+
+### Model Files
+
+The YOLO model will be downloaded automatically on first run. If you want to include a pre-downloaded model:
+
+1. Download the model (e.g., `yolov8n.pt`)
+2. Create a `models/` directory
+3. Upload via Git LFS:
+   ```bash
+   git lfs track "models/*.pt"
+   git add models/yolov8n.pt
+   git commit -m "Add YOLO model"
+   git push
+   ```
+
+### Sample Videos
+
+To include example videos:
+
+1. Create a `data/` directory
+2. Add sample videos (keep under 100MB each)
+3. Upload via Git LFS:
+   ```bash
+   git lfs track "data/*.mp4"
+   git add data/vehicles.mp4
+   git commit -m "Add sample video"
+   git push
+   ```
+
+### Environment Variables
+
+If you need to set environment variables:
+
+1. Go to Space Settings
+2. Click "Variables and secrets"
+3. Add any required variables
+
+## 🐛 Troubleshooting
+
+### Build Fails
+
+**Issue**: Dependencies fail to install
+
+**Solution**: 
+- Check `requirements.txt` for version conflicts
+- Ensure all packages are available on PyPI
+- Try pinning specific versions
+
+### Out of Memory
+
+**Issue**: Space runs out of memory during processing
+
+**Solution**:
+- Upgrade to a better hardware tier (Settings → Hardware)
+- Reduce video resolution in preprocessing
+- Use smaller YOLO model (yolov8n instead of yolov8l)
+
+### Slow Processing
+
+**Issue**: Video processing is very slow
+
+**Solution**:
+- Upgrade to GPU hardware (Settings → Hardware)
+- Use smaller model for faster inference
+- Reduce input video resolution
+
+### Model Download Fails
+
+**Issue**: YOLO model fails to download
+
+**Solution**:
+- Pre-download model and include in repository
+- Check internet connectivity in Space
+- Use alternative model source
+
+## 📊 Hardware Recommendations
+
+| Video Resolution | Model Size | Recommended Hardware |
+|-----------------|------------|---------------------|
+| 720p | YOLOv8n | CPU Basic (Free) |
+| 1080p | YOLOv8n/s | CPU Upgrade |
+| 1080p | YOLOv8m/l | T4 Small (GPU) |
+| 4K | YOLOv8l | A10G Small (GPU) |
+
+## 🔒 Security Notes
+
+- Never commit API keys or secrets to the repository
+- Use Hugging Face Secrets for sensitive data
+- Validate all user inputs
+- Limit file upload sizes
+
+## 📈 Monitoring
+
+After deployment:
+
+1. Monitor Space usage in Settings
+2. Check error logs regularly
+3. Review user feedback
+4. Update dependencies periodically
+
+## 🔄 Updating Your Space
+
+To update after deployment:
+
+```bash
+# Make changes locally
+# Test thoroughly
+
+# Commit and push
+git add .
+git commit -m "Description of changes"
+git push
+
+# Space will automatically rebuild
+```
+
+## 📝 Post-Deployment
+
+1. Test all functionality
+2. Share Space link with team
+3. Add Space to your profile
+4. Consider writing a blog post about the project
+5. Share on social media
+
+## 🎓 Academic Use
+
+For academic submissions:
+
+1. Ensure all student names are visible in README
+2. Include enrollment numbers
+3. Add CITATION.cff for proper attribution
+4. Document all external libraries used
+5. Include technical documentation
+
+## ✅ Final Verification
+
+Before marking as complete:
+
+- [ ] Space builds successfully
+- [ ] Video upload works
+- [ ] Processing completes without errors
+- [ ] Output video is downloadable
+- [ ] Statistics are displayed correctly
+- [ ] Error messages are user-friendly
+- [ ] All student names are visible
+- [ ] README renders correctly
+- [ ] License is visible
+
+## 🎉 Success!
+
+Your Vehicle Speed Estimation System is now live on Hugging Face Spaces!
+
+Share your Space URL:
+```
+https://huggingface.co/spaces/YOUR_USERNAME/vehicle-speed-estimation
+```
+
+---
+
+**Developed by:**
+- Abhay Gupta (0205CC221005)
+- Aditi Lakhera (0205CC221011)
+- Balraj Patel (0205CC221049)
+- Bhumika Patel (0205CC221050)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Abhay Gupta, Aditi Lakhera, Balraj Patel, Bhumika Patel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

app.py

@@ -0,0 +1,329 @@
+"""
+Vehicle Speed Estimation and Counting - Gradio Interface
+=========================================================
+
+A real-time vehicle detection, tracking, counting, and speed estimation system
+using YOLO object detection and perspective transformation techniques.
+
+Authors:
+    - Abhay Gupta (0205CC221005)
+    - Aditi Lakhera (0205CC221011)
+    - Balraj Patel (0205CC221049)
+    - Bhumika Patel (0205CC221050)
+
+This application provides an interactive web interface for analyzing traffic videos
+and estimating vehicle speeds using computer vision techniques.
+"""
+
+import os
+import sys
+import tempfile
+import logging
+from pathlib import Path
+from typing import Optional, Tuple
+
+import gradio as gr
+import cv2
+import numpy as np
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Import application modules
+try:
+    from main import process_video
+    from config import VehicleDetectionConfig
+except ImportError as e:
+    logger.error(f"Failed to import required modules: {e}")
+    raise
+
+
+def validate_video_file(video_path: str) -> Tuple[bool, str]:
+    """
+    Validate uploaded video file.
+    
+    Args:
+        video_path: Path to video file
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if not video_path:
+        return False, "No video file provided"
+    
+    if not os.path.exists(video_path):
+        return False, f"Video file not found: {video_path}"
+    
+    # Check file size (limit to 100MB for HF Spaces)
+    file_size_mb = os.path.getsize(video_path) / (1024 * 1024)
+    if file_size_mb > 100:
+        return False, f"Video file too large ({file_size_mb:.1f}MB). Maximum size is 100MB"
+    
+    # Validate video can be opened
+    try:
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            return False, "Unable to open video file. Please ensure it's a valid video format"
+        
+        # Check if video has frames
+        ret, _ = cap.read()
+        cap.release()
+        
+        if not ret:
+            return False, "Video file appears to be empty or corrupted"
+            
+        return True, ""
+    except Exception as e:
+        return False, f"Error validating video: {str(e)}"
+
+
+def estimate_vehicle_speed(
+    video_file: str,
+    model_choice: str,
+    line_position: int,
+    confidence_threshold: float,
+    progress=gr.Progress()
+) -> Tuple[Optional[str], str]:
+    """
+    Process video and estimate vehicle speeds.
+    
+    Args:
+        video_file: Path to uploaded video
+        model_choice: YOLO model selection
+        line_position: Y-coordinate for counting line
+        confidence_threshold: Detection confidence threshold
+        progress: Gradio progress tracker
+        
+    Returns:
+        Tuple of (output_video_path, statistics_text)
+    """
+    try:
+        # Validate input
+        progress(0, desc="Validating video file...")
+        is_valid, error_msg = validate_video_file(video_file)
+        if not is_valid:
+            logger.error(f"Video validation failed: {error_msg}")
+            return None, f"❌ Error: {error_msg}"
+        
+        # Create temporary output file
+        output_path = tempfile.mktemp(suffix='.mp4')
+        
+        # Configure processing
+        progress(0.1, desc="Configuring detection parameters...")
+        config = VehicleDetectionConfig(
+            input_video=video_file,
+            output_video=output_path,
+            model_name=model_choice,
+            line_y=line_position,
+            confidence_threshold=confidence_threshold
+        )
+        
+        # Process video
+        progress(0.2, desc="Processing video (this may take a few minutes)...")
+        logger.info(f"Starting video processing: {video_file}")
+        
+        try:
+            stats = process_video(
+                config=config,
+                progress_callback=lambda p: progress(0.2 + p * 0.7, desc=f"Processing... {int(p*100)}%")
+            )
+            
+            progress(0.95, desc="Finalizing output...")
+            
+            # Format statistics
+            stats_text = f"""
+## 📊 Processing Results
+
+### Vehicle Count Statistics
+- **Total Vehicles Detected:** {stats['total_count']}
+- **Vehicles Entering (In):** {stats['in_count']}
+- **Vehicles Exiting (Out):** {stats['out_count']}
+
+### Speed Analysis
+- **Average Speed:** {stats['avg_speed']:.1f} km/h
+- **Maximum Speed:** {stats['max_speed']:.1f} km/h
+- **Minimum Speed:** {stats['min_speed']:.1f} km/h
+
+### Processing Information
+- **Frames Processed:** {stats['frames_processed']}
+- **Processing Time:** {stats['processing_time']:.2f} seconds
+- **Model Used:** {model_choice}
+- **Detection Confidence:** {confidence_threshold:.2f}
+
+✅ **Processing completed successfully!**
+"""
+            
+            progress(1.0, desc="Complete!")
+            logger.info("Video processing completed successfully")
+            return output_path, stats_text
+            
+        except Exception as e:
+            logger.error(f"Error during video processing: {e}", exc_info=True)
+            return None, f"❌ **Processing Error:** {str(e)}\n\nPlease try with different settings or a different video."
+    
+    except Exception as e:
+        logger.error(f"Unexpected error in estimate_vehicle_speed: {e}", exc_info=True)
+        return None, f"❌ **Unexpected Error:** {str(e)}"
+
+
+def create_demo_interface() -> gr.Blocks:
+    """
+    Create Gradio interface for vehicle speed estimation.
+    
+    Returns:
+        Gradio Blocks interface
+    """
+    with gr.Blocks(
+        title="Vehicle Speed Estimation & Counting",
+        theme=gr.themes.Soft()
+    ) as demo:
+        
+        gr.Markdown("""
+# 🚗 Vehicle Speed Estimation & Counting System
+
+An intelligent traffic analysis system that detects, tracks, counts, and estimates the speed of vehicles in video footage using advanced computer vision techniques.
+
+### 🎯 Features
+- **Real-time Vehicle Detection** using YOLO
+- **Multi-Object Tracking** with ByteTrack
+- **Accurate Speed Estimation** via perspective transformation
+- **Vehicle Counting** with configurable detection zones
+
+### 👥 Developed By
+- **Abhay Gupta** (0205CC221005)
+- **Aditi Lakhera** (0205CC221011)
+- **Balraj Patel** (0205CC221049)
+- **Bhumika Patel** (0205CC221050)
+
+---
+""")
+        
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("### 📤 Input Configuration")
+                
+                video_input = gr.Video(
+                    label="Upload Traffic Video",
+                    format="mp4"
+                )
+                
+                with gr.Accordion("⚙️ Advanced Settings", open=False):
+                    model_choice = gr.Dropdown(
+                        choices=["yolov8n", "yolov8s", "yolov8m", "yolov8l"],
+                        value="yolov8n",
+                        label="YOLO Model",
+                        info="Larger models are more accurate but slower"
+                    )
+                    
+                    line_position = gr.Slider(
+                        minimum=100,
+                        maximum=1000,
+                        value=480,
+                        step=10,
+                        label="Counting Line Position (Y-coordinate)",
+                        info="Vertical position of the vehicle counting line"
+                    )
+                    
+                    confidence_threshold = gr.Slider(
+                        minimum=0.1,
+                        maximum=0.9,
+                        value=0.3,
+                        step=0.05,
+                        label="Detection Confidence Threshold",
+                        info="Higher values reduce false positives"
+                    )
+                
+                process_btn = gr.Button(
+                    "🚀 Process Video",
+                    variant="primary",
+                    size="lg"
+                )
+                
+                gr.Markdown("""
+### 📋 Instructions
+1. Upload a traffic video (MP4 format, max 100MB)
+2. Adjust settings if needed (optional)
+3. Click "Process Video" and wait for results
+4. Download the annotated video with speed estimates
+
+### 💡 Tips
+- Use videos with clear vehicle visibility
+- Ensure consistent camera angle
+- Better lighting improves detection accuracy
+""")
+            
+            with gr.Column(scale=1):
+                gr.Markdown("### 📥 Output Results")
+                
+                video_output = gr.Video(
+                    label="Processed Video with Annotations"
+                )
+                
+                stats_output = gr.Markdown(
+                    label="Statistics",
+                    value="*Processing results will appear here...*"
+                )
+        
+        # Example videos section
+        gr.Markdown("""
+---
+### 🎬 Example Videos
+Upload your own traffic video or use sample footage to test the system.
+""")
+        
+        gr.Examples(
+            examples=[
+                ["./data/vehicles.mp4", "yolov8n", 480, 0.3],
+            ],
+            inputs=[video_input, model_choice, line_position, confidence_threshold],
+            outputs=[video_output, stats_output],
+            fn=estimate_vehicle_speed,
+            cache_examples=False,
+            label="Sample Videos"
+        )
+        
+        # Connect processing function
+        process_btn.click(
+            fn=estimate_vehicle_speed,
+            inputs=[video_input, model_choice, line_position, confidence_threshold],
+            outputs=[video_output, stats_output]
+        )
+        
+        gr.Markdown("""
+---
+### 🔬 Technical Details
+
+This system uses:
+- **YOLO (You Only Look Once)** for real-time object detection
+- **ByteTrack** for multi-object tracking across frames
+- **Perspective Transformation** for accurate speed calculation
+- **OpenCV** for video processing and computer vision operations
+
+### 📚 References
+- [Ultralytics YOLO](https://github.com/ultralytics/ultralytics)
+- [Supervision Library](https://github.com/roboflow/supervision)
+- [OpenCV](https://opencv.org/)
+
+### 📄 License
+MIT License - See LICENSE file for details
+""")
+    
+    return demo
+
+
+if __name__ == "__main__":
+    try:
+        logger.info("Starting Vehicle Speed Estimation application...")
+        demo = create_demo_interface()
+        demo.launch(
+            server_name="0.0.0.0",
+            server_port=7860,
+            share=False
+        )
+    except Exception as e:
+        logger.error(f"Failed to launch application: {e}", exc_info=True)
+        sys.exit(1)

config.py

@@ -0,0 +1,205 @@
+"""
+Vehicle Detection Configuration Module
+=======================================
+
+Manages configuration settings for vehicle detection, tracking, and speed estimation.
+
+Authors:
+    - Abhay Gupta (0205CC221005)
+    - Aditi Lakhera (0205CC221011)
+    - Balraj Patel (0205CC221049)
+    - Bhumika Patel (0205CC221050)
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import List, Tuple, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class VehicleDetectionConfig:
+    """
+    Configuration class for vehicle detection and speed estimation system.
+    
+    This class encapsulates all configuration parameters needed for the
+    vehicle detection pipeline, including video paths, model settings,
+    detection zones, and perspective transformation parameters.
+    """
+    
+    # Video Configuration
+    input_video: str = "./data/vehicles.mp4"
+    output_video: str = "./data/vehicles_output.mp4"
+    
+    # Model Configuration
+    model_name: str = "yolov8n"
+    model_path: Optional[str] = None
+    confidence_threshold: float = 0.3
+    iou_threshold: float = 0.7
+    
+    # Detection Zone Configuration
+    line_y: int = 480
+    line_offset: int = 55
+    crossing_threshold: int = 1
+    
+    # Perspective Transformation Configuration
+    # Source points define the region in the original video frame
+    source_points: List[List[int]] = field(default_factory=lambda: [
+        [450, 300],   # Top-left
+        [860, 300],   # Top-right
+        [1900, 720],  # Bottom-right
+        [-660, 720]   # Bottom-left
+    ])
+    
+    # Target points define the transformed top-down view dimensions (in meters)
+    target_width_meters: float = 25.0
+    target_height_meters: float = 100.0
+    
+    # Display Configuration
+    window_name: str = "Vehicle Speed Estimation - Traffic Analysis"
+    display_enabled: bool = True
+    
+    # Annotation Configuration
+    enable_boxes: bool = True
+    enable_labels: bool = True
+    enable_traces: bool = True
+    enable_line_zones: bool = True
+    trace_length: int = 20
+    
+    # Speed Estimation Configuration
+    speed_history_seconds: int = 1
+    speed_unit: str = "km/h"  # Options: "km/h", "mph", "m/s"
+    
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        self._validate_config()
+        self._setup_model_path()
+    
+    def _validate_config(self) -> None:
+        """
+        Validate configuration parameters.
+        
+        Raises:
+            ValueError: If configuration parameters are invalid
+        """
+        # Validate video paths
+        if not self.input_video:
+            raise ValueError("Input video path cannot be empty")
+        
+        # Validate model configuration
+        if not 0.0 <= self.confidence_threshold <= 1.0:
+            raise ValueError(f"Confidence threshold must be between 0 and 1, got {self.confidence_threshold}")
+        
+        if not 0.0 <= self.iou_threshold <= 1.0:
+            raise ValueError(f"IOU threshold must be between 0 and 1, got {self.iou_threshold}")
+        
+        # Validate detection zone
+        if self.line_y < 0:
+            raise ValueError(f"Line Y position must be positive, got {self.line_y}")
+        
+        if self.line_offset < 0:
+            raise ValueError(f"Line offset must be positive, got {self.line_offset}")
+        
+        # Validate perspective transformation
+        if len(self.source_points) != 4:
+            raise ValueError(f"Source points must contain exactly 4 points, got {len(self.source_points)}")
+        
+        for i, point in enumerate(self.source_points):
+            if len(point) != 2:
+                raise ValueError(f"Source point {i} must have 2 coordinates, got {len(point)}")
+        
+        if self.target_width_meters <= 0 or self.target_height_meters <= 0:
+            raise ValueError("Target dimensions must be positive")
+        
+        # Validate speed configuration
+        if self.speed_unit not in ["km/h", "mph", "m/s"]:
+            raise ValueError(f"Invalid speed unit: {self.speed_unit}. Must be 'km/h', 'mph', or 'm/s'")
+        
+        logger.info("Configuration validation successful")
+    
+    def _setup_model_path(self) -> None:
+        """Set up the model path based on model name."""
+        if self.model_path is None:
+            # Try to find model in models directory
+            model_dir = "./models"
+            potential_paths = [
+                f"{model_dir}/{self.model_name}.pt",
+                f"{model_dir}/VisDrone_YOLO_x2.pt",  # Custom trained model
+                self.model_name  # Let ultralytics download from hub
+            ]
+            
+            for path in potential_paths:
+                if os.path.exists(path):
+                    self.model_path = path
+                    logger.info(f"Using model from: {path}")
+                    return
+            
+            # Use model name directly (will be downloaded by ultralytics)
+            self.model_path = self.model_name
+            logger.info(f"Model will be downloaded: {self.model_name}")
+    
+    @property
+    def target_points(self) -> List[List[float]]:
+        """
+        Generate target points for perspective transformation.
+        
+        Returns:
+            List of 4 points defining the target perspective in meters
+        """
+        w, h = self.target_width_meters, self.target_height_meters
+        return [
+            [0, 0],      # Top-left
+            [w, 0],      # Top-right
+            [w, h],      # Bottom-right
+            [0, h]       # Bottom-left
+        ]
+    
+    def get_speed_conversion_factor(self) -> float:
+        """
+        Get conversion factor for speed unit.
+        
+        Returns:
+            Conversion factor from m/s to desired unit
+        """
+        conversions = {
+            "km/h": 3.6,
+            "mph": 2.23694,
+            "m/s": 1.0
+        }
+        return conversions[self.speed_unit]
+    
+    def to_dict(self) -> dict:
+        """
+        Convert configuration to dictionary.
+        
+        Returns:
+            Dictionary representation of configuration
+        """
+        return {
+            "input_video": self.input_video,
+            "output_video": self.output_video,
+            "model_name": self.model_name,
+            "model_path": self.model_path,
+            "confidence_threshold": self.confidence_threshold,
+            "line_y": self.line_y,
+            "speed_unit": self.speed_unit,
+        }
+    
+    def __repr__(self) -> str:
+        """String representation of configuration."""
+        return f"VehicleDetectionConfig(model={self.model_name}, input={self.input_video})"
+
+
+# Default configuration instance for backward compatibility
+DEFAULT_CONFIG = VehicleDetectionConfig()
+
+# Export commonly used configuration values
+IN_VIDEO_PATH = DEFAULT_CONFIG.input_video
+OUT_VIDEO_PATH = DEFAULT_CONFIG.output_video
+YOLO_MODEL_PATH = DEFAULT_CONFIG.model_path
+LINE_Y = DEFAULT_CONFIG.line_y
+SOURCE_POINTS = DEFAULT_CONFIG.source_points
+TARGET_POINTS = DEFAULT_CONFIG.target_points
+WINDOW_NAME = DEFAULT_CONFIG.window_name

main.py

@@ -0,0 +1,417 @@
+"""
+Vehicle Detection, Tracking, Counting, and Speed Estimation System
+===================================================================
+
+A comprehensive computer vision pipeline for analyzing traffic videos,
+detecting vehicles, tracking their movement, counting them, and estimating
+their speeds using YOLO object detection and perspective transformation.
+
+Authors:
+    - Abhay Gupta (0205CC221005)
+    - Aditi Lakhera (0205CC221011)
+    - Balraj Patel (0205CC221049)
+    - Bhumika Patel (0205CC221050)
+
+Technical Approach:
+    - YOLO for real-time object detection
+    - ByteTrack for multi-object tracking
+    - Perspective transformation for speed calculation
+    - Line zones for vehicle counting
+"""
+
+import sys
+import logging
+from pathlib import Path
+from typing import Dict, Optional, Callable
+from time import time
+
+import cv2
+import numpy as np
+import supervision as sv
+from ultralytics import YOLO
+
+from src import FrameAnnotator, VehicleSpeedEstimator, PerspectiveTransformer
+from src.exceptions import (
+    VideoProcessingError,
+    ModelLoadError,
+    ConfigurationError
+)
+from config import VehicleDetectionConfig
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+class VehicleDetectionPipeline:
+    """
+    Main pipeline for vehicle detection, tracking, counting, and speed estimation.
+    
+    This class orchestrates the entire processing workflow, from loading the model
+    to processing each frame and generating the output video.
+    """
+    
+    def __init__(self, config: VehicleDetectionConfig):
+        """
+        Initialize the detection pipeline.
+        
+        Args:
+            config: Configuration object with all parameters
+            
+        Raises:
+            ModelLoadError: If model cannot be loaded
+            ConfigurationError: If configuration is invalid
+        """
+        self.config = config
+        self.model = None
+        self.tracker = None
+        self.line_zone = None
+        self.speed_estimator = None
+        self.annotator = None
+        self.video_info = None
+        
+        logger.info(f"Initializing pipeline with config: {config}")
+        self._initialize_components()
+    
+    def _initialize_components(self) -> None:
+        """Initialize all pipeline components."""
+        try:
+            # Load YOLO model
+            logger.info(f"Loading YOLO model: {self.config.model_path}")
+            self.model = YOLO(self.config.model_path)
+            self.model.conf = self.config.confidence_threshold
+            self.model.iou = self.config.iou_threshold
+            logger.info("Model loaded successfully")
+            
+        except Exception as e:
+            logger.error(f"Failed to load model: {e}")
+            raise ModelLoadError(f"Could not load YOLO model from {self.config.model_path}: {e}")
+    
+    def _setup_video_components(self, video_path: str) -> None:
+        """
+        Set up video-specific components.
+        
+        Args:
+            video_path: Path to input video
+            
+        Raises:
+            VideoProcessingError: If video cannot be opened
+        """
+        try:
+            # Get video information
+            self.video_info = sv.VideoInfo.from_video_path(video_path)
+            logger.info(f"Video info: {self.video_info.width}x{self.video_info.height} @ {self.video_info.fps}fps")
+            
+            # Initialize ByteTrack tracker
+            self.tracker = sv.ByteTrack(
+                frame_rate=self.video_info.fps,
+                track_activation_threshold=self.config.confidence_threshold
+            )
+            logger.info("Tracker initialized")
+            
+            # Set up counting line zone
+            line_start = sv.Point(
+                x=self.config.line_offset,
+                y=self.config.line_y
+            )
+            line_end = sv.Point(
+                x=self.video_info.width - self.config.line_offset,
+                y=self.config.line_y
+            )
+            
+            self.line_zone = sv.LineZone(
+                start=line_start,
+                end=line_end,
+                triggering_anchors=(sv.Position.BOTTOM_CENTER,)
+            )
+            logger.info(f"Line zone created at y={self.config.line_y}")
+            
+            # Initialize perspective transformer
+            source_pts = np.array(self.config.source_points, dtype=np.float32)
+            target_pts = np.array(self.config.target_points, dtype=np.float32)
+            
+            transformer = PerspectiveTransformer(
+                source_points=source_pts,
+                target_points=target_pts
+            )
+            logger.info("Perspective transformer initialized")
+            
+            # Initialize speed estimator
+            self.speed_estimator = VehicleSpeedEstimator(
+                fps=self.video_info.fps,
+                transformer=transformer,
+                history_duration=self.config.speed_history_seconds,
+                speed_unit=self.config.speed_unit
+            )
+            logger.info("Speed estimator initialized")
+            
+            # Initialize frame annotator
+            self.annotator = FrameAnnotator(
+                video_resolution=(self.video_info.width, self.video_info.height),
+                show_boxes=self.config.enable_boxes,
+                show_labels=self.config.enable_labels,
+                show_traces=self.config.enable_traces,
+                show_line_zones=self.config.enable_line_zones,
+                trace_length=self.config.trace_length,
+                zone_polygon=source_pts
+            )
+            logger.info("Frame annotator initialized")
+            
+        except Exception as e:
+            logger.error(f"Failed to setup video components: {e}")
+            raise VideoProcessingError(f"Error setting up video processing: {e}")
+    
+    def _process_single_frame(self, frame: np.ndarray) -> tuple:
+        """
+        Process a single video frame.
+        
+        Args:
+            frame: Input video frame
+            
+        Returns:
+            Tuple of (annotated_frame, detections)
+        """
+        # Run YOLO detection
+        results = self.model(frame, verbose=False)[0]
+        detections = sv.Detections.from_ultralytics(results)
+        
+        # Update tracker
+        detections = self.tracker.update_with_detections(detections)
+        
+        # Trigger line zone counting
+        self.line_zone.trigger(detections)
+        
+        # Estimate speeds
+        detections = self.speed_estimator.estimate(detections)
+        
+        # Generate labels
+        labels = self._create_labels(detections)
+        
+        # Annotate frame
+        annotated_frame = self.annotator.draw_annotations(
+            frame=frame,
+            detections=detections,
+            labels=labels,
+            line_zones=[self.line_zone]
+        )
+        
+        return annotated_frame, detections
+    
+    def _create_labels(self, detections: sv.Detections) -> list:
+        """
+        Create display labels for detected vehicles.
+        
+        Args:
+            detections: Detection results
+            
+        Returns:
+            List of label strings
+        """
+        labels = []
+        
+        if not hasattr(detections, 'tracker_id') or detections.tracker_id is None:
+            return labels
+        
+        for idx, tracker_id in enumerate(detections.tracker_id):
+            # Get class name
+            class_name = "Vehicle"
+            if "class_name" in detections.data:
+                class_name = detections.data["class_name"][idx]
+            
+            # Get speed
+            speed_text = ""
+            if "speed" in detections.data:
+                speed = detections.data["speed"][idx]
+                if speed > 0:
+                    speed_text = f" {speed:.0f}{self.config.speed_unit}"
+            
+            # Create label
+            label = f"{class_name} #{tracker_id}{speed_text}"
+            labels.append(label)
+        
+        return labels
+    
+    def process_video(
+        self,
+        progress_callback: Optional[Callable[[float], None]] = None
+    ) -> Dict:
+        """
+        Process the entire video.
+        
+        Args:
+            progress_callback: Optional callback for progress updates
+            
+        Returns:
+            Dictionary with processing statistics
+            
+        Raises:
+            VideoProcessingError: If video processing fails
+        """
+        start_time = time()
+        
+        try:
+            # Validate input video
+            if not Path(self.config.input_video).exists():
+                raise VideoProcessingError(f"Input video not found: {self.config.input_video}")
+            
+            # Setup components
+            self._setup_video_components(self.config.input_video)
+            
+            # Create output directory if needed
+            output_path = Path(self.config.output_video)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            # Initialize statistics
+            frame_count = 0
+            total_frames = self.video_info.total_frames or 0
+            all_speeds = []
+            
+            # Setup display window if enabled
+            if self.config.display_enabled:
+                cv2.namedWindow(self.config.window_name, cv2.WINDOW_NORMAL)
+                cv2.resizeWindow(
+                    self.config.window_name,
+                    self.video_info.width,
+                    self.video_info.height
+                )
+            
+            # Process video
+            logger.info("Starting video processing...")
+            frame_generator = sv.get_video_frames_generator(self.config.input_video)
+            
+            with sv.VideoSink(self.config.output_video, self.video_info) as sink:
+                for frame in frame_generator:
+                    try:
+                        # Process frame
+                        annotated_frame, detections = self._process_single_frame(frame)
+                        
+                        # Collect speed statistics
+                        if "speed" in detections.data:
+                            speeds = detections.data["speed"]
+                            all_speeds.extend([s for s in speeds if s > 0])
+                        
+                        # Write to output
+                        sink.write_frame(annotated_frame)
+                        
+                        # Display if enabled
+                        if self.config.display_enabled:
+                            cv2.imshow(self.config.window_name, annotated_frame)
+                            
+                            # Check for quit
+                            if cv2.waitKey(1) & 0xFF == ord('q'):
+                                logger.info("Processing interrupted by user")
+                                break
+                            
+                            # Check if window was closed
+                            if cv2.getWindowProperty(
+                                self.config.window_name,
+                                cv2.WND_PROP_VISIBLE
+                            ) < 1:
+                                logger.info("Window closed by user")
+                                break
+                        
+                        # Update progress
+                        frame_count += 1
+                        if progress_callback and total_frames > 0:
+                            progress = frame_count / total_frames
+                            progress_callback(progress)
+                    
+                    except Exception as e:
+                        logger.warning(f"Error processing frame {frame_count}: {e}")
+                        continue
+            
+            # Cleanup
+            if self.config.display_enabled:
+                cv2.destroyAllWindows()
+            
+            # Calculate statistics
+            processing_time = time() - start_time
+            stats = {
+                'total_count': self.line_zone.in_count + self.line_zone.out_count,
+                'in_count': self.line_zone.in_count,
+                'out_count': self.line_zone.out_count,
+                'avg_speed': np.mean(all_speeds) if all_speeds else 0.0,
+                'max_speed': np.max(all_speeds) if all_speeds else 0.0,
+                'min_speed': np.min(all_speeds) if all_speeds else 0.0,
+                'frames_processed': frame_count,
+                'processing_time': processing_time,
+                'fps': frame_count / processing_time if processing_time > 0 else 0
+            }
+            
+            logger.info(f"Processing complete: {frame_count} frames in {processing_time:.2f}s")
+            logger.info(f"Vehicles counted: {stats['total_count']} (In: {stats['in_count']}, Out: {stats['out_count']})")
+            
+            return stats
+            
+        except Exception as e:
+            logger.error(f"Video processing failed: {e}", exc_info=True)
+            raise VideoProcessingError(f"Failed to process video: {e}")
+
+
+def process_video(
+    config: VehicleDetectionConfig,
+    progress_callback: Optional[Callable[[float], None]] = None
+) -> Dict:
+    """
+    Convenience function to process a video with given configuration.
+    
+    Args:
+        config: Configuration object
+        progress_callback: Optional progress callback
+        
+    Returns:
+        Processing statistics dictionary
+    """
+    pipeline = VehicleDetectionPipeline(config)
+    return pipeline.process_video(progress_callback)
+
+
+def main():
+    """Main entry point for CLI usage."""
+    try:
+        logger.info("=" * 60)
+        logger.info("Vehicle Speed Estimation & Counting System")
+        logger.info("=" * 60)
+        
+        # Load configuration
+        config = VehicleDetectionConfig()
+        logger.info(f"Configuration: {config}")
+        
+        # Process video
+        stats = process_video(config)
+        
+        # Display results
+        print("\n" + "=" * 60)
+        print("PROCESSING RESULTS")
+        print("=" * 60)
+        print(f"Output saved to: {config.output_video}")
+        print(f"\nVehicle Count:")
+        print(f"  Total: {stats['total_count']}")
+        print(f"  In: {stats['in_count']}")
+        print(f"  Out: {stats['out_count']}")
+        print(f"\nSpeed Statistics ({config.speed_unit}):")
+        print(f"  Average: {stats['avg_speed']:.1f}")
+        print(f"  Maximum: {stats['max_speed']:.1f}")
+        print(f"  Minimum: {stats['min_speed']:.1f}")
+        print(f"\nProcessing Info:")
+        print(f"  Frames: {stats['frames_processed']}")
+        print(f"  Time: {stats['processing_time']:.2f}s")
+        print(f"  FPS: {stats['fps']:.1f}")
+        print("=" * 60)
+        
+        return 0
+        
+    except KeyboardInterrupt:
+        logger.info("Processing interrupted by user")
+        return 1
+    except Exception as e:
+        logger.error(f"Fatal error: {e}", exc_info=True)
+        print(f"\n❌ Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

requirements.txt

@@ -0,0 +1,10 @@
+# Python dependencies
+gradio==4.44.0
+numpy==2.3.1
+opencv-contrib-python==4.11.0.86
+opencv-python==4.11.0.86
+supervision==0.26.0
+ultralytics==8.3.161
+
+# Additional utilities
+Pillow>=10.0.0