FrameLab

A professional multi-camera video analysis application for bike fitting and biomechanical analysis. Features AI-powered pose detection, real-time angle measurements, zoom/pan controls, and synchronized multi-view recording.

Features

Multi-Camera Support

• Up to 4 cameras simultaneously in a 2x2 grid layout
• Flexible quadrant system - enable/disable individual camera positions
• Custom camera names - label cameras (e.g., "Side View", "Front View")
• Persistent layouts - camera positions saved between sessions
• Video file playback - load and analyze recorded sessions

AI Pose Detection

• Real-time pose estimation using MediaPipe
• 33 body landmarks with automatic tracking
• Cycling-specific angles: knee, hip, ankle, elbow, shoulder, back
• Live angle display overlaid on video feed
• Pause and adjust - freeze frame and manually correct joint positions
• Persistent adjustments - manual corrections track with live video

Recording & Playback

• Synchronized recording from all active cameras
• Automatic organization by athlete/bike/date
• Angle data export - JSON file with per-frame angle measurements
• Frame buffer - pause live cameras and scrub through last 10 seconds
• Video controls - play, pause, speed adjustment (0.25x-1x), loop
• Timeline scrubbing - slider to jump to any frame

Zoom & Pan

• Dynamic zoom - 1.0x to 4.0x in 0.25x increments
• Click-and-drag panning when zoomed in
• Per-camera zoom state - independent zoom for each view
• Reset to default - click zoom level to return to 1.0x

Session Management

• Athlete profiles - organize recordings by athlete
• Multiple bikes per athlete - separate fits for different setups
• Change session on-the-fly - switch athlete/bike without restart
• Auto-created directories - structured file organization
• Settings persistence - camera names and positions saved

Quick Start

Installation

1. Clone the repository:

git clone https://github.com/andrefecto/framelab.git
cd framelab

2. Create virtual environment:

python3 -m venv venv

3. Activate virtual environment:

   • macOS/Linux:

     source venv/bin/activate

   • Windows:

     venv\Scripts\activate

4. Install dependencies:

pip install -r requirements.txt

5. Run the application:

python main.py

First Run

1. Set default directory - choose or create folder for athlete data
2. Create/select athlete - enter athlete name or pick existing
3. Create/select bike - enter bike name or pick existing
4. Configure cameras - application auto-detects connected cameras
5. Start analyzing - cameras display in quadrant layout

Usage Guide

Camera Setup

1. Rename cameras: File → Camera Names

   • Give each camera a friendly name (e.g., "Side Camera")
   • Names appear in dropdowns and video filenames

2. Assign to quadrants: Use dropdown in each quadrant

   • Select camera from list
   • Choose "(None)" to clear quadrant
   • Drag between quadrants to rearrange

3. Enable/disable quadrants: View → Configure Quadrants

   • Toggle checkboxes to show/hide quadrants
   • Layout automatically adjusts

Recording

1. Enable pose detection: View → Toggle Pose Detection
2. Click Record button in any camera's control bar
3. Ride naturally - pose and angles tracked in real-time
4. Click Stop when finished
5. Files saved automatically:
   • Video: YYYY-MM-DD_HH-MM-SS_CameraName.mp4
   • Angles: YYYY-MM-DD_HH-MM-SS_CameraName_angles.json

Pose Adjustment

1. Pause the camera (live cameras only)
2. Click on any joint/landmark
3. Drag to correct position
4. Angles recalculate in real-time
5. Resume - adjustments track with live pose

Frame Scrubbing (Live Cameras)

1. Pause camera to freeze current frame
2. Use << >> buttons to step frame-by-frame
3. Drag timeline slider to jump to specific frame
4. Buffer holds last 10 seconds (~300 frames)
5. Pose detection re-runs on each frame

Zoom & Pan

1. Click + button to zoom in (up to 4.0x)
2. Click zoom level to reset to 1.0x
3. Click - button to zoom out
4. Click and drag on video to pan when zoomed
5. Works on live and recorded video

Video Playback

1. Select quadrant and choose "Load Video..."
2. Browse to recorded video file
3. Use playback controls:
   • Play/Pause
   • Loop toggle
   • Speed (0.25x, 0.5x, 0.75x, 1x)
   • Timeline scrubber
4. Enable pose detection to analyze recorded footage

Project Structure

framelab/
├── main.py                    # Application entry point
├── camera/
│   ├── camera.py             # Camera class with capture, recording, pose
│   └── detection.py          # Camera detection utilities
├── pose/
│   ├── estimator.py          # MediaPipe pose estimation
│   └── renderer.py           # Angle calculation and visualization
├── gui/
│   ├── layout.py             # Main window layout and camera grid
│   ├── quadrants.py          # Quadrant management
│   ├── startup.py            # Startup workflow (athlete/bike selection)
│   ├── dialogs.py            # File dialogs
│   ├── pose_editor.py        # Manual pose adjustment
│   └── state.py              # Global application state
├── athlete/
│   └── manager.py            # Athlete/bike directory management
├── utils/
│   ├── logger.py             # Logging configuration
│   └── settings.py           # Settings persistence
└── requirements.txt          # Python dependencies

System Requirements

• Python: 3.9-3.12 (MediaPipe compatibility)
• OS: Windows 10+, macOS 10.14+, Linux (Ubuntu 18.04+)
• RAM: 4GB minimum, 8GB+ recommended
• Camera: USB webcams (720p minimum, 1080p recommended)
• GPU: Any modern GPU (DearPyGUI uses GPU acceleration)

Dependencies

• DearPyGUI - GPU-accelerated Python UI framework
• MediaPipe - Google's pose estimation library
• OpenCV - Computer vision and video I/O
• NumPy - Numerical computing

See requirements.txt for complete list with versions.

Configuration Files

settings.json

Automatically created in project root. Stores:

• Default athlete data directory
• Camera friendly names (by camera ID)
• Camera quadrant positions (by camera ID)

Example:

{
  "default_directory": "/Users/name/bike_data",
  "camera_names": {
    "0": "Side Camera",
    "1": "Front Camera"
  },
  "camera_positions": {
    "0": 0,
    "1": 1
  }
}

File Organization

Recordings are automatically organized:

{default_directory}/
└── {athlete_name}/
    └── {bike_name}/
        ├── 2025-11-11_13-45-30_Side_Camera.mp4
        ├── 2025-11-11_13-45-30_Side_Camera_angles.json
        ├── 2025-11-11_13-47-15_Front_Camera.mp4
        └── 2025-11-11_13-47-15_Front_Camera_angles.json

Angle Measurements

The application calculates and displays these cycling-specific angles:

• Knee Angle - angle at knee joint during pedal stroke
• Hip Angle - hip flexion angle
• Ankle Angle - ankle dorsiflexion/plantarflexion
• Elbow Angle - arm bend at elbow
• Shoulder Angle - shoulder position relative to torso
• Back Angle - torso angle relative to horizontal

Angles are displayed in degrees directly on the video feed.

Keyboard Shortcuts

Currently none - all controls via UI buttons. Future versions may add shortcuts.

Troubleshooting

Camera Issues

• Not detected: Check system camera permissions
• Black screen: Wait 2-3 frames for initialization
• Wrong camera selected: Use dropdown to switch cameras
• Poor tracking: Ensure good lighting and full body in frame

Pose Detection

• Inaccurate: Improve lighting, minimize background clutter
• Missing landmarks: Ensure full body visible in frame
• Can't click points: Pose detection must be enabled and camera paused

Recording

• Files not saving: Check disk space and directory permissions
• Video choppy: Reduce number of active cameras
• Angles missing: Enable pose detection before recording

Performance

• Low FPS: Reduce number of active cameras or disable pose detection
• High CPU usage: Normal with multiple cameras and pose detection
• Memory issues: Close other applications, reduce frame buffer size

Known Limitations

• Maximum 4 cameras simultaneously (2x2 grid)
• Frame buffer limited to last 10 seconds for live cameras
• Pose detection requires clear view of body
• Manual adjustments only available when paused (live cameras)
• Video files cannot be renamed from within app

Future Enhancements

• Synchronize playback across multiple loaded videos
• Export comparison reports (PDF/CSV)
• Custom angle definitions
• Measurement overlays (distances, not just angles)
• Keyboard shortcuts
• Dark/light theme toggle
• Save pose adjustments to separate file
• Batch processing of recorded videos
• Drag Coefficient Calculations
• Automatic bike measurements

Contributing

Contributions welcome! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/YourFeature)
3. Commit your changes (git commit -m 'Add YourFeature')
4. Push to branch (git push origin feature/YourFeature)
5. Open a Pull Request

Please follow existing code style and add appropriate logging.

License

GPL-3.0 License - see LICENSE file for details.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Acknowledgments

• DearPyGUI - Modern GPU-accelerated Python UI
• MediaPipe - Real-time pose estimation by Google
• OpenCV - Computer vision foundation
• Cycling and bike fitting community for feedback

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Donations

If you find this project useful and would like to support its development, consider making a donation:

• GitHub Sponsors: Sponsor this project
• PayPal: paypal.me/AndreFecteau
• Buy Me a Coffee: buymeacoffee.com/andrefecto

Your support helps maintain and improve this free and open-source tool for the cycling community!

---

Built for bike fitters, coaches, and cyclists who want professional-grade analysis tools without subscription fees.

If this project helps you, please give it a ⭐ on GitHub!