本项目是一个面向人体动作识别任务的骨骼序列分析系统。系统以 RGB 视频或骨骼序列为输入，完成关键点提取、骨骼格式构造、ST-GCN 动作分类、Top-K 结果输出与可视化展示。项目在 PYSKL 框架基础上进行二次开发，并集成 MediaPipe、MMDetection、MMPose、OpenCV 与 Gradio，形成可交互的端到端推理流程。
公开仓库侧重展示系统设计、工程集成方式、推理流程和实验记录。出于 GitHub 大文件限制、第三方模型条款、数据集使用协议和人物隐私考虑，本仓库不分发模型权重、原始视频、测试视频、网络素材、受限数据集或由视频生成的骨骼数据。
下方动图展示了系统运行后的骨骼叠加输出效果，是本项目最直观的演示材料。示例素材仅用于展示动作识别流程，公开仓库不分发原始数据集视频或模型权重。
骨骼动作识别通常包含两个相互独立但强耦合的阶段：人体姿态估计与骨骼序列分类。本项目将这两个阶段整合到一个可运行的 Web 系统中，并保留两条不同技术路线，便于比较不同骨骼来源对动作分类的影响。
系统实现了以下能力：
- 从普通 RGB 视频中提取人体骨骼关键点。
- 将不同来源的关键点转换为动作识别模型可接受的输入结构。
- 使用 ST-GCN 系列模型完成 NTU RGB+D 60 动作类别识别。
- 支持视频输入、骨骼数据导出、骨骼数据离线识别三类工作流。
- 提供 MediaPipe 单目 3D 方案与 MMPose HRNet 2D 方案的并行实现。
- 通过 Gradio 封装为可交互 Web 应用，便于演示、调试和实验对比。
该项目更接近一个工程化集成与实验验证系统，而不是单一模型训练脚本。核心工作集中在模型加载、输入格式适配、跨框架推理调用、骨骼序列组织、结果可视化和公开仓库合规整理。
MediaPipe Pose 从单目 RGB 视频中估计人体关键点，并输出包含世界坐标的 3D landmark。本系统将 MediaPipe 关键点映射为 NTU 25 关节格式，再输入 3D ST-GCN 模型进行动作分类。
该路线的特点是依赖较轻、推理速度较快、部署门槛较低，但与 NTU RGB+D 原始 Kinect 3D 骨骼存在数据分布差异，因此在复杂场景下可能出现跨域误差。
该路线采用两阶段 top-down 姿态估计流程：
- 使用 Faster R-CNN 检测画面中的人体框。
- 使用 HRNet 对每个人体框提取 COCO 17 关节 2D 姿态。
- 对跨帧人体轨迹进行整理，构造 PYSKL 所需的骨骼输入。
- 使用基于 HRNet 2D 骨骼训练的 ST-GCN 模型进行分类。
该方案推理成本更高，但输入骨骼格式与对应 ST-GCN 训练数据更一致，通常具备更稳定的动作识别效果。
RGB Video
|
+-- MediaPipe Pose -------------------> NTU 25 3D Skeleton
| |
| v
| 3D ST-GCN Classifier
|
+-- Faster R-CNN + HRNet (MMPose) ----> COCO 17 2D Skeleton
|
v
2D ST-GCN Classifier
Classifier Output -> Top-K Results -> Visualization -> Gradio Web UI
主要模块分工如下：
app.py：系统入口，负责模型加载、推理流程、Gradio 界面和结果展示。pyskl/：PYSKL 框架源码及动作识别模型定义。configs/：PYSKL 原始配置与本项目使用的 ST-GCN 配置。resources/：检测与姿态估计配置文件，权重目录仅保留占位。models/：动作识别权重目录，仅保留占位。scripts/：性能测试和识别结果评估脚本。benchmark_results/：小型实验结果文件，用于记录系统级测试输出。
pyskl/
├── app.py
├── README.md
├── requirements.txt
├── setup.py / setup.cfg
├── LICENSE
├── pyskl/
├── configs/
├── scripts/
├── resources/
│ ├── faster_rcnn_config.py
│ ├── hrnet_config.py
│ ├── mmpose_guide.md
│ └── checkpoints/
├── models/
│ ├── stgcn_3d/
│ └── stgcn_2d_hrnet/
└── benchmark_results/
以下内容不包含在公开仓库中：
resources/checkpoints/*.pthmodels/**/*.pthwork_dirs/test_videos/benchmark_videos/benchmark_seketons/resources/sample_video.mp4- 压缩包、训练日志、缓存文件和 Python 编译产物
仓库中的 .gitkeep 文件仅用于保留空目录结构。实际运行时，需要将权重文件放入对应目录。
本项目运行依赖以下权重文件，但公开仓库不直接分发：
| 目标路径 | 用途 | 说明 |
|---|---|---|
resources/checkpoints/faster_rcnn_person.pth |
人体检测 | 来自 OpenMMLab / MMDetection 公开模型 |
resources/checkpoints/hrnet_w32_pose.pth |
姿态估计 | 来自 OpenMMLab / MMPose 公开模型 |
models/stgcn_3d/model.pth |
MediaPipe 3D 方案动作分类 | 可由 NTU RGB+D 60 训练流程复现，或使用已确认可分发的权重 |
models/stgcn_2d_hrnet/model.pth |
HRNet 2D 方案动作分类 | 可参考 PYSKL model zoo 或自行训练 |
权重文件名和目录结构需要保持一致，否则默认代码无法直接加载模型。
对于基于 NTU RGB+D 等受限数据集训练得到的模型权重，本仓库只记录实验设置和结果，不公开发布训练权重。这样可以避免将受限数据集的派生成果作为公开资产再分发。
本仓库不分发任何原始视频、网络视频、公开数据集视频、骨骼 .pkl 文件或由视频生成的派生数据。
使用者需要自行保证输入视频具有合法来源，并确认相关版权、肖像权和隐私授权。公开数据集通常有独立使用条款；即使数据集可申请下载，也不意味着可以将其中的视频、截图、骨骼文件或派生数据重新上传到 GitHub。
本项目的代码许可证不自动覆盖第三方模型权重、数据集、视频素材或派生数据。第三方组件与数据资源应分别遵守其原始许可证和使用协议。
- Ubuntu 20.04 / 22.04 / 24.04，推荐 WSL2 Ubuntu
- Python 3.9
- PyTorch 2.0.1
- CUDA 11.8，CPU 可运行但速度较慢
mmcv-full==1.7.2mmdet==2.28.2mmpose==0.29.0mediapipe>=0.10.0gradio>=3.50.0
以下命令建议在 WSL Ubuntu 或 Linux 环境中执行。
conda create -n pyskl python=3.9 -y
conda activate pyskl安装 PyTorch：
pip install torch==2.0.1 torchvision==0.15.2 --index-url https://download.pytorch.org/whl/cu118如果没有 GPU，可使用 CPU 版本：
pip install torch==2.0.1 torchvision==0.15.2安装 OpenMMLab 相关依赖：
pip install mmcv-full==1.7.2 -f https://download.openmmlab.com/mmcv/dist/cu118/torch2.0/index.html安装项目依赖：
cd /path/to/skeleton-action-recognition
pip install -e .
pip install -r requirements.txt由于 mmpose==0.29.0 默认限制 mmcv <= 1.7.0，而本项目使用 mmcv-full==1.7.2，需要放宽版本检测：
python -c "import mmpose, os; p = os.path.join(os.path.dirname(mmpose.__file__), '__init__.py'); \
s = open(p).read().replace(\"mmcv_maximum_version = '1.7.0'\", \"mmcv_maximum_version = '1.8.0'\"); \
open(p, 'w').write(s)"安装中文字体，用于可视化标题显示：
sudo apt install fonts-wqy-microhei -y
rm -rf ~/.cache/matplotlib确认权重文件已经放入对应目录后，启动系统：
conda activate pyskl
python app.py默认访问地址通常为：
http://localhost:7860
如果端口被占用，Gradio 会自动切换到其他端口，请以终端输出为准。
系统界面提供两组主流程：
- 视频动作识别：上传视频，提取骨骼，执行动作分类，返回 Top-K 结果和可视化视频。
- 骨骼数据处理：将视频转换为
.pkl骨骼数据，或对已有.pkl文件进行离线识别。
公开仓库不提供测试视频。建议使用自行拍摄且可公开使用的短视频进行验证。
动作分类指标使用 top_k_accuracy。项目中的主要结果如下：
| 方案 | 骨骼格式 | 训练/评估设置 | Top-1 | Top-5 |
|---|---|---|---|---|
| MediaPipe + 3D ST-GCN | NTU 25 关节 3D | NTU RGB+D 60 X-Sub | 86.34% | 97.33% |
| HRNet + 2D ST-GCN | COCO 17 关节 2D | NTU RGB+D 60 X-Sub，HRNet 2D 骨骼 | 89.0% | - |
这些结果用于描述实验配置和系统能力，不表示仓库分发了对应数据集、原始视频、骨骼数据或模型权重。
- 在同一 Web 应用中封装两条姿态估计与动作识别链路。
- 对 MediaPipe 33 landmark、NTU 25 关节和 COCO 17 关节进行格式适配。
- 将视频逐帧处理、人体检测、姿态估计、跨帧骨骼组织和 ST-GCN 推理串联为统一流程。
- 支持骨骼数据导出与离线识别，便于将姿态估计和动作分类阶段解耦。
- 对 GPU/CPU 运行、中文字体、Gradio 端口、MMPose/MMCV 版本兼容问题进行工程处理。
- 保留小型 benchmark 结果，记录不同方案在实际系统中的运行表现。
- 系统识别类别限定为 NTU RGB+D 60 的 60 个动作；开放集动作会被归入最相近类别。
- MediaPipe 方案依赖单目 3D 估计，与 Kinect 3D 骨骼训练分布存在差异。
- MMPose 方案精度更稳定，但检测和姿态估计阶段计算成本较高。
- 双人遮挡、人物过小、低光照、强运动模糊或画面裁切会影响骨骼质量。
- COCO 17 与 NTU 25 格式都不包含手指级细节，对细粒度手部动作区分有限。
- 公开仓库缺少权重和测试视频，默认不能做到 clone 后直接完整运行。
Q：为什么仓库没有 .pth 文件？
A：模型权重属于大二进制资产，并且可能涉及第三方模型条款或数据集派生风险。公开仓库只保留代码、配置和说明。
Q：为什么目录里有空的 .gitkeep 文件？
A：Git 不追踪空目录。.gitkeep 用于保留权重目录结构，便于用户按 README 放置权重文件。
Q：为什么不提供样例视频？
A：公开视频、数据集视频和网络视频都可能涉及版权、肖像权或隐私限制。公开仓库不分发这些素材。
Q：启动时报 No module named 'mmcv._ext'？
A：通常是安装了纯 Python 版 mmcv，而不是带 CUDA/C++ 扩展的 mmcv-full。请重新安装与当前 PyTorch/CUDA 匹配的 mmcv-full==1.7.2。
Q：MMPose 报 MMCV==1.7.2 is used but incompatible？
A：请执行安装步骤中的 MMPose 版本检测修正命令。
- PYSKL: https://github.com/kennymckormick/pyskl
- ST-GCN: Spatial Temporal Graph Convolutional Networks for Skeleton-Based Action Recognition
- NTU RGB+D: https://rose1.ntu.edu.sg/dataset/actionRecognition/
- MediaPipe Pose: https://google.github.io/mediapipe/solutions/pose.html
- MMDetection: https://github.com/open-mmlab/mmdetection
- MMPose: https://github.com/open-mmlab/mmpose
本项目基于 PYSKL / OpenMMLab 相关代码进行二次开发。仓库中的 PYSKL 原始代码遵循 Apache License 2.0，详见 LICENSE。
需要区分以下资产边界：
- 仓库代码：遵循仓库内许可证及上游代码许可证。
- 第三方库：遵循各自项目许可证。
- 第三方模型权重：遵循对应模型发布方条款。
- 数据集、视频和派生骨骼数据：遵循原始数据来源的使用协议和隐私约束。
如果基于本项目继续开发或公开发布修改版本，请保留上游版权声明、许可证信息和数据使用边界说明。