简介面向计算机相关专业毕业设计或课程设计场景这份源码压缩包以MediaPipe提取人体关键点结合LSTM时序建模实现视频流中动作姿态的实时分类识别可应用于体育动作分析、康复训练等场景。压缩包共280个文件包含16个Python程序文件、2个预训练模型h5文件、240个npy数据文件用于训练与测试的关键点序列、16段mp4演示视频及说明文档整体约22.09MB结构清晰便于直接运行与二次开发。目前已有186人下载学习代码完整且经验证可稳定运行还附有训练好的模型与演示样例适合入门进阶、毕设项目、课程大作业或初期立项演示。项目默认路径建议使用英文命名解压后即可结合自身数据调整LSTM结构与MediaPipe配置扩展不同动作类别。1. 人体动作姿态识别为什么 MediaPipe 加 LSTM 这对组合值得在毕业设计里复现人体动作姿态识别听着像是要训一个能看懂视频的神经网络但真做起来大部分工作量其实在“姿态特征怎么来”和“时序怎么对齐”上。这个项目标题的核心思路很直接用 MediaPipe 先把每一帧画面里的人体抽成 33 个关键点骨架再把连续几十帧的骨架坐标拼成时间序列丢给 LSTM 做分类。这样你不需要从零训练一个姿态估计网络也不用处理原始图像的高维输入整个项目在普通笔记本上就能跑。这套方案适合两类人一类是毕业设计选了动作识别方向、不想把时间全耗在调参和显卡上的学生另一类是工作中临时要做人体行为分析、需要快速验证方案可行性的开发者。下文从原理、环境、数据、训练到踩坑按一条可复现的路径走一遍参数和代码都直接能抄走改自己的。2. 先把原理踩实MediaPipe 提取的是骨架LSTM 分类的是时间序列2.1 为什么是 MediaPipe而不是 OpenPose 或 YOLO 系姿态估计很多人一上来就纠结选哪个姿态估计模型我建议先看清楚分工MediaPipe 在这条链路里只负责“单帧关键点检测”它不干活时序建模。和 OpenPose 比MediaPipe 胜在轻量——官方提供了 CPU 上实时的解决方案不需要编译 C 工程Python 里pip install mediapipe就能用和 YOLO 系列的 pose 分支比MediaPipe 在单人场景下关键点输出更稳定且自带可见性置信度这个属性在后面对齐数据时很有用。省下的时间可以全花在真正要做的 LSTM 时序分类上。做毕设时最怕的就是环境问题吞掉两周时间而 OpenPose 在 Windows 上编译 pybind11、配置 CUDA 的流程足以让一个新手失去动力。MediaPipe 在这类方案里扮演的是“特征提取器”相当于别人把最难的一步替你做完了。2.2 LSTM 在这个项目里到底在学什么LSTM 处理的是“骨架坐标序列”。比如一个“抬手”动作在 30 帧里表现为手腕关键点的 y 坐标从躯干旁侧逐步抬升到头顶附近然后又放下来。LSTM 学的就是这种坐标随时间的动态变化模式不是某一帧长什么样。关键点在于输入数据组织方式每一帧由 MediaPipe 输出 33 个关键点每个点有x,y,z,visibility四个值。如果全部原样丢进网络维度是 132信息冗余很高因为不同人的身高臂长不一样同一动作在画面里位置也不一样。所以在喂给 LSTM 前必须做归一化和坐标系统一。常见的做法是以左髋和右髋的中点为原点用两肩宽度或躯干高度作为缩放单位把 x、y 都转成相对坐标。2.3 最小特征工程把一帧关键点转成一个向量下面这段是我常用的特征构造函数输入是 MediaPipe 的检测结果输出是一个可直接拼成时间步的特征向量import numpy as np def pose_to_feature(landmarks, frame_w640, frame_h480): 将 MediaPipe Pose 输出的 landmarks 转成特征向量。 landmarks: pose_landmarks.landmark每项有 x, y, z, visibility 返回: 长度为 33*2 1 的 numpy 数组 pts [] # 用髋部中心作为坐标原点做一个简单的相对位置归一化 hip_center_x (landmarks[23].x landmarks[24].x) / 2 hip_center_y (landmarks[23].y landmarks[24].y) / 2 for lm in landmarks: # 原始 x,y 减去髋部中心再除以图像宽度作为粗略尺度归一化 px (lm.x - hip_center_x) * frame_w / frame_w # 保持在 [-1, 1] 附近 py (lm.y - hip_center_y) * frame_h / frame_h pts.append(px) pts.append(py) # 额外加一个特征髋部中心在画面中的 y 坐标用来区分站立、下蹲这类整体位移 pts.append(hip_center_y) return np.array(pts, dtypenp.float32)这里的逻辑分三层第一用髋部中心当原点抹掉人体在画面中的绝对位置差异第二x、y 做了简单缩放让不同身高的人尽量对齐第三额外保留了髋部中心的 y 坐标因为“下蹲”这类动作整体质心会下降完全抹掉的话容易丢信息。实际使用时你还可以把肩膀宽度、躯干倾斜角加进去但毕设阶段先跑通这条主链路比加花活更重要。参数说明frame_w和frame_h只是用来把坐标归一到同数量级不必和真实分辨率严格一致如果你发现某个类别的动作区分度不够优先检查这个特征向量的可视化分布而不是先改 LSTM 结构。3. 环境搭建与最小复现从摄像头到可直接分类的姿态向量3.1 安装顺序与版本选择mediapipe 的玄学就藏在这里MediaPipe 的安装本身不复杂但版本踩坑集中在这几点Python 版本、mediapipe 版本和 OpenCV 版本之间的组合。以我这边的实操经验Python 3.8 配 mediapipe 0.8.x 是最省心的一组如果你用 Python 3.10尽量选 mediapipe 0.9.x 以上否则 import 阶段就可能报AttributeError之类的错。安装命令放在一个requirements.txt里mediapipe0.8.10 opencv-python4.5.5.64 numpy1.21.6 tensorflow2.9.1建议按这个顺序装先装 numpy 和 opencv-python再装 mediapipe最后装 tensorflow。原因是 tensorflow 会依赖特定版本的 numpy如果你先装 TF 再装 mediapipe有概率因为 numpy 版本被 TF 锁死反过来装能规避这个冲突。装完跑一句python -c import mediapipe as mp; print(mp.__version__)验证能出版本号就算过了第一关。3.2 用 MediaPipe 跑通第一帧姿态检测这里给一个能直接运行的示例它的作用不是做分类而是确认你从摄像头拿到的帧能顺利变成 landmarksimport cv2 import mediapipe as mp mp_pose mp.solutions.pose mp_drawing mp.solutions.drawing_utils cap cv2.VideoCapture(0) with mp_pose.Pose( static_image_modeFalse, model_complexity1, min_detection_confidence0.5, min_tracking_confidence0.5) as pose: while cap.isOpened(): ret, frame cap.read() if not ret: break # MediaPipe 需要 RGBOpenCV 读出来是 BGR必须先转换 frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results pose.process(frame_rgb) if results.pose_landmarks: # 在画面里画出骨架方便确认检测是否正常 mp_drawing.draw_landmarks( frame, results.pose_landmarks, mp_pose.POSE_CONNECTIONS) # 调用上一节的特征函数得到这一帧的特征向量 feat pose_to_feature(results.pose_landmarks.landmark) print(feat.shape, feat[:5]) cv2.imshow(pose, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()这段代码的关键参数有三个model_complexity1表示中等模型复杂度速度精度平衡如果电脑卡就把这个值改成 0min_detection_confidence是初始检测置信度阈值低于 0.5 时画面抖动较多但调的过高人稍微离远一点就检测不到min_tracking_confidence是跟踪阶段的阈值跟踪和检测是两套机制帧率不够时调低这个值比调低 detection 更有效。跑起来后如果看到骨架附着在人体上说明整条数据链路已经通了。因为毕设里必须全部使用国产化软件还要写融合国产操作系统的部署方案不能只考虑 Windows 平台这里额外提一个点mediapipe 在 Linux 下的安装比较友好但在国产化桌面环境里可能需要手动编译。建议前期在物理机 Windows 上把代码调通后期部署再切到国产化环境。3.3 把连续帧拼成 LSTM 的输入样本单帧特征只是“一张照片的骨架描述”LSTM 需要的是“一段时间的骨架变化”。所以要在内存里维护一个定长队列每一帧把特征推入队列满 30 帧后这 30 个时间步就组成一个样本from collections import deque SEQUENCE_LEN 30 # 时间步数量对应大约 1 秒的视频30fps 下 FEATURE_DIM 33 * 2 1 # 上一节 pose_to_feature 的输出长度 frame_buffer deque(maxlenSEQUENCE_LEN) def build_lstm_input(feature_vector): 每帧调用一次返回一个 (1, SEQUENCE_LEN, FEATURE_DIM) 的数组 当缓冲未满时返回 None。 frame_buffer.append(feature_vector) if len(frame_buffer) SEQUENCE_LEN: return None # deque 转 numpy 数组注意保持时间顺序 seq np.array(frame_buffer, dtypenp.float32) # 加一个 batch 维度 return np.expand_dims(seq, axis0)SEQUENCE_LEN30不是拍脑袋定的它对应的是 30 帧率下一秒钟的视频。大多数动作挥手、点头、下蹲都在 0.5 到 2 秒之间完成窗口太短学不到完整动作太长会混入前后多余的姿态。如果你的摄像头是 25fps30 帧就是 1.2 秒还勉强能用如果是 15fps建议把SEQUENCE_LEN往下调到 20 或 25而不是硬凑长度。4. 数据采集与 LSTM 训练把“抬手 / 走路 / 下蹲”变成一条时间序列4.1 自采数据的最小方案录制、切窗与标签对齐模型训练绕不开数据。毕设项目里的公开数据集往往和你的动作定义不一致最稳妥的办法是自己录。给每个动作类别建一个目录例如data/ squat/ 下蹲 wave/ 抬手 walk/ 走路每个类别录 100 到 200 段序列。录制时保持同一帧率每段动作开始时按下记录键动作结束再停止每段控制在 1 到 2 秒。采集代码就是 3.2 节的内容加一个写文件逻辑把frame_buffer满了之后得到的(30, 67)数组存成.npy文件即可。切窗阶段最容易忽略的是数据偏差如果你每一段录制都是动作正中间正好 30 帧模型会学到“这个动作总是从半路开始”推理时从动作起始点进入就识别不准。一个补救办法是刻意多录一些从不同起始位置截取的动作片段或者在录制的长视频里做随机滑窗窗口起点在动作开始前 5 帧到开始后 5 帧之间随机偏移。数据准备的代码不复杂但对最终识别准确率的影响比模型结构大了不止一倍。4.2 LSTM 模型定义与训练参数模型用小结构即可毕竟输入是 30 个时间步的低维姿态向量不是图像。两层 LSTM 加一层全连接输出节点数等于你的动作类别数最后接 softmaximport tensorflow as tf from tensorflow.keras import layers, models NUM_CLASSES 3 # squat / wave / walk按你的实际类别改 SEQUENCE_LEN 30 FEATURE_DIM 67 def build_model(): model models.Sequential([ layers.Input(shape(SEQUENCE_LEN, FEATURE_DIM)), layers.LSTM(64, return_sequencesTrue), layers.Dropout(0.3), layers.LSTM(32), layers.Dropout(0.3), layers.Dense(32, activationrelu), layers.Dense(NUM_CLASSES, activationsoftmax) ]) model.compile( optimizertf.keras.optimizers.Adam(learning_rate0.001), losssparse_categorical_crossentropy, metrics[accuracy] ) return model model build_model() model.summary()几个参数值得说清楚第一LSTM(64, return_sequencesTrue)的含义是第一个 LSTM 层输出的还是序列要喂给第二层 LSTM如果这里写成False第二层 LSTM 就接收不到完整的时序信息第二Dropout(0.3)加在两层 LSTM 之间对小数据集防过拟合很关键如果你每个类别只有三五十个样本建议把 dropout 提到 0.5第三learning_rate0.001是 Adam 比较稳的起点动作识别这类小输入模型很少需要低于 0.0005 的学习率但如果 loss 在 2 附近震荡不降先看是不是标签值从 1 开始而不是从 0 开始。训练用model.fit配合早停和 checkpoint。早停的 patience 设在 10 到 15因为小数据集上 val_loss 波动本来就大patience 太小会在刚过拟合时就停住from tensorflow.keras.callbacks import EarlyStopping, ModelCheckpoint def load_dataset(data_dir): 扫描 data_dir 下的子目录每个子目录存 .npy 序列文件。 返回 X: (N, 30, 67), y: (N,) import pathlib X, y [], [] label_names sorted([p.name for p in pathlib.Path(data_dir).iterdir() if p.is_dir()]) label_map {name: i for i, name in enumerate(label_names)} for name, idx in label_map.items(): for npy_file in pathlib.Path(data_dir).joinpath(name).glob(*.npy): data np.load(npy_file) # 防止录进去的长度不齐 if data.shape (SEQUENCE_LEN, FEATURE_DIM): X.append(data) y.append(idx) return np.array(X), np.array(y) X, y load_dataset(data) callbacks [ EarlyStopping(monitorval_loss, patience12, restore_best_weightsTrue), ModelCheckpoint(best_model.h5, monitorval_loss, save_best_onlyTrue) ] model.fit(X, y, validation_split0.2, batch_size16, epochs50, callbackscallbacks)batch_size16是一个比较中间的值。样本数不大时batch 过小会让梯度震荡过大容易收敛到不稳定的局部最优。手头数据总量到 500 段以上时把 batch 提到 32 能明显缩短训练时间。验证集比例 0.2 也合理但如果某个类别的样本特别少建议用stratifyy按类别比例切分避免某一类全被分到验证集导致 val_acc 忽高忽低。4.3 训练完怎么验证留出跨时段数据盲测很多毕设项目训练和验证是同一段视频里切出来的结果必然虚高。我在流程里习惯这样验证录数据分两批上午录一批训练集下午录一批测试集测试集不参与训练只用来最后评估。一个简单做法是把测试视频里每一帧喂给build_lstm_input攒够 30 帧后执行def predict_action(seq_input, model, label_names): seq_input: (1, 30, 67) 的批量输入 返回 (类别名, 各类别概率) probs model.predict(seq_input, verbose0)[0] pred_idx int(np.argmax(probs)) return label_names[pred_idx], probs[pred_idx]这里注意一个使用细节model.predict每次调用都有额外开销30 帧才调用一次基本无感。但如果你打算做实时识别不要每帧都 predict而是每 5 帧预测一次既省时间又自然产生平滑效果。这个技巧在最后一章展开讲。5. 避坑MediaPipe、序列长度和坐标系会让你翻车的地方5.1 现象AttributeError: PoseLandmarkerResult object has no attribute pose_landmarks原因MediaPipe 在 0.9.x 之后把解决方案 API 从mp.solutions.pose切换成了新的mp.tasks.vision.PoseLandmarker两者的结果对象字段名不同。很多网上的旧教程教的是solutions.pose如果你装的是新版本就会在取landmarks时报这个错。解决先看版本再决定代码风格。如果你用的mp.solutions.pose代码里就是results.pose_landmarks.landmark如果你用的是新版PoseLandmarker字段变成了result.pose_landmarks[0]且坐标已经归一化到 [0,1]。我在项目里提供的源码需要明确指定版本配套。5.2 现象训练时精度不错但实际用摄像头测左手动作总是被识别成右手。原因摄像头画面默认是镜像的而 MediaPipe 标注的左右是画面中的左右。你对着摄像头抬起左手模型看到的是画面右侧的关键点集合训练时又把“右手抬起”的样本和“画面右侧抬手”对应了起来于是推理结果恰好相反。解决在构造特征前对 x 坐标做一次镜像处理也就是让x 1.0 - x。如果你只是自己用不区分左右那无所谓但只要类别里有“左手摸耳”“右手摸耳”这类对称动作必须在特征函数里加这行。做完之后用一段几十秒的实时视频验证左右是否一致。5.3 现象model.fit时报维度错误或者训练完测试时报expected sequence_length to be 30原因最可能是录制视频的帧率不同。有的摄像头是 30fps有的是 15fps录出来的同一动作时间步差一倍还有人把不同长度视频直接拿去切窗导致(27, 67)这样的样本混进去。解决在数据加载时严格过滤data.shape (SEQUENCE_LEN, FEATURE_DIM)才留下。更稳妥的是录制时统一帧率或者先对关键点序列重采样到固定长度。重采样不要用线性插值动作识别里一般直接等间距抽样或补最后一帧凑齐长度。5.4 现象loss 能下降但 val_acc 卡在 60% 左右不动且每个类别预测比例严重不均衡。原因自采数据最常见的类别不平衡比如走路录了 300 段下蹲只录了 80 段。模型为了降低整体 loss倾向于把模糊样本全部预测成大类小类别准确率极低。解决先给model.fit加上class_weight从小到大类别的惩罚权重比如大类 1.0小类 2.0 到 3.0。如果加了之后小类上来了而大类掉下去了再调整数据比例把大类样本随机抽掉一部分直到两类数量差在 1.5 倍以内。这个方案省事且有效改网络结构在数据不平衡时优先级不高。5.5 现象实时测试时预测标签一帧一变明明一个连续抬手动作中途跳成“下蹲”原因滑窗重叠导致相邻窗口内容高度相似但模型对帧质量敏感度差异大偶尔几帧关键点检测抖动序列尾部姿态稍微扭曲预测结果就直接翻转。这不是模型过拟合而是缺少输出平滑。解决不要对每个滑窗单独处理而是对模型输出的类别概率做队列平滑。一个简单的滑动投票实现是维护长度为 5 的结果队列取出现次数最多的类别作为最终输出。如果平滑后还有跳变说明窗口重叠产生的部分样本与训练数据分布不一致需要增加训练样本中的姿态多样性。这个问题的完整代码在第六章给出。6. 进阶用滑窗投票加状态持久化把帧级预测变成稳到能演示的动作流毕设答辩或者实际展示时最怕的不是模型准确率不够而是画面上的标签在几个类别之间来回跳。单个时刻的概率输出并不稳定因为 MediaPipe 在快速运动时关键点会发生瞬时抖动导致相邻两个窗口的特征在尾部几帧差异较大。我常用的做法是给预测结果加一个“状态持久化”层from collections import Counter class ActionVoter: 基于多数投票的滑窗平滑器。 窗口长度投票决定的类别只有当某一类别票数超过半数才切换当前状态。 def __init__(self, window_size5, min_votes3): self.window_size window_size self.min_votes min_votes self.history [] self.current_action None def update(self, pred_label): 输入: LSTM 当前帧输出的类别标签 输出: 平滑后的类别标签 self.history.append(pred_label) if len(self.history) self.window_size: self.history.pop(0) if len(self.history) self.min_votes: return self.current_action counter Counter(self.history) top_label, top_count counter.most_common(1)[0] # 出现频率达到阈值才切换状态否则维持上一状态 if top_count self.min_votes: self.current_action top_label return self.current_action使用时机是每产生一个新的窗口预测就调用一次voter.update(label)。min_votes3意味着 5 个窗口中至少有 3 个都投同一个类别状态才发生切换这样可以过滤掉单帧或者双帧的误判。实际使用里我还习惯在此基础上加一个类别概率阈值如果最高概率低于 0.6直接不更新current_action让上一状态继续保持这样能进一步降低不确定区域的噪声。参数调整经验窗口越大输出越稳但动作切换的响应会变慢。展示“抬手”和“放下”这种一秒钟内完成的动作时window_size5是上限如果动作本身持续三秒以上window_size7也没问题。如果你想做更精细的过滤可以在update前对五个窗口的概率做指数加权平均但这通常只影响边界的平滑度不影响整体观感。我自己在这类项目上翻过最狠的一次车就是把 LSTM 的序列长度设成了 60结果模型对慢动作识别很好但对快动作整体滞后半拍——后来才意识到是窗口长度覆盖了 2 秒快动作在 1 秒内已经完成剩下的 1 秒全是无关姿态。从那以后我养成了一个习惯先录一段目标动作数一下它持续了多少帧序列长度直接取这个帧数的 80% 左右而不是先定一个“看起来合理”的数字。这套流程做完你应该能从摄像头实时识别出自己定义的动作也能把准确率稳定在一个能向别人演示的水平。希望帮到你。本文还有配套的精品资源点击获取