README.md

metadata

title: Athletic Ability Analysis
emoji: 🏃‍♂️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.32.2
app_file: app.py
pinned: false
license: mit

🏃‍♂️ Athletic Ability Analysis

A powerful web application that analyzes athletic jump performance from videos using computer vision and pose estimation. Upload a video file or provide a YouTube URL to get detailed metrics about your jump height, flight time, and overall athletic performance.

✨ Features

• 🎥 YouTube Integration: Analyze videos directly from YouTube URLs
• 📁 File Upload: Support for MP4, AVI, MOV, and other video formats
• 📊 Detailed Analytics: Get jump height, flight time, normalized rise, and performance insights
• 🎯 Real-time Processing: Fast analysis using Google's MediaPipe pose estimation
• 📱 Modern Interface: Beautiful, responsive Gradio interface
• 🔬 Scientific Accuracy: Precise biomechanical analysis

🚀 Live Demo

Try the live demo on Hugging Face Spaces: Athletic Ability Analysis

📊 How It Works

1. Pose Detection: Uses Google's MediaPipe to detect human pose landmarks in each video frame
2. Hip Tracking: Tracks the midpoint between left and right hip joints throughout the video
3. Jump Analysis: Calculates jump metrics based on hip trajectory:
   • Jump Height: Vertical distance from crouch to apex (in cm)
   • Flight Time: Duration of airborne phase (in seconds)
   • Normalized Rise: Jump height relative to body position (0-1 scale)
   • Performance Insights: Contextual feedback based on performance level

🛠️ Technology Stack

• Backend: Python with OpenCV, NumPy, and MediaPipe
• Frontend: Gradio for beautiful, interactive web interface
• Video Processing: yt-dlp for YouTube downloads, OpenCV for video analysis
• Deployment: Hugging Face Spaces

🚀 Deploy to Hugging Face Spaces

Quick Deployment

1. Fork this repository on GitHub
2. Create a new Space on Hugging Face Spaces
3. Connect your GitHub repo to the Space
4. Set the Space type to "Gradio"
5. Wait for automatic deployment

Manual Deployment

1. Clone the repository:

   git clone https://github.com/YOUR_USERNAME/athletic-ability-analysis
   cd athletic-ability-analysis
   

2. Create a new Space on Hugging Face Spaces

3. Upload files to your Space:

   • app.py (main application)
   • requirements.txt (dependencies)
   • README.md (this file)

4. Space will automatically deploy using Gradio

📁 Project Structure

athletic-ability-analysis/
├── app.py               # Main Gradio application
├── requirements.txt     # Python dependencies
├── README.md           # This file (with HF Spaces header)
└── .gitignore         # Git ignore file

🎯 Usage

Web Interface

1. Visit your Hugging Face Space URL
2. Enter your height in centimeters for accurate calculations
3. Choose input method:
   • YouTube: Paste a YouTube URL containing a jump video
   • File Upload: Upload a video file from your device
4. Click "Analyze" and wait for processing
5. View detailed results including metrics and performance insights

Supported Video Formats

• YouTube: Any public YouTube video URL
• Upload: MP4, AVI, MOV, MKV, WebM

📝 Video Requirements

For optimal results, ensure your videos meet these criteria:

• 🎯 Full Body Visible: Person should be completely visible throughout the jump
• 💡 Good Lighting: Clear visibility with minimal shadows
• 🎬 Clean Background: Minimal clutter for better pose detection
• ⏱️ Optimal Duration: 3-30 seconds works best
• 📐 Vertical Jumps: Straight vertical jumps produce most accurate results
• 🔓 Public Access: For YouTube videos, ensure they're not private

📊 Performance Metrics

The app analyzes and provides:

• Jump Height (cm): Absolute vertical distance based on your body height
• Flight Time (s): Duration of airborne phase
• Normalized Rise: Jump efficiency relative to body size
• Performance Level: Contextual feedback (Excellent/Good/Moderate/Starting)
• Training Insights: Personalized recommendations

🔬 Technical Details

• Pose Estimation: MediaPipe Pose with 33 body landmarks
• Processing: Real-time frame-by-frame analysis
• Smoothing: Moving average filtering for noise reduction
• Calculations: Biomechanically accurate jump metrics
• Performance: Optimized for cloud deployment

⚠️ Limitations

• Processing Time: Large videos may take 2-5 minutes to process
• File Size: Recommended maximum 100MB for uploads
• Pose Visibility: Person must be clearly visible throughout the jump
• Jump Type: Optimized for vertical jumps (not broad jumps)

🔧 Local Development

To run locally:

1. Install dependencies:

   pip install -r requirements.txt
   

2. Run the application:

   python app.py
   

3. Open in browser: Gradio will provide a local URL

🤝 Contributing

Contributions are welcome! Please feel free to:

• Submit bug reports and feature requests
• Improve documentation
• Add new analysis features
• Optimize performance

📄 License

This project is open source and available under the MIT License.

🆘 Support & Troubleshooting

If you encounter issues:

1. Video Quality: Ensure good lighting and clear visibility
2. YouTube URLs: Make sure the video is public and accessible
3. File Formats: Use supported video formats (MP4, AVI, MOV, etc.)
4. Processing Time: Be patient with large or high-resolution videos
5. Pose Detection: Person should be fully visible during the jump

🙏 Acknowledgments

• Google MediaPipe for state-of-the-art pose estimation
• OpenCV for computer vision processing
• yt-dlp for YouTube video downloading
• Gradio for the beautiful web interface
• Hugging Face for hosting and deployment platform

📈 Example Results

🎉 Jump Analysis Results

📊 Performance Metrics
- Jump Height: 52.34 cm
- Flight Time: 0.623 seconds  
- Normalized Rise: 0.387 (38.7%)

🔥 Excellent jump height! This is above average performance.
⏱️ Great flight time! Shows good explosive power.