README.md

---
language: en
license: mit
tags:
  - yolo
  - yolov11
  - object-detection
  - tennis
  - sports
  - computer-vision
  - pytorch
  - ultralytics
  - courtside
datasets:
  - tennis-ball-detection
metrics:
  - precision
  - recall
  - mAP
library_name: ultralytics
pipeline_tag: object-detection
---

# CourtSide Computer Vision v0.1 🎾

Fine-tuned YOLOv11n model for detecting tennis balls in images and videos. Part of the CourtSide Computer Vision suite for comprehensive tennis match analysis.

![Ball Detection Example](ball_detection_example.png)

## Model Details

- **Model Name**: CourtSide Computer Vision v0.1
- **Model Type**: Object Detection
- **Architecture**: YOLOv11 Nano (n)
- **Framework**: Ultralytics YOLOv11
- **Parameters**: 2.6M
- **Input Size**: 640x640
- **Classes**: 1 (`tennis_ball`)

## Performance Metrics

Evaluated on validation set (62 images):

| Metric | Value |
|--------|-------|
| **mAP@50** | **67.87%** |
| **mAP@50-95** | 24.93% |
| **Precision** | 84.3% |
| **Recall** | 59.5% |
| **Inference Speed** (M4 Pro) | 10.3ms |

## Training Details

### Dataset

This model was trained on the **Tennis Ball Detection Dataset** by Viren Dhanwani, available on Roboflow Universe.

- **Training images**: 408
- **Validation images**: 62
- **Test images**: 50
- **Total**: 520 annotated images
- **Annotation format**: YOLO format (bounding boxes)
- **Source**: [Roboflow Universe - Tennis Ball Detection](https://universe.roboflow.com/viren-dhanwani/tennis-ball-detection)

### Training Configuration
```yaml
Model: YOLOv11n (nano)
Epochs: 100
Batch size: 16
Image size: 640x640
Device: Apple M4 Pro (MPS)
Optimizer: AdamW
Learning rate: 0.001 → 0.01
Training time: ~23 minutes
```

### Augmentation
- HSV color jitter (h=0.015, s=0.7, v=0.4)
- Random horizontal flip (p=0.5)
- Translation (±10%)
- Scaling (±50%)
- Mosaic augmentation

### Loss Weights
- Box loss: 7.5
- Class loss: 0.5
- DFL loss: 1.5

## Usage

### Installation
```bash
pip install ultralytics
```

### Python API
```python
from ultralytics import YOLO
from PIL import Image

# Load CourtSide Computer Vision model
model = YOLO('courtsidecv_v0.1.pt')

# Predict on image
results = model.predict('tennis_match.jpg', conf=0.3)

# Display results
results[0].show()

# Get bounding boxes
for box in results[0].boxes:
    x1, y1, x2, y2 = box.xyxy[0]
    confidence = box.conf[0]
    print(f"Ball detected at [{x1:.0f}, {y1:.0f}, {x2:.0f}, {y2:.0f}] with {confidence:.2%} confidence")
```

### Video Processing
```python
from ultralytics import YOLO

model = YOLO('courtsidecv_v0.1.pt')

# Process video
results = model.predict(
    source='tennis_match.mp4',
    conf=0.3,
    save=True,
    save_txt=True
)
```

### Command Line
```bash
# Predict on image
yolo detect predict model=courtsidecv_v0.1.pt source=image.jpg conf=0.3

# Predict on video
yolo detect predict model=courtsidecv_v0.1.pt source=video.mp4 conf=0.3 save=True

# Validate model
yolo detect val model=courtsidecv_v0.1.pt data=dataset.yaml
```

## Recommended Hyperparameters

### Inference Settings
```python
# Balanced (recommended)
conf_threshold = 0.30  # Confidence threshold
iou_threshold = 0.45   # NMS IoU threshold
max_det = 50           # Maximum detections per image

# High precision (fewer false positives)
conf_threshold = 0.50
iou_threshold = 0.45
max_det = 30

# High recall (detect more balls, more false positives)
conf_threshold = 0.20
iou_threshold = 0.40
max_det = 100
```

## Limitations

- **Small objects**: Performance may degrade for tennis balls that are very far from the camera (< 20px)
- **Motion blur**: Fast-moving balls may be harder to detect
- **Occlusion**: Partially hidden balls may not be detected
- **Similar objects**: May occasionally detect other small round objects
- **Lighting**: Optimized for outdoor tennis lighting conditions

## Model Biases

- Trained primarily on standard yellow tennis balls
- Dataset includes various court types but may have dataset-specific biases
- Better performance on professional match footage vs amateur recordings

## Use Cases

✅ **Recommended:**
- Tennis match analysis and statistics
- Automated highlight generation
- Player training and coaching tools
- Ball trajectory tracking
- Sports analytics dashboards
- Action recognition pipelines

⚠️ **Not Recommended:**
- Real-time umpiring decisions (use as assistance only)
- Safety-critical applications
- Detection of non-yellow tennis balls without fine-tuning

## Example Results

### Sample Detections

**Precision: 84.3%** - When the model detects a ball, it's correct 84% of the time
**Recall: 59.5%** - The model detects approximately 6 out of 10 tennis balls

### Confidence Interpretation

| Confidence Range | Interpretation |
|------------------|----------------|
| > 0.7 | High confidence - very likely a tennis ball |
| 0.5 - 0.7 | Medium confidence - probably a tennis ball |
| 0.3 - 0.5 | Low confidence - possible tennis ball |
| < 0.3 | Very low confidence - likely false positive |

## CourtSide Computer Vision Suite

This model is part of the **CourtSide Computer Vision** project, a comprehensive tennis analysis system featuring:
- 🎾 Ball detection (this model)
- 👤 Player detection and tracking
- 🎯 Action recognition (forehand, backhand, serve, etc.)
- 📊 Match statistics generation

## Model Card Authors

- **Developed by**: Vuong
- **Model date**: November 2024
- **Model version**: v0.1
- **Model type**: Object Detection (YOLOv11)

## Citations

### This Model

If you use this model, please cite:
```bibtex
@misc{courtsidecv_v0.1_2024,
  title={CourtSide Computer Vision v0.1: Tennis Ball Detection with YOLOv11},
  author={Vuong},
  year={2024},
  publisher={Hugging Face},
  howpublished={\url{https://huggingface.co/...}}
}
```

### Dataset

This model was trained using the Tennis Ball Detection dataset. Please cite:
```bibtex
@misc{tennis-ball-detection_dataset,
  title = {tennis ball detection Dataset},
  type = {Open Source Dataset},
  author = {Viren Dhanwani},
  howpublished = {\url{https://universe.roboflow.com/viren-dhanwani/tennis-ball-detection}},
  url = {https://universe.roboflow.com/viren-dhanwani/tennis-ball-detection},
  journal = {Roboflow Universe},
  publisher = {Roboflow},
  year = {2023},
  month = {feb},
  note = {visited on 2024-11-20}
}
```

## License

MIT License - Free for commercial and academic use.

## Acknowledgments

- Built with [Ultralytics YOLOv11](https://github.com/ultralytics/ultralytics)
- Dataset by Viren Dhanwani via [Roboflow Universe](https://universe.roboflow.com/viren-dhanwani/tennis-ball-detection)
- Part of the CourtSide Computer Vision project for tennis analysis

## Contact & Support

For questions, issues, or collaboration:
- GitHub Issues: [tennis_analysis/issues](https://github.com/...)
- Model Updates: Check for newer versions on Hugging Face

## Related Models

Coming soon in the CourtSide Computer Vision suite:
- CourtSide CV - Player Detection
- CourtSide CV - Racket Detection
- CourtSide CV - Court Segmentation

## Model Changelog

### v0.1 (2024-11-20)
- Initial release
- YOLOv11n architecture
- mAP@50: 67.87%
- 520 training images from Roboflow dataset
- Optimized for tennis ball detection in match footage

---

**Model Size**: 5.4 MB  
**Inference Speed**: 10-65ms (device dependent)  
**Supported Formats**: PyTorch (.pt), ONNX, TensorRT, CoreML

🎾 Ready for production use in tennis analysis applications!