CoolFace
Apppublic

ddlsandeep/cricket-video-annotation

sourceHugging Faceupdated 1y agoView on Hugging Face
0likes
App README

🏏 Cricket Video Annotation Project

A comprehensive web-based video annotation system for cricket analysis, featuring video frame extraction, web-based annotation tools, and YOLO-compatible dataset export.

📋 Table of Contents

✨ Features

🎥 Video Processing

  • —Video Upload: Support for common video formats (MP4, AVI, MOV, etc.)
  • —Frame Extraction: Extract frames with customizable intervals (every Nth frame)
  • —High-Quality Output: JPEG frames with 95% quality preservation
  • —Timestamp Preservation: Frame naming includes temporal information

🖊️ Annotation Tools

  • —Web-Based Annotator: Integrated annotation interface
  • —Multiple Classes: Cricket Ball (0), Bat (1), Player (2)
  • —Bounding Box Drawing: Click and drag to create annotations
  • —Frame Navigation: Arrow key navigation between frames
  • —Real-time Updates: Instant annotation saving and loading

📊 Export & Dataset Generation

  • —YOLO v8-v10 Compatible: Ready-to-use dataset format
  • —Train/Val Split: Automatic dataset splitting (configurable ratio)
  • —Multiple Export Formats:
  • —Complete YOLO dataset (ZIP)
  • —Individual frame annotations
  • —JSON format for detailed analysis
  • —Dataset Statistics: Comprehensive annotation metrics

🔧 Technical Features

  • —Python 3.12 Compatible: Modern Python support
  • —Flask Web Framework: Lightweight and fast
  • —OpenCV Integration: Robust video processing
  • —Cross-Platform: Windows, macOS, Linux support
  • —Responsive UI: Modern, mobile-friendly interface

💻 System Requirements

Minimum Requirements

  • —Python: 3.8 or higher (3.12 recommended)
  • —RAM: 4GB minimum, 8GB recommended
  • —Storage: 1GB free space minimum
  • —Browser: Modern browser (Chrome, Firefox, Safari, Edge)

Recommended Requirements

  • —Python: 3.12
  • —RAM: 16GB for large video processing
  • —Storage: 10GB+ for video datasets
  • —GPU: Optional, for faster video processing

🚀 Installation

1. Clone the Repository

bash
git clone <repository-url>
cd Cricket

2. Create Virtual Environment (Recommended)

bash
# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

bash
pip install -r requirements.txt

4. Verify Installation

bash
python test_flow.py

⚡ Quick Start

1. Start the Application

bash
python app.py

2. Access the Web Interface

Open your browser and navigate to: http://localhost:5000

3. Upload a Video

  1. 1.Click "Select video" to choose your cricket video file
  2. 2.Set frame extraction interval (default: every frame)
  3. 3.Click "Convert to frames"

4. Annotate Frames

  1. 1.Click "🖊️ Web Annotator" button
  2. 2.Select a frame to annotate
  3. 3.Draw bounding boxes for cricket objects
  4. 4.Navigate between frames using arrow keys

5. Export Dataset

  1. 1.Use export buttons to download YOLO-compatible dataset
  2. 2.Choose train/validation split ratio
  3. 3.Download complete dataset ZIP file

📖 Usage Guide

Video Upload and Processing

Supported Video Formats
  • —MP4 (recommended)
  • —AVI
  • —MOV
  • —MKV
  • —WebM
Frame Extraction Options
  • —Every Frame: Extract all frames (default)
  • —Every Nth Frame: Extract every N frames (e.g., every 5th frame)
  • —Custom Interval: Set specific frame extraction rate
Frame Naming Convention
{video_name}_frame_{frame_number:06d}_{timestamp_nanoseconds}.jpg

Example: cricket_match_frame_000123_1234567890.jpg

Annotation Interface

Getting Started
  1. 1.Access Annotator: Click "🖊️ Web Annotator" from results page
  2. 2.Select Frame: Click on any frame thumbnail to open annotation view
  3. 3.Draw Boxes: Click and drag to create bounding boxes
  4. 4.Class Selection: Choose object class (Ball, Bat, Player)
  5. 5.Save: Annotations are automatically saved
Keyboard Shortcuts
  • —← → Arrow Keys: Navigate between frames
  • —Delete: Remove selected annotation box
  • —Escape: Cancel current drawing operation
Annotation Classes
Class IDClass NameDescription
0Cricket BallThe cricket ball in play
1BatCricket bat
2PlayerCricket player/person

Dataset Export

YOLO Dataset Format

The system generates YOLO v8-v10 compatible datasets with the following structure:

dataset/
├── images/
│   ├── train/          # Training images
│   └── val/            # Validation images
├── labels/
│   ├── train/          # Training labels
│   └── val/            # Validation labels
├── data.yaml           # YOLO configuration
└── README.txt         # Dataset documentation
Export Options
  1. 1.Complete Dataset: Full YOLO-compatible ZIP file
  2. 2.Legacy Format: Single directory with all images
  3. 3.Individual Frames: Export annotations per frame
  4. 4.JSON Format: Detailed annotation data
Training Split Configuration
  • —Default: 80% training, 20% validation
  • —Customizable: Set train/val ratio via URL parameter
  • —Random Split: Ensures unbiased dataset distribution

📁 Project Structure

Cricket/
├── app.py                 # Main Flask application
├── annotator.py           # Standalone annotation tool
├── label.py              # LabelImg integration
├── test_flow.py          # Project testing script
├── requirements.txt      # Python dependencies
├── classes.txt           # Class definitions
├── README.md            # This file
├── templates/           # HTML templates
│   ├── index.html       # Main upload page
│   ├── result.html      # Results display
│   ├── annotator.html   # Annotation overview
│   └── frame_annotator.html # Single frame annotation
├── static/              # Static assets
│   └── styles.css       # CSS styling
├── uploads/             # Uploaded videos (auto-created)
├── frames/              # Extracted frames (auto-created)
└── __pycache__/         # Python cache (auto-created)

🔌 API Documentation

Main Application Routes

Video Upload
  • —POST /upload
  • —Upload video file for processing
  • —Parameters: video (file), every_nth (integer)
Frame Management
  • —GET /frames/<job_id>/<filename>
  • —Serve frame images
  • —GET /open-folder/<job_id>
  • —Open frames directory in file explorer
Annotation Routes
  • —GET /annotator/<job_id>
  • —Main annotation interface
  • —GET /annotator/<job_id>/frame/<frame_name>
  • —Single frame annotation view

Annotation API Endpoints

Annotations Management
  • —GET /annotator/<job_id>/api/annotations/<frame_name>
  • —Get annotations for a frame
  • —POST /annotator/<job_id>/api/annotations/<frame_name>
  • —Add new annotation
  • —PUT /annotator/<job_id>/api/annotations/<frame_name>/<annotation_id>
  • —Update annotation
  • —DELETE /annotator/<job_id>/api/annotations/<frame_name>/<annotation_id>
  • —Delete annotation
Export Functions
  • —GET /annotator/<job_id>/api/export/<frame_name>
  • —Export single frame annotations
  • —GET /annotator/<job_id>/api/export_all
  • —Export all annotations
  • —GET /annotator/<job_id>/api/download_dataset
  • —Download complete YOLO dataset
Statistics and Navigation
  • —GET /annotator/<job_id>/api/stats
  • —Get annotation statistics
  • —GET /annotator/<job_id>/api/frames
  • —Get list of all frames
  • —GET /annotator/<job_id>/api/frames/<frame_name>/next
  • —Get next frame
  • —GET /annotator/<job_id>/api/frames/<frame_name>/prev
  • —Get previous frame

🛠️ Troubleshooting

Common Issues

Port Already in Use
bash
# Check what's using the port
netstat -ano | findstr :5000  # Windows
lsof -i :5000                 # macOS/Linux

# Change port in app.py
app.run(host="0.0.0.0", port=5001, debug=True)
Video Processing Errors
  • —Unsupported Format: Convert video to MP4 using FFmpeg
  • —Large File Size: Use frame extraction to reduce processing time
  • —Memory Issues: Increase system RAM or process smaller videos
Annotation Interface Issues
  • —Browser Compatibility: Use Chrome, Firefox, or Safari
  • —JavaScript Errors: Clear browser cache and reload
  • —Slow Performance: Close other browser tabs
Installation Problems
bash
# Update pip
python -m pip install --upgrade pip

# Install with verbose output
pip install -r requirements.txt -v

# Check Python version
python --version

Performance Optimization

For Large Videos
  1. 1.Increase Frame Interval: Use every 5th or 10th frame
  2. 2.Process in Batches: Split long videos into segments
  3. 3.Use SSD Storage: Faster read/write operations
  4. 4.Close Other Applications: Free up system resources
For Annotation Speed
  1. 1.Use Keyboard Shortcuts: Arrow keys for navigation
  2. 2.Batch Annotations: Annotate similar frames together
  3. 3.Use High-Quality Monitor: Better visibility for small objects

🤝 Contributing

Development Setup

  1. 1.Fork the repository
  2. 2.Create a feature branch
  3. 3.Make your changes
  4. 4.Add tests if applicable
  5. 5.Submit a pull request

Code Style

  • —Follow PEP 8 guidelines
  • —Add docstrings to functions
  • —Include type hints where appropriate
  • —Write clear commit messages

Testing

bash
# Run the test suite
python test_flow.py

# Test specific components
python -m pytest tests/

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • —OpenCV: Computer vision library
  • —Flask: Web framework
  • —YOLO: Object detection format
  • —labelImg: Annotation tool inspiration

📞 Support

For issues and questions:

  1. 1.Check the troubleshooting section
  2. 2.Review existing GitHub issues
  3. 3.Create a new issue with detailed information
  4. 4.Include system information and error logs

Happy Cricket Analysis! 🏏