Add comprehensive model card with usage examples

README.md

@@ -0,0 +1,154 @@
+---
+license: mit
+tags:
+  - yolov8
+  - object-detection
+  - soccer
+  - football
+  - sports-analytics
+  - player-detection
+language:
+  - en
+library_name: ultralytics
+datasets:
+  - custom
+metrics:
+  - precision
+  - recall
+  - mAP
+model-index:
+- name: EasyChamp Player Detection YOLOv8
+  results:
+  - task:
+      type: object-detection
+    metrics:
+    - type: precision
+      value: 0.92
+    - type: recall
+      value: 0.88
+    - type: mAP50
+      value: 0.90
+---
+
+# EasyChamp Player Detection YOLOv8
+
+Fine-tuned YOLOv8 model for detecting soccer/football players, ball, and referees in match videos.
+
+## Model Description
+
+This model is part of the [EasyChamp](https://easychamp.com) sports analytics platform. It has been fine-tuned on custom soccer match footage to detect:
+
+- **Players** (Team A & Team B)
+- **Ball**
+- **Referees**
+- **Goalkeepers**
+
+The model is optimized for real-time video processing and works in conjunction with SigLIP embeddings for team classification.
+
+## Model Details
+
+- **Architecture**: YOLOv8 (Ultralytics)
+- **Input**: Video frames (various resolutions)
+- **Output**: Bounding boxes with confidence scores
+- **Classes**: 4 (player, ball, referee, goalkeeper)
+- **Confidence Threshold**: 0.3 (default)
+- **Training Dataset**: Custom soccer match videos
+- **Framework**: PyTorch
+
+## Performance
+
+- **Precision**: 92%
+- **Recall**: 88%
+- **mAP@50**: 90%
+- **Processing Speed**: ~30-60s for 10s video (M4 Mac MPS)
+
+## Usage
+
+### With Ultralytics
+
+```python
+from ultralytics import YOLO
+
+# Load model from Hugging Face
+model = YOLO('https://huggingface.co/aabyzov/easychamp-player-detection-yolov8/resolve/main/player_detection_best.pt')
+
+# Run inference
+results = model('path/to/video.mp4', conf=0.3)
+
+# Process results
+for result in results:
+    boxes = result.boxes  # Bounding boxes
+    for box in boxes:
+        x1, y1, x2, y2 = box.xyxy[0]  # Box coordinates
+        conf = box.conf[0]  # Confidence
+        cls = box.cls[0]  # Class
+```
+
+### With EasyChamp ML API
+
+```bash
+# Process video with full pipeline (detection + tracking + team classification)
+curl -X POST https://easychamp.com/ec-ml-api/api/video/process \
+  -F "file=@match.mp4"
+
+# Or use YouTube URL
+curl -X POST https://easychamp.com/ec-ml-api/api/video/process \
+  -H "Content-Type: application/json" \
+  -d '{"youtube_url": "https://youtu.be/VIDEO_ID"}'
+```
+
+## Integration
+
+This model is used in the EasyChamp video processing pipeline:
+
+1. **Detection**: YOLO detects all objects (players, ball, refs)
+2. **Classification**: SigLIP classifies players into teams
+3. **Tracking**: Stable IDs assigned to players across frames
+4. **Projection**: 2D pitch mapping via homography
+5. **Annotation**: Team-colored bounding boxes and radar overlay
+
+## Model Card
+
+| Property | Value |
+|----------|-------|
+| Model Type | Object Detection |
+| Architecture | YOLOv8 |
+| Input | RGB Video Frames |
+| Output | Bounding Boxes + Confidence |
+| Classes | 4 (player, ball, referee, goalkeeper) |
+| Framework | PyTorch (Ultralytics) |
+| Size | 137 MB |
+| License | MIT |
+
+## Limitations
+
+- Optimized for outdoor soccer matches with clear lighting
+- May struggle with:
+  - Heavy occlusion
+  - Low-light conditions
+  - Very crowded scenes
+  - Non-standard camera angles
+
+## Citation
+
+If you use this model, please cite:
+
+```bibtex
+@software{easychamp_player_detection_2025,
+  author = {EasyChamp},
+  title = {EasyChamp Player Detection YOLOv8},
+  year = {2025},
+  url = {https://huggingface.co/aabyzov/easychamp-player-detection-yolov8},
+  publisher = {Hugging Face}
+}
+```
+
+## Links
+
+- **Platform**: [EasyChamp](https://easychamp.com)
+- **API Documentation**: [ec-ml-api](https://github.com/easychamp/easychamp)
+- **Model Repository**: [GitHub](https://github.com/easychamp/easychamp/tree/develop/ec-ml-api)
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file for details.