README.md

metadata

title: Par-ity Project
emoji: ⛳
colorFrom: blue
colorTo: green
sdk: streamlit
app_file: app/streamlit_app.py
pinned: false

Par-ity Project: Golf Swing Analysis with AI Assistant ⛳🏌️‍♀️

A comprehensive golf swing analysis platform that combines computer vision-based swing analysis with an AI-powered technique assistant. This integrated system provides both automated video analysis and expert knowledge retrieval for improving your golf swing.

Features

🎥 Video Analysis

• Upload or provide YouTube links to golf swing videos
• Automated swing analysis using computer vision
• Pose estimation and tracking
• Swing phase segmentation (setup, backswing, downswing, follow-through)
• Club and ball trajectory analysis
• Annotated video generation with visual feedback
• Key position comparison (setup, top of backswing, impact)
• AI-powered improvement recommendations

🤖 Golf Swing Technique Assistant (RAG)

• Expert Knowledge Base: 2,000+ professional golf instruction articles
• Semantic Search: Ask questions in natural language
• Contextual Answers: Get detailed responses with source citations
• Interactive Chat: Build conversations about your swing technique
• TPI Content: Based on Titleist Performance Institute materials

What You Can Do

Video Analysis Options

After uploading a video, you get 4 analysis options:

1. Generate Annotated Video - Visual feedback showing swing phases and metrics
2. Generate Improvement Recommendations - AI-powered personalized tips
3. Key Frame Analysis - Detailed review of critical swing positions
4. Golf Swing Chatbot - Ask specific technique questions

Example Questions for the AI Assistant

• "What wrist motion happens during the downswing?"
• "I'm having trouble with my slice, can you help?"
• "What should I focus on to increase my driving distance?"
• "How do I fix my inconsistent ball striking?"
• "What physical limitations can affect my swing?"

Setup Instructions

1. Install Dependencies

pip install -r requirements.txt

2. Directory Setup

./setup_directories.sh

3. OpenAI API Key (Optional)

For enhanced AI responses, set up an OpenAI API key:

Option 1: Environment File

cp .env.example .env
# Edit .env and add your API key

Option 2: Streamlit Secrets Create .streamlit/secrets.toml:

[openai]
api_key = "your-openai-api-key-here"

Option 3: Enter in App You can also enter the API key directly in the Streamlit interface.

4. Run the Application

cd app
streamlit run streamlit_app.py

Or use the convenience script:

./run_streamlit.sh

How It Works

Video Analysis Pipeline

1. Video Processing: Extracts frames and detects objects using YOLOv8
2. Pose Analysis: Uses MediaPipe for detailed body positioning
3. Swing Segmentation: Identifies swing phases automatically
4. Trajectory Analysis: Tracks club and ball movement
5. AI Recommendations: Generates personalized improvement tips

RAG (Retrieval-Augmented Generation) System

1. Knowledge Processing: Loads and processes 2,000+ golf instruction articles
2. Semantic Embeddings: Creates vector representations using Sentence Transformers
3. Smart Search: Uses FAISS for fast similarity search
4. Response Generation: Combines retrieved knowledge with AI (GPT-3.5) or fallback mode

File Structure

Golf_Swing_Analysis/
├── app/                                # Main application
│   ├── streamlit_app.py               # Integrated Streamlit app
│   ├── golf_swing_rag.py             # RAG system
│   ├── models/                        # Analysis models
│   ├── utils/                         # Utility functions
│   └── components/                    # UI components
├── golf_swing_articles_complete.csv   # Knowledge base (2,000+ articles)
├── requirements.txt                   # Python dependencies
├── .env.example                       # Environment variables template
├── test_rag_integration.py           # Integration test script
└── Generated files (after first run):
    ├── golf_swing_embeddings.pkl     # Cached embeddings
    ├── golf_swing_index.faiss        # Vector search index
    └── downloads/                     # Processed videos

Technical Details

Technologies Used

• Computer Vision: YOLOv8, MediaPipe, OpenCV
• AI/ML: OpenAI GPT-3.5/4, Ollama (local LLM option)
• RAG Stack: Sentence Transformers, FAISS, LangChain
• Web Interface: Streamlit
• Data Processing: Pandas, NumPy

Performance Features

• Cached Embeddings: First-time setup creates embeddings saved for future use
• Efficient Search: FAISS enables fast similarity search over thousands of chunks
• Automatic Cleanup: Temporary files are managed automatically
• Batch Processing: Video frames and embeddings processed efficiently

Usage Guide

1. Video Analysis Workflow

1. Choose input method (YouTube URL or file upload)
2. Click "Analyze Swing" to process the video
3. Select from 4 analysis options
4. Download results and annotated videos

2. AI Assistant Workflow

1. Click "Golf Swing Chatbot" after video analysis (or use standalone)
2. Ask questions about golf swing technique
3. Review detailed answers with source citations
4. Build conversations for comprehensive understanding

Example Use Cases

Video Analysis

• Beginner Golfer: Upload practice swing video → Get annotated feedback → Learn proper positions
• Intermediate Player: Analyze driver swing → Get AI recommendations → Focus on specific improvements
• Coach: Use key frame analysis → Show students critical positions → Provide visual evidence

AI Assistant

• Technique Questions: "How should my weight shift during the swing?"
• Problem Solving: "I keep hitting fat shots with my irons, what's wrong?"
• Learning: "Explain the biomechanics of the golf swing"
• Specific Issues: "I have limited hip mobility, how does this affect my swing?"

Troubleshooting

First Run Setup

• Initial embedding creation takes 5-10 minutes (one-time process)
• Ensure adequate RAM (8GB+ recommended) for large knowledge base
• Video processing time depends on length and resolution

Common Issues

• Missing Dependencies: Run pip install --upgrade -r requirements.txt
• Import Errors: Ensure you're running from the correct directory
• RAG Not Available: Check that golf_swing_articles_complete.csv exists
• Video Issues: Ensure videos are in supported formats (MP4, MOV, AVI)

Testing Integration

Run the test script to verify everything works:

python3 test_rag_integration.py

Contributing

This system is designed to be extensible:

1. Video Analysis: Add new computer vision models or metrics
2. Knowledge Base: Include additional golf instruction sources
3. AI Models: Experiment with different embedding models or LLMs
4. UI/UX: Enhance the Streamlit interface with new features

License

This project is for educational and personal use. The golf instruction content is sourced from publicly available articles and should be attributed to original sources.

---

Built with ❤️ to empower golfers with AI-powered analysis and expert knowledge