Yoga Pose Classification Toolkit

Prerequisites

• Python 3.x
• Install Python packages:

Typical end‑to‑end workflow

1. (Optional) Extract raw images from the included Parquet dataset into train/test folders using extract_images.py.
2. Run pose_detection.py to generate per‑image pose landmark JSON files under PoseData/label_*.
3. Train and evaluate a classifier with ml_pose_classifier.py. Optionally export to ONNX or TFLite.
4. Run the webcam demo with realtime_pose_classifier.py using your saved model.

Script: extract_images.py

• Extract images and labels from the provided Parquet files (in YogaDataSet/data/) and save them into folders by label for training and testing.

• Input: YogaDataSet/data/train-00000-of-00001.parquet, YogaDataSet/data/test-00000-of-00001.parquet
• Output: Images under TrainData/train/label_* and/or TrainData/test/label_*

• The script creates label_0, label_1, … subfolders and writes image files with their original extensions.

Script: pose_detection.py

• Run MediaPipe Pose on your labeled image folders and save normalized landmark coordinates to JSON files for training.

• Uses the nose as the head reference point and applies: position = (pos − headPos) × 100, rounded to 2 decimals. This matches the training pipeline.

• Input: An images root (default TrainData/train) organized as label_*/*.jpg|png|…
• Output: JSON files under PoseData/label_*/<image_name>.json

• Supported image extensions: .jpg, .jpeg, .png, .bmp, .tiff
• Requires a working OpenCV + MediaPipe install (see requirements.txt).

Script: ml_pose_classifier.py

• Train, evaluate, and export pose classifiers from landmark JSONs. Supports Random Forest, SVM, Gradient Boosting, Logistic Regression, and a knowledge‑distilled RF→MLP variant.

• Directory structure like:
  • PoseData/label_0/*.json
  • PoseData/label_1/*.json
  • …

• --data/-d Pose JSON root (default: PoseData)
• --model/-m Model type: random_forest (default), svm, gradient_boost, logistic, distilled_rf
• --test-size/-t Test split ratio (default: 0.2)
• --save-model/-s Path to save the trained model (.pkl via joblib)
• --load-model/-l Path to load an existing model
• --predict/-p Predict a single JSON file
• --evaluate/-e Evaluate a folder of JSON files
• --export-onnx Export the trained model to ONNX (tree models or distilled MLP)
• --export-model-type Controls which model flavor to export
• --export-tflite Export distilled student MLP to TFLite (requires extra deps)

• ONNX export depends on skl2onnx and onnx. TFLite export additionally needs onnx-tf and tensorflow.
• Linear classifiers (svm, logistic) are not supported by Unity Barracuda. Prefer random_forest or the distilled MLP for deployment.

Script: realtime_pose_classifier.py

• Run live pose classification from your webcam using a previously trained model. Draws the skeleton, highlights the used joints, and overlays prediction + confidence.

• If --model is not provided, the script auto‑searches common filenames in the project root:
  • pose_classifier_random_forest.pkl
  • pose_classifier_logistic.pkl
  • pose_classifier_distilled_rf.pkl

• Q: Quit
• L: Toggle landmark keypoints
• C: Toggle pose connections
• R: Reset prediction history (smoothing window)

• Uses the same preprocessing as training (nose‑relative coordinates ×100, 2‑decimal rounding, StandardScaler).
• For smoother predictions, a small history window is used to compute a stable label and average confidence.

Useful folders and artifacts

• YogaDataSet/data/ — Parquet files used by extract_images.py.
• TrainData/train|test/label_*/ — Image folders produced by extraction.
• PoseData/label_*/ — Landmark JSONs generated by pose_detection.py.
• models/ — Example trained/exported models and label mappings.
• confusion_matrix_*.png — Saved confusion matrix plots (when enabled in training script).

Troubleshooting

• MediaPipe install issues on macOS: ensure you’re using a supported Python version and the latest pip; try reinstalling mediapipe and opencv-python.
• Camera cannot open: try a different --camera index, close other apps using the camera, or allow camera permissions for Python in macOS Privacy settings.
• Model not found in real‑time script: pass --model with an explicit path to your .pkl file.