Running Analysis Project

Overview

This project provides a real-time running analysis tool using computer vision and pose estimation techniques. It captures video input from a camera, analyzes the runner's form, and provides instant feedback on various biomechanical metrics.

Features

• Real-time pose estimation using multiple model options (MoveNet, BlazePose)
• Calculation of key running metrics (e.g., head angle, trunk angle, knee angles, arm swing)
• Visual feedback with adjustable display modes (angles, metrics, recommendations)
• Audio feedback for immediate form corrections
• Metric logging for post-run analysis
• Video recording and playback functionality

Requirements

• Python 3.12+
• uv (Python package manager)

Installation

1. Clone the repository:

   git clone https://github.com/your-username/running-analysis.git
   cd running-analysis
   

2. Install the required dependencies:

   uv sync
   

3. Download the necessary model files and place them in the models/ directory.

Usage

Run the main script with desired options:

uv run python main.py --model_type blazepose --side right --runner_height 182

Options:

• --model_type: Choose from 'movenet' or 'blazepose' (default: blazepose)
• --side: 'left' or 'right', depending on which side of the runner is facing the camera (default: right)
• --runner_height: Height of the runner in cm (default: 182)
• --sex: 'male' or 'female'; selects the torso-length anthropometric ratio (default: male)

Keypoint Mapping

All models output keypoints using the COCO 17-keypoint format:

Index	Keypoint	Index	Keypoint
0	nose	9	left_wrist
1	left_eye	10	right_wrist
2	right_eye	11	left_hip
3	left_ear	12	right_hip
4	right_ear	13	left_knee
5	left_shoulder	14	right_knee
6	right_shoulder	15	left_ankle
7	left_elbow	16	right_ankle
8	right_elbow

BlazePose natively uses 33 landmarks but is converted to this format via BlazePoseModel._convert_to_movenet_format().

Key Components

• core/analyzer.py: Main analysis loop and frame processing
• models/: Contains different pose estimation model implementations
• metrics/: Calculates various running metrics
• visualization/: Handles display of metrics and pose on video frames
• feedback/: Provides recommendations and audio feedback
• utils/: Utility functions for angle calculation, filtering, etc.

Customization

• Adjust thresholds in feedback/assessment_calculator.py to customize metric assessments
• Modify feedback/recommendations.py to change the recommendation logic
• Update core/config.py for global configuration settings

Post-Run Analysis

After each session:

1. Options to review recorded video
2. View summary of logged metrics
3. Save or delete session data

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgements

• TensorFlow for MoveNet implementation
• Google's MediaPipe for BlazePose
• Contributors to the Lite-HRNet project