Quaternion Biomechanics Engine

A Python module for Yoga Pose Correction that converts body-segment quaternion orientations from calibrated IMU sensors into meaningful biomechanical parameters, compares them against yoga pose templates, and generates human-readable correction feedback.

Overview

This engine assumes IMU sensors already provide synchronized, calibrated quaternion orientation data. No sensor fusion, Madgwick filters, Kalman filters, or accelerometer/gyroscope processing is performed.

Sensor Mapping

Sensor	Body Segment
S1	right_upper_arm
S2	right_forearm
S3	left_upper_arm
S4	left_forearm
S5	upper_spine
S6	lower_spine
S7	right_thigh
S8	left_thigh
S9	left_shin
S10	right_shin

Installation

pip install -r requirements.txt

Quick Start

from quaternion_biomechanics_engine import QuaternionBiomechanicsEngine

engine = QuaternionBiomechanicsEngine()

# Step 1: Calibrate in neutral standing pose (Tadasana)
calibration_frames = [...]  # 30 frames of sensor data
engine.calibrate(calibration_frames)

# Step 2: Process live frame against a target pose
frame = {
    "S1": [0.998, 0.01, 0.05, 0.02],
    "S2": [0.995, 0.02, 0.08, 0.01],
    # ... S3 through S10
}
result = engine.analyze(frame, target_pose="warrior_pose")

print(result["pose_score"])    # 92.0
print(result["feedback"])      # ["Bend your left knee more.", ...]

Input Format

Each frame is a dictionary of sensor quaternions in scalar-first order [qw, qx, qy, qz]:

{
    "S1": [0.998, 0.01, 0.05, 0.02],
    "S2": [0.995, 0.02, 0.08, 0.01],
    "S3": [0.997, -0.01, 0.04, 0.03],
    "S4": [0.996, 0.00, 0.06, 0.02],
    "S5": [0.999, 0.00, 0.02, 0.01],
    "S6": [1.000, 0.00, 0.00, 0.00],
    "S7": [0.990, 0.03, 0.10, 0.01],
    "S8": [0.985, 0.05, 0.12, 0.02],
    "S9": [0.980, 0.04, 0.15, 0.01],
    "S10": [0.992, 0.02, 0.09, 0.00]
}

Output Format

{
    "joint_angles": {
        "right_elbow": 175.2,
        "left_elbow": 174.8,
        "right_knee": 178.5,
        "left_knee": 92.3,
        "spine_bend": 2.1,
        "torso_rotation": -1.5
    },
    "pose_parameters": {
        "arm_symmetry": 95.0,
        "knee_symmetry": 45.0,
        "spine_straightness": 96.0,
        "torso_tilt": 1.2,
        "torso_rotation": -1.5,
        "shoulder_alignment": 92.0,
        "posture_stability": 88.0
    },
    "pose_score": 92.0,
    "feedback": [
        "Bend your left knee more.",
        "Raise your right arm slightly."
    ]
}

Module Architecture

quaternion_biomechanics_engine/
├── sensor_mapping.py       # Module 1: Body segment registry & sensor mapping
├── calibration.py          # Module 2: Neutral pose calibration
├── quaternion_utils.py     # Module 3: Quaternion math utilities
├── relative_orientation.py # Module 4: Relative segment orientations
├── joint_angles.py         # Module 5: Joint angle extraction
├── pose_parameters.py      # Module 6: High-level posture parameters
├── pose_templates.py       # Module 7: Yoga pose templates
├── pose_comparison.py      # Module 8: Pose comparison & scoring
├── feedback_engine.py      # Module 9: Human-readable feedback
└── engine.py               # Main orchestrator

Supported Yoga Poses

Pose Name	Key Parameters
Tadasana	Straight spine, extended knees, arms at sides
Vrikshasana	Single-leg balance, arms overhead, hip abduction
Warrior I	Front knee ~90°, back leg straight, arms raised

Key Algorithms

Calibration

corrected_quaternion = inverse(calibration_quaternion) × live_quaternion

Relative Joint Orientation

Q_relative = inverse(parent_segment) × child_segment

Examples:

Right elbow: inverse(right_upper_arm) × right_forearm
Left knee: inverse(left_thigh) × left_shin
Spine: inverse(lower_spine) × upper_spine

Joint Angle Extraction

Hinge joints (elbow, knee) use swing-twist decomposition about the medial-lateral axis for direct quaternion-to-angle computation without relying solely on Euler angles.

Running Examples

# Run the example script (generates example_input.json and example_output.json)
python examples/example_usage.py

# Run tests
pip install pytest
pytest tests/ -v

API Reference