Metadata-Version: 2.4
Name: wunderscout
Version: 0.1.11
Summary: Scouting and vision tools for YOLO and sports analytics.
Project-URL: Homepage, https://github.com/qhuboo/wunderscout
Project-URL: Issues, https://github.com/qhuboo/wunderscout/issues
Keywords: scouting,sports-analytics,vision,yolo
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: matplotlib>=3.10.6
Requires-Dist: more-itertools>=10.8.0
Requires-Dist: networkx>=3.5
Requires-Dist: numpy>=2.3.2
Requires-Dist: opencv-python>=4.11.0.86
Requires-Dist: pandas>=2.3.2
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: roboflow>=1.2.7
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: scipy>=1.16.2
Requires-Dist: seaborn>=0.13.2
Requires-Dist: supervision>=0.26.1
Requires-Dist: torch>=2.8.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: transformers>=4.56.1
Requires-Dist: ultralytics>=8.3.193
Requires-Dist: umap-learn>=0.5.9.post2
Description-Content-Type: text/markdown

# wunderscout

A Python library for extracting player and ball tracking data from soccer match footage using YOLO, Siglip embeddings, and homography.

## Features

- **Detection & Tracking**: Uses YOLO for player/ball/pitch-keypoint detection and ByteTrack for temporal consistency.
- **Automated Team Clustering**: Groups players into teams using Siglip vision transformer embeddings and K-Means clustering via UMAP dimensionality reduction.
- **Pitch Mapping**: Transforms 2D image coordinates to a normalized 0-1 coordinate system using pitch keypoint homography.
- **Goalkeeper Attribution**: Assigns goalkeepers to teams based on proximity to team centroids.
- **Data Export**: Generates Home and Away CSV files containing frame-by-frame XY coordinates.

## Installation

```bash
uv add wunderscout
```

## Usage

The `ScoutingPipeline` class manages calibration, tracking, and data export.

```python
from wunderscout import ScoutingPipeline

# Initialize with paths to trained YOLO weights
pipeline = ScoutingPipeline(
    player_weights="players.pt",
    field_weights="pitch.pt"
)

# Run processing
pipeline.run(
    video_path="input_match.mp4",
    output_video_path="ouput_match.mp4"
)
```

## Internal Components

- **VisionEngine**: Manages YOLO models and generates Siglip embeddings for player crops.
- **PitchMapper**: Computes homography matrices based on a 32-point pitch configuration. Handles RANSAC-based perspective transforms.
- **TeamClassifier**: Performs unsupervised clustering on player embeddings. Uses a rolling consensus buffer to stabilize team assignments across frames.
- **DataExporter**: Formats tracking results into CSV files with frame indices and normalized pitch coordinates.

## Dependencies

- `ultralytics`
- `supervision`
- `transformers`
- `umap-learn`
- `scikit-learn`
- `opencv-python`

## License

MIT
