Exercise Rep Tracker

Exercise rep tracker with real-time pose estimation, rep counting, form quality scoring, and spinal curvature analysis. Supports squat, deadlift, and bench press via video files or live webcam. Built with OpenCV, MediaPipe, and tkinter.

Features

• Multi-Exercise Support: Squat (knee angle), deadlift (hip angle), bench press (elbow angle)
• Pose Estimation: MediaPipe detects 33 body landmarks per frame
• Rep Counting: 4-state machine with hysteresis for accurate counting
• Form Quality Scoring: Per-rep 0-100 score based on weighted biomechanical factors (depth, symmetry, tempo, torso angle, lockout, elbow flare, etc.)
• Bar Path Tracking: Tracks barbell position via proxy landmarks, scores path straightness (vertical for squat/deadlift, diagonal for bench)
• Rep Velocity: Concentric/eccentric phase timing, angular velocity, and tempo ratio
• Spinal Curvature Detection: Monitors torso lean, head-shoulder offset, and lateral deviation during squat and deadlift
• Live Webcam Mode: Real-time tracking with mirror support
• Video Overlay: HUD with rep count, angle sparkline, depth bar, quality gauge, factor breakdown, bar path trail, spine indicator
• GUI: Dark-themed tkinter interface with live video preview, threshold sliders, rep history, and session statistics

Requirements

• Python 3.7+
• opencv-python
• mediapipe
• numpy
• Pillow

Installation

1. Clone the repository

2. Create and activate a virtual environment:

   Windows:

   python -m venv .venv
   .venv\Scripts\activate

   macOS/Linux:

   python3 -m venv .venv
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

Usage

GUI (Recommended)

python gui.py

• Select Video File or Live Webcam mode
• Choose an exercise from the dropdown (thresholds auto-update)
• Adjust up/down angle thresholds if needed
• Click Start Processing and watch real-time stats

CLI

# Basic usage
python main.py input_video.mp4

# Specify exercise
python main.py input_video.mp4 --exercise deadlift

# Save annotated output video
python main.py input_video.mp4 --exercise bench -o output.mp4

# Custom thresholds
python main.py input_video.mp4 --standing-threshold 165 --squatting-threshold 85

CLI Arguments

Argument	Description
input_video	Path to input video file (required)
--exercise	Exercise type: squat, deadlift, bench (default: squat)
-o, --output	Path to save annotated output video
--standing-threshold	Angle threshold for up position (degrees)
--squatting-threshold	Angle threshold for down position (degrees)

How It Works

1. Pose Detection -- MediaPipe detects body landmarks in each frame
2. Angle Calculation -- Computes joint angles (knee, hip, or elbow) from landmark triples
3. State Machine -- Tracks transitions: UP -> GOING_DOWN -> DOWN -> GOING_UP -> UP
4. Rep Counting -- Counts a rep only on completing the full cycle
5. Quality Scoring -- Evaluates form factors (depth, symmetry, tempo, etc.) and produces a 0-100 score per rep
6. Bar Path Tracking -- Records barbell position through each rep via wrist/shoulder proxy landmarks, scores deviation from ideal path
7. Velocity Analysis -- Splits each rep into eccentric/concentric phases, computes angular velocity and tempo ratio
8. Spine Analysis -- Monitors torso lean and curvature during squat and deadlift (disabled for bench)
9. Visualization -- Draws all metrics as a HUD overlay on the video frame

Running Tests

python -m pytest tests.py -v
# or
python tests.py

Tips

• Camera Angle: Side or front-side view works best
• Lighting: Good lighting improves pose detection accuracy
• Visibility: Ensure the relevant joints are visible (hips/knees/ankles for squat, shoulders/elbows/wrists for bench)
• Threshold Tuning: If reps aren't counting, adjust the up/down thresholds in the GUI

Adding a New Exercise

Add an entry to the EXERCISES dict in exercises.py with:

• joints, angle_triple, angle_name -- which body parts to track
• up_threshold, down_threshold -- angle thresholds for the state machine
• states -- custom state labels
• scorer_factors, scorer_params -- quality scoring configuration
• bar_path -- bar position tracking configuration
• spine_enabled -- whether to run spinal curvature analysis