Pose2Par ⛳

Professional Golf Swing Biomechanical Analysis — From Standard Video to 3D Motion Data

---

Pose2Par turns an ordinary video of a golf swing into full 3D biomechanical data — pelvis rotation, torso rotation, X-factor, and swing event timing — all without a motion capture lab.
It combines deep-learning pose estimation (MMPose), AI marker enhancement (LSTM / Transformer), and physics-based biomechanical modelling (OpenSim) into a single, Docker-powered pipeline with an easy-to-use desktop UI.

---

📸 UI Preview

Capture, analyse, and visualise golf swing biomechanics — all from one interface.

---

✅ Validation

Pose2Par has been independently validated against laboratory-grade 3D motion capture equipment. Key findings:

Metric	Reliability
Swing event timing	✅ High
Pelvis rotation (Top of Backswing)	✅ High
X-Factor (Top of Backswing)	✅ High
Impact detection (low handicap)	✅ Good
Impact detection (high handicap)	⚠️ Mixed
Swing finish phase	❌ Limited (self-occlusion)
Angular velocity	❌ Unreliable
Sagittal-plane tilt	❌ Unreliable (single camera depth)

→ Read the full, transparent breakdown: VALIDATION.md

---

🎯 Features

• Live Swing Capture — high-FPS camera support (up to 120 FPS) with automatic swing detection
• 2D Pose Estimation — powered by MMPose with state-of-the-art keypoint detection
• AI Marker Enhancement — LSTM and Transformer models correct and fill tracking gaps
• 3D Biomechanical Modelling — OpenSim calculates true joint angles from markerless video
• Golf-Specific Metrics:
  • Pelvis rotation angle
  • Torso rotation angle
  • X-Factor (torso–pelvis separation)
  • Swing phase labels (address → backswing → downswing → follow-through)
  • Key event timestamps (top of backswing, ball impact)
• Interactive Desktop UI — capture, replay, graph, and export in one window
• CSV Export — frame-by-frame metric export for external analysis
• Fully Containerised — Docker pipeline for reproducible, portable deployment

---

🏗️ Architecture

Pose2Par uses a three-stage pipeline:

Video Input → MMPose (Pose Estimation) → Marker Enhancer (ML Enhancement) → OpenSim (Biomechanics) → Analysis & Visualization

Pipeline Stages

1. MMPose: 2D pose estimation using state-of-the-art deep learning models
2. Marker Enhancer: LSTM/Transformer models to improve marker tracking and fill gaps
3. OpenSim: Biomechanical modeling and joint angle calculations
4. Analysis: Event detection, metric calculation, and visualization

📋 Prerequisites

System Requirements

• OS: Windows 10/11 (tested), Linux (should work with minor modifications)
• GPU: NVIDIA GPU with CUDA support (recommended for real-time performance)
• RAM: 8GB minimum, 16GB recommended
• Storage: 10GB free space (for Docker images and dependencies)

Software Requirements

• Python: 3.8 or higher
• Docker Desktop: Latest version with Docker Compose
• NVIDIA GPU Drivers: If using GPU acceleration
• NVIDIA Container Toolkit: For GPU support in Docker (Linux only)

Hardware Requirements

• Camera: External USB webcam or capture card
  • Recommended: High-FPS camera (60-120 FPS) for optimal swing capture
  • Minimum: 30 FPS webcam
• Camera Position: Face-on view of golfer during swing

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/cavanaulton/pose2par.git
cd pose2par

2. Run Setup Script

Windows:

setup.bat

Linux/Mac:

chmod +x setup.sh
./setup.sh

This will:

• Verify Python and Docker installation
• Install Python dependencies
• Build Docker images (MMPose, Marker Enhancer, OpenSim)
• Create necessary directories

3. Launch the Application

Windows:

scripts\run_pose2par.bat

Python (any OS):

python src/UI.py

📖 Detailed Installation

Step 1: Install Prerequisites

Install Python

Download and install Python 3.8+ from python.org

Install Docker Desktop

1. Download from docker.com
2. Install and ensure Docker is running
3. (Windows) Enable WSL 2 backend if prompted

Install NVIDIA Drivers (for GPU acceleration)

1. Download latest drivers from nvidia.com
2. Install NVIDIA Container Toolkit (Linux):

   distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
   curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
   curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
   sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
   sudo systemctl restart docker

Step 2: Install Python Dependencies

pip install -r requirements_ui.txt

Step 3: Build Docker Images

# Windows
build_docker_images.bat

# Linux/Mac
docker-compose -f docker-compose.build.yml build

This builds three Docker images:

• mmpose:latest - Pose estimation
• marker_enhancer:latest - ML-based marker enhancement
• opensim:latest - Biomechanical modeling

Note: First build may take 20-30 minutes depending on your internet speed and system.

Step 4: Configure Camera (Optional)

Edit config.py to customize camera settings:

# Camera settings
CAMERA_WIDTH = 1920
CAMERA_HEIGHT = 1080
CAMERA_FPS = 60

# Force specific camera index (None for auto-detection)
FORCE_CAMERA_INDEX = None  # or set to specific index like 2

# Golfer handedness
GOLFER_HANDEDNESS = 'right'  # or 'left'

🎮 Usage

Capturing a Golf Swing

1. Launch the UI: Run python UI.py or run_pose2par.bat
2. Select Camera: Choose your external camera from the dropdown
3. Position Golfer: Ensure face-on view with full body visible
4. Start Recording: Click "Start Recording" button
5. Capture Swing: Record 3-5 seconds including full swing
6. Stop Recording: Click "Stop Recording"

Analyzing a Swing

1. Run Analysis: Click "Analyze Swing" button
2. Wait for Processing: Pipeline runs automatically (2-5 minutes typical)
3. View Results:
   • Playback with overlay visualization
   • Real-time angle graphs
   • Frame-by-frame metrics
4. Export Data: Click "Export" to save CSV with all metrics

Working with Existing Videos

1. Place video file in pipeline_data/input_video/ as input_video.mp4
2. Click "Analyze Swing" in UI, or
3. Run pipeline manually:

   python run_full_pipeline.py

📊 Output Files

After analysis, you'll find:

• pipeline_data/mmpose_output/ - Raw pose estimation data
• pipeline_data/marker_enhancer_output/ - Enhanced marker trajectories (.trc files)
• pipeline_data/opensim_output/ - Biomechanical analysis results (.mot files, joint angles)
• pipeline_data/exports/ - CSV exports for external analysis

🔧 Configuration

Camera Configuration (config.py)

# Camera settings
CAMERA_WIDTH = 1920
CAMERA_HEIGHT = 1080
CAMERA_FPS = 60
FORCE_CAMERA_INDEX = None  # Auto-detect or specify index

# Skip built-in webcams
SKIP_BUILTIN_WEBCAM = True

# Golf analysis settings
GOLFER_HANDEDNESS = 'right'  # 'right' or 'left'
CAMERA_VIEW = 'face_on'      # 'face_on' or 'down_the_line'

Pipeline Configuration

Edit Docker service parameters in docker-compose.yml:

# MMPose settings
--bbox-thr 0.4    # Bounding box confidence threshold
--kpt-thr 0.3     # Keypoint confidence threshold

# Marker Enhancer settings
--fps 60          # Video framerate
--subject_height 1.70  # Subject height in meters
--subject_weight 74.0  # Subject weight in kg

🧪 Development

Project Structure

pose2par/
├── UI.py                    # Main application UI
├── config.py                # Configuration settings
├── docker_handler.py        # Docker pipeline orchestration
├── event_detection.py       # Golf swing event detection
├── camera_detector.py       # Camera detection utilities
├── run_full_pipeline.py     # Standalone pipeline runner
├── setup.bat                # Windows setup script
├── build_docker_images.bat  # Docker image builder
├── run_pose2par.bat         # Windows launcher
├── docker-compose.yml       # Docker services configuration
├── requirements_ui.txt      # Python dependencies
├── mmpose/                  # MMPose pose estimation
├── marker-enhancer/         # ML-based marker enhancement
├── opensim/                 # OpenSim biomechanical models
├── docker_image_files/      # Dockerfiles for each service
├── pipeline_data/           # Pipeline input/output/working directory
│   ├── input_video/        # Input videos
│   ├── mmpose_output/      # Pose estimation output
│   ├── marker_enhancer_output/  # Enhanced markers
│   ├── opensim_output/     # Biomechanical analysis
│   └── exports/            # CSV exports
├── scripts/                 # Utility scripts
└── models/                  # Pre-trained model weights

Running Individual Pipeline Stages

Test individual stages using Docker Compose profiles:

# MMPose only
docker-compose run mmpose-only

# Marker Enhancer only
docker-compose run marker-enhancer-only

# OpenSim only
docker-compose run opensim-only

Adding New Biomechanical Metrics

1. Modify OpenSim scripts in opensim/scripts/
2. Update docker_handler.py to parse new metrics
3. Update UI.py to visualize new metrics

🐛 Troubleshooting

Docker Issues

Problem: "Cannot connect to Docker daemon"

# Ensure Docker Desktop is running
# Windows: Check system tray for Docker icon
# Linux: sudo systemctl start docker

Problem: "CUDA not available" in Docker container

# Windows: Ensure WSL 2 is enabled and NVIDIA drivers are installed in Windows
# Linux: Install nvidia-container-toolkit

Camera Issues

Problem: Camera not detected

# Check camera connection
# Try different USB port
# Set FORCE_CAMERA_INDEX in config.py

Problem: Low FPS during capture

# Reduce CAMERA_FPS in config.py
# Check camera specifications
# Close other applications using camera

Pipeline Issues

Problem: "No pose detected" error

# Ensure golfer is fully visible in frame
# Check lighting conditions
# Lower --bbox-thr threshold in docker-compose.yml

Problem: Docker build fails

# Ensure stable internet connection
# Clear Docker cache: docker system prune -a
# Rebuild: docker-compose -f docker-compose.build.yml build --no-cache

📚 Citation

If you use Pose2Par in your research, please cite:

@software{pose2par,
  title={Pose2Par: Markerless Golf Swing Biomechanical Analysis via Monocular Video},
  author={Aulton, Cavan},
  year={2026},
  url={https://github.com/cavanaulton/pose2par}
}

Acknowledgements

Pose2Par builds on the following open-source projects — thank you to their maintainers:

Project	Licence	Use in Pose2Par
MMPose	Apache 2.0	2D pose estimation backbone
OpenSim	Apache 2.0	Biomechanical modelling engine
PyTorch	BSD	ML model training and inference

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Individual components may have their own licenses:

• MMPose: Apache License 2.0
• OpenSim: Apache License 2.0
• Marker Enhancer: Check marker-enhancer/LICENSE

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes and test them
4. Open a Pull Request with a clear description

💬 Support

• Bug reports / feature requests: GitHub Issues
• Discussion: GitHub Discussions

🗺️ Roadmap

• Down-the-line camera view support
• Multi-camera fusion for improved depth estimation
• Cloud-based processing option
• Expanded biomechanical metrics (hip speed, shoulder plane)
• Mobile companion app

📝 Changelog

See CHANGELOG.md for version history.

⚠️ Disclaimer

Pose2Par is a research and coaching tool for biomechanical analysis. Results should be interpreted by qualified professionals. This software is not intended for medical diagnosis or treatment. See VALIDATION.md for a full account of accuracy and known limitations.

---

Made with ⛳ for golf biomechanics research

VALIDATION.md · CHANGELOG.md · LICENSE · Issues