Upload folder using huggingface_hub

README.md

@@ -0,0 +1,342 @@
+---
+language: en
+license: mit
+tags:
+  - yolo
+  - yolov11
+  - object-detection
+  - tennis
+  - racket
+  - sports
+  - computer-vision
+  - pytorch
+  - ultralytics
+datasets:
+  - custom
+metrics:
+  - precision
+  - recall
+  - mAP
+library_name: ultralytics
+pipeline_tag: object-detection
+---
+
+# YOLOv11 Tennis Racket Detection 🎾
+
+Fine-tuned YOLOv11n model for detecting tennis rackets in images and videos.
+
+## Model Details
+
+- **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% (estimated) |
+| **Recall** | ~44% (estimated) |
+| **Inference Speed** (M4 Pro) | ~10ms |
+
+## Training Details
+
+### Dataset
+- **Training images**: 582
+- **Validation images**: 66
+- **Test images**: 55
+- **Total**: 703 annotated images
+- **Annotation format**: YOLO format (bounding boxes)
+
+### 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
+from PIL import Image
+
+# Load model
+model = YOLO('path/to/raquette_subset_best.pt')
+
+# 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('path/to/raquette_subset_best.pt')
+
+# 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=raquette_subset_best.pt source=image.jpg conf=0.4
+
+# Predict on video
+yolo detect predict model=raquette_subset_best.pt source=video.mp4 conf=0.4 save=True
+
+# Track rackets in video
+yolo detect track model=raquette_subset_best.pt source=video.mp4 conf=0.4
+
+# Validate model
+yolo detect val model=raquette_subset_best.pt 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
+- Player technique analysis
+- Swing detection and tracking
+- Automated coaching feedback
+- Sports analytics and statistics
+- Training video analysis
+
+⚠️ **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
+
+### 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 |
+
+## Integration with Tennis Ball Detection
+
+This model works well in combination with the Tennis Ball Detection model:
+
+```python
+from ultralytics import YOLO
+
+# Load both models
+model_racket = YOLO('raquette_subset_best.pt')
+model_ball = YOLO('tennis_ball_subset_best.pt')
+
+# Detect both in same image
+racket_results = model_racket.predict('match.jpg', conf=0.4)
+ball_results = model_ball.predict('match.jpg', conf=0.3)
+
+# Combine detections for analysis
+print(f"Rackets: {len(racket_results[0].boxes)}")
+print(f"Balls: {len(ball_results[0].boxes)}")
+```
+
+## Advanced Usage
+
+### Detect Player Actions
+
+```python
+from ultralytics import YOLO
+import cv2
+
+model = YOLO('raquette_subset_best.pt')
+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 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)}")
+```
+
+## Model Card Authors
+
+- **Developed by**: Vuong
+- **Model date**: November 2024
+- **Model version**: 1.0
+- **Model type**: Object Detection (YOLOv11)
+
+## Citation
+
+If you use this model, please cite:
+
+```bibtex
+@misc{yolov11_tennis_racket_2024,
+  title={YOLOv11 Tennis Racket Detection},
+  author={Vuong},
+  year={2024},
+  publisher={Hugging Face},
+  howpublished={\url{https://huggingface.co/...}}
+}
+```
+
+## License
+
+MIT License - Free for commercial and academic use.
+
+## Acknowledgments
+
+- Built with [Ultralytics YOLOv11](https://github.com/ultralytics/ultralytics)
+- Trained on custom annotated tennis dataset
+- Part of the Tennis Analysis project
+
+## 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
+
+- [YOLOv11 Tennis Ball Detection](https://huggingface.co/...) - Companion model for ball detection
+
+## Common Issues & Solutions
+
+### Issue: Low Recall
+**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 Motion
+**Solution**: Use model tracking (`model.track()`) instead of simple prediction
+
+### Issue: Multiple Detections per Racket
+**Solution**: Increase NMS IoU threshold to 0.50-0.55
+
+## Model Changelog
+
+### v1.0 (2024-11-20)
+- Initial release
+- YOLOv11n architecture
+- mAP@50: 66.67%
+- 703 training images
+
+---
+
+**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!

config.txt

@@ -0,0 +1,5 @@
+# Configuration
+model_name: tennis-racket-yolov11
+framework: ultralytics
+architecture: yolov11n
+task: object-detection

example.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python
+# Example usage for tennis-racket-yolov11
+
+from ultralytics import YOLO
+
+# Load model from local file
+model = YOLO('model.pt')
+
+# Or download from Hugging Face (after upload)
+# model = YOLO('hf://YOUR_USERNAME/tennis-racket-yolov11/model.pt')
+
+# Predict on image
+results = model.predict('image.jpg', conf=0.3)
+results[0].show()
+
+# Predict on video
+results = model.predict('video.mp4', conf=0.3, save=True)

model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4ee842b864d5c4e5baae8239889ed416a29b6550a7a1b2cc2f4774550194e35b
+size 5453978

requirements.txt

@@ -0,0 +1,5 @@
+ultralytics>=8.0.0
+torch>=2.0.0
+opencv-python>=4.0.0
+pillow>=9.0.0
+numpy>=1.20.0