README.md

---
license: mit
tags:
- yolov8
- object-detection
- computer-vision
- sports-analytics
- football
datasets:
- roboflow
---

# ⚽ P.U.L.S.E AI Detection Models

These are the official pre-trained object detection models for **[P.U.L.S.E AI (Positional & Universal Live Statistical Engine)](https://github.com/AurevinP/PULSE_AI)**. 

They are based on the Ultralytics YOLOv8 architecture and fine-tuned specifically for football (soccer) analytics.

## Available Models

| Filename | Base Model | Purpose |
|---|---|---|
| [ball_tracker_200_epoch_92L_25M.pt](AurevinP/PULSE_AI_Models/ball_tracker_200_epoch_92L_25M.pt) | YOLOv8 | Detects and tracks the football on the pitch. |
| [yolov8s_player_tracker.pt](AurevinP/PULSE_AI_Models/yolov8s_player_tracker.pt) | YOLOv8s | Detects players, goalkeepers, and referees. |

> **Note:** The team clustering model (SigLIP + UMAP + KMeans) used by P.U.L.S.E AI is trained dynamically from the input video at runtime and does not require pre-downloaded weights.

## How to Use with P.U.L.S.E AI

If you are using the P.U.L.S.E AI repository, these models will be downloaded automatically when you run the pipeline setup, or you can download them manually using the built-in script:

```bash
# From the root of the PULSE AI repository:
python download_models.py
```

## Manual Python Usage

If you wish to use these weights independently of the main P.U.L.S.E AI pipeline, you can load them directly via the `ultralytics` library:

```python
from huggingface_hub import hf_hub_download
from ultralytics import YOLO

# 1. Download the ball tracker
ball_model_path = hf_hub_download(
    repo_id="AurevinP/PULSE_AI_Models", 
    filename="ball_tracker_200_epoch_92L_25M.pt"
)

# 2. Load into YOLO
model = YOLO(ball_model_path)

# 3. Run inference
results = model("path/to/football_video.mp4")
```