notebooks | documentation | papers

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: Your first steps in understanding and setting up SportsLabKit.
• User Guide: A comprehensive guide for effectively using the toolkit in real-world scenarios.
• Core Components: Deep dive into the essential elements that make up SportsLabKit, including tracking algorithms and DataFrame wrappers.

Installation

To install SportsLabKit, simply run:

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:

import sportslabkit as slk

from sportslabkit.mot import SORTTracker

# Initialize your camera and models
cam = slk.Camera(path_to_mp4)
det_model = slk.detection_model.load('YOLOv8x', imgsz=640)
motion_model = slk.motion_model.load('KalmanFilter', dt=1/30, process_noise=10000, measurement_noise=10)

# Configure and execute the tracker
tracker = SORTTracker(detection_model=det_model, motion_model=motion_model)
tracker.track(cam[:100])
res = tracker.to_bbdf()

save_path = "assets/tracking_results.mp4"
res.visualize_frames(cam.video_path, save_path)

# 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 for more information.

Contributors

Atom Scott 🚧

Ikuma Uchida ✅

shunsuke-iwashita 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

Related Papers

SoccerTrack: A Dataset and Tracking Algorithm for Soccer with Fish-eye and Drone Videos Atom Scott*, Ikuma Uchida*, Masaki Onishi, Yoshinari Kameda, Kazuhiro Fukui, Keisuke Fujii Presented at CVPR Workshop on Computer Vision for Sports (CVSports'22). *Authors contributed equally.

See papers that cite SoccerTrack on Google Scholar.

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}
}