简介本资源是一套面向高校学生与深度学习入门者的Python毕业设计项目围绕时空图卷积网络ST-GCN实现骨骼动作识别适合作为课程设计、毕业设计参考或计算机视觉方向的实践练手。项目基于人体骨骼图结构通过图卷积同时捕捉动作的空间连接与时序变化可应用于健康监测、人机交互、视频监控及智能游戏等场景。压缩包共91个文件约52.54MB包含29个py源码、13个yaml配置、12个pyc缓存、11个gif演示、9个txt说明、3个pt预训练模型及mp4演示视频等覆盖数据生成、模型定义、训练配置与离线/实时识别脚本。已有175人学习下载。读者可获得完整可运行的源码、训练好的模型权重与项目文档文档记录了设计思路、实验过程与结果分析便于快速复现、二次开发与答辩准备。1. 从一份 94.5 分的毕设说起ST-GCN 骨骼动作识别资源能跑出什么如果你手头正好有一份骨架数据却卡在「怎么把关节坐标喂进网络」这一步这份基于时空图卷积ST-GCN的骨骼动作识别资源值得先拆开看。它不是一篇讲原理的论文复现而是一套能直接跑的 Python 毕业设计工程源码、训练好的权重、NTU-RGB-D 和 Kinetics 两套数据管线、离线与实时两个 demo外加一份答辩文档。作者自述代码逐项测过、答辩评审平均分 94.5这个分数不代表模型有多前沿但说明工程闭环是完整的——数据进得去、模型训得动、结果出得来。骨骼动作识别解决的是「只看人体关节轨迹判断在做什么动作」的问题。相比直接吃 RGB 视频骨架输入少了背景、光照、衣着干扰维度低、隐私性好在康复评估、体育动作分析、人机交互里都用得上。ST-GCN 的价值在于它把骨架天然组织成一张时空图空间维度上按人体骨骼连接建边时间维度上把相邻帧同一关节连起来再用图卷积在这张图上做特征聚合。这套资源把这条链路完整落地了适合两类人一是要交毕业设计、需要一份能讲清楚也能跑通的项目二是想拿骨架数据做实验、不想从零搭数据加载和训练框架的开发者。下面按「资源里有什么 → 怎么跑起来 → 坑在哪 → 怎么改」的顺序拆。2. 拆开 ST-GCN-master目录结构、模型文件与数据管线怎么对应拿到一个压缩包先别急着python main.py。ST-GCN 这类工程最容易翻车的地方不是模型本身而是数据格式和配置对不上。花十分钟把目录结构和它背后的数据流对齐后面能省掉大量报错排查。2.1 从目录树反推三条主链路这份资源的顶层结构大致可以分成四块每一块对应一条独立的执行链路目录/文件作用对应链路main.py/config/训练与测试入口、配置目录训练链路feeder/数据加载含feeder.py、feeder_kinetics.py数据链路net/网络定义st_gcn.py、st_gcn_twostream.py模型链路processor/推理与可视化demo_offline.py、demo_realtime.py推理链路models/预训练权重如OriginSTGCN.pt、kinetics-st_gcn.pt直接推理resource/骨架数据、标签、参考模型说明数据与文档net/st_gcn.py是单流 ST-GCN 的主体st_gcn_twostream.py是双流版本关节流 骨骼流models/里那几个.pt就是训练好的权重。feeder/下的两个文件分别对应 NTU-RGB-D 和 Kinetics 两种数据组织方式这是新手最容易混的地方——两套数据的关节数量、帧长、标签体系都不一样配置写错就会在加载阶段直接崩。2.2 模型文件与配置的对应关系models/里能看到OriginSTGCN.pt、AddEdgeSTGCN12345.pt、kinetics-st_gcn.pt这几个权重。从命名能推断OriginSTGCN是原始图结构AddEdgeSTGCN12345是在邻接矩阵上做了边权增强的变体kinetics-st_gcn是在 Kinetics 骨架数据上训的。config/st_gcn/下按数据集分了子目录训练时用哪个配置就得配哪个权重和哪套 feeder。常见做法是先确认你要跑 NTU-RGB-D 还是 Kinetics再决定用哪个 config、哪个 feeder、哪个权重。三者必须一致这是这份资源里最硬的一条约束。2.3 数据管线的关键参数feeder/feeder.py里控制数据形状的核心参数有几个改之前先理解含义num_classes分类数NTU-RGB-D 常见 60 类Kinetics 是 400 类写错会导致输出维度对不上标签。max_frames/ 采样帧数控制每条样本取多少帧太大显存吃紧太小动作信息丢失。bone开关是否使用骨骼流双流时用单流推理保持关闭。window_size时间卷积的感受野影响时序建模范围。这些参数在 config 的 yaml 里也有对应项命令行参数会覆盖配置文件。我一般先只改 config不动源码默认值保证可复现。2.4 跑通训练前的最小检查在正式训练前建议先做一次数据加载自检确认张量形状符合预期# 数据自检确认 feeder 输出的张量形状与标签范围 from feeder.feeder import Feeder data_loader Feeder( data_path./resource/NTU-RGB-D/xview/, # 骨架数据路径 label_path./resource/NTU-RGB-D/xview/, # 标签路径 max_frames300, # 采样帧数 num_classes60 # NTU-RGB-D 类别数 ) data, label, index data_loader[0] print(data shape:, data.shape) # 期望 (C, T, V, M) print(label:, label, index:, index)逻辑说明Feeder返回的是(C, T, V, M)四维张量C 是通道坐标维度T 是帧数V 是关节数M 是人数。如果打印出来的 V 不是 25NTU 标准关节数说明数据文件或配置对不上。参数上max_frames要和训练配置里的采样策略一致num_classes必须等于标签实际类别数否则后面算 loss 会直接报维度错误。这一步跑通再进main.py训练能过滤掉八成低级错误。3. 从零跑通训练与推理环境、命令与 demo 实操环境配好、数据自检通过之后训练和推理就是按链路走命令。这一章把环境依赖、训练命令、离线 demo 和实时 demo 分开讲每一步都落到可复制的命令和参数上。3.1 环境依赖与版本约束requirements.txt里列了核心依赖PyTorch 是主体。这类 2019 年前后的 ST-GCN 工程对版本比较敏感常见做法是锁一个能跑通的组合而不是无脑装最新版# 建议在独立虚拟环境里装依赖避免污染全局 python -m venv stgcn_env source stgcn_env/bin/activate # Windows 用 stgcn_env\Scripts\activate # 按 requirements 安装PyTorch 版本按本机 CUDA 选 pip install -r requirements.txt pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118逻辑说明先建虚拟环境隔离依赖再装 requirements。PyTorch 单独装是因为它的 wheel 和 CUDA 版本绑定直接写进 requirements 容易装到 CPU 版或版本不匹配。参数上cu118对应 CUDA 11.8如果你的显卡驱动支持别的版本换成对应索引即可。装完用python -c import torch; print(torch.cuda.is_available())确认 GPU 可用返回 False 就先解决驱动问题别急着训练。3.2 训练命令与关键参数训练入口是main.py配合config/下的 yaml。典型命令# 在 NTU-RGB-D 上训练单流 ST-GCN python main.py recognition \ -c config/st_gcn/nturgbd-cross-view/train.yaml \ --device 0 \ --work-dir work_dir/recognition/ntu_xview逻辑说明recognition是子命令指定任务类型-c指向训练配置--device 0指定用第 0 块 GPU--work-dir是日志和权重输出目录。参数上如果显存不够去 yaml 里调小batch_size如果训练 loss 不降先检查学习率和数据标签是否对齐。work_dir目录建议每次训练换一个避免旧日志覆盖出问题时能回溯。3.3 离线 demo拿现成权重直接出结果不想训练、只想看效果直接跑离线 demo 最快# 用预训练权重跑离线推理 python processor/demo_offline.py \ --config config/st_gcn/nturgbd-cross-view/test.yaml \ --weights models/OriginSTGCN.pt \ --video resource/media/sample.mp4逻辑说明demo_offline.py读视频或骨架序列加载权重输出动作类别。参数上--weights要和--config匹配用 NTU 的权重配 Kinetics 的配置会得到无意义结果。--video指向待推理的素材如果资源里没带视频用resource/media/下的示例或自己准备一段。输出通常是类别标签加置信度置信度普遍偏低时多半是输入骨架的归一化方式和训练时不一致。3.4 实时 demo 与可视化demo_realtime.py走摄像头或视频流配合processor/processor.py做逐帧推理。这条链路对帧率和延迟敏感常见做法是先把max_frames调小、降低采样密度保证实时性# 实时推理注意帧率与显存占用 python processor/demo_realtime.py \ --config config/st_gcn/nturgbd-cross-view/test.yaml \ --weights models/OriginSTGCN.pt \ --camera 0逻辑说明--camera 0指定默认摄像头。实时链路里预处理和推理是串行的帧率上不去时优先看预处理耗时而不是盲目换模型。参数上如果画面卡顿降低输入分辨率或减少max_frames如果识别结果抖动严重加一个滑动窗口做多数投票平滑。processor/io.py和DrawLine.py负责骨架绘制可视化不对时先查关节连接定义是否和数据集一致。4. 避坑与排查数据格式、权重匹配和显存这三类问题最常翻车这份资源能跑通但「能跑通」和「你拿到就能跑通」是两回事。下面几条是我拆这类 ST-GCN 工程时反复遇到的坑按现象、原因、解决写清楚。4.1 加载数据时报形状不匹配现象运行main.py或 feeder 自检时报张量维度错误或V维度不是 25。原因NTU-RGB-D 和 Kinetics 的关节数、坐标维度不同feeder 选错或数据文件放错目录。解决先确认数据集NTU 用feeder.py、Kinetics 用feeder_kinetics.py再核对data_path下的.npy或.txt文件命名是否符合 feeder 的解析规则。数据自检那一步就是专门用来提前暴露这个问题的。4.2 权重和配置对不上推理结果全是同一类现象离线 demo 跑出来所有输入都预测成同一个类别置信度还很低。原因权重是在某个数据集上训的配置却指向另一个数据集的类别数和图结构。解决models/OriginSTGCN.pt配 NTU 的 configkinetics-st_gcn.pt配 Kinetics 的 configAddEdgeSTGCN12345.pt配带边权增强的配置。三者一致是硬约束别混用。4.3 训练中途显存溢出现象训练跑几十个 iteration 后报 CUDA out of memory。原因batch_size或max_frames偏大加上双流模型参数量翻倍。解决先把batch_size减半再考虑降max_frames双流训练时两条流分开跑或分时加载别同时驻留。显存碎片也会导致溢出训练脚本里定期torch.cuda.empty_cache()能缓解。4.4 实时 demo 帧率低、延迟高现象demo_realtime.py画面卡顿识别结果滞后。原因预处理和推理串行且每帧都做完整前向。解决降低输入分辨率、减少采样帧数或改成每隔 N 帧推理一次、中间帧复用结果。实时场景里延迟比精度更影响体验先保帧率再谈准确率。4.5 可视化骨架连线错乱现象DrawLine.py画出来的骨架连线和人体对不上。原因关节索引顺序和数据集定义不一致NTU 和 Kinetics 的关节编号不同。解决对照resource/里的说明确认关节顺序改DrawLine.py里的连接表。可视化错了不影响推理数值但会误导你对结果的判断答辩演示前一定要核对。5. 改模型与换数据从 OriginSTGCN 到 AddEdge 的进阶玩法跑通默认链路之后这份资源真正的价值在于它留了改造空间。net/st_gcn.py和st_gcn_twostream.py是干净的实现AddEdgeSTGCN12345.pt这个权重说明作者试过在邻接矩阵上做边权增强这正是 ST-GCN 系列最常见的改进方向。5.1 理解邻接矩阵改模型的入口ST-GCN 的核心是把人体骨架建成图邻接矩阵决定「哪些关节互相影响」。原始实现用固定的骨骼连接AddEdge版本在边上加了可学习或加权的连接。想改模型先找到net/utils/下构建邻接矩阵的代码看清A是怎么生成的# 邻接矩阵构建的典型逻辑示意按实际源码调整 import numpy as np num_node 25 # NTU 关节数 # 自连接 self_link [(i, i) for i in range(num_node)] # 相邻关节连接按人体骨骼定义 neighbor_link [(0,1),(1,20),(2,20),(3,2),(4,20),(5,4),(6,5),(7,6), (8,20),(9,8),(10,9),(11,10),(12,20),(13,12),(14,13), (15,14),(16,20),(17,16),(18,17),(19,18),(21,22), (22,23),(23,24),(24,21)] A np.zeros((num_node, num_node)) for i, j in self_link neighbor_link: A[i, j] 1 A[j, i] 1逻辑说明这段构建的是基础邻接矩阵self_link是自连接neighbor_link是骨骼连接。参数上num_node必须和数据集关节数一致连接表必须和人体拓扑一致。想加边权就在A上做归一化或引入可学习参数AddEdge版本大概率就是在这个位置改的。改完记得同步改配置里的图结构参数否则权重加载会报 key 不匹配。5.2 换数据集要动哪些地方想用自己的骨架数据需要改三处feeder 的解析逻辑、config 里的类别数和关节数、以及邻接矩阵的关节连接。常见做法是先把自有数据整理成和 NTU 相同的目录结构和文件格式再复用feeder.py这样改动最小。数据量小的时候冻结主干、只训分类头能避免过拟合。5.3 验证改动是否有效改完模型别只看训练 loss用固定随机种子跑一次完整测试对比改动前后的 top-1 准确率。main.py的测试子命令能直接加载权重评估# 加载指定权重做测试评估 python main.py recognition \ -c config/st_gcn/nturgbd-cross-view/test.yaml \ --weights work_dir/recognition/ntu_xview/epoch50_model.pt \ --test逻辑说明--test走评估流程输出准确率。参数上权重路径指向你要验证的那次训练产物config 用对应的测试配置。对比时固定数据和随机种子否则准确率波动分不清是改动带来的还是随机性。5.4 一个具体技巧双流融合的权重分配st_gcn_twostream.py是关节流加骨骼流的双流结构两路结果融合时权重怎么分很影响最终精度。我一般先让两路各自单独评估看哪路更强再按验证集表现分配融合权重而不是简单取平均。融合前把两路的输出做 softmax 再加权比直接加权 logits 更稳。这套流程走下来你会发现这份资源真正的门槛不在模型而在数据对齐和配置一致性——从那以后我每次拿到新的 ST-GCN 工程都强制先跑一遍数据自检、再核对权重与配置的对应关系这两步做完后面基本不会出玄学问题。希望帮到你。本文还有配套的精品资源点击获取