MediaPipe人体姿态识别实战：关键点检测与动作计数-北京尧图网络

简介面向计算机相关专业学生与实战学习者这份基于MediaPipe实现的人体姿态识别Python源码及模型包适用于毕业设计、课程设计、期末大作业或答辩演示等场景适合有一定Python基础、希望接触姿态识别的中级学习者。资源共138个文件压缩后约11MB包含Python源码、H5格式训练模型、npy格式关键点/特征数据文件、mp4格式运行效果演示视频以及README说明文档目录结构清晰便于按模块查阅和二次开发。项目代码经测试运行稳定功能完整评审得分96.5分配套的视频演示与说明文档可帮助理解姿态识别模型的加载、推理与结果可视化流程npy数据文件也便于自行训练与实验对比。该资源已有206人学习下载适合需要快速搭建人体姿态识别原型或完成课程项目的学生参考借鉴从代码结构到实验结果均有完整呈现压缩包内附带的README也对环境配置与运行方式做了说明。1. 人体姿态识别到底识别什么拿到“源码模型”前先想清楚的三件事人体姿态识别在工程上不是“认出画面里是一个人”而是把人的骨架关键点逐帧抠出来——鼻子、肩膀、手肘、手腕、髋、膝、踝一共 33 个点每个点带归一化坐标和可见度。标题里的 mediapipe 是这个任务里性价比最高的方案它把 BlazePose 的检测加跟踪管线封装成几行 Python 调用普通 CPU 就能跑实时视频。拿到这类“Python 源码模型”的压缩包我建议你先别急着解压跑 demo而是先确认三件事依赖环境隔离没有、模型走的是 Solutions API 还是 Task API、以及你最终要的是“画出骨架”还是“算出动作指标”。这三件想清楚后面几百行代码才不会白写。2. 把 mediapipe 跑起来环境搭建与第一个最小推理脚本2.1 为什么要选 mediapipe 而不是自训模型做人体姿态识别技术路线大致有三条一条是自己标注数据训练关键点回归网络常见的有基于 HRNet、OpenPose 的思路效果上限高但工程成本也高你得准备算力和标注工具另一条是用现成的人体检测器加关键点分支组合起来当管线用第三条就是 mediapipe 这种开箱即用的方案。我一般会直接选 mediapipe理由是它把“检测人体框关键点回归帧间跟踪平滑滤波”这几件事打包好了。它的模型基于 BlazePose 架构分 Lite、Full、Heavy 三个复杂度档位同一个 Python 接口切参数就能换精度和速度。对于“实时摄像头监控”“健身动作计数”“体态打分”这类需求你不需要自己训练模型只需要处理它输出的关键点坐标。这也解释了为什么压缩包叫“源码模型”——源码负责调推理和算业务指标模型本身就是那几个几 MB 的 TFLite 文件。2.2 安装与第一个实时推理脚本先搭一个干净的虚拟环境这一步能省掉后面大量依赖冲突的麻烦。我习惯用 venv 或 conda 单开一个环境避免 mediapipe 的依赖和主业环境纠缠在一起。python -m venv venv_pose source venv_pose/bin/activate # Windows 下是 venv_pose\Scripts\activate pip install mediapipe opencv-python numpy装完后写一个最小的摄像头推理脚本确认模型能加载、关键点能输出。下面这份代码是手动画点版本故意不用 drawing_utils方便你看清坐标是怎么落到像素位置的import cv2 import mediapipe as mp mp_pose mp.solutions.pose cap cv2.VideoCapture(0) # 0 是默认摄像头改成视频路径也能读 with mp_pose.Pose( static_image_modeFalse, # 视频流用 False先检测人体后续帧走跟踪 model_complexity1, # 0Lite 最快1Full 均衡2Heavy 最准 smooth_landmarksTrue, # 对关键点做时序平滑压抖动 min_detection_confidence0.5, min_tracking_confidence0.5) as pose: while cap.isOpened(): ok, frame cap.read() if not ok: break # mediapipe 吃 RGBOpenCV 读进来是 BGR必须先转 rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results pose.process(rgb) if results.pose_landmarks is not None: h, w, _ frame.shape # 拿原图尺寸把归一化坐标换算成像素 for idx, lm in enumerate(results.pose_landmarks.landmark): x, y int(lm.x * w), int(lm.y * h) cv2.circle(frame, (x, y), 3, (0, 255, 0), -1) cv2.imshow(pose, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()这段脚本的逻辑很直白读一帧 - 转 RGB - 丢给 pose.process - 取 landmarks - 把归一化坐标乘上宽高还原成像素坐标 - 画点。这里每个关键点的 x、y 都落在 0 到 1 之间z 表示相对臀部中心的深度单位不是像素后面算角度时要注意别直接拿 z 当实际距离。参数里最值得调整的是 model_complexity。做离线视频分析、画面里人比较小我会拉到 2跑实时直播或者树莓派这类弱设备就降到 0。smooth_landmarks 建议保持 True它本质是帧间平滑能明显减少关键点抖跳。min_detection_confidence 和 min_tracking_confidence 都是 0 到 1 的阈值前者管“多久重新检测一次人”后者管“跟踪失效就放弃”默认 0.5 够用不需要动。2.3 跑通后先做一个“黑匣子测试”很多新手看到画面上有绿点就开始接业务逻辑我建议你先花五分钟验证模型输出的稳定性。怎么做找一段固定机位的视频人站原地做几个简单的抬手动作把 landmarks 的原始坐标打出来存成 CSV。然后检查两点离镜头远的帧里手腕点的 visibility 是不是掉得厉害动作过程里肩点和髋点有没有突然跳到另一侧。这一步叫黑匣子测试因为你不模型内部发生什么只看输入输出的可靠性。如果抖动频繁先怀疑 smooth_landmarks 没开或者阈值太低如果人一动骨骼就“左右换手”多半是检测置信度不够模型重新触发检测把左右肩搞反了。这个测试做完你对“源码模型”里的模型部分就有底了后面写任何计数逻辑都建立在稳定的输入上。3. 拆解姿态识别流程关键点索引、角度计算与可视化实现3.1 33 个关键点的索引表与坐标语义mediapipe Pose 输出的 33 个关键点是有固定顺序的索引从 0 到 32。做动作分析时最常打交道的几个点我列在下面索引关键点说明0nose鼻子判断人体朝向的辅助点11 / 12left / right shoulder左右肩躯干和手臂的分界13 / 14left / right elbow左右肘和肩、腕配合算肘角15 / 16left / right wrist左右腕臂动作的末端23 / 24left / right hip左右髋躯干和腿的分界25 / 26left / right knee左右膝算腿弯曲角度27 / 28left / right ankle左右踝腿动作的末端每个 landmark 有四个属性x、y归一化坐标0 到 1、z深度相对臀部中心、visibility可见度0 到 1。这里要特别提醒x、y 是归一化的画点或者算像素距离时要乘图像宽高z 不是绝对深度拿它很难反推真实距离visibility 是很多工程问题的根源人在画面边缘、肢体遮挡时这个值会掉到 0.3 以下这种关键点必须过滤否则后续角度计算会被带偏。3.2 角度计算用向量夹角而不是肉眼量姿态识别的核心价值是“动作指标”而动作指标的基石是关节角度。比如深蹲计数本质是髋-膝-踝三点形成的膝角变化屈肘动作本质是肩-肘-腕三点形成的肘角变化。计算三点角度最稳的方式是向量点积加反余弦。下面这个函数我用在无数个项目里输入三个关键点的坐标返回以中间点为顶点的角度值import numpy as np def calc_angle(a, b, c): 以 b 为顶点计算 a-b-c 的角度度 a np.array(a[:2], dtypenp.float32) # 只取 x, y不要 z b np.array(b[:2], dtypenp.float32) c np.array(c[:2], dtypenp.float32) v1 a - b v2 c - b cos_a np.dot(v1, v2) / (np.linalg.norm(v1) * np.linalg.norm(v2) 1e-9) cos_a np.clip(cos_a, -1.0, 1.0) # 浮点误差可能让值超出 [-1,1] return np.degrees(np.arccos(cos_a))逻辑说明先把三个点的 x、y 取出来构成两个向量 v1a 指向 b和 v2b 指向 c。用点积公式计算夹角余弦再通过 np.arccos 转成弧度乘 57.2958 变成角度。加 1e-9 是防止两个向量长度乘积为 0 时除零np.clip 防止浮点误差导致 arccos 收到超出定义域的值。参数上要注意两点一是只取 x、y不要混入 z。z 是深度估计和 x、y 不在一个度量体系混进来角度会凭空多出误差。二是这个函数算出的角度范围是 0 到 180 度它不区分“膝盖往前弯”还是“往后伸”如果业务需要区分要额外结合关键点的位置关系判断。3.3 用 drawing_utils 输出完整骨架手动画点只能看到点看不到骨骼连线。mediapipe 自带的 drawing_utils 能一次把 33 个点和连接线画出来但要注意一个细节draw_landmarks 需要的是 NormalizedLandmarkList 这个 proto 结构不是普通列表。从 results 里拿到的正好是它直接传就行。这里给出带完整可视化的版本import cv2 import mediapipe as mp mp_pose mp.solutions.pose mp_drawing mp.solutions.drawing_utils def draw_pose(frame, results): 把 pose 结果画到原图上返回 BGR 图像 rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) mp_drawing.draw_landmarks( rgb, results.pose_landmarks, mp_pose.POSE_CONNECTIONS, mp_drawing.DrawingSpec(color(0, 255, 0), thickness2), mp_drawing.DrawingSpec(color(0, 0, 255), thickness2)) return cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)这段代码的核心是 POSE_CONNECTIONS它是一个定义好的关键点连接表告诉 drawing_utils 哪些点之间要连线。DrawingSpec 的 color 用 RGB 顺序第一个参数配的是关键点样式第二个配的是连线样式。因为 mediapipe 处理的是 RGB 图画完要再转回 BGR 给 OpenCV 显示或写入视频。3.4 坐标系混乱是最大陷阱做姿态识别时最容易翻车的地方不是模型调用而是坐标系的来回倒腾。OpenCV 读图像是 BGRmediapipe 推理要 RGB画图又回到 BGR关键点坐标是归一化的画图要乘回像素写 CSV 存分析又要存归一化原始值。一个项目里这几个变换交叉出现稍不留神就会画出来的骨架错位或者偏移。我自己的习惯是定一条铁律推理前统一转 RGB推理后统一转回 BGR坐标一律保存归一化原始值只在“画点”和“算像素距离”这两个环节临时乘宽高。这样所有下游逻辑比如角度计算、计数状态机都基于同一套归一化坐标不会出现“训练时用的归一化值、推理时用的像素值”这种互相打架的局面。4. 把关键点变成业务指标深蹲计数与姿态评分的改造方案4.1 状态机是计数的正确姿势拿到膝角序列后最直观的做法是“角度小于 100 就算一次深蹲”但这种阈值判断在实际视频里会疯狂误计。因为关键点本身有抖动角度会在阈值边缘反复横跳一秒钟给你数出三四个深蹲。正确的做法是引入状态机。把动作拆成“站立态”和“下蹲态”只有从站立进入下蹲、再回到站立这一整个闭环才计一次。加上冷却帧机制防止状态切换瞬间的噪声干扰。下面这个类是深蹲计数的核心实现class SquatCounter: def __init__(self): self.state stand self.reps 0 self.cooldown 0 # 状态切换后的冷却帧数 self.angle_buffer [] # 最近几帧的膝角用于平滑 def update(self, knee_angle, visibility_ok): 每帧调用一次返回累计次数 if not visibility_ok: return self.reps # 关键点不可信这帧直接跳过 # 简单移动平均窗口 5 帧 self.angle_buffer.append(knee_angle) if len(self.angle_buffer) 5: self.angle_buffer.pop(0) angle sum(self.angle_buffer) / len(self.angle_buffer) if self.cooldown 0: self.cooldown - 1 if self.state stand and angle 100: self.state squat elif self.state squat and angle 150 and self.cooldown 0: self.state stand self.reps 1 self.cooldown 15 # 15 帧内不允许再次计数防抖 return self.reps逻辑说明每次 update 先检查 visibility_ok关键点不可见时直接返回不参与状态变更。角度进入前先过一帧 5 窗口的移动平均把单帧噪声压平。状态机只在“站立 - 下蹲”瞬间锁状态在“下蹲 - 站立”并且冷却结束才计数。参数上可以按场景调深蹲是否到底的标准就是那个 100 度如果你做的是半蹲可以改到 120站立判定 150 度对应膝盖接近伸直。cooldown 是防抖的核心参数普通视频 10 到 20 帧合适放慢动作视频要调大否则一个慢速深蹲可能被计两次。4.2 姿态评分角度误差映射成百分制健身纠正、体态打分这类需求不关心次数关心“动作标不标准”。实现思路是把当前关节角度和标准动作的目标角度做误差映射越接近满分越高。def posture_score(current_angle, target_angle, tolerance20): 把当前角度映射到 0-100 分 current_angle: 当前帧关节角度 target_angle: 标准动作的目标角度 tolerance: 偏差多少度以内算满分超过多少度直接 0 分 diff abs(current_angle - target_angle) if diff tolerance: return 0 return max(0, int(100 * (1 - diff / tolerance)))这个函数的业务含义是肘部标准角度是 90 度当前测出来 95 度tolerance 给 20那得分就是 75 分。tolerance 决定打分松紧给动作纠正类场景一般给 15 到 25给教练展示场景可以更严格。实际工程里还要给多关节加权平均比如深蹲时膝角权重 0.5、髋角权重 0.3、背角权重 0.2合成一个综合分。4.3 完整流程从视频帧到带数据的输出视频把上面几块拼起来一个完整的“输入视频 - 输出骨架叠加视频实时计数”的管线是这样import cv2 import mediapipe as mp mp_pose mp.solutions.pose input_path squat_test.mp4 output_path squat_result.mp4 cap cv2.VideoCapture(input_path) fps int(cap.get(cv2.CAP_PROP_FPS)) width int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) height int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) writer cv2.VideoWriter(output_path, cv2.VideoWriter_fourcc(*mp4v), fps, (width, height)) counter SquatCounter() with mp_pose.Pose(model_complexity1, min_detection_confidence0.5) as pose: while cap.isOpened(): ok, frame cap.read() if not ok: break rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results pose.process(rgb) if results.pose_landmarks is not None: lm results.pose_landmarks.landmark # 取左髋 23、左膝 25、左踝 27算左腿膝角 hip [lm[23].x, lm[23].y] knee [lm[25].x, lm[25].y] ankle [lm[27].x, lm[27].y] angle calc_angle(hip, knee, ankle) visibility_ok lm[25].visibility 0.5 and lm[27].visibility 0.5 reps counter.update(angle, visibility_ok) cv2.putText(frame, fREPS: {reps}, (30, 60), cv2.FONT_HERSHEY_SIMPLEX, 1.5, (0, 255, 0), 3) frame draw_pose(frame, results) writer.write(frame) cap.release() writer.release()这段代码把前面所有内容串起来了calc_angle 算角度、SquatCounter 做状态机计数、draw_pose 画骨架、putText 叠加计数文本、VideoWriter 写输出视频。参数上注意 VideoWriter 的尺寸必须和源视频一致否则打不开输出文件编码器用 mp4v 兼容性最好。5. 人体姿态识别常见问题排查从装不上、跑不动到数错数的 5 个场景5.1 安装后导入报错protobuf 版本冲突现象执行 import mediapipe 时直接抛错提示 RuntimeError 和 protobuf 相关或者装完 mediapipe 后项目里其他模块开始异常。原因mediapipe 内部强依赖特定范围的 protobuf 版本而你的项目之前已经装了一个更高或更低版本pip 解析依赖时没有彻底降级两个版本在运行时冲突。这是这类源码包最常见的第一道坎。解决不要在主环境里强装临时开一个干净虚拟环境。如果已经装了先卸载再重装pip uninstall protobuf mediapipe 后重新 pip install mediapipe让 pip 自己解析依赖版本。换用虚拟环境后这个坑基本不会再踩第二次。5.2 摄像头画面左右颠倒抬手抬错边现象对着摄像头抬手画面里左肘角度变化但计算用的右肘数据没反应左右手完全反了。原因摄像头自拍场景通常有镜像显示OpenCV 读到的原始画面本身没镜像但人看到的是镜像另外 mediapipe 的坐标体系以图像左上角为原点你视觉直觉里的“左手”和坐标系里的左手可能是两回事。解决按业务实际需求决定是否 cv2.flip(frame, 1) 镜像画面。动作识别项目里我建议不要镜像统一按图像坐标系来处理左右侧只有做展示类应用时才镜像画面。同时要确认代码里取的 13/14、15/16 索引和你动作侧一致。5.3 人离得远一点骨架就开始乱跳现象人物在画面中占比小或者走动到画面边缘时关键点突然飘移肩点跳到背景上visibility 明显下降。原因BlazePose 的检测器对目标尺寸敏感人体框太小或部分出画时回归出的关键点在语义上不可信。visibility 存在的意义就是告诉你“这个点别当真”。解决过滤条件是硬性的凡是 visibility 低于 0.5 的关键点一律不参与角度计算和计数。另外尽量让人体在画面中占足够大比例离线视频分析时可以把 model_complexity 提到 2增加小目标下的关键点回归精度。5.4 视频处理很卡CPU 占用拉满现象跑实时摄像头时画面掉到十几帧每秒处理 1080p 视频时动辄几分钟。原因最常见的是每帧都做完整检测而不是进入跟踪模式或者输入分辨率过高模型在每一帧的推理时间被拉长。static_image_modeTrue 是重灾区不少人写循环时没注意这个参数。解决视频流必须保持 static_image_modeFalse这样只有第一帧或丢失跟踪时做完整检测后续帧走帧间跟踪推理开销小一个量级。其次先缩放图像到 640x480 左右再喂给模型推理速度能翻倍。最终手段是 model_complexity 降到 0精度损失换实时性。5.5 计数逻辑不收敛深蹲数出“半蹲”现象同一个深蹲视频跑两遍结果一次计数偏多一次偏少或者半蹲被算成了全蹲。原因计数阈值和冷却参数没有按实际视频调。半蹲的膝角可能到 110 度左右如果阈值设在 100半蹲就不会触发状态切换但画面抖动可能让角度瞬间越过阈值配合过短的冷却窗口就会误计。解决每次拿到新视频先把 30 帧左右的关键点角度打印出来看一眼实际角度范围再定阈值。全蹲膝角一般小于 90 度半蹲在 100 到 130 之间。阈值和冷却时间要成对调阈值卡得紧就把冷却拉大阈值卡得松就缩小冷却这两个是互锁的参数不要只改一个。6. 姿态识别落地最后一公里模型导出、推理提速与离线验证真正把“源码模型”用进产品还差三件事。第一件是接口选型。前面的代码用的是 mp.solutions.pose这是经典 API写演示和验证最快但要做跨平台部署我建议切到新的 Task API也就是 PoseLandmarker。两者推理底层是同一套模型但 Task API 的输入输出更规范支持直接加载 .task 格式的模型文件也支持视频流模式和 GPU delegate在移动端落地时更省事。第二件事是推理提速。除了前面说的缩放分辨率和 model_complexity0还有一个容易被忽略的技巧减少重复检测。实时场景里人离开画面又回来模型要重新检测这瞬间 CPU 会拉高。PoseLandmarker 的 running_mode 选 VIDEO底层会自动分配检测和跟踪的优先级比手动每帧喂图更稳。另外如果业务只关心上半身动作可以裁掉图像下半部分再送进去输入小一圈延迟低一截。第三件事是离线验证这一步最重要也最容易被跳过。我每次写完一个姿态识别方案都会把关键点输出成 CSV再用画图工具拉出角度曲线检查平滑度和异常跳点import csv import cv2 import mediapipe as mp mp_pose mp.solutions.pose cap cv2.VideoCapture(test.mp4) with open(landmarks.csv, w, newline) as f: writer csv.writer(f) writer.writerow([frame, left_knee_angle, right_knee_angle, left_hip_visible, right_knee_visible]) frame_idx 0 with mp_pose.Pose(model_complexity2) as pose: while cap.isOpened(): ok, frame cap.read() if not ok: break rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results pose.process(rgb) if results.pose_landmarks: lm results.pose_landmarks.landmark # 左右膝角分别算出来写入 CSV l_knee calc_angle([lm[23].x, lm[23].y], [lm[25].x, lm[25].y], [lm[27].x, lm[27].y]) r_knee calc_angle([lm[24].x, lm[24].y], [lm[26].x, lm[26].y], [lm[28].x, lm[28].y]) writer.writerow([frame_idx, l_knee, r_knee, lm[23].visibility, lm[25].visibility]) frame_idx 1 cap.release()把 CSV 拉进电子表格或者画图工具一眼就能看出哪几帧角度突变、哪几帧 visibility 低到不可信。曲线光滑但偶发尖峰就调 smooth_landmarks 或移动平均窗口整段乱跳先怀疑模型复杂度和画面里的人体占比。这套离线验证方法比我调试实时画面时边看边猜效率高得多。我自己的习惯是任何“源码模型”项目动手改业务逻辑之前先把这一套 CSV 验证流程跑通确认输入数据是稳的。数据都不稳后面堆再多状态机和评分函数都是白费。这个习惯帮我避开了很多只在演示视频里成立的方案。希望帮到你。本文还有配套的精品资源点击获取

MediaPipe人体姿态识别实战：关键点检测与动作计数

相关推荐

C# WinForms三层架构图书管理系统：从增删查改到SQL Server实战

MySQL 8自动化运维：一键安装与巡检脚本实战解析

以项目带学习：AI入门到实战的完整路线与避坑指南

更多资讯

Qt信号与槽机制全解析：对讲机模型、连接配对与调试实战

多智能体强化学习驱动的CUDA内核自动生成与性能优化

用代码生成视觉内容：artcraft项目从设计到实操的完整指南

C++函数参数传递详解：值传递、引用传递与指针传递的GESP考点

遥感油罐检测数据集：1000张航拍图+VOC/COCO/YOLO三格式标签

退货季背后的逆向物流与可持续生活：从退货潮到循环供应链

今日更新

悟空开源无代码平台实战：从实体建模到应用设计避坑指南

基于.NET9的多租户权限系统：数据权限与动态API落地实践

场地预约小程序毕设实战：SSM+微信小程序+MySQL数据库设计到避坑

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？