PYSKL

注意：此仓库目前不由开发者维护。欢迎创建分支并基于这些代码进行开发。

[报告]

PYSKL 是一个专注于基于 SKeLeton 数据的 PYTorch 动作识别工具箱。它将支持多种基于骨骼的动作识别算法。我们基于开源项目 MMAction2 构建了这个项目。

该仓库是 PoseConv3D 和 STGCN++ 的官方实现。

变更日志

• 改进了骨骼提取脚本（PR）。现在支持非分布式骨骼提取和 k400 风格（2023-03-20）。
• 支持 PyTorch 2.0：当为训练/测试脚本设置 --compile 并检测到 torch.__version__ >= 'v2.0.0' 时，将在训练/测试前使用 torch.compile 编译模型。实验性功能，绝对不保证性能（2023-03-16）。
• 提供了一个基于 ST-GCN++ 的实时手势识别演示，更多详情和说明请参阅 Demo（2023-02-10）。
• 提供了用于估计各模型推理速度的 脚本（2022-12-30）。
• 支持 RGBPoseConv3D，这是一种基于 RGB 和人体骨骼的双流 3D-CNN 动作识别方法。请按照 指南 在 NTURGB+D 上训练和测试 RGBPoseConv3D（2022-12-29）。

支持的算法

• DG-STGCN (Arxiv) [MODELZOO]
• ST-GCN (AAAI 2018) [MODELZOO]
• ST-GCN++ (ACMMM 2022) [MODELZOO]
• PoseConv3D (CVPR 2022 Oral) [MODELZOO]
• AAGCN (TIP) [MODELZOO]
• MS-G3D (CVPR 2020 Oral) [MODELZOO]
• CTR-GCN (ICCV 2021) [MODELZOO]

支持的骨骼数据集

• NTURGB+D (CVPR 2016) 和 NTURGB+D 120 (TPAMI 2019)
• Kinetics 400 (CVPR 2017)
• UCF101 (ArXiv 2012)
• HMDB51 (ICCV 2021)
• FineGYM (CVPR 2020)
• Diving48 (ECCV 2018)

安装

git clone https://github.com/kennymckormick/pyskl.git
cd pyskl
# 此命令在 conda 22.9.0 下运行良好，如果您使用的是较早版本的 conda 并遇到一些错误，请先更新您的 conda
conda env create -f pyskl.yaml
conda activate pyskl
pip install -e .

Python 3.10 安装

git clone https://github.com/kennymckormick/pyskl.git
cd pyskl
conda env create -f pyskl_310.yaml
conda activate pyskl
pip install -e .

演示

请查看 demo.md。

数据准备

我们为每个支持的数据集提供了 HRNet 2D 骨骼，并为 NTURGB+D 和 NTURGB+D 120 数据集提供了 Kinect 3D 骨骼。要获取人体骨骼标注，您可以：

1. 使用我们预处理过的骨骼标注：我们直接以 pickle 文件的形式提供所有数据集的已处理骨骼数据（可直接用于训练和测试），下载链接和标注格式说明请参阅 Data Doc。
2. 对于 NTURGB+D 3D 骨骼，您可以从 https://github.com/shahroudy/NTURGB-D 下载官方标注，并使用我们提供的 脚本 生成已处理的 pickle 文件。生成的文件与提供的 ntu60_3danno.pkl 和 ntu120_3danno.pkl 相同。详细说明请参阅 Data Doc。
3. 我们还提供了从 RGB 视频中提取 2D HRNet 骨骼的脚本，您可以参考 diving48_example 从任意 RGB 视频数据集中提取 2D 骨骼。

您可以用 vis_skeleton 来可视化提供的骨骼数据。

训练与测试

您可以使用以下命令进行训练和测试。基本上，我们支持在单台服务器上使用多个 GPU 进行分布式训练。

# 训练
bash tools/dist_train.sh {config_name} {num_gpus} {other_options}
# 测试
bash tools/dist_test.sh {config_name} {checkpoint} {num_gpus} --out {output_file} --eval top_k_accuracy mean_class_accuracy

有关具体示例，请参阅我们所支持的每种算法的 README。

引用

如果您在研究中使用 PYSKL，或希望引用 Model Zoo 中发布的基准结果，请使用以下 BibTeX 条目，以及您所使用的具体算法对应的 BibTeX 条目。

@inproceedings{duan2022pyskl,
  title={Pyskl: 骨骼动作识别的最佳实践},
  author={Duan, Haodong 和 Wang, Jiaqi 和 Chen, Kai 和 Lin, Dahua},
  booktitle={第30届 ACM 国际多媒体会议论文集},
  pages={7351--7354},
  year={2022}
}

贡献

PYSKL 是一个基于 Apache2 许可证的开源项目。我们非常欢迎社区对 PYSKL 的改进与贡献。对于重要的贡献（例如支持一项新颖且重要的任务），我们将在更新的技术报告中添加相应内容，并将贡献者列入作者名单。

任何用户都可以通过提交 PR 来为 PYSKL 做出贡献。所有 PR 都将在合并到主分支之前接受评审。如果您计划在 PYSKL 中提交一个大型 PR，建议您先通过我的邮箱 dhd.efz@gmail.com 与我沟通设计细节，这样可以节省大量的评审时间。

联系方式

如有任何问题，请随时联系：dhd.efz@gmail.com

PYSKL 快速上手指南

PYSKL 是一个基于 PyTorch 的骨架（Skeleton）动作识别工具箱，支持多种主流算法（如 ST-GCN++, PoseConv3D 等）。本项目基于 MMAction2 构建，是 PoseConv3D 和 STGCN++ 的官方实现。

注意：目前该仓库已不再由原作者主动维护，但代码仍可自由 Fork 和使用。

环境准备

• 操作系统：Linux (推荐)
• Python 版本：Python 3.7+ (官方提供 Python 3.10 专用配置)
• 深度学习框架：PyTorch (支持 PyTorch 2.0，可开启 torch.compile 加速)
• 依赖管理：Conda (推荐使用 Conda 22.9.0 或更高版本以避免环境创建错误)
• 硬件要求：支持 CUDA 的 NVIDIA GPU (用于训练和高效推理)，CPU 亦可运行部分演示。

安装步骤

1. 克隆项目

git clone https://github.com/kennymckormick/pyskl.git
cd pyskl

2. 创建虚拟环境并安装依赖

方案 A：标准安装 (推荐) 适用于大多数环境，使用官方提供的 pyskl.yaml。

# 确保 conda 版本较新 (建议 >= 22.9.0)
conda env create -f pyskl.yaml
conda activate pyskl
pip install -e .

方案 B：Python 3.10 专用安装 如果你需要使用 Python 3.10，请使用专用的配置文件。

conda env create -f pyskl_310.yaml
conda activate pyskl
pip install -e .

提示：国内用户若遇到 conda 下载慢的问题，可临时切换至清华或中科大镜像源： conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/

基本使用

1. 数据准备

PYSKL 不直接处理原始视频，而是使用预提取的骨架数据（pickle 格式）。

• 直接使用预处理数据：官方提供了 NTU-RGB+D, Kinetics 等数据集的处理后文件。请参考 Data Doc 下载对应的 pickle 文件。
• 自行提取骨架：
  • 对于 NTU 3D 数据，可下载官方标注并使用 /tools/data/ntu_preproc.py 转换。
  • 对于普通 RGB 视频，可参考 /examples/extract_diving48_skeleton/diving48_example.ipynb 使用 HRNet 提取 2D 骨架。

2. 模型训练

支持多卡分布式训练。以下命令表示使用 {num_gpus} 张显卡，加载 {config_name} 配置文件进行训练。

bash tools/dist_train.sh {config_name} {num_gpus} {other_options}

示例：使用 2 张卡训练 ST-GCN++ 模型

bash tools/dist_train.sh configs/stgcn++/stgcn++_ntu60_xsub.py 2

3. 模型测试与评估

使用训练好的权重文件 {checkpoint} 进行测试，并输出评估指标。

bash tools/dist_test.sh {config_name} {checkpoint} {num_gpus} --out {output_file} --eval top_k_accuracy mean_class_accuracy

示例：测试并评估准确率

bash tools/dist_test.sh configs/stgcn++/stgcn++_ntu60_xsub.py work_dirs/stgcn++/latest.pth 2 --out results.pkl --eval top_k_accuracy mean_class_accuracy

4. 实时演示 (可选)

项目提供了一个基于 CPU 的实时手势识别演示（需摄像头），具体使用方法请查看 Demo 文档。

# 简要预览
python demo/demo_skeleton.py --config {config_file} --checkpoint {checkpoint_file}