first commit

.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Output files
+output/
+*.mp4
+*.avi
+*.mov
+*.csv
+*.png
+!example_videos/*.mp4
+
+# Model weights (downloaded at runtime)
+*.pt
+*.pth
+*.onnx
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Gradio
+gradio_cached_examples/
+flagged/
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+tmp/
+temp/
+*.tmp

CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Running the Application
+
+Start the Gradio web interface:
+```bash
+python app.py
+```
+
+The app launches on `http://localhost:7860` by default (port 7860, binds to 0.0.0.0).
+
+## Architecture Overview
+
+This is a Gradio-based web application for tennis ball tracking using computer vision. The processing pipeline has three main stages:
+
+1. **Detection** ([detector.py](detector.py)): YOLOv8 detects tennis balls (COCO class 32) in each frame
+2. **Tracking** ([tracker.py](tracker.py)): Kalman filter smooths trajectories and predicts positions during occlusion
+3. **Visualization** ([utils/visualization.py](utils/visualization.py)): Overlays trajectory trails, bounding boxes, speed labels, and generates plots
+
+### Key Design Patterns
+
+**Processing Flow** ([app.py](app.py:30-188)):
+- `process_video()` orchestrates the full pipeline
+- Uses context managers (`VideoReader`, `VideoWriter`) for safe I/O
+- Frame-by-frame processing: detect → update tracker → render overlays → write frame
+- Trajectory data accumulated in tracker, exported to CSV at end
+
+**State Management** ([tracker.py](tracker.py:13-211)):
+- `BallTracker` maintains Kalman filter state vector: `[x, y, vx, vy]`
+- Handles initialization on first detection
+- Predicts ball position when detection is lost (up to `max_missing_frames`)
+- Resets tracker if ball missing too long
+
+**Detection Selection** ([app.py](app.py:104-115)):
+- When multiple detections occur, uses highest confidence detection
+- Minimum box size filter (5x5 pixels) in [detector.py](detector.py:107)
+
+## Module Dependencies
+
+```
+app.py (main entry point)
+├── detector.py (BallDetector class)
+├── tracker.py (BallTracker class)
+└── utils/
+    ├── io_utils.py (VideoReader, VideoWriter, CSV export)
+    └── visualization.py (drawing functions, plotting)
+```
+
+All utilities are imported via `utils/__init__.py` which re-exports from submodules.
+
+## Configuration Parameters
+
+**Detector** ([detector.py](detector.py:24-49)):
+- `model_name`: 'yolov8n' (fastest), 'yolov8s', 'yolov8m' (most accurate)
+- `confidence_threshold`: 0.1-0.9 (lower = more sensitive)
+- `device`: auto-detected ('cuda' if available, else 'cpu')
+
+**Tracker** ([tracker.py](tracker.py:28-47)):
+- `dt`: time step, calculated as `1.0 / fps`
+- `max_missing_frames`: typically `int(fps * 0.5)` (half-second tolerance)
+- `process_noise`: 0.1 (Kalman filter Q matrix)
+- `measurement_noise`: 10.0 (Kalman filter R matrix)
+
+## Output Files
+
+All outputs saved to `output/` directory:
+- `tracked_video.mp4`: Video with overlays (bounding boxes, trails, speed labels, info panel)
+- `trajectory.csv`: Frame-by-frame data with columns: frame, timestamp, x/y position, velocity, speed
+- `trajectory_plot.png`: 2D plot with color-coded speed gradient (blue=slow, red=fast)
+
+## Speed Estimation
+
+Speed calculated from Kalman filter velocity: `speed = sqrt(vx² + vy²) / dt`
+
+**Units**: Speed is in pixels/second. The "km/h" label uses rough approximation (`speed * 0.01`) - real-world conversion requires camera calibration.
+
+## Deployment Notes
+
+**Hugging Face Spaces**:
+- Use YOLOv8n model for free tier (limited GPU)
+- App automatically creates `output/` directory on startup
+- Gradio interface configured with `share=False` by default
+
+**Model Downloads**:
+- YOLOv8 weights downloaded automatically by Ultralytics on first run
+- Models cached in `~/.cache/torch/hub/` directory

README.md

@@ -1,13 +1,286 @@
+# 🎾 TennisVision – AI Ball Tracker
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Gradio](https://img.shields.io/badge/gradio-4.0+-orange.svg)](https://gradio.app/)
+[![YOLOv8](https://img.shields.io/badge/YOLOv8-Ultralytics-00ADD8.svg)](https://github.com/ultralytics/ultralytics)
+
+A comprehensive AI-powered tennis ball tracking demo application that detects and tracks tennis balls in video clips using state-of-the-art computer vision models.
+
+## 🌟 Features
+
+- **Real-time Ball Detection**: Uses YOLOv8 models for accurate tennis ball detection
+- **Kalman Filter Tracking**: Smooth trajectory tracking with velocity estimation
+- **Speed Visualization**: Real-time speed estimation and overlay
+- **2D Trajectory Plot**: Color-coded trajectory visualization based on ball speed
+- **Data Export**: Download processed videos and trajectory data in CSV format
+- **Interactive UI**: User-friendly Gradio interface with adjustable parameters
+
+## 🎯 Demo Capabilities
+
+1. ✅ Accept short tennis video clips (user-uploaded)
+2. ✅ Detect and track tennis balls frame-by-frame using YOLOv8
+3. ✅ Visualize ball trajectory and speed as video overlays
+4. ✅ Display 2D trajectory plot (X vs Y) color-coded by speed
+5. ✅ Provide downloadable outputs:
+   - Processed video with trajectory overlays
+   - CSV file with timestamped coordinates and speed estimates
+   - Trajectory plot image
+
+## 🏗️ Project Structure
+
+```
+tennisvision/
+├── app.py                    # Gradio application entry point
+├── detector.py               # YOLOv8 detection model wrapper
+├── tracker.py                # Kalman filter-based ball tracker
+├── utils/
+│   ├── __init__.py          # Utility package initialization
+│   ├── visualization.py     # Overlay rendering and plotting
+│   └── io_utils.py          # Video I/O and CSV export
+├── example_videos/          # Sample tennis videos (user-provided)
+├── output/                  # Generated output files
+├── requirements.txt         # Python dependencies
+└── README.md               # This file
+```
+
+## 🚀 Quick Start
+
+### Local Installation
+
+1. **Clone or download this repository**
+
+```bash
+git clone <repository-url>
+cd tennisvision
+```
+
+2. **Install dependencies**
+
+```bash
+pip install -r requirements.txt
+```
+
+3. **Run the application**
+
+```bash
+python app.py
+```
+
+4. **Open your browser** to `http://localhost:7860`
+
+### Usage
+
+1. **Upload a tennis video** (MP4, AVI, or MOV format)
+2. **Select detection model**:
+   - `yolov8n` - Fastest (recommended for Hugging Face Spaces)
+   - `yolov8s` - Balanced speed/accuracy
+   - `yolov8m` - Most accurate
+3. **Adjust confidence threshold** (0.1 - 0.9):
+   - Lower values detect more balls but may include false positives
+   - Higher values are more conservative
+4. **Click "Run Tracking"** and wait for processing
+5. **View results** in tabs:
+   - Processed video with overlays
+   - 2D trajectory plot
+   - Download CSV and video files
+
+## 🤗 Hugging Face Spaces Deployment
+
+### Method 1: Using the Web Interface
+
+1. Create a new Space on [Hugging Face](https://huggingface.co/spaces)
+2. Select **Gradio** as the SDK
+3. Upload all files from the `tennisvision/` directory
+4. The Space will automatically build and deploy
+
+### Method 2: Using Git
+
+1. Create a new Space and clone it:
+
+```bash
+git clone https://huggingface.co/spaces/<your-username>/<space-name>
+cd <space-name>
+```
+
+2. Copy all files from `tennisvision/`:
+
+```bash
+cp -r path/to/tennisvision/* .
+```
+
+3. Commit and push:
+
+```bash
+git add .
+git commit -m "Initial commit: TennisVision ball tracker"
+git push
+```
+
+### Configuration Files for Hugging Face
+
+Create a `README.md` in the Space root with:
+
+```yaml
 ---
-title: Tennisvision
-emoji: 📚
-colorFrom: yellow
-colorTo: purple
+title: TennisVision - AI Ball Tracker
+emoji: 🎾
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 5.49.1
+sdk_version: 4.0.0
 app_file: app.py
 pinned: false
-license: apache-2.0
 ---
+```
+
+## 📊 Output Files
+
+### 1. Processed Video (`tracked_video.mp4`)
+- Original video with overlays
+- Ball bounding boxes
+- Trajectory trail (last 20 positions)
+- Speed labels
+- Info panel with frame count and timestamp
+
+### 2. Trajectory CSV (`trajectory.csv`)
+Columns:
+- `frame`: Frame number
+- `timestamp_sec`: Time in seconds
+- `x_pixels`, `y_pixels`: Ball center coordinates
+- `velocity_x_px_per_sec`, `velocity_y_px_per_sec`: Velocity components
+- `speed_px_per_sec`: Instantaneous speed
+
+### 3. Trajectory Plot (`trajectory_plot.png`)
+- 2D visualization of ball path
+- Color gradient representing speed (blue = slow, red = fast)
+- Start and end markers
+
+## 🛠️ Technical Details
+
+### Detection Models
+
+**YOLOv8** (You Only Look Once v8) from Ultralytics:
+- Pre-trained on COCO dataset
+- Detects sports balls (class 32)
+- Variants: `yolov8n` (nano), `yolov8s` (small), `yolov8m` (medium)
+
+### Tracking Algorithm
+
+**Kalman Filter**:
+- State vector: `[x, y, vx, vy]` (position and velocity)
+- Constant velocity motion model
+- Predicts ball position when detection is lost
+- Smooths noisy detections
+
+### Speed Estimation
+
+```
+speed = sqrt(vx² + vy²) / dt
+```
+where `dt = 1 / fps`
+
+*Note: Speed is in pixels/sec. Real-world conversion requires camera calibration.*
+
+## 🎨 Visualization Features
+
+- **Bounding Boxes**: Green boxes around detected balls
+- **Trajectory Trail**: Fading trail showing recent positions
+- **Speed Label**: Real-time speed estimate (km/h approximation)
+- **Info Panel**: Frame number, timestamp, detection confidence
+- **2D Plot**: Complete trajectory with color-coded speed
+
+## ⚠️ Limitations
+
+- Requires visible ball in video
+- Works best with clear, high-resolution footage
+- Speed estimates are in pixels (not calibrated to real-world units)
+- Processing time scales with video length and model size
+- Free Hugging Face Spaces have limited GPU resources (use YOLOv8n)
+
+## 🔧 Configuration
+
+### Detector Parameters
+
+```python
+detector = BallDetector(
+    model_name="yolov8n",           # Model variant
+    confidence_threshold=0.3,       # Min confidence score
+    device="cuda"                   # or "cpu"
+)
+```
+
+### Tracker Parameters
+
+```python
+tracker = BallTracker(
+    dt=1.0/30.0,                   # Time step (1/fps)
+    process_noise=0.1,             # Process noise std
+    measurement_noise=10.0,        # Measurement noise std
+    max_missing_frames=10          # Max frames without detection
+)
+```
+
+## 🧪 Example Videos
+
+Place sample videos in `example_videos/`:
+- `serve.mp4` - Tennis serve motion
+- `rally.mp4` - Rally with multiple ball trajectories
+
+*Note: Sample videos not included in repository. Use your own tennis footage.*
+
+## 🐛 Troubleshooting
+
+**No ball detected:**
+- Lower the confidence threshold
+- Ensure ball is clearly visible
+- Try a different model (yolov8s or yolov8m)
+
+**Slow processing:**
+- Use yolov8n model
+- Process shorter clips
+- Use GPU if available
+
+**Poor tracking accuracy:**
+- Increase confidence threshold
+- Adjust Kalman filter parameters
+- Use higher resolution video
+
+## 📚 Dependencies
+
+- **torch** >= 2.0.0 - Deep learning framework
+- **ultralytics** >= 8.0.0 - YOLOv8 implementation
+- **opencv-python-headless** == 4.8.1.78 - Video processing
+- **gradio** >= 4.0.0 - Web interface
+- **matplotlib** >= 3.7.0 - Plotting
+- **filterpy** >= 1.4.5 - Kalman filter
+- **numpy** >= 1.24.0 - Numerical operations
+
+## 🙏 Acknowledgments
+
+- [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics) - Object detection
+- [Gradio](https://gradio.app/) - Web interface framework
+- [FilterPy](https://github.com/rlabbe/filterpy) - Kalman filter implementation
+
+## 📄 License
+
+This project is open-source and available for educational and research purposes.
+
+## 🤝 Contributing
+
+Contributions are welcome! Areas for improvement:
+- [ ] Add RT-DETR model support
+- [ ] Implement bounce detection
+- [ ] Add FPS benchmark display
+- [ ] Camera calibration for real-world speed
+- [ ] Multi-ball tracking
+- [ ] Player detection and tracking
+
+## 📧 Contact
+
+For questions or issues, please open an issue on the repository.
+
+---
+
+**Built with ❤️ for the tennis and computer vision community**
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+🎾 Enjoy tracking! 🚀

__init__.py

@@ -0,0 +1,14 @@
+"""
+TennisVision - AI Ball Tracker
+
+A comprehensive tennis ball tracking system using YOLOv8 detection
+and Kalman filter-based tracking.
+"""
+
+__version__ = "1.0.0"
+__author__ = "TennisVision Team"
+
+from .detector import BallDetector
+from .tracker import BallTracker
+
+__all__ = ['BallDetector', 'BallTracker']

app.py

@@ -1,7 +1,325 @@
+"""
+TennisVision - AI Ball Tracker
+Gradio application for tennis ball detection and tracking.
+"""
+
 import gradio as gr
+import cv2
+import numpy as np
+import os
+import tempfile
+from pathlib import Path
+from typing import Tuple, Optional
+
+from detector import BallDetector
+from tracker import BallTracker
+from utils import (
+    VideoReader,
+    VideoWriter,
+    export_trajectory_csv,
+    validate_video_file,
+    create_output_directory,
+    draw_detection,
+    draw_trajectory_trail,
+    draw_speed_label,
+    draw_info_panel,
+    create_trajectory_plot
+)
+
+
+def process_video(
+    video_path: str,
+    model_name: str,
+    confidence_threshold: float,
+    progress=gr.Progress()
+) -> Tuple[Optional[str], Optional[str], Optional[str], str]:
+    """
+    Process a video to track the tennis ball.
+
+    Args:
+        video_path: Path to input video file
+        model_name: Detection model identifier
+        confidence_threshold: Minimum detection confidence
+        progress: Gradio progress tracker
+
+    Returns:
+        Tuple of (output_video_path, csv_path, plot_path, status_message)
+    """
+    try:
+        # Validate input video
+        is_valid, msg = validate_video_file(video_path)
+        if not is_valid:
+            return None, None, None, f"❌ Error: {msg}"
+
+        progress(0, desc="Initializing models...")
+
+        # Initialize detector and tracker
+        detector = BallDetector(
+            model_name=model_name,
+            confidence_threshold=confidence_threshold
+        )
+
+        # Read video properties
+        with VideoReader(video_path) as reader:
+            video_props = reader.get_properties()
+
+        fps = video_props['fps']
+        frame_count = video_props['frame_count']
+        width = video_props['width']
+        height = video_props['height']
+
+        # Initialize tracker
+        tracker = BallTracker(dt=1.0 / fps, max_missing_frames=int(fps * 0.5))
+
+        # Create temporary output files
+        output_dir = create_output_directory("output")
+        temp_video = tempfile.NamedTemporaryFile(
+            delete=False, suffix='.mp4', dir=output_dir
+        )
+        output_video_path = temp_video.name
+        temp_video.close()
+
+        csv_path = output_dir / "trajectory.csv"
+        plot_path = output_dir / "trajectory_plot.png"
+
+        progress(0.1, desc="Processing frames...")
+
+        # Process video
+        detection_count = 0
+        with VideoReader(video_path) as reader, \
+             VideoWriter(output_video_path, fps, width, height) as writer:
+
+            for frame_num, frame in reader.read_frames():
+                # Update progress
+                progress_pct = 0.1 + 0.7 * (frame_num / frame_count)
+                progress(
+                    progress_pct,
+                    desc=f"Processing frame {frame_num + 1}/{frame_count}"
+                )
+
+                # Detect ball
+                detections = detector.detect(frame)
+
+                # Update tracker
+                if len(detections) > 0:
+                    # Use highest confidence detection
+                    best_detection = detections[0]
+                    cx, cy = detector.get_ball_center(best_detection)
+                    state = tracker.update((cx, cy))
+                    detection_count += 1
+
+                    # Draw detection box
+                    frame = draw_detection(frame, best_detection)
+                else:
+                    # Predict without detection
+                    state = tracker.update(None)
+
+                # Draw trajectory and info if tracker is active
+                if state is not None and tracker.is_initialized():
+                    x, y, vx, vy = state
+
+                    # Draw trajectory trail
+                    positions = tracker.get_last_n_positions(20)
+                    frame = draw_trajectory_trail(frame, positions)
+
+                    # Calculate and draw speed
+                    speed = tracker.get_speed(state)
+                    frame = draw_speed_label(frame, (x, y), speed, fps)
+
+                # Draw info panel
+                conf = detections[0][4] if len(detections) > 0 else None
+                frame = draw_info_panel(frame, frame_num + 1, frame_count, fps, conf)
+
+                # Write frame
+                writer.write_frame(frame)
+
+        # Export trajectory data
+        progress(0.8, desc="Exporting trajectory data...")
+        trajectory = tracker.get_trajectory()
+
+        if len(trajectory) == 0:
+            return None, None, None, "❌ No ball detected in video. Try lowering the confidence threshold."
+
+        # Export CSV
+        export_success = export_trajectory_csv(trajectory, fps, str(csv_path))
+        if not export_success:
+            csv_path = None
+
+        # Create trajectory plot
+        progress(0.9, desc="Creating trajectory plot...")
+        try:
+            create_trajectory_plot(trajectory, fps, str(plot_path))
+        except Exception as e:
+            print(f"Failed to create plot: {e}")
+            plot_path = None
+
+        progress(1.0, desc="Complete!")
+
+        # Generate status message
+        status = f"""✅ **Processing Complete!**
+
+**Video Info:**
+- Total Frames: {frame_count}
+- Frame Rate: {fps:.1f} FPS
+- Resolution: {width}x{height}
+
+**Tracking Results:**
+- Ball Detected: {detection_count} frames ({100 * detection_count / frame_count:.1f}%)
+- Trajectory Points: {len(trajectory)}
+
+**Outputs:**
+- Processed video with overlays
+- Trajectory CSV with {len(trajectory)} data points
+- 2D trajectory plot color-coded by speed
+"""
+
+        return (
+            output_video_path,
+            str(csv_path) if csv_path else None,
+            str(plot_path) if plot_path else None,
+            status
+        )
+
+    except Exception as e:
+        error_msg = f"❌ **Error during processing:** {str(e)}"
+        print(error_msg)
+        import traceback
+        traceback.print_exc()
+        return None, None, None, error_msg
+
+
+# Create Gradio interface
+def create_interface():
+    """Create and configure the Gradio interface."""
+
+    with gr.Blocks(
+        title="TennisVision - AI Ball Tracker",
+        theme=gr.themes.Soft()
+    ) as app:
+        gr.Markdown(
+            """
+            # 🎾 TennisVision - AI Ball Tracker
+
+            Upload a tennis video to automatically detect and track the ball using
+            state-of-the-art computer vision models.
+
+            **Features:**
+            - Real-time ball detection with YOLOv8
+            - Smooth trajectory tracking with Kalman filter
+            - Speed estimation and visualization
+            - Downloadable outputs (video, CSV, plot)
+            """
+        )
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("### ⚙️ Input & Settings")
+
+                video_input = gr.Video(
+                    label="Upload Tennis Video",
+                    sources=["upload"]
+                )
+
+                model_dropdown = gr.Dropdown(
+                    choices=["yolov8n", "yolov8s", "yolov8m"],
+                    value="yolov8n",
+                    label="Detection Model",
+                    info="yolov8n is fastest, yolov8m is most accurate"
+                )
+
+                confidence_slider = gr.Slider(
+                    minimum=0.1,
+                    maximum=0.9,
+                    value=0.3,
+                    step=0.05,
+                    label="Confidence Threshold",
+                    info="Lower = more detections (may include false positives)"
+                )
+
+                process_btn = gr.Button(
+                    "🚀 Run Tracking",
+                    variant="primary",
+                    size="lg"
+                )
+
+                gr.Markdown(
+                    """
+                    ### 💡 Tips
+                    - Use short clips (5-15 seconds) for faster processing
+                    - Ensure the ball is visible and in motion
+                    - Lower confidence threshold if ball is not detected
+                    - YOLOv8n provides fastest inference (~30 FPS)
+                    """
+                )
+
+            with gr.Column(scale=2):
+                gr.Markdown("### 📊 Results")
+
+                status_output = gr.Markdown(
+                    "Upload a video and click **Run Tracking** to begin."
+                )
+
+                with gr.Tabs():
+                    with gr.Tab("📹 Processed Video"):
+                        video_output = gr.Video(
+                            label="Tracked Video",
+                            show_label=False
+                        )
+
+                    with gr.Tab("📈 Trajectory Plot"):
+                        plot_output = gr.Image(
+                            label="2D Trajectory",
+                            show_label=False
+                        )
+
+                    with gr.Tab("📥 Downloads"):
+                        gr.Markdown("### Download Files")
+                        csv_output = gr.File(
+                            label="Trajectory Data (CSV)"
+                        )
+                        video_download = gr.File(
+                            label="Processed Video (MP4)"
+                        )
+
+        # Event handlers
+        process_btn.click(
+            fn=process_video,
+            inputs=[video_input, model_dropdown, confidence_slider],
+            outputs=[video_output, csv_output, plot_output, status_output]
+        ).then(
+            fn=lambda x: x,
+            inputs=[video_output],
+            outputs=[video_download]
+        )
+
+        gr.Markdown(
+            """
+            ---
+            ### 📚 About
+
+            **TennisVision** uses YOLOv8 for ball detection and Kalman filtering
+            for smooth trajectory tracking. The system estimates ball speed and
+            visualizes the complete trajectory with color-coded speed indicators.
+
+            **Model:** YOLOv8 (Ultralytics)
+            **Tracking:** Kalman Filter
+            **Framework:** Gradio + OpenCV
+
+            Built for deployment on Hugging Face Spaces 🤗
+            """
+        )
+
+    return app
+
 
-def greet(name):
-    return "Hello " + name + "!!"
+if __name__ == "__main__":
+    # Create output directory
+    create_output_directory("output")
 
-demo = gr.Interface(fn=greet, inputs="text", outputs="text")
-demo.launch()
+    # Launch app
+    app = create_interface()
+    app.launch(
+        share=False,
+        server_name="0.0.0.0",
+        server_port=7860
+    )

detector.py

@@ -0,0 +1,155 @@
+"""
+Ball Detection Module using YOLO and RT-DETR models.
+
+This module provides a unified interface for detecting tennis balls
+in video frames using state-of-the-art object detection models.
+"""
+
+import torch
+import numpy as np
+from typing import List, Tuple, Optional
+from ultralytics import YOLO
+
+
+class BallDetector:
+    """
+    Wrapper class for ball detection using YOLOv8 or RT-DETR.
+
+    Attributes:
+        model_name (str): Name of the detection model ('yolov8n', 'yolov8s', etc.)
+        confidence_threshold (float): Minimum confidence score for detections
+        device (str): Device to run inference on ('cuda' or 'cpu')
+    """
+
+    def __init__(
+        self,
+        model_name: str = "yolov8n",
+        confidence_threshold: float = 0.3,
+        device: Optional[str] = None
+    ):
+        """
+        Initialize the ball detector.
+
+        Args:
+            model_name: Model identifier (e.g., 'yolov8n', 'yolov8s')
+            confidence_threshold: Minimum confidence for valid detections
+            device: Compute device ('cuda', 'cpu', or None for auto-detect)
+        """
+        self.model_name = model_name
+        self.confidence_threshold = confidence_threshold
+
+        # Auto-detect device if not specified
+        if device is None:
+            self.device = 'cuda' if torch.cuda.is_available() else 'cpu'
+        else:
+            self.device = device
+
+        # Load model
+        self.model = self._load_model()
+
+    def _load_model(self) -> YOLO:
+        """
+        Load the specified detection model.
+
+        Returns:
+            Loaded YOLO model instance
+
+        Raises:
+            ValueError: If model name is not supported
+        """
+        try:
+            if self.model_name.startswith('yolov8'):
+                # Load YOLOv8 model from Ultralytics
+                model = YOLO(f'{self.model_name}.pt')
+                model.to(self.device)
+                return model
+            else:
+                raise ValueError(f"Unsupported model: {self.model_name}")
+        except Exception as e:
+            raise RuntimeError(f"Failed to load model {self.model_name}: {str(e)}")
+
+    def detect(self, frame: np.ndarray) -> List[Tuple[int, int, int, int, float]]:
+        """
+        Detect tennis balls in a single frame.
+
+        Args:
+            frame: Input frame as numpy array (H, W, 3) in BGR format
+
+        Returns:
+            List of detections, each as (x1, y1, x2, y2, confidence)
+            where (x1, y1) is top-left and (x2, y2) is bottom-right
+        """
+        try:
+            # Run inference
+            results = self.model.predict(
+                frame,
+                conf=self.confidence_threshold,
+                device=self.device,
+                verbose=False,
+                classes=[32]  # Sports ball class in COCO dataset
+            )
+
+            detections = []
+
+            # Parse results
+            if len(results) > 0 and results[0].boxes is not None:
+                boxes = results[0].boxes
+
+                for box in boxes:
+                    # Extract bounding box coordinates
+                    x1, y1, x2, y2 = box.xyxy[0].cpu().numpy()
+                    confidence = float(box.conf[0].cpu().numpy())
+
+                    # Filter small detections (likely noise)
+                    width = x2 - x1
+                    height = y2 - y1
+
+                    if width > 5 and height > 5:  # Minimum size threshold
+                        detections.append((
+                            int(x1), int(y1), int(x2), int(y2), confidence
+                        ))
+
+            # Sort by confidence (highest first)
+            detections.sort(key=lambda x: x[4], reverse=True)
+
+            return detections
+
+        except Exception as e:
+            print(f"Detection error: {str(e)}")
+            return []
+
+    def get_ball_center(
+        self,
+        detection: Tuple[int, int, int, int, float]
+    ) -> Tuple[float, float]:
+        """
+        Calculate the center point of a ball detection.
+
+        Args:
+            detection: Bounding box as (x1, y1, x2, y2, confidence)
+
+        Returns:
+            Center coordinates as (cx, cy)
+        """
+        x1, y1, x2, y2, _ = detection
+        cx = (x1 + x2) / 2.0
+        cy = (y1 + y2) / 2.0
+        return cx, cy
+
+    def get_ball_size(
+        self,
+        detection: Tuple[int, int, int, int, float]
+    ) -> Tuple[float, float]:
+        """
+        Calculate the width and height of a ball detection.
+
+        Args:
+            detection: Bounding box as (x1, y1, x2, y2, confidence)
+
+        Returns:
+            Size as (width, height)
+        """
+        x1, y1, x2, y2, _ = detection
+        width = x2 - x1
+        height = y2 - y1
+        return width, height

packages.txt

@@ -0,0 +1,7 @@
+libgl1
+libglib2.0-0
+libsm6
+libxext6
+libxrender-dev
+libgomp1
+ffmpeg

requirements.txt

@@ -0,0 +1,9 @@
+torch>=2.0.0
+torchvision>=0.15.0
+opencv-python-headless==4.8.1.78
+ultralytics>=8.0.0
+numpy>=1.24.0
+gradio>=4.0.0
+matplotlib>=3.7.0
+filterpy>=1.4.5
+Pillow>=10.0.0

tracker.py

@@ -0,0 +1,210 @@
+"""
+Ball Tracking Module using Kalman Filter.
+
+This module implements a Kalman filter-based tracker for smoothing
+and predicting tennis ball positions across video frames.
+"""
+
+import numpy as np
+from typing import Optional, Tuple, List
+from filterpy.kalman import KalmanFilter
+
+
+class BallTracker:
+    """
+    Kalman filter-based tracker for tennis ball position and velocity.
+
+    The tracker maintains state estimates for:
+    - Position (x, y)
+    - Velocity (vx, vy)
+
+    Attributes:
+        dt (float): Time step between frames (1/fps)
+        process_noise (float): Process noise covariance
+        measurement_noise (float): Measurement noise covariance
+        max_missing_frames (int): Maximum frames without detection before reset
+    """
+
+    def __init__(
+        self,
+        dt: float = 1.0 / 30.0,
+        process_noise: float = 0.1,
+        measurement_noise: float = 10.0,
+        max_missing_frames: int = 10
+    ):
+        """
+        Initialize the ball tracker.
+
+        Args:
+            dt: Time step between frames (seconds)
+            process_noise: Process noise standard deviation
+            measurement_noise: Measurement noise standard deviation
+            max_missing_frames: Max consecutive frames without detection
+        """
+        self.dt = dt
+        self.process_noise = process_noise
+        self.measurement_noise = measurement_noise
+        self.max_missing_frames = max_missing_frames
+
+        # Initialize Kalman filter
+        self.kf = self._create_kalman_filter()
+
+        # Tracking state
+        self.initialized = False
+        self.missing_frames = 0
+        self.trajectory = []  # List of (x, y, vx, vy, frame_num)
+        self.frame_count = 0
+
+    def _create_kalman_filter(self) -> KalmanFilter:
+        """
+        Create and configure a Kalman filter for 2D position tracking.
+
+        State vector: [x, y, vx, vy]
+        Measurement vector: [x, y]
+
+        Returns:
+            Configured KalmanFilter instance
+        """
+        kf = KalmanFilter(dim_x=4, dim_z=2)
+
+        # State transition matrix (constant velocity model)
+        kf.F = np.array([
+            [1, 0, self.dt, 0],
+            [0, 1, 0, self.dt],
+            [0, 0, 1, 0],
+            [0, 0, 0, 1]
+        ])
+
+        # Measurement matrix (observe position only)
+        kf.H = np.array([
+            [1, 0, 0, 0],
+            [0, 1, 0, 0]
+        ])
+
+        # Measurement noise covariance
+        kf.R = np.eye(2) * self.measurement_noise
+
+        # Process noise covariance
+        q = self.process_noise
+        kf.Q = np.array([
+            [q * self.dt**4 / 4, 0, q * self.dt**3 / 2, 0],
+            [0, q * self.dt**4 / 4, 0, q * self.dt**3 / 2],
+            [q * self.dt**3 / 2, 0, q * self.dt**2, 0],
+            [0, q * self.dt**3 / 2, 0, q * self.dt**2]
+        ])
+
+        # Initial state covariance
+        kf.P = np.eye(4) * 100
+
+        return kf
+
+    def update(
+        self,
+        measurement: Optional[Tuple[float, float]] = None
+    ) -> Optional[Tuple[float, float, float, float]]:
+        """
+        Update tracker with a new measurement or predict if no detection.
+
+        Args:
+            measurement: Ball center position as (x, y), or None if not detected
+
+        Returns:
+            Estimated state as (x, y, vx, vy) or None if tracker not initialized
+        """
+        self.frame_count += 1
+
+        if measurement is not None:
+            # Detection available
+            if not self.initialized:
+                # Initialize tracker with first detection
+                self.kf.x = np.array([
+                    measurement[0],
+                    measurement[1],
+                    0.0,
+                    0.0
+                ])
+                self.initialized = True
+                self.missing_frames = 0
+            else:
+                # Update with measurement
+                z = np.array([measurement[0], measurement[1]])
+                self.kf.predict()
+                self.kf.update(z)
+                self.missing_frames = 0
+
+            # Record trajectory
+            x, y, vx, vy = self.kf.x
+            self.trajectory.append((
+                float(x), float(y), float(vx), float(vy), self.frame_count
+            ))
+
+            return (float(x), float(y), float(vx), float(vy))
+
+        else:
+            # No detection - predict only
+            if self.initialized:
+                self.kf.predict()
+                self.missing_frames += 1
+
+                # Reset if too many missing frames
+                if self.missing_frames > self.max_missing_frames:
+                    self.reset()
+                    return None
+
+                # Return prediction
+                x, y, vx, vy = self.kf.x
+                self.trajectory.append((
+                    float(x), float(y), float(vx), float(vy), self.frame_count
+                ))
+                return (float(x), float(y), float(vx), float(vy))
+
+            return None
+
+    def reset(self):
+        """Reset tracker to uninitialized state."""
+        self.kf = self._create_kalman_filter()
+        self.initialized = False
+        self.missing_frames = 0
+
+    def get_trajectory(self) -> List[Tuple[float, float, float, float, int]]:
+        """
+        Get the complete trajectory history.
+
+        Returns:
+            List of trajectory points as (x, y, vx, vy, frame_num)
+        """
+        return self.trajectory
+
+    def get_speed(self, state: Tuple[float, float, float, float]) -> float:
+        """
+        Calculate speed from velocity components.
+
+        Args:
+            state: Tracker state as (x, y, vx, vy)
+
+        Returns:
+            Speed in pixels per second
+        """
+        _, _, vx, vy = state
+        speed = np.sqrt(vx**2 + vy**2) / self.dt
+        return float(speed)
+
+    def get_last_n_positions(self, n: int = 20) -> List[Tuple[float, float]]:
+        """
+        Get the last N tracked positions for trail visualization.
+
+        Args:
+            n: Number of recent positions to return
+
+        Returns:
+            List of (x, y) coordinates
+        """
+        if len(self.trajectory) == 0:
+            return []
+
+        recent = self.trajectory[-n:]
+        return [(x, y) for x, y, _, _, _ in recent]
+
+    def is_initialized(self) -> bool:
+        """Check if tracker has been initialized with a detection."""
+        return self.initialized

utils/__init__.py

@@ -0,0 +1,32 @@
+"""Utility modules for TennisVision."""
+
+from .visualization import (
+    draw_detection,
+    draw_trajectory_trail,
+    draw_speed_label,
+    draw_info_panel,
+    create_trajectory_plot
+)
+
+from .io_utils import (
+    VideoReader,
+    VideoWriter,
+    export_trajectory_csv,
+    get_video_info,
+    validate_video_file,
+    create_output_directory
+)
+
+__all__ = [
+    'draw_detection',
+    'draw_trajectory_trail',
+    'draw_speed_label',
+    'draw_info_panel',
+    'create_trajectory_plot',
+    'VideoReader',
+    'VideoWriter',
+    'export_trajectory_csv',
+    'get_video_info',
+    'validate_video_file',
+    'create_output_directory'
+]

utils/io_utils.py

@@ -0,0 +1,287 @@
+"""
+I/O utilities for video processing and data export.
+
+This module provides functions for reading/writing videos,
+exporting trajectory data to CSV, and handling file operations.
+"""
+
+import cv2
+import csv
+import numpy as np
+from typing import List, Tuple, Optional, Generator
+from pathlib import Path
+
+
+class VideoReader:
+    """
+    Context manager for reading video files frame by frame.
+
+    Attributes:
+        video_path (str): Path to input video file
+        cap (cv2.VideoCapture): OpenCV video capture object
+    """
+
+    def __init__(self, video_path: str):
+        """
+        Initialize video reader.
+
+        Args:
+            video_path: Path to the video file
+
+        Raises:
+            FileNotFoundError: If video file doesn't exist
+            RuntimeError: If video cannot be opened
+        """
+        self.video_path = video_path
+
+        if not Path(video_path).exists():
+            raise FileNotFoundError(f"Video file not found: {video_path}")
+
+        self.cap = cv2.VideoCapture(video_path)
+
+        if not self.cap.isOpened():
+            raise RuntimeError(f"Failed to open video: {video_path}")
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - release video capture."""
+        self.cap.release()
+
+    def get_properties(self) -> dict:
+        """
+        Get video properties.
+
+        Returns:
+            Dictionary containing fps, frame_count, width, height
+        """
+        return {
+            'fps': self.cap.get(cv2.CAP_PROP_FPS),
+            'frame_count': int(self.cap.get(cv2.CAP_PROP_FRAME_COUNT)),
+            'width': int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH)),
+            'height': int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        }
+
+    def read_frames(self) -> Generator[Tuple[int, np.ndarray], None, None]:
+        """
+        Generator that yields frames from the video.
+
+        Yields:
+            Tuple of (frame_number, frame_array)
+        """
+        frame_num = 0
+        while True:
+            ret, frame = self.cap.read()
+            if not ret:
+                break
+            yield frame_num, frame
+            frame_num += 1
+
+    def read_frame(self) -> Tuple[bool, Optional[np.ndarray]]:
+        """
+        Read a single frame.
+
+        Returns:
+            Tuple of (success, frame) where success is a boolean
+        """
+        return self.cap.read()
+
+
+class VideoWriter:
+    """
+    Context manager for writing video files.
+
+    Attributes:
+        output_path (str): Path to output video file
+        fps (float): Frame rate
+        width (int): Frame width
+        height (int): Frame height
+    """
+
+    def __init__(
+        self,
+        output_path: str,
+        fps: float,
+        width: int,
+        height: int,
+        codec: str = 'mp4v'
+    ):
+        """
+        Initialize video writer.
+
+        Args:
+            output_path: Path to save the video
+            fps: Frame rate
+            width: Frame width in pixels
+            height: Frame height in pixels
+            codec: Video codec fourcc code
+        """
+        self.output_path = output_path
+        self.fps = fps
+        self.width = width
+        self.height = height
+
+        # Create output directory if it doesn't exist
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+
+        # Initialize video writer
+        fourcc = cv2.VideoWriter_fourcc(*codec)
+        self.writer = cv2.VideoWriter(
+            output_path,
+            fourcc,
+            fps,
+            (width, height)
+        )
+
+        if not self.writer.isOpened():
+            raise RuntimeError(f"Failed to create video writer: {output_path}")
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - release video writer."""
+        self.writer.release()
+
+    def write_frame(self, frame: np.ndarray):
+        """
+        Write a single frame to the video.
+
+        Args:
+            frame: Frame array in BGR format
+        """
+        # Ensure frame has correct dimensions
+        if frame.shape[1] != self.width or frame.shape[0] != self.height:
+            frame = cv2.resize(frame, (self.width, self.height))
+
+        self.writer.write(frame)
+
+
+def export_trajectory_csv(
+    trajectory: List[Tuple[float, float, float, float, int]],
+    fps: float,
+    output_path: str
+) -> bool:
+    """
+    Export trajectory data to CSV file.
+
+    Args:
+        trajectory: List of (x, y, vx, vy, frame_num) tuples
+        fps: Video frame rate
+        output_path: Path to save CSV file
+
+    Returns:
+        True if successful, False otherwise
+    """
+    try:
+        # Create output directory if needed
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+
+        with open(output_path, 'w', newline='') as csvfile:
+            writer = csv.writer(csvfile)
+
+            # Write header
+            writer.writerow([
+                'frame',
+                'timestamp_sec',
+                'x_pixels',
+                'y_pixels',
+                'velocity_x_px_per_sec',
+                'velocity_y_px_per_sec',
+                'speed_px_per_sec'
+            ])
+
+            # Write data rows
+            for x, y, vx, vy, frame_num in trajectory:
+                timestamp = frame_num / fps
+                speed = np.sqrt(vx**2 + vy**2) / (1.0 / fps)
+
+                writer.writerow([
+                    frame_num,
+                    f"{timestamp:.3f}",
+                    f"{x:.2f}",
+                    f"{y:.2f}",
+                    f"{vx / (1.0 / fps):.2f}",
+                    f"{vy / (1.0 / fps):.2f}",
+                    f"{speed:.2f}"
+                ])
+
+        return True
+
+    except Exception as e:
+        print(f"Error exporting CSV: {str(e)}")
+        return False
+
+
+def get_video_info(video_path: str) -> Optional[dict]:
+    """
+    Get basic information about a video file.
+
+    Args:
+        video_path: Path to video file
+
+    Returns:
+        Dictionary with video properties or None if failed
+    """
+    try:
+        with VideoReader(video_path) as reader:
+            return reader.get_properties()
+    except Exception as e:
+        print(f"Error reading video info: {str(e)}")
+        return None
+
+
+def validate_video_file(video_path: str) -> Tuple[bool, str]:
+    """
+    Validate that a video file exists and can be opened.
+
+    Args:
+        video_path: Path to video file
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if not video_path:
+        return False, "No video path provided"
+
+    path = Path(video_path)
+
+    if not path.exists():
+        return False, f"Video file not found: {video_path}"
+
+    if not path.is_file():
+        return False, f"Path is not a file: {video_path}"
+
+    # Try to open the video
+    try:
+        with VideoReader(video_path) as reader:
+            props = reader.get_properties()
+
+            if props['frame_count'] == 0:
+                return False, "Video has no frames"
+
+            if props['fps'] <= 0:
+                return False, "Invalid video frame rate"
+
+            return True, "Valid video file"
+
+    except Exception as e:
+        return False, f"Failed to open video: {str(e)}"
+
+
+def create_output_directory(output_dir: str = "output") -> Path:
+    """
+    Create output directory if it doesn't exist.
+
+    Args:
+        output_dir: Directory name/path
+
+    Returns:
+        Path object for the output directory
+    """
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+    return output_path

utils/visualization.py

@@ -0,0 +1,315 @@
+"""
+Visualization utilities for ball tracking.
+
+This module provides functions for rendering bounding boxes, trajectories,
+and creating 2D trajectory plots with speed-based color coding.
+"""
+
+import cv2
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.colors as mcolors
+from typing import List, Tuple, Optional
+from matplotlib.figure import Figure
+
+
+def draw_detection(
+    frame: np.ndarray,
+    detection: Tuple[int, int, int, int, float],
+    color: Tuple[int, int, int] = (0, 255, 0),
+    thickness: int = 2
+) -> np.ndarray:
+    """
+    Draw a bounding box for a detection on the frame.
+
+    Args:
+        frame: Input frame (BGR format)
+        detection: Bounding box as (x1, y1, x2, y2, confidence)
+        color: Box color in BGR format
+        thickness: Line thickness
+
+    Returns:
+        Frame with drawn bounding box
+    """
+    x1, y1, x2, y2, conf = detection
+
+    # Draw rectangle
+    cv2.rectangle(frame, (x1, y1), (x2, y2), color, thickness)
+
+    # Draw confidence label
+    label = f"{conf:.2f}"
+    label_size, _ = cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, 0.5, 1)
+    label_y = max(y1 - 10, label_size[1])
+
+    cv2.rectangle(
+        frame,
+        (x1, label_y - label_size[1] - 5),
+        (x1 + label_size[0], label_y + 5),
+        color,
+        -1
+    )
+    cv2.putText(
+        frame,
+        label,
+        (x1, label_y),
+        cv2.FONT_HERSHEY_SIMPLEX,
+        0.5,
+        (0, 0, 0),
+        1
+    )
+
+    return frame
+
+
+def draw_trajectory_trail(
+    frame: np.ndarray,
+    positions: List[Tuple[float, float]],
+    color: Tuple[int, int, int] = (0, 255, 255),
+    max_points: int = 20
+) -> np.ndarray:
+    """
+    Draw a trail showing recent ball positions.
+
+    Args:
+        frame: Input frame (BGR format)
+        positions: List of (x, y) positions (most recent last)
+        color: Trail color in BGR format
+        max_points: Maximum number of points to show
+
+    Returns:
+        Frame with drawn trajectory trail
+    """
+    if len(positions) < 2:
+        return frame
+
+    # Use only recent positions
+    recent = positions[-max_points:]
+
+    # Draw lines connecting positions with fading effect
+    for i in range(1, len(recent)):
+        # Calculate alpha (opacity) based on position in trail
+        alpha = i / len(recent)
+
+        # Blend color with background
+        pt1 = (int(recent[i - 1][0]), int(recent[i - 1][1]))
+        pt2 = (int(recent[i][0]), int(recent[i][1]))
+
+        # Draw line with thickness varying by position
+        thickness = max(1, int(2 * alpha))
+        line_color = tuple(int(c * alpha) for c in color)
+
+        cv2.line(frame, pt1, pt2, line_color, thickness, cv2.LINE_AA)
+
+    # Draw circle at current position
+    if len(recent) > 0:
+        curr_pos = (int(recent[-1][0]), int(recent[-1][1]))
+        cv2.circle(frame, curr_pos, 5, color, -1, cv2.LINE_AA)
+
+    return frame
+
+
+def draw_speed_label(
+    frame: np.ndarray,
+    position: Tuple[float, float],
+    speed: float,
+    fps: float,
+    color: Tuple[int, int, int] = (255, 255, 255)
+) -> np.ndarray:
+    """
+    Draw speed information near the ball position.
+
+    Args:
+        frame: Input frame (BGR format)
+        position: Ball position as (x, y)
+        speed: Speed in pixels per second
+        fps: Video frame rate
+        color: Text color in BGR format
+
+    Returns:
+        Frame with speed label
+    """
+    x, y = int(position[0]), int(position[1])
+
+    # Convert pixel speed to approximate real-world units
+    # (This is a rough estimate; proper conversion requires camera calibration)
+    speed_kmh = speed * 0.01  # Rough approximation
+
+    label = f"{speed_kmh:.1f} km/h"
+
+    # Draw label with background
+    font = cv2.FONT_HERSHEY_SIMPLEX
+    font_scale = 0.6
+    thickness = 2
+    label_size, _ = cv2.getTextSize(label, font, font_scale, thickness)
+
+    # Position label above the ball
+    label_x = x - label_size[0] // 2
+    label_y = y - 20
+
+    # Ensure label stays within frame
+    label_x = max(0, min(label_x, frame.shape[1] - label_size[0]))
+    label_y = max(label_size[1] + 5, label_y)
+
+    # Draw background rectangle
+    cv2.rectangle(
+        frame,
+        (label_x - 5, label_y - label_size[1] - 5),
+        (label_x + label_size[0] + 5, label_y + 5),
+        (0, 0, 0),
+        -1
+    )
+
+    # Draw text
+    cv2.putText(
+        frame,
+        label,
+        (label_x, label_y),
+        font,
+        font_scale,
+        color,
+        thickness,
+        cv2.LINE_AA
+    )
+
+    return frame
+
+
+def draw_info_panel(
+    frame: np.ndarray,
+    frame_num: int,
+    total_frames: int,
+    fps: float,
+    detection_conf: Optional[float] = None
+) -> np.ndarray:
+    """
+    Draw an information panel at the top of the frame.
+
+    Args:
+        frame: Input frame (BGR format)
+        frame_num: Current frame number
+        total_frames: Total number of frames
+        fps: Video frame rate
+        detection_conf: Detection confidence (if available)
+
+    Returns:
+        Frame with info panel
+    """
+    # Create semi-transparent overlay
+    overlay = frame.copy()
+    cv2.rectangle(overlay, (0, 0), (frame.shape[1], 60), (0, 0, 0), -1)
+    frame = cv2.addWeighted(overlay, 0.6, frame, 0.4, 0)
+
+    # Draw text information
+    font = cv2.FONT_HERSHEY_SIMPLEX
+    font_scale = 0.6
+    color = (255, 255, 255)
+    thickness = 2
+
+    # Frame counter
+    frame_text = f"Frame: {frame_num}/{total_frames}"
+    cv2.putText(frame, frame_text, (10, 25), font, font_scale, color, thickness)
+
+    # Time
+    time_text = f"Time: {frame_num / fps:.2f}s"
+    cv2.putText(frame, time_text, (10, 50), font, font_scale, color, thickness)
+
+    # Detection confidence (if available)
+    if detection_conf is not None:
+        conf_text = f"Confidence: {detection_conf:.2%}"
+        cv2.putText(frame, conf_text, (250, 25), font, font_scale, color, thickness)
+
+    return frame
+
+
+def create_trajectory_plot(
+    trajectory: List[Tuple[float, float, float, float, int]],
+    fps: float,
+    output_path: Optional[str] = None
+) -> Figure:
+    """
+    Create a 2D trajectory plot color-coded by speed.
+
+    Args:
+        trajectory: List of (x, y, vx, vy, frame_num) tuples
+        fps: Video frame rate
+        output_path: Path to save plot (optional)
+
+    Returns:
+        Matplotlib Figure object
+    """
+    if len(trajectory) == 0:
+        # Create empty plot
+        fig, ax = plt.subplots(figsize=(10, 8))
+        ax.text(
+            0.5, 0.5, "No trajectory data available",
+            ha='center', va='center', fontsize=14
+        )
+        ax.set_xlim(0, 1)
+        ax.set_ylim(0, 1)
+        return fig
+
+    # Extract coordinates and velocities
+    x_coords = [p[0] for p in trajectory]
+    y_coords = [p[1] for p in trajectory]
+    vx = [p[2] for p in trajectory]
+    vy = [p[3] for p in trajectory]
+
+    # Calculate speeds
+    speeds = [np.sqrt(vx[i]**2 + vy[i]**2) / (1.0 / fps) for i in range(len(vx))]
+
+    # Create figure
+    fig, ax = plt.subplots(figsize=(12, 10))
+
+    # Normalize speeds for color mapping
+    if max(speeds) > 0:
+        norm = mcolors.Normalize(vmin=min(speeds), vmax=max(speeds))
+        colormap = plt.cm.jet
+    else:
+        norm = None
+        colormap = None
+
+    # Plot trajectory with color-coded speeds
+    for i in range(1, len(x_coords)):
+        if norm is not None:
+            color = colormap(norm(speeds[i]))
+        else:
+            color = 'blue'
+
+        ax.plot(
+            [x_coords[i - 1], x_coords[i]],
+            [y_coords[i - 1], y_coords[i]],
+            color=color,
+            linewidth=2,
+            alpha=0.7
+        )
+
+    # Add start and end markers
+    ax.scatter(x_coords[0], y_coords[0], c='green', s=100, marker='o',
+               label='Start', zorder=5, edgecolors='black', linewidths=2)
+    ax.scatter(x_coords[-1], y_coords[-1], c='red', s=100, marker='X',
+               label='End', zorder=5, edgecolors='black', linewidths=2)
+
+    # Formatting
+    ax.set_xlabel('X Position (pixels)', fontsize=12, fontweight='bold')
+    ax.set_ylabel('Y Position (pixels)', fontsize=12, fontweight='bold')
+    ax.set_title('Tennis Ball Trajectory (Color = Speed)', fontsize=14, fontweight='bold')
+    ax.legend(loc='best', fontsize=10)
+    ax.grid(True, alpha=0.3)
+    ax.invert_yaxis()  # Invert Y-axis to match image coordinates
+
+    # Add colorbar
+    if norm is not None:
+        sm = plt.cm.ScalarMappable(cmap=colormap, norm=norm)
+        sm.set_array([])
+        cbar = plt.colorbar(sm, ax=ax, label='Speed (pixels/sec)')
+
+    plt.tight_layout()
+
+    # Save if path provided
+    if output_path:
+        try:
+            plt.savefig(output_path, dpi=150, bbox_inches='tight')
+        except Exception as e:
+            print(f"Error saving plot: {str(e)}")
+
+    return fig