<div align="center">
<p>
<a align="center" href="" target="_blank">
<img
width="100%"
src="./docs/_static/sportslabkit-banner.png"
>
</a>
</p>
<br>
[notebooks](https://github.com/atomscott/sportslabkit/notebooks) | [documentation](https://sportslabkit.readthedocs.io/) | [papers](https://scholar.google.com/citations?user=bjSLu7wAAAAJ&hl=en)
<br>
[](https://soccertrack.readthedocs.io/en/latest/?badge=latest)
[](https://www.kaggle.com/datasets/atomscott/soccertrack)
[](https://paperswithcode.com/dataset/soccertrack-dataset)
[](https://pypi.org/project/soccertrack/)
</div>
# SportsLabKit
## Introduction
Meet SportsLabKit: The essential toolkit for advanced sports analytics. Designed for pros and amateurs alike, we convert raw game footage into actionable data.
We're kicking off with soccer and expanding to other sports soon. Need to quantify your game? Make human movement computable with SportsLabKit.
## Features
### Core Capabilities
- **High-Performance Tracking**: In-house implementations of SORT, DeepSORT, ByteTrack, and TeamTrack for object tracking in sports.
### Flexibility
- **Plug-and-Play Architecture**: Swap out detection and ReID models on the fly. Supported models include YOLOv8 and torch-ReID.
### Usability
- **2D Pitch Calibration**: Translate bounding boxes to 2D pitch coordinates.
- **DataFrame Wrappers**: `BoundingBoxDataFrame` and `CoordinatesDataFrame` for effortless manipulation and analysis of tracking data.
### Tutorials
- [**Get Started**](./notebooks/01_get_started): Your first steps in understanding and setting up SportsLabKit.
- [**User Guide**](./notebooks/02_user_guide): A comprehensive guide for effectively using the toolkit in real-world scenarios.
- [**Core Components**](./notebooks/03_core_components/): Deep dive into the essential elements that make up SportsLabKit, including tracking algorithms and DataFrame wrappers.
## Installation
To install SportsLabKit, simply run:
```bash
pip install SportsLabKit
```
> **Note**: We're in active development, so expect updates and changes.
## Example Usage
To get started with tracking your first game, follow this simple example:
```python
import sportslabkit as slk
# Initialize your camera and models
cam = slk.Camera(path_to_mp4)
det_model = slk.detection_model.load('YOLOv8x')
motion_model = slk.motion_model.load('KalmanFilter')
# Configure and execute the tracker
tracker = slk.mot.SORTTracker(detection_model=det_model, motion_model=motion_model)
bbdf = tracker.track(cam)
# The tracking data is now ready for analysis
```
The output is a `BoundingBoxDataFrame`, a multi-level Pandas DataFrame that contains Team ID, Player ID, and various attributes like bounding box dimensions. Each row is indexed by Frame ID for easy analysis. The DataFrame is also customizable, allowing you to adapt Team and Player IDs as needed.
## Roadmap
- **Better CV tools**: Implement state of the art tracking methods, add event detection etc.
- **Unified Data Representation**: In the pipeline are event data detection and a single DataFrame structure for both event and trajectory data.
- **Enhanced Compatibility**: Upcoming support for data export to standard formats for easy integration with other tools.
## Contributing
See the [Contributing Guide](./contributing.md) for more information.
## Contributors
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tbody>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://atomscott.me/"><img src="https://avatars.githubusercontent.com/u/22371492?v=4?s=100" width="100px;" alt="Atom Scott"/><br /><sub><b>Atom Scott</b></sub></a><br /><a href="#maintenance-AtomScott" title="Maintenance">🚧</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/IkumaUchida"><img src="https://avatars.githubusercontent.com/u/48281753?v=4?s=100" width="100px;" alt="Ikuma Uchida"/><br /><sub><b>Ikuma Uchida</b></sub></a><br /><a href="#tutorial-IkumaUchida" title="Tutorials">✅</a></td>
</tr>
</tbody>
</table>
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
## Related Papers
<table>
<td width=30% style='padding: 20px;'>
<a href="https://openaccess.thecvf.com/content/CVPR2022W/CVSports/papers/Scott_SoccerTrack_A_Dataset_and_Tracking_Algorithm_for_Soccer_With_Fish-Eye_CVPRW_2022_paper.pdf">
<img src='./docs/_static/paper_preview.jpg'/>
</a>
</td>
<td width=70%>
<p>
<b>SoccerTrack:</b><br>
A Dataset and Tracking Algorithm for Soccer with Fish-eye and Drone Videos
</p>
<p>
Atom Scott*, Ikuma Uchida*, Masaki Onishi, Yoshinari Kameda, Kazuhiro Fukui, Keisuke Fujii
</p>
<p>
<i> Presented at CVPR Workshop on Computer Vision for Sports (CVSports'22). *Authors contributed equally. </i>
</p>
<div>
<a href='https://openaccess.thecvf.com/content/CVPR2022W/CVSports/papers/Scott_SoccerTrack_A_Dataset_and_Tracking_Algorithm_for_Soccer_With_Fish-Eye_CVPRW_2022_paper.pdf'>
<img src='https://img.shields.io/badge/Paper-PDF-red?style=for-the-badge&logo=adobe-acrobat-reader'/>
</a>
<a href='https://github.com/AtomScott/SoccerTrack'>
<img src='https://img.shields.io/badge/Code-Page-blue?style=for-the-badge&logo=github'/>
</a>
<a href='https://soccertrack.readthedocs.io/'>
<img src='https://img.shields.io/badge/Documentation-Page-blue?style=for-the-badge&logo=read-the-docs'/>
</a>
</div>
</td>
</table>
See papers that cite SoccerTrack on [Google Scholar](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=13090652901875753929).
## Citation
```
@inproceedings{scott2022soccertrack,
title={SoccerTrack: A Dataset and Tracking Algorithm for Soccer With Fish-Eye and Drone Videos},
author={Scott, Atom and Uchida, Ikuma and Onishi, Masaki and Kameda, Yoshinari and Fukui, Kazuhiro and Fujii, Keisuke},
booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
pages={3569--3579},
year={2022}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/AtomScott/SportsLabKit",
"name": "sportslabkit",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "sports,analytics,data,science,machine,learning",
"author": "Atom Scott",
"author_email": "atom.james.scott@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a1/19/57c166b7167fe865f2b74d578be8b297c778db450301e78215653c8b0cab/sportslabkit-0.3.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <p>\n <a align=\"center\" href=\"\" target=\"_blank\">\n <img\n width=\"100%\"\n src=\"./docs/_static/sportslabkit-banner.png\"\n >\n </a>\n </p>\n <br>\n\n [notebooks](https://github.com/atomscott/sportslabkit/notebooks) | [documentation](https://sportslabkit.readthedocs.io/) | [papers](https://scholar.google.com/citations?user=bjSLu7wAAAAJ&hl=en)\n\n <br>\n\n [](https://soccertrack.readthedocs.io/en/latest/?badge=latest) \n [](https://www.kaggle.com/datasets/atomscott/soccertrack)\n [](https://paperswithcode.com/dataset/soccertrack-dataset)\n [](https://pypi.org/project/soccertrack/)\n\n</div>\n\n# SportsLabKit\n\n## Introduction\n\nMeet SportsLabKit: The essential toolkit for advanced sports analytics. Designed for pros and amateurs alike, we convert raw game footage into actionable data.\n\nWe're kicking off with soccer and expanding to other sports soon. Need to quantify your game? Make human movement computable with SportsLabKit.\n\n\n## Features\n\n### Core Capabilities\n- **High-Performance Tracking**: In-house implementations of SORT, DeepSORT, ByteTrack, and TeamTrack for object tracking in sports.\n\n### Flexibility\n- **Plug-and-Play Architecture**: Swap out detection and ReID models on the fly. Supported models include YOLOv8 and torch-ReID.\n\n### Usability\n- **2D Pitch Calibration**: Translate bounding boxes to 2D pitch coordinates.\n \n- **DataFrame Wrappers**: `BoundingBoxDataFrame` and `CoordinatesDataFrame` for effortless manipulation and analysis of tracking data.\n\n### Tutorials\n- [**Get Started**](./notebooks/01_get_started): Your first steps in understanding and setting up SportsLabKit.\n- [**User Guide**](./notebooks/02_user_guide): A comprehensive guide for effectively using the toolkit in real-world scenarios.\n- [**Core Components**](./notebooks/03_core_components/): Deep dive into the essential elements that make up SportsLabKit, including tracking algorithms and DataFrame wrappers.\n\n## Installation\n\nTo install SportsLabKit, simply run:\n\n```bash\npip install SportsLabKit\n```\n\n> **Note**: We're in active development, so expect updates and changes.\n\n## Example Usage\n\nTo get started with tracking your first game, follow this simple example:\n\n```python\nimport sportslabkit as slk\n\n# Initialize your camera and models\ncam = slk.Camera(path_to_mp4)\ndet_model = slk.detection_model.load('YOLOv8x')\nmotion_model = slk.motion_model.load('KalmanFilter')\n\n# Configure and execute the tracker\ntracker = slk.mot.SORTTracker(detection_model=det_model, motion_model=motion_model)\nbbdf = tracker.track(cam)\n\n# The tracking data is now ready for analysis\n```\n\nThe output is a `BoundingBoxDataFrame`, a multi-level Pandas DataFrame that contains Team ID, Player ID, and various attributes like bounding box dimensions. Each row is indexed by Frame ID for easy analysis. The DataFrame is also customizable, allowing you to adapt Team and Player IDs as needed.\n\n\n\n## Roadmap\n\n- **Better CV tools**: Implement state of the art tracking methods, add event detection etc.\n\n- **Unified Data Representation**: In the pipeline are event data detection and a single DataFrame structure for both event and trajectory data.\n \n- **Enhanced Compatibility**: Upcoming support for data export to standard formats for easy integration with other tools.\n\n\n## Contributing\n\nSee the [Contributing Guide](./contributing.md) for more information.\n\n\n## Contributors\n\n<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->\n[](#contributors-)\n<!-- ALL-CONTRIBUTORS-BADGE:END -->\n\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n<table>\n <tbody>\n <tr>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://atomscott.me/\"><img src=\"https://avatars.githubusercontent.com/u/22371492?v=4?s=100\" width=\"100px;\" alt=\"Atom Scott\"/><br /><sub><b>Atom Scott</b></sub></a><br /><a href=\"#maintenance-AtomScott\" title=\"Maintenance\">\ud83d\udea7</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/IkumaUchida\"><img src=\"https://avatars.githubusercontent.com/u/48281753?v=4?s=100\" width=\"100px;\" alt=\"Ikuma Uchida\"/><br /><sub><b>Ikuma Uchida</b></sub></a><br /><a href=\"#tutorial-IkumaUchida\" title=\"Tutorials\">\u2705</a></td>\n </tr>\n </tbody>\n</table>\n\n<!-- markdownlint-restore -->\n<!-- prettier-ignore-end -->\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n\n## Related Papers\n\n<table>\n<td width=30% style='padding: 20px;'>\n<a href=\"https://openaccess.thecvf.com/content/CVPR2022W/CVSports/papers/Scott_SoccerTrack_A_Dataset_and_Tracking_Algorithm_for_Soccer_With_Fish-Eye_CVPRW_2022_paper.pdf\">\n<img src='./docs/_static/paper_preview.jpg'/>\n</a>\n</td>\n<td width=70%>\n <p>\n <b>SoccerTrack:</b><br>\n A Dataset and Tracking Algorithm for Soccer with Fish-eye and Drone Videos\n </p>\n <p>\n Atom Scott*, Ikuma Uchida*, Masaki Onishi, Yoshinari Kameda, Kazuhiro Fukui, Keisuke Fujii\n </p>\n <p>\n <i> Presented at CVPR Workshop on Computer Vision for Sports (CVSports'22). *Authors contributed equally. </i>\n </p>\n <div>\n <a href='https://openaccess.thecvf.com/content/CVPR2022W/CVSports/papers/Scott_SoccerTrack_A_Dataset_and_Tracking_Algorithm_for_Soccer_With_Fish-Eye_CVPRW_2022_paper.pdf'>\n <img src='https://img.shields.io/badge/Paper-PDF-red?style=for-the-badge&logo=adobe-acrobat-reader'/>\n </a>\n <a href='https://github.com/AtomScott/SoccerTrack'>\n <img src='https://img.shields.io/badge/Code-Page-blue?style=for-the-badge&logo=github'/>\n </a>\n <a href='https://soccertrack.readthedocs.io/'>\n <img src='https://img.shields.io/badge/Documentation-Page-blue?style=for-the-badge&logo=read-the-docs'/>\n </a>\n </div>\n</td>\n</table>\n\nSee papers that cite SoccerTrack on [Google Scholar](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=13090652901875753929).\n## Citation\n\n```\n@inproceedings{scott2022soccertrack,\n title={SoccerTrack: A Dataset and Tracking Algorithm for Soccer With Fish-Eye and Drone Videos},\n author={Scott, Atom and Uchida, Ikuma and Onishi, Masaki and Kameda, Yoshinari and Fukui, Kazuhiro and Fujii, Keisuke},\n booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},\n pages={3569--3579},\n year={2022}\n}\n```\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A Python package for sports analytics.",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://sportslabkit.readthedocs.io/en/latest/",
"Homepage": "https://github.com/AtomScott/SportsLabKit",
"Repository": "https://github.com/AtomScott/SportsLabKit"
},
"split_keywords": [
"sports",
"analytics",
"data",
"science",
"machine",
"learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "97f59999f1e06ff8d62a9a20ef6f3ecfa31ef7ceba5da61ed97d53b52f5a46d8",
"md5": "afdb7282cb6f201a2147ad454316959c",
"sha256": "ae8f8d3ffb6f2e148d44f2583246cb2da6bd39d4c30ce5c1d33cbe3b7141ac76"
},
"downloads": -1,
"filename": "sportslabkit-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "afdb7282cb6f201a2147ad454316959c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 175576,
"upload_time": "2023-09-04T18:12:38",
"upload_time_iso_8601": "2023-09-04T18:12:38.900267Z",
"url": "https://files.pythonhosted.org/packages/97/f5/9999f1e06ff8d62a9a20ef6f3ecfa31ef7ceba5da61ed97d53b52f5a46d8/sportslabkit-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a11957c166b7167fe865f2b74d578be8b297c778db450301e78215653c8b0cab",
"md5": "18d3a154a243e932741df8cc3feb1268",
"sha256": "ef857ad7c3fb320e81d1e462d7e90f4fda0a5b0bd11c6b070a065f3b2c342f2b"
},
"downloads": -1,
"filename": "sportslabkit-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "18d3a154a243e932741df8cc3feb1268",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 147696,
"upload_time": "2023-09-04T18:12:41",
"upload_time_iso_8601": "2023-09-04T18:12:41.207163Z",
"url": "https://files.pythonhosted.org/packages/a1/19/57c166b7167fe865f2b74d578be8b297c778db450301e78215653c8b0cab/sportslabkit-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-04 18:12:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AtomScott",
"github_project": "SportsLabKit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sportslabkit"
}
JSON
