QP-Biomechanics Demo

A powerful iOS application for analyzing human movement and biomechanics from video files. Built with SwiftUI and powered by the QuickPose SDK, this app tracks 33 body joints, measures joint angles, and exports detailed biomechanical data for further analysis.

Features

• Video Analysis: Select and process videos to track human movement
• 33 Body Joint Tracking: Comprehensive tracking of all major body landmarks
• Multiple Visualization Modes:
  • Whole Body Skeleton overlay
  • Range of Motion & Angles measurements
• Biomechanical Measurements:
  • Joint angle calculations (hip, knee, ankle, shoulder, elbow)
  • Range of motion tracking for all major joints
  • Real-time overlay visualization on processed videos
• Data Export: Export landmark data to CSV format for external analysis
• Processing History: View and manage previously analyzed videos
• Share & Save: Export processed videos and CSV files

Screenshots

The app provides an intuitive interface for:

• Selecting videos from your device
• Choosing visualization overlay types
• Monitoring processing progress
• Viewing detailed results with video playback
• Accessing processing history

Requirements

• QuickPose SDK (requires SDK key)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/QP-Biomechanics-Demo.git
cd QP-Biomechanics-Demo

2. Open the project in Xcode:

open "QP-Biomechanics Demo.xcodeproj"

3. Install dependencies:

   • The project uses Swift Package Manager
   • Dependencies will be automatically resolved when you open the project
   • Required package: QuickPoseCore SDK

4. Configure your QuickPose SDK key:

   • Open QP-Biomechanics Demo/Config/QuickPoseConfig.swift
   • Replace "YOUR SDK KEY HERE" with your actual QuickPose SDK key
   • Get your free SDK key at https://dev.quickpose.ai

5. Build and run the project in Xcode (⌘R)

Configuration

QuickPose SDK Setup

To use this app, you need a QuickPose SDK key:

1. Visit QuickPose Developer Portal
2. Sign up for a free account
3. Generate your SDK key
4. Add it to QuickPoseConfig.swift:

struct QuickPoseConfig {
    static let sdkKey = "YOUR_SDK_KEY_HERE"
    static let defaultIsFrontCamera = false
}

Customization Options

You can customize various settings in QuickPoseConfig.swift:

• Camera Orientation: Set defaultIsFrontCamera to true if processing front-camera videos
• CSV Export: Configure includeConfidence and previewRowCount in the CSV struct
• Output Format: Adjust outputVideoFormat in the Processing struct

Usage

Basic Workflow

1. Launch the App: Open the app to see the main menu
2. Select Video: Tap "Select Video to Analyze" and choose a video from your device
3. Choose Overlay Type:
   • Whole Body Skeleton: Shows complete body skeleton overlay
   • Range of Motion & Angles: Shows joint angles and range of motion measurements
4. Process Video: Tap "Start Processing" and wait for analysis to complete
5. View Results: Review the processed video with overlays and landmark data
6. Export Data: Share or save the processed video and CSV file

Viewing History

• Tap "View History" on the main screen
• Browse previously processed videos
• View detailed statistics and export data
• Delete old processing sessions

Data Export

CSV Format

The exported CSV file contains frame-by-frame landmark data:

• Frame: Frame number in the video
• Timestamp: Time in seconds
• Joint Name: Name of the body landmark (e.g., "leftKnee", "rightShoulder")
• X, Y, Z: 3D coordinates of the landmark
• Visibility: Confidence score for landmark detection (0-1)

Tracked Landmarks

The app tracks 33 body landmarks:

Face: nose, eyes (inner, center, outer), ears, mouth corners

Upper Body: shoulders, elbows, wrists, hands (pinky, index, thumb)

Lower Body: hips, knees, ankles, heels, foot indices

Project Structure

QP-Biomechanics Demo/
├── Config/
│   └── QuickPoseConfig.swift          # SDK configuration
├── Models/
│   ├── LandmarkData.swift             # Data structures for landmarks
│   └── ProcessingHistory.swift        # Processing session management
├── Views/
│   ├── ContentView.swift              # Main app screen
│   ├── VideoPickerView.swift          # Video selection interface
│   ├── VideoProcessingView.swift      # Processing screen with overlays
│   ├── ProcessingResultsView.swift    # Results display
│   └── HistoryView.swift              # Processing history
├── Services/
│   └── CSVExporter.swift              # CSV export functionality
├── Assets.xcassets/                   # App assets
└── QP_Biomechanics_DemoApp.swift      # App entry point

Architecture

The app follows SwiftUI best practices with clear separation of concerns:

• Views: SwiftUI views for UI components
• Models: Data structures and business logic
• Services: Utility services (CSV export, etc.)
• Config: Configuration and constants

Key Components

• QuickPosePostProcessor: Handles video processing and landmark detection
• ProcessingSession: Manages frame-by-frame landmark data
• CSVExporter: Exports landmark data to CSV format
• ProcessingHistory: Tracks and persists processing sessions

Technical Details

Video Processing

The app uses the QuickPose SDK to:

1. Load video files from the device
2. Process each frame to detect body landmarks
3. Apply visual overlays (skeleton or biomechanics)
4. Export processed video with overlays

Biomechanics Analysis

Two overlay modes are available:

1. Whole Body Skeleton: Complete body pose visualization
2. Range of Motion & Angles: Detailed measurements including:
   • Shoulder, elbow, hip, knee, and ankle angles
   • Range of motion for major joints
   • Hip-to-knee angle relationships

Data Storage

• Processing sessions are stored in memory during app runtime
• CSV files are saved to temporary directory
• Processed videos are saved to temporary directory
• Users can share/export files to permanent storage

Performance Considerations

• Video processing is performed asynchronously to prevent UI blocking
• Progress updates are throttled for smooth UI performance
• Large videos may take several minutes to process depending on:
  • Video duration
  • Video resolution
  • Device processing power

Troubleshooting

Common Issues

"Invalid SDK Key" Error

• Verify your SDK key in QuickPoseConfig.swift
• Ensure you have an active QuickPose account
• Check your internet connection

Processing Fails

• Ensure the video contains visible human subjects
• Check that the video format is supported (MP4, MOV)
• Try with a shorter video first

CSV Export Fails

• Check available storage space
• Ensure the app has file system permissions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

License

Please check with QuickPose for SDK licensing terms.

Acknowledgments

• Built with QuickPose SDK
• UI designed with SwiftUI

Contact

For questions or support, please open an issue on GitHub.

---

Note: This is a demonstration application. For production use, ensure proper error handling, data validation, and user privacy considerations are implemented.