Ball Tracking & Kinematics Analysis

This project tracks a ball in high-speed footage using YOLO and analyzes its motion (position, velocity, acceleration).

Features

• Detects and tracks a ball in images or videos
• Supports image sequences (.tif, .png, .jpg) and video files
• Exports tracking data to CSV
• Optional debug video with annotations
• MATLAB script for kinematic analysis and visualization

Structure

• main.py — ball detection and tracking (YOLO-based)
• config.json — configuration (paths, FPS, model)
• ballCalc.m — post-processing and plots (trajectory, speed, acceleration)

Setup

pip install opencv-python numpy ultralytics

Place your YOLO model in:

models/

or just define which model to use and it should be auto downloaded into the folder.

Usage

1. Adjust paths and settings in config.json
2. Run tracking:

python main.py

3. Analyze results in MATLAB:

ballCalc.m

Output

• output/ball_tracking_results.csv — tracked positions
• output/ball_tracking_debug.mp4 — annotated video (optional)

MATLAB generates:

• Trajectory plot
• Position vs time
• Speed
• Acceleration

Notes

• Designed for high-speed recordings (e.g. 5000 FPS)
• Missing detections are interpolated in post-processing
• Uses YOLO tracking via ultralytics