README.md

---
language: en
license: mit
tags:
  - yolo
  - yolov11
  - object-detection
  - tennis
  - racket
  - sports
  - computer-vision
  - pytorch
  - ultralytics
  - courtside
datasets:
  - dataset1-yx5qr
metrics:
  - precision
  - recall
  - mAP
library_name: ultralytics
pipeline_tag: object-detection
model-index:
- name: CourtSide Computer Vision v0.2
  results:
  - task:
      type: object-detection
    metrics:
    - type: mAP@50
      value: 66.67
    - type: precision
      value: 71
    - type: recall
      value: 44
---

# CourtSide Computer Vision v0.2 - Racket Detection 🎾

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

## Model Details

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

## Performance Metrics

Evaluated on validation set (66 images):

| Metric | Value |
|--------|-------|
| **mAP@50** | **66.67%** |
| **mAP@50-95** | 33.33% |
| **Precision** | ~71% |
| **Recall** | ~44% |
| **Inference Speed** (M4 Pro) | ~10ms |

## Training Details

### Dataset

This model was trained on the **dataset1** by Tesi, available on Roboflow Universe.

- **Training images**: 582
- **Validation images**: 66
- **Test images**: 55
- **Total**: 703 annotated images
- **Annotation format**: YOLO format (bounding boxes)
- **Source**: [Roboflow Universe - Dataset1](https://universe.roboflow.com/tesi-mpvmr/dataset1-yx5qr)

### 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: ~26 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

# Load CourtSide Computer Vision v0.2 model
model = YOLO('Davidsv/CourtSide-Computer-Vision-v0.2')

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

# 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"Racket detected at [{x1:.0f}, {y1:.0f}, {x2:.0f}, {y2:.0f}] with {confidence:.2%} confidence")
```

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

model = YOLO('Davidsv/CourtSide-Computer-Vision-v0.2')

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

# Track rackets across frames
results = model.track(
    source='tennis_match.mp4',
    conf=0.4,
    tracker='bytetrack.yaml'
)
```

### Command Line
```bash
# Predict on image
yolo detect predict model=Davidsv/CourtSide-Computer-Vision-v0.2 source=image.jpg conf=0.4

# Predict on video
yolo detect predict model=Davidsv/CourtSide-Computer-Vision-v0.2 source=video.mp4 conf=0.4 save=True

# Track rackets in video
yolo detect track model=Davidsv/CourtSide-Computer-Vision-v0.2 source=video.mp4 conf=0.4

# Validate model
yolo detect val model=Davidsv/CourtSide-Computer-Vision-v0.2 data=dataset.yaml
```

## Recommended Hyperparameters

### Inference Settings
```python
# Balanced (recommended)
conf_threshold = 0.40  # Confidence threshold
iou_threshold = 0.45   # NMS IoU threshold
max_det = 10           # Maximum detections per image (usually 2-4 rackets)

# High precision (fewer false positives)
conf_threshold = 0.55
iou_threshold = 0.45
max_det = 8

# High recall (detect more rackets, more false positives)
conf_threshold = 0.30
iou_threshold = 0.40
max_det = 15
```

## Limitations

- **Motion blur**: Rackets in very fast motion may be harder to detect
- **Occlusion**: Partially hidden rackets (behind player, net, etc.) may not be detected
- **Angles**: Extreme viewing angles may reduce detection accuracy
- **Racket types**: Trained on standard tennis rackets, may not generalize to unusual designs
- **Similar objects**: May occasionally detect similar elongated objects

## Model Biases

- Trained on professional and amateur match footage
- Better performance on standard racket designs and colors
- Dataset may have court-type or player-level biases
- Optimized for typical tennis camera angles

## Use Cases

✅ **Recommended:**
- Tennis match analysis and statistics
- Player technique analysis
- Swing detection and tracking
- Automated coaching feedback
- Sports analytics dashboards
- Training video analysis
- Action recognition pipelines (combined with ball detection)

⚠️ **Not Recommended:**
- Real-time officiating decisions
- Safety-critical applications
- Detection of non-tennis rackets without fine-tuning

## Example Results

### Sample Detections

**mAP@50: 66.67%** - Good detection performance on typical tennis scenes  
**Precision: ~71%** - When detected, about 7 out of 10 detections are correct  
**Recall: ~44%** - Detects approximately 4-5 out of 10 rackets

### Confidence Interpretation

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

## CourtSide Computer Vision Suite

This model is part of the **CourtSide Computer Vision** project for comprehensive tennis analysis:

### Available Models

- **v0.1** - Tennis Ball Detection ([Davidsv/CourtSide-Computer-Vision-v0.1](https://huggingface.co/Davidsv/CourtSide-Computer-Vision-v0.1))
- **v0.2** - Tennis Racket Detection (this model)

### Combined Usage Example
```python
from ultralytics import YOLO

# Load both CourtSide CV models
model_ball = YOLO('Davidsv/CourtSide-Computer-Vision-v0.1')      # Ball detection
model_racket = YOLO('Davidsv/CourtSide-Computer-Vision-v0.2')    # Racket detection

# Detect both in same image
ball_results = model_ball.predict('match.jpg', conf=0.3)
racket_results = model_racket.predict('match.jpg', conf=0.4)

# Combine detections for comprehensive analysis
print(f"Balls detected: {len(ball_results[0].boxes)}")
print(f"Rackets detected: {len(racket_results[0].boxes)}")
```

## Advanced Usage

### Detect and Track Swing Actions
```python
from ultralytics import YOLO
import cv2

model = YOLO('Davidsv/CourtSide-Computer-Vision-v0.2')
video = cv2.VideoCapture('match.mp4')

frame_count = 0
racket_positions = []

while True:
    ret, frame = video.read()
    if not ret:
        break

    # Detect rackets
    results = model.predict(frame, conf=0.4, verbose=False)

    # Track racket movement for swing analysis
    for box in results[0].boxes:
        x1, y1, x2, y2 = box.xyxy[0]
        center_x = (x1 + x2) / 2
        center_y = (y1 + y2) / 2
        racket_positions.append((frame_count, center_x, center_y))

    frame_count += 1

# Analyze swing patterns
print(f"Total racket detections: {len(racket_positions)}")
```

### Full Tennis Analysis Pipeline
```python
from ultralytics import YOLO

# Load all CourtSide models
ball_model = YOLO('Davidsv/CourtSide-Computer-Vision-v0.1')
racket_model = YOLO('Davidsv/CourtSide-Computer-Vision-v0.2')

# Process video with both models
ball_results = ball_model.track('match.mp4', conf=0.3)
racket_results = racket_model.track('match.mp4', conf=0.4)

# Combine for action recognition and analytics
```

## Model Card Authors

- **Developed by**: Davidsv (Vuong)
- **Model date**: November 2024
- **Model version**: v0.2
- **Model type**: Object Detection (YOLOv11)
- **Part of**: CourtSide Computer Vision Suite

## Citations

### This Model

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

### Dataset

This model was trained using the dataset1 dataset. Please cite:
```bibtex
@misc{dataset1-yx5qr_dataset,
  title = {dataset1 Dataset},
  type = {Open Source Dataset},
  author = {Tesi},
  howpublished = {\url{https://universe.roboflow.com/tesi-mpvmr/dataset1-yx5qr}},
  url = {https://universe.roboflow.com/tesi-mpvmr/dataset1-yx5qr},
  journal = {Roboflow Universe},
  publisher = {Roboflow},
  year = {2023},
  month = {mar},
  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 Tesi via [Roboflow Universe](https://universe.roboflow.com/tesi-mpvmr/dataset1-yx5qr)
- Part of the CourtSide Computer Vision project for tennis analysis

## Contact & Support

For questions, issues, or collaboration:
- Hugging Face: [@Davidsv](https://huggingface.co/Davidsv)
- Model Updates: Check for newer versions in the CourtSide CV series

## Common Issues & Solutions

### Issue: Low Recall (Missing Rackets)
**Solution**: Lower confidence threshold to 0.30-0.35

### Issue: Too Many False Positives
**Solution**: Increase confidence threshold to 0.50-0.55

### Issue: Missed Rackets in Fast Motion
**Solution**: Use `model.track()` instead of `model.predict()` for better temporal consistency

### Issue: Multiple Detections per Racket
**Solution**: Increase NMS IoU threshold to 0.50-0.55

### Issue: Poor Performance on Unusual Angles
**Solution**: Consider fine-tuning on your specific camera setup or use data augmentation

## Model Changelog

### v0.2 (2024-11-20)
- Initial release of racket detection model
- YOLOv11n architecture
- mAP@50: 66.67%
- 703 training images from Roboflow dataset
- Optimized for standard tennis racket detection
- Part of CourtSide Computer Vision suite

---

**Model Size**: 5.4 MB  
**Inference Speed**: 10-65ms (device dependent)  
**Supported Formats**: PyTorch (.pt), ONNX, TensorRT, CoreML  
**Model Hub**: [Davidsv/CourtSide-Computer-Vision-v0.2](https://huggingface.co/Davidsv/CourtSide-Computer-Vision-v0.2)

🎾 Ready for production use in tennis analysis applications!