简介这份资源面向计算机相关专业的本科生与研究生提供一套基于时空图卷积网络ST-GCN的骨骼动作识别完整毕业设计项目适合作为毕业设计、期末大作业或课程设计的高分参考方案。项目围绕骨架关键点数据展开涵盖数据预处理、图卷积模型构建、双流网络设计以及离线与实时识别演示等核心环节代码注释详尽新手也能较快理解整体流程。压缩包共90个文件约52.61MB包含29个Python源码文件、13个YAML配置、12个编译缓存文件以及GIF演示、PNG图示、TXT说明、Markdown文档、预训练权重pt文件、MP4演示视频和Shell脚本等覆盖从训练到推理的完整链路。目前已有188人学习下载。读者可获得可直接部署运行的工程代码、模型权重与配置模板并借助目录中的工具脚本与说明文档快速复现实验、理解ST-GCN在骨骼动作识别中的实现细节为答辩与二次开发提供扎实基础。1. 从一份 98 分毕设说起ST-GCN 骨骼动作识别到底能跑出什么如果你正在为计算机视觉方向的毕业设计选题发愁或者手头有一个「人体动作识别」的需求但不知道从哪下手这份基于时空图卷积ST-GCN的 Python 项目大概率能让你少走两周弯路。它不是那种只有几行 demo 的玩具代码而是一套完整的骨骼动作识别工程从 NTU-RGBD、Kinetics 骨架数据的预处理到 ST-GCN 双流网络定义再到离线视频推理和实时摄像头 demo目录结构清晰关键位置有中文注释新手照着 README 也能把环境跑通。适合谁做毕业设计、期末大作业、课程设计的学生以及想快速验证骨骼动作识别方案可行性的算法工程师。它解决的核心问题是把「人体骨架序列 → 动作类别」这条链路用图卷积网络跑通并且给你一份能改、能扩、能写进论文的代码基线。2. ST-GCN 的骨架图建模为什么它比 CNN 更适合动作识别2.1 骨骼数据的图结构本质人体骨架天然不是一张规则网格。以 NTU-RGBD 为例每帧有 25 个关节点关节点之间由骨骼边连接形成一张空间图时间维度上同一关节点在连续帧之间又形成时序边。传统 CNN 处理的是规则网格图像像素把它硬套到骨架上会丢失关节之间的拓扑关系。ST-GCN 的做法是把骨架序列建模成一张时空图空间维度用人体物理连接定义邻接矩阵时间维度用帧间连接定义时序边然后在图上做卷积。具体来说空间图卷积的核心公式是f_out(v) Σ_{u∈B(v)} (1/Z(v)) · f_in(u) · W(l(v,u))其中B(v)是节点 v 的邻居集合Z(v)是归一化系数W是根据邻居类型分配的权重。这个公式看起来抽象落到代码里其实就是邻接矩阵乘特征再乘权重矩阵。项目里net/utils/st_gcn.py和net/utils/st_gcn_twostream.py就是这套逻辑的实现AddEdgeWeight_2.txt和AddEdgeSTGCN12345.pt则对应了带边权重的改进版本。2.2 空间配置与分区策略ST-GCN 把每个关节的邻居分成三个子集根节点自身、向心组离骨架重心更近的邻居、离心组离重心更远的邻居。这种分区策略让网络能区分「向身体中心收缩」和「向外伸展」两种运动模式。项目里config/st_gcn和config/st_gcn.twostream两个目录下的配置文件就是用来指定分区策略、边权重类型等参数的。常见做法是先用tools/ntu_gendata.py把原始 NTU 数据转成.npy格式的骨架序列再用feeder/feeder.py加载。如果你用的是 Kinetics 数据对应脚本是tools/kinetics_gendata.py和feeder/feeder_kinetics.py。这里有个容易忽略的点NTU 和 Kinetics 的关节数量不同NTU 是 25Kinetics 是 18所以配置文件和 feeder 必须匹配不能混用。2.3 双流网络的互补逻辑单流 ST-GCN 只输入关节坐标Joint Stream对动作的判别力有限。项目里的st_gcn_twostream.py实现了双流结构一路输入关节坐标另一路输入骨骼向量Bone Stream即相邻关节的坐标差。两路分别训练后融合分数通常能提升 2~4 个百分点的准确率。kinetics-motion.txt和reference_model.txt就是双流训练时用来记录运动信息和参考模型的文件。提示如果你只想快速跑通单流用config/st_gcn下的配置即可想冲高分再上双流但双流训练时间大约是单流的 1.8 倍。3. 从零部署环境、数据、训练、推理四步走3.1 环境安装与依赖确认项目根目录有requirements.txt但直接pip install -r有时会因为 PyTorch 版本不匹配翻车。我一般会先确认 Python 版本建议 3.7~3.9再手动装 PyTorch。以下是经过验证的安装顺序# 创建虚拟环境避免污染全局 python -m venv stgcn_env source stgcn_env/bin/activate # Windows 用 stgcn_env\Scripts\activate # 先装 PyTorch版本按你的 CUDA 选这里以 CUDA 11.3 为例 pip install torch1.10.0cu113 torchvision0.11.1cu113 -f https://download.pytorch.org/whl/torch_stable.html # 再装项目其他依赖 pip install -r requirements.txt # 确认 GPU 可用 python -c import torch; print(torch.cuda.is_available())逻辑说明PyTorch 必须最先装因为requirements.txt里可能包含torch的松散版本约束先装固定版本能避免后续被覆盖。torch.cuda.is_available()返回True才说明 GPU 环境正常否则训练会退到 CPU速度差 20 倍以上。参数方面CUDA 版本要和显卡驱动匹配不确定的话用nvidia-smi看右上角的 CUDA Version。3.2 数据准备NTU 与 Kinetics 两条路项目支持两种数据源。NTU-RGBD 需要你自行下载原始数据项目里NTU-RGB-D目录是占位然后用tools/ntu_gendata.py转换# 转换 NTU 数据生成训练和验证用的 .npy 文件 python tools/ntu_gendata.py --data_path ./NTU-RGB-D/nturgbd_skeletons_s001_to_s017/ \ --out_folder ./data/ntu --ignored_sample_path ./NTU-RGB-D/samples_with_missing_skeletons.txt参数说明--data_path指向原始骨架文件目录--out_folder是输出目录--ignored_sample_path用来排除缺失骨架的样本NTU 官方提供这个列表。转换完成后feeder/feeder.py会自动读取.npy文件并按配置切分训练集和验证集。Kinetics 数据则用tools/kinetics_gendata.py但要注意 Kinetics 的原始数据是视频需要先用姿态估计工具如 OpenPose提取骨架项目里pose目录就是放姿态估计相关文件的。这一步是新手最容易卡住的地方OpenPose 的安装本身就有一定门槛建议直接用项目提供的demo_asset里的示例骨架数据先跑通流程再回头处理自己的数据。3.3 训练配置与启动训练入口是main.py配置文件在config/st_gcn/下。以 NTU 单流为例# 启动训练指定配置文件和输出目录 python main.py --config config/st_gcn/ntu-xsub/train.yaml \ --work-dir work_dir/ntu_xsub --device 0逻辑说明--config指定 YAML 配置文件里面定义了学习率、batch size、epoch 数、图结构参数等--work-dir是模型权重和日志的输出目录--device 0指定用第 0 号 GPU。训练过程中work_dir下会生成log和model两个子目录log里能看到 loss 和 accuracy 曲线。关键参数怎么改如果显存不够把配置文件里的batch_size从 64 降到 32 或 16如果收敛太慢检查learning_rate是否设成了 0.1ST-GCN 原论文用的就是这个值太大容易震荡太小收敛慢。AddEdgeWeight_2.txt里记录了边权重相关的调参经验值得在改配置前翻一翻。3.4 离线推理与实时 Demo训练完成后用demo_offline.py对视频文件做推理# 对单个视频做动作识别 python demo_offline.py --video ./demo_asset/test.mp4 \ --model ./work_dir/ntu_xsub/model/best_model.pt \ --config config/st_gcn/ntu-xsub/train.yaml参数说明--video是输入视频路径--model是训练好的权重文件--config必须和训练时一致否则图结构对不上会报维度错误。demo_realtime.py则是调用摄像头做实时识别适合答辩时演示。recognition.py和processor.py是推理流程的底层实现想改后处理逻辑比如加平滑滤波可以从这里入手。注意实时 demo 对帧率有要求如果摄像头帧率低于 15fps识别结果会明显抖动。常见做法是在processor.py里加一个滑动窗口投票取最近 5 帧的多数结果作为输出。4. 避坑与排查那些让我熬夜的报错4.1 维度不匹配RuntimeError: mat1 and mat2 shapes cannot be multiplied现象训练启动后立刻报矩阵乘法维度错误。原因配置文件中num_class或in_channels和实际数据不一致比如用 NTU 的配置跑 Kinetics 数据25 关节 vs 18 关节。解决确认feeder和config匹配NTU 用config/st_gcn/ntu-xsub/Kinetics 用config/st_gcn/kinetics-skeleton/不要交叉使用。4.2 数据加载卡死Dataloader worker 报 BrokenPipeError现象训练开始后卡在第一个 epoch或者直接报BrokenPipeError。原因num_workers设得太大或者共享内存不足。解决把配置文件里的num_workers从 8 降到 2 或 0先确认单进程能跑通再往上加。Linux 下还可以检查/dev/shm大小太小的话需要重新挂载。4.3 模型加载失败Missing key(s) in state_dict现象用demo_offline.py加载权重时报 key 不匹配。原因训练用的是双流模型推理时加载了单流配置或者反过来。解决检查--config和训练时是否一致双流模型要用st_gcn_twostream.py对应的配置。如果只是部分 key 缺失比如少了bn层可以用strictFalse加载但准确率可能下降。4.4 准确率异常低验证集 acc 一直在 10% 左右现象训练 loss 在降但验证准确率不涨。原因最常见的是标签错位——feeder里读到的 label 和实际动作类别对不上或者数据预处理时把训练集和验证集搞反了。解决先用JustTest.py跑一个小样本打印几条数据的 label 和形状确认无误后再全量训练。另一个可能是学习率太大导致模型震荡试着降到 0.01。4.5 实时 demo 延迟高摄像头画面和识别结果不同步现象demo_realtime.py跑起来后画面卡顿识别结果滞后好几秒。原因姿态估计和 ST-GCN 推理串行执行且没有做帧丢弃。解决常见做法是把姿态估计和动作识别放到两个线程中间用一个固定长度的队列缓冲或者降低输入分辨率牺牲一点精度换帧率。processor.py里的io.py负责数据流转改这里比改模型更有效。5. 进阶技巧用边权重和双流融合把准确率再提一档如果你已经把基础流程跑通答辩想拿更高分可以从两个方向继续挖。第一个方向是边权重改进。原始 ST-GCN 的邻接矩阵是 0/1 的表示「有没有连接」但实际动作中不同骨骼边的重要性不同——比如「挥手」动作里手臂边的权重应该比腿部边大。项目里的AddEdgeWeight_2.txt和AddEdgeSTGCN12345.pt就是带边权重的版本思路是用注意力机制或可学习的边权重矩阵替换固定邻接矩阵。具体做法是在st_gcn.py里找到邻接矩阵定义的位置把self.A从固定 tensor 改成nn.Parameter让网络自己学。第二个方向是双流融合策略。单流跑通后分别训练 Joint Stream 和 Bone Stream然后在推理时融合分数。融合方式有两种早期融合把两路特征拼接后送分类器和晚期融合两路各自出分数再平均或加权。项目里st_gcn_twostream.py用的是晚期融合实现简单且稳定。如果你想再进一步可以试加权融合——给 Bone Stream 更高的权重因为骨骼向量对动作方向的判别力通常更强。验证方法上建议每次改动只动一个变量跑完对比验证集准确率。我一般会固定随机种子在main.py里设torch.manual_seed(42)这样两次实验的差异才能归因到改动本身而不是数据 shuffle 的玄学。另外work_dir下的日志文件要保留方便回溯哪次配置对应哪个结果。从那以后我每次改模型结构前都会先用JustTest.py跑一个 mini-batch 的前向传播确认维度对得上再开全量训练——这个习惯帮我省了至少十次通宵排查。希望这份拆解能帮到你把这份 ST-GCN 毕设真正跑起来、改起来。本文还有配套的精品资源点击获取
