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
• 📊 Comprehensive Biomechanical Analysis: Jump height, flight time, peak power, force development, and more
• 🤖 AI Sports Coach: Get personalized sport recommendations and technique improvements
• 🎯 Real-time Processing: Fast analysis using Google's MediaPipe pose estimation
• 📱 Modern Interface: Beautiful, responsive Gradio interface with multiple analysis modes
• 🔬 Scientific Accuracy: Professional-grade biomechanical analysis
• ⚡ Advanced Metrics: Peak power output, rate of force development, impulse, and ground contact time

🚀 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. ⚠️ IMPORTANT: Set up API Key Environment Variable:
   • Go to your Space's "Settings" tab
   • Add a new "Secret" with name: GEMINI_API_KEY
   • Add your Gemini API key as the value
   • This keeps your API key secure and private
6. 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)
   • athletic_performance.py (analysis module)
   • requirements.txt (dependencies)
   • README.md (this file)

4. 🔐 Set up Secure API Key:

   • In your Space settings, add environment variable: GEMINI_API_KEY
   • Get your free API key from Google AI Studio
   • NEVER commit API keys to your repository!

5. Space will automatically deploy using Gradio

🔐 API Key Security

For the AI Sports Coach feature, you need a Google Gemini API key:

• 🆓 Free: Get your key at Google AI Studio
• 🔒 Secure: Set as environment variable GEMINI_API_KEY in HF Spaces
• 🚫 Never: Commit API keys to code repositories
• ✅ Best Practice: Use HF Spaces secrets for deployment

📁 Project Structure

athletic-ability-analysis/
├── app.py                    # Main Gradio application & UI
├── athletic_performance.py   # Core analysis & AI integration
├── requirements.txt          # Python dependencies
├── README.md                # This file (with HF Spaces header)
├── deploy_hf.py             # Deployment helper script
├── test_deployment.py       # Dependency testing
└── .gitignore              # Git ignore file

🎯 Usage

Web Interface

1. Visit your Hugging Face Space URL

2. Enter your height and weight for accurate biomechanical calculations

3. Choose your analysis type:

   📊 Standard Analysis:

   • YouTube or File Upload tabs
   • Get comprehensive biomechanical metrics

   🤖 AI Sports Coach:

   • Select your gender
   • Provide video (YouTube URL or upload)
   • Get personalized sport recommendations
   • Receive jump technique improvement suggestions

4. Click analyze and wait for processing

5. View comprehensive results with detailed 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.