瑜伽姿势分类工具包

本仓库包含一个小型、以脚本为核心的流水线，用于准备数据、使用 MediaPipe 提取姿势关键点、训练机器学习姿势分类器，以及运行实时摄像头演示。

以下各节介绍项目根目录中每个 Python 脚本的功能以及在 macOS (zsh) 上的使用方法。关于依赖项，请参见 requirements.txt。

前提条件

• Python 3.x
• 安装 Python 包：

pip install -r requirements.txt

可选但推荐：在安装前创建并激活虚拟环境。

典型的端到端工作流程

1)（可选）使用 extract_images.py 从包含的 Parquet 数据集中提取原始图像到训练/测试文件夹。 2) 运行 pose_detection.py 在 PoseData/label_* 下生成每张图像的姿势关键点 JSON 文件。 3) 使用 ml_pose_classifier.py 训练和评估分类器。可选择导出为 ONNX 或 TFLite。 4) 使用保存的模型运行 realtime_pose_classifier.py 进行摄像头演示。

脚本：extract_images.py

用途

• 从提供的 Parquet 文件（位于 YogaDataSet/data/）中提取图像和标签，并按标签保存到训练和测试文件夹中。

输入/输出

• 输入：YogaDataSet/data/train-00000-of-00001.parquet、YogaDataSet/data/test-00000-of-00001.parquet
• 输出：图像保存在 TrainData/train/label_* 和/或 TrainData/test/label_* 下

用法

# 同时处理训练集和测试集（默认行为）
python extract_images.py

# 仅处理训练集
python extract_images.py --train --output TrainData

# 仅处理测试集到自定义文件夹
python extract_images.py --test --output MyOutputDir

注意事项

• 该脚本会创建 label_0、label_1、… 子文件夹，并以原始扩展名写入图像文件。

脚本：pose_detection.py

用途

• 在带标签的图像文件夹上运行 MediaPipe Pose，并将归一化的关键点坐标保存为 JSON 文件，用于训练。

预处理

• 使用鼻子作为头部参考点，并应用：position = (pos − headPos) × 100，四舍五入到 2 位小数。这与训练流水线保持一致。

输入/输出

• 输入：图像根目录（默认 TrainData/train），组织结构为 label_*/*.jpg|png|…
• 输出：JSON 文件保存在 PoseData/label_*/<image_name>.json 下

用法

# 从默认输入处理图像到 PoseData
python pose_detection.py

# 自定义输入和输出
python pose_detection.py --input TrainData/train --output PoseData --batch-size 100

提示

• 支持的图像扩展名：.jpg、.jpeg、.png、.bmp、.tiff
• 需要正常工作的 OpenCV + MediaPipe 安装（参见 requirements.txt）。

脚本：ml_pose_classifier.py

用途

• 从关键点 JSON 训练、评估和导出姿势分类器。支持随机森林、SVM、梯度提升、逻辑回归，以及知识蒸馏的 RF→MLP 变体。

数据格式要求

• 目录结构如下：
  • PoseData/label_0/*.json
  • PoseData/label_1/*.json
  • …

常用选项

• --data/-d 姿势 JSON 根目录（默认：PoseData）
• --model/-m 模型类型：random_forest（默认）、svm、gradient_boost、logistic、distilled_rf
• --test-size/-t 测试集划分比例（默认：0.2）
• --save-model/-s 保存训练模型的路径（通过 joblib 保存为 .pkl）
• --load-model/-l 加载现有模型的路径
• --predict/-p 预测单个 JSON 文件
• --evaluate/-e 评估一个 JSON 文件夹
• --export-onnx 将训练好的模型导出为 ONNX（树模型或蒸馏 MLP）
• --export-model-type 控制要导出的模型类型
• --export-tflite 将蒸馏的学生 MLP 导出为 TFLite（需要额外依赖）

常用命令

# 1) 训练随机森林并保存
python ml_pose_classifier.py \
	--data PoseData \
	--model random_forest \
	--test-size 0.2 \
	--save-model models/pose_classifier_random_forest.pkl

# 2) 在留出文件夹（如 TestData）上评估已保存的模型
python ml_pose_classifier.py \
	--model random_forest \
	--load-model models/pose_classifier_random_forest.pkl \
	--evaluate TestData

# 3) 导出到 ONNX（随机森林或蒸馏 MLP）
python ml_pose_classifier.py \
	--model random_forest \
	--load-model models/pose_classifier_random_forest.pkl \
	--export-onnx models/pose_classifier_random_forest.onnx

# 4) 知识蒸馏：训练 RF 教师模型 + MLP 学生模型
python ml_pose_classifier.py \
	--data PoseData \
	--model distilled_rf \
	--save-model models/pose_classifier_distilled_rf.pkl

# 5) 将学生 MLP 导出到 TFLite（需要额外的包）
python ml_pose_classifier.py \
	--model distilled_rf \
	--load-model models/pose_classifier_distilled_rf.pkl \
	--export-tflite models/pose_classifier_distilled_mlp.tflite

注意事项

• ONNX 导出依赖于 skl2onnx 和 onnx。TFLite 导出还需要 onnx-tf 和 tensorflow。
• 线性分类器（svm、logistic）不支持 Unity Barracuda。部署时请使用 random_forest 或蒸馏 MLP。

脚本：realtime_pose_classifier.py

用途

• 使用之前训练的模型从摄像头运行实时姿势分类。绘制骨骼、高亮使用的关键点，并叠加预测结果和置信度。

模型加载

• 如果未提供 --model，脚本会自动在项目根目录中搜索常见文件名：
  • pose_classifier_random_forest.pkl
  • pose_classifier_logistic.pkl
  • pose_classifier_distilled_rf.pkl

用法

# 自动检测模型并打开默认摄像头（0）
python realtime_pose_classifier.py

# 指定模型文件和摄像头索引
python realtime_pose_classifier.py \
	--model models/pose_classifier_random_forest.pkl \
	--camera 0

键盘控制

• Q：退出
• L：切换关键点显示
• C：切换姿势连接线
• R：重置预测历史（平滑窗口）

注意事项

• 使用与训练相同的预处理（相对于鼻子的坐标 ×100，2 位小数四舍五入，StandardScaler）。
• 为了获得更平滑的预测，使用小的历史窗口来计算稳定的标签和平均置信度。

常用文件夹和产物

• YogaDataSet/data/ — extract_images.py 使用的 Parquet 文件。
• TrainData/train|test/label_*/ — 提取生成的图像文件夹。
• PoseData/label_*/ — pose_detection.py 生成的关键点 JSON 文件。
• models/ — 示例训练/导出的模型和标签映射。
• confusion_matrix_*.png — 保存的混淆矩阵图（在训练脚本中启用时）。

故障排除

• macOS 上 MediaPipe 安装问题：确保使用受支持的 Python 版本和最新的 pip；尝试重新安装 mediapipe 和 opencv-python。
• 无法打开摄像头：尝试不同的 --camera 索引，关闭其他使用摄像头的应用程序，或在 macOS 隐私设置中为 Python 授予摄像头权限。
• 实时脚本中找不到模型：使用 --model 传递 .pkl 文件的显式路径。