Skip to content

README.md

Latest commit

 

History

History
executable file
·
246 lines (178 loc) · 8.02 KB

README.md

File metadata and controls

executable file
·
246 lines (178 loc) · 8.02 KB

Gait Analysis System

A comprehensive markerless gait analysis system using computer vision and machine learning techniques for analyzing human walking patterns.

🎯 Overview

This system provides a complete pipeline for markerless gait analysis using:

  • Computer Vision: Real-time pose estimation with MediaPipe
  • Machine Learning: Temporal Convolutional Networks (TCN) for gait pattern analysis
  • Data Processing: Advanced preprocessing and feature extraction
  • Visualization: Real-time pose visualization with trail effects

✨ Key Features

  • 🔄 Unified Pose Estimation: Extensible architecture supporting multiple pose estimation backends
  • 🧠 TCN Architecture: Temporal sequence modeling for gait analysis
  • 📊 Advanced Analytics: Gait event detection, phase analysis, and performance metrics
  • 🎨 Real-time Visualization: Interactive pose visualization with trail effects
  • 🔧 Modular Design: Easy to extend with new pose models and analysis methods
  • 📈 Cross-validation: Robust evaluation pipeline with comprehensive metrics
  • 📁 Organized Outputs: All results centralized in outputs/ directory

🏗️ System Architecture

Extensible Pose Processing

The unified pose processor manager makes it easy to add new pose estimation models:

  1. Create a new processor class inheriting from PoseProcessor
  2. Implement required abstract methods
  3. Add the model to the AVAILABLE_MODELS dictionary
  4. Update the create_processor method

Project Structure

gait_analysis/
├── core/           # Core system modules (pose processing, TCN model, training)
├── usecases/       # Use case implementations (gait analysis, testing)
├── scripts/        # Utility scripts
├── configs/        # Configuration files
├── docs/           # Documentation
├── archive/        # Legacy scripts (see archive/README.md)
├── data/           # Input data and trained models
├── videos/         # Video files
└── outputs/        # Output results (analysis, logs, models, visualizations)

🚀 Quick Start

1. Setup Environment

On macOS/Linux:

./setup_environment.sh

On Windows:

setup_environment.bat

2. Activate Virtual Environment

source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate     # Windows

3. Test Installation

# Test the complete system
python3 usecases/testing/test_system.py

# Test pose models specifically
python3 usecases/testing/test_pose_models.py

# Show available models
python3 scripts/pose_model_comparison.py --info

4. Run Analysis

# Basic gait analysis with MediaPipe
python3 usecases/gait_analysis/main_gait_analysis.py \
    --videos videos/raw/sample.mp4 \
    --output outputs/gait_analysis/

# Pose detection only
python3 usecases/gait_analysis/main_gait_analysis.py \
    --videos videos/raw/sample.mp4 \
    --pose-detection-only

# With real-time visualization
python3 usecases/gait_analysis/main_gait_analysis.py \
    --videos videos/raw/sample.mp4 \
    --with-visualization

🎯 Pose Estimation Models

Supported Frameworks

Framework Status Notes
MediaPipe ✅ Implemented Default, actively used
OpenPose ⚠️ Legacy Code in archive/, not integrated
YOLO-Pose ❌ Not implemented Architecture ready for integration
MMPose ❌ Not implemented Architecture ready for integration
ViTPose ❌ Not implemented Architecture ready for integration

Current Limitations

  • Single-person detection only: The system is currently configured with num_poses=1, detecting only one person per frame. Multi-person detection is supported by MediaPipe but not yet implemented in this codebase.

MediaPipe (Default)

  • Speed: Fast, real-time processing
  • Accuracy: Good for most applications
  • Resource Usage: Low, works on CPU
  • Best For: Real-time applications, mobile/edge devices
  • Landmarks: 33 pose landmarks, converted to BODY_25 format (25 keypoints)

Adding New Models

The system architecture is designed to easily support additional pose estimation models:

  1. Create a new processor class that inherits from PoseProcessor abstract base class
  2. Implement the required abstract methods (process_video, process_webcam, cleanup)
  3. Add the model to the AVAILABLE_MODELS dictionary in PoseProcessorManager
  4. Update the create_processor method to handle the new model type

See core/pose_processor_manager.py for the extensible architecture and core/mediapipe_integration.py for an implementation example.

Model Comparison

# Compare available models on the same video
python3 scripts/pose_model_comparison.py --video videos/raw/sample.mp4 --compare

# Process with specific model
python3 usecases/gait_analysis/main_gait_analysis.py \
    --videos videos/raw/sample.mp4 \
    --pose-model mediapipe

🎨 Real-time Pose Visualization

The system includes an interactive real-time pose visualization tool that displays pose keypoints as colored dots with trail effects.

Example Visualizations

Real-time pose visualization in outdoor environment Real-time pose visualization in lab environment

Quick Demo

# Basic visualization with trail effect
python3 usecases/gait_analysis/features/realtime_pose_visualization.py videos/raw/sample.mp4

# Show confidence values
python3 usecases/gait_analysis/features/realtime_pose_visualization.py videos/raw/sample.mp4 --show-confidence

# Fast performance mode
python3 usecases/gait_analysis/features/realtime_pose_visualization.py videos/raw/sample.mp4 --model-complexity 0 --no-trail

Interactive Controls

  • 'q': Quit visualization
  • 't': Toggle trail effect
  • 'c': Toggle connections
  • 'r': Reset trail
  • SPACE: Pause/resume
  • '1', '2', '3': Change model complexity

📊 Output Structure

All results are organized in the outputs/ directory:

outputs/
├── gait_analysis/      # Main gait analysis results
├── mediapipe/          # MediaPipe pose detection outputs
├── test_results/       # Testing and validation results
├── logs/               # Application logs
├── visualizations/     # Charts, graphs, and visual outputs
└── models/             # Trained models and artifacts

📚 Documentation

🔧 Configuration

The system uses JSON configuration files for customization:

{
  "pose_model": "mediapipe",
  "task_type": "phase_detection",
  "num_classes": 4,
  "num_filters": 64,
  "kernel_size": 3,
  "num_blocks": 4,
  "dropout_rate": 0.2,
  "learning_rate": 0.001,
  "epochs": 100,
  "batch_size": 32
}

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Submit a pull request

📄 License

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

🙏 Acknowledgments

  • MediaPipe team for the pose estimation framework
  • TensorFlow/Keras community for the deep learning framework
  • OpenCV community for computer vision tools

Note: Legacy scripts from the initial development phase have been moved to the archive/ directory. See archive/README.md for details about the archived files and migration notes.