简介一份面向Python及计算机视觉学习者的实战教程围绕MediaPipe框架讲解如何调用预训练模型实时完成面部关键点、手部跟踪与全身姿态估计。教程从环境依赖安装、网络摄像头视频流读取讲起逐步覆盖面部检测、Holistic模型下的多部位地标绘制并配有可直接运行的示例代码、效果说明和应用场景分析如手势控制、健身指导、AR交互整体结构清晰适合计算机视觉入门者快速上手也方便有经验的开发者做原型验证。文档还梳理了各模型的适用场景面部关键点可用于表情分析手部跟踪服务于手势交互全身姿态估计应用于动作比对。资源包共1个docx文档体积约16KB轻量便于下载阅读。已有357人学习浏览文档中对MediaPipe跨平台特性、预训练模型能力及代码实现均有讲解是一份可操作性强、重点突出的技术笔记。1. 用 Python 和 MediaPipe 做三合一姿态检测先从一次翻车说起摄像头前面站着一个人想让程序实时说出他有没有抬手、扭头、眨眼——这个需求听起来不难但真上手时会发现靠 OpenCV 凭空算关键点根本是玄学肤色分割在复杂背景下一碰就碎帧率掉到个位数一顿操作下来连「手在哪」都稳定不了。后来换用 MediaPipe才把这条链路走通。MediaPipe 是 Google 开源的机器学习推理框架内置了人脸网格、姿势估计和手部关键点三套预训练模型Python 调用非常直接CPU 上就能跑到实时帧率。这篇笔记就把「怎么用 Python 把三套检测串起来、参数怎么设、哪些地方容易翻车」一次讲透给正准备做行为分析、交互控制或动作纠正的从业者一条能直接复现的路径。2. 为什么选 MediaPipe方案对比与最小环境搭建2.1 三套模型分别解决什么问题人脸、姿态、手部关键点MediaPipe 在 Python 侧最常用的三件套是 FaceMesh、Pose 和 Hands它们各自解决的是完全不同的检测任务。FaceMesh 输出 468 个人脸关键点覆盖眉毛、眼睛、嘴唇、面部轮廓甚至瞳孔位置。它不是为了做人脸识别那是 FaceNet 那类模型的活而是给出「脸在画面里长什么样」的稠密几何描述。基于这 468 个点你可以算眼睛开合度、头部朝向、嘴部动作这些是专注度分析、疲劳提醒、表情驱动类应用的基础。Pose 基于 BlazePose 架构输出 33 个身体关键点从鼻子、肩膀、肘、腕一路到脚踝。它定位的是「人的骨架」不是人形框。有了骨架坐标可以算肘关节角度、判断深蹲幅度、识别跌倒姿态这是动作计数、健身纠正、安防异常行为检测里最常用的输入。Hands 输出每只手 21 个关键点并且能区分左右手。它内部是两段式管线先用一个轻量 palm detector 在整图上找到手掌位置再在裁剪区域里精确定位 21 个关键点。这意味着手部检测比人体姿态更依赖「手在画面里够不够大」。三套模型的输出结构很统一都是 normalized landmark0~1 浮点数格式一致是它们能拼进同一条推理链路的关键前提。2.2 MediaPipe 与 OpenPose、YOLO-pose 的边界实时单机场景谁更合适从业者常在这三个方案之间犹豫我先说结论实时单机、CPU 优先、跨平台选 MediaPipe追求学术级精度、有多卡 GPU 资源考虑 OpenPose已经重度依赖 YOLO 生态、需要目标框和关键点同时输出YOLO-pose 更顺手。OpenPose 是姿态估计领域的老牌方案关键点定义细致精度上限高但它对算力的要求是另一个量级原版在 CPU 上跑单人实时几乎不现实通常需要 CUDA 加速部署成本明显更高。如果你的业务是离线批处理、对精度极度敏感它才有优势。YOLO-pose 把关键点检测做成了目标检测的附属输出每个检测框自带对应关键点。这种方案在「画面里有多人、需要先框人再取点」的语义下很自然模型权重也轻。但它的关键点数量通常是人体的 17 点或 28 点版本手部、面部细节远不如 MediaPipe 细做手势或面部动作分析时不够用。MediaPipe 的优势恰恰在工程落地上模型小、推理快、CPU 可跑官方还同时维护 Python 和移动端接口。代价是精度上限不如学术方案关键点偶尔会抖动。对绝大多数实时交互、行为判断类的产品需求来说这个精度足够了而且省下来的部署成本是实打实的。2.3 最小依赖清单与安装验证Python 环境、mediapipe 安装、跑通第一段代码安装这一步本身不难但环境搭配上有一些需要注意的地方。建议用 Python 3.9~3.11 的 64 位环境新版本 mediapipe 对 Python 版本的支持有明确上限装之前先确认一下自己环境里的 Python 版本避免遇到 wheel 不匹配的报错。# 创建虚拟环境Windows / Linux / macOS 通用 python -m venv mp_env # Windows 激活 mp_env\Scripts\activate # Linux / macOS 激活 # source mp_env/bin/activate # 安装核心依赖 pip install mediapipe opencv-python numpy # 验证安装 python -c import mediapipe as mp; print(mp.__version__)这段命令先建了一个独立的虚拟环境这是为了避免 mediapipe 和项目的其他包互相污染依赖。pip install 一行把三样东西装齐mediapipe 本身、opencv-python 用来读摄像头和图像处理、numpy 用来做数组运算。最后一句验证命令会打印出版本号看到输出就说明基本环境没问题。如果打印失败大多数情况是 Python 版本超出 wheel 支持范围换一个 3.10 左右的版本基本能解决。装完库之后先用一张静态图做冒烟测试比直接上摄像头好排错。下面这段代码读入本地图片跑一次姿势检测并打印出关键点数量import cv2 import mediapipe as mp mp_pose mp.solutions.pose pose mp_pose.Pose(static_image_modeTrue, model_complexity1) image cv2.imread(test.jpg) image_rgb cv2.cvtColor(image, cv2.COLOR_BGR2RGB) results pose.process(image_rgb) if results.pose_landmarks: print(f检测到 {len(results.pose_landmarks.landmark)} 个关键点) else: print(未检测到人体姿态) pose.close()这段代码的逻辑是把图像从 OpenCV 默认的 BGR 色彩空间转到 MediaPipe 要求的 RGB然后调用 process 方法推理。static_image_modeTrue 表示对单张静态图做完整检测model_complexity1 表示使用完整模型比 0 更准比 2 更快。最后记得调用 pose.close() 释放资源这是新手很容易漏掉的一步不释放的话在循环场景里会累积内存占用。3. 从单模型到三合一人脸、身体、手部检测的实现步骤3.1 人脸检测FaceMesh 的 468 关键点与注意力方向判断FaceMesh 在 Python 侧的接口设计得很简单初始化时调整好参数送入 RGB 帧就能拿到多张脸的 468 点坐标。实际业务里用得最多的不是全部 468 点而是眼睛周围那几个点——通过它们可以算出眼纵横比EAR用来判断睁眼还是闭眼。FaceMesh 初始化有三个关键参数static_image_mode 控制是静态图模式还是视频跟踪模式max_num_faces 限制一帧最多检测几张脸默认是 1业务场景经常需要调大min_detection_confidence 是检测阶段的最低置信度阈值默认 0.5调高会减少误检但可能漏掉模糊的小脸。对于视频流我一般强烈建议把 static_image_mode 设为 False让模型进入跟踪模式。跟踪模式不会每帧都做全图人脸检测而是基于上一帧的结果做局部跟踪速度更快、抖动也更小。代价是如果脸在画面里突然大幅移动或转侧跟踪可能丢失模型会重新启动全图检测。在实际产品里这通常比每帧全量检测的体验好得多。眨眼判断是 FaceMesh 最经典的应用核心是指标 EAREye Aspect Ratio。计算方式是用眼睛六个关键点中的两组垂直距离取平均再除以水平距离。人正常睁眼时 EAR 在 0.2~0.35 之间闭眼时会显著下降到 0.1 以下。按视频帧序列统计 EAR 的持续低值就能判断一次眨眼的开始和结束。持续低值超过某个时长比如 0.5 秒可以判为闭眼超过正常值这是疲劳驾驶提醒系统的常见做法。3.2 身体姿势检测Pose 的 33 关键点与骨架连线绘制Pose 模型用 BlazePose 算法输出 33 个关键点比 COCO 的 17 点多了面部区域和手脚的一些点实际做动作分析时信息更充分。它同样有两种使用模式静态图和视频跟踪参数上多了一个 model_complexity。model_complexity 是 Pose 独有的性能开关取值 0、1、2。0 是最轻量模型速度快但精度弱适合低功耗设备1 是平衡档大多数产品场景我会默认用 12 是最大模型精度最好但 CPU 推理耗时明显增加。在 PC 上跑 model_complexity2 还能接受在树莓派这类设备上就要谨慎了。绘制骨架线是调试阶段的刚需。MediaPipe 提供了现成的绘图工具把 Pose 输出的 landmark 按预设的连接关系画出来骨骼走向一目了然。但要注意传进去的图必须是 RGB 的如果你直接把 BGR 帧传过去绘制结果的颜色会偏蓝调看着很别扭。关键点绘制有一个容易被忽略的点landmark 坐标全部是归一化的浮点数范围在 0~1 之间表示相对于图像宽高的比例。绘图工具内部会自动换算成像素坐标。你如果要自己算关节角度也别忘了先乘上图像的宽和高再算几何关系否则角度数值会完全失真。3.3 手势识别Hands 的 21 关键点与左右手判定逻辑Hands 模型输出的 21 个点从手腕0 号点开始沿手掌到五个指尖分布。它在设计上有一个有意思的细节模型同时输出左右手标签但这个左右是基于「画面里的人自己的左右」来定义的不是基于观众视角。如果你直接把 label 当成观众视角的左右手在镜像画面里一定会反这在做手势交互时是典型的坑。Hands 初始化时有两个参数需要留意max_num_hands 控制一帧最多检测几只手默认是 2如果你要处理多人或者一人双手的特殊场景记得调大min_detection_confidence 默认 0.5新手往往会为了拉高检测率把它调低到 0.3 甚至 0.2结果误检大量增加背景里的晃动物体也被当成手。手部检测对目标大小非常敏感因为前置的 palm detector 是在缩略图上做检测的。手在画面里占的面积太小直接检测不到占得太大超出检测框范围关键点也会漏。这是一个需要靠部署经验来调的问题后面避坑章节会展开讲。手势的语义判断一般不用模型而是基于 21 个关键点的几何关系自己写规则判断手指伸直还是弯曲看的是指尖点到手腕的距离与该手指指根到手腕距离的比值判断握拳看五个指尖是否都贴近手掌中心。这套规则在大多数场景下够用而且逻辑透明、容易调试。3.4 把三个模型串进同一路视频帧同步推理与结果整合把三套模型拼进同一循环最直接的做法是每一帧都依次调用三个 process但这样 CPU 占用会比较高。更常见的做法是控制推理频率比如姿势检测每帧跑、手势检测每两帧跑一次画出上一帧的结果。下面这段代码演示了完整的整合流程import cv2 import mediapipe as mp mp_face_mesh mp.solutions.face_mesh mp_pose mp.solutions.pose mp_hands mp.solutions.hands mp_drawing mp.solutions.drawing_utils mp_drawing_styles mp.solutions.drawing_styles face_mesh mp_face_mesh.FaceMesh( static_image_modeFalse, max_num_faces1, min_detection_confidence0.5) pose mp_pose.Pose( static_image_modeFalse, model_complexity1, min_detection_confidence0.5, min_tracking_confidence0.5) hands mp_hands.Hands( static_image_modeFalse, max_num_hands2, min_detection_confidence0.5, min_tracking_confidence0.5) cap cv2.VideoCapture(0) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) frame_count 0 while cap.isOpened(): ret, frame cap.read() if not ret: break frame_count 1 frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) frame_rgb.flags.writeable False # 每帧跑人脸和姿势每 2 帧跑一次手势 face_results face_mesh.process(frame_rgb) pose_results pose.process(frame_rgb) if frame_count % 2 0: hand_results hands.process(frame_rgb) else: hand_results None # 绘制结果 if face_results.multi_face_landmarks: for face_landmarks in face_results.multi_face_landmarks: mp_drawing.draw_landmarks( imageframe, landmark_listface_landmarks, connectionsmp_face_mesh.FACEMESH_TESSELATION, landmark_drawing_specNone, connection_drawing_specmp_drawing_styles .get_default_face_mesh_tesselation_style()) if pose_results.pose_landmarks: mp_drawing.draw_landmarks( imageframe, landmark_listpose_results.pose_landmarks, connectionsmp_pose.POSE_CONNECTIONS, landmark_drawing_specmp_drawing_styles .get_default_pose_landmarks_style()) if hand_results and hand_results.multi_hand_landmarks: for hand_landmarks in hand_results.multi_hand_landmarks: mp_drawing.draw_landmarks( imageframe, landmark_listhand_landmarks, connectionsmp_hands.HAND_CONNECTIONS, landmark_drawing_specmp_drawing_styles .get_default_hand_landmarks_style(), connection_drawing_specmp_drawing_styles .get_default_hand_connections_style()) cv2.imshow(MediaPipe Multi-Task Detection, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()这段代码里有几个细节值得拆开说。frame_rgb.flags.writeable False 这一行是性能关键它告诉 numpy 这块内存不允许原地修改MediaPipe 内部就能跳过一些数据拷贝推理速度能快不少但代价是你不能再原地往 frame_rgb 上画图所以要画的时候得用原始 BGR 帧。这是官方惯例的坑点很多教程不提。手势检测隔帧执行的策略是有依据的Hands 的 palm detector 比较耗时而手部动作在相邻两帧之间变化通常不大隔一帧取一次结果完全够用。我用了 frame_count % 2 0 这个取模条件控制频率你可以随手改成 3 或 5观察一下帧率和精度的平衡点在哪里。绘制人脸网格用的是 FACEMESH_TESSELATION 连接关系这个是密集三角网格画出来很炫但视觉上会糊成一片。如果你只看眼睛或嘴部建议换成 FACEMESH_CONTOURS 或者自己挑几个关键点画视觉会清爽很多CPU 也能省一点。4. 实战避坑MediaPipe 三合一检测的 5 个高频问题4.1 CPU 占用居高不下三个模型一起跑风扇狂转现象代码跑起来后 CPU 占用直接冲到 80% 以上笔记本风扇声音明显变大帧率降到 10fps 以下画面肉眼可见地卡顿。原因三个模型默认都是每帧全量推理且输入分辨率如果按摄像头默认的 1280×720 甚至更高每个人脸、手势检测都要在较大画面上做缩放计算整个链路叠加起来的算力消耗非常可观。解决把摄像头分辨率强制设为 640×480 或更低这是最有效的一招检测精度损失很小但帧率提升明显再按前面的代码把 Hands 推理频率降为每 2~3 帧一次Pose 的 model_complexity 从 1 降到 0如果只是粗略判断姿态而不是做精细角度分析几乎无感知。做完这三步通常能把占用从 80% 压到 40% 以下。4.2 手一离远就检测不到小目标检测失效现象手在摄像头前 30 厘米内检测正常稍微往后一放手部关键点就消失了人在画面里站着手自然垂在身体两侧也时常检测不出来。原因Hands 模型的前置 palm detector 在缩略图上工作手在图像里占比小、纹理弱检测器在缩略图上容易把它漏掉。这是两段式管线在物理层面的局限不是代码写错。解决两个思路。一是做大手在画面里的成像面积可以物理上让摄像头离人更近或者在代码里把画面中手所在的 ROI 区域裁剪出来再送进 Hands 模型。二是给手部检测加引导利用 Pose 输出里手腕点的位置裁剪出以手腕为中心的方形区域放大后再检测这种方法效果比单纯调 confidence 阈值明显得多我在实际项目里用它把手部检测的有效距离从 30 厘米拉到 80 厘米左右。另外min_detection_confidence 不建议低于 0.5调太低会大面积误检背景里的杂志、键盘、纸团都可能被当成手。4.3 左手右手搞反了镜像与身体坐标的冲突现象画面里人举起右手程序输出的 label 是 Left或者对着镜子做测试左右手判断完全颠倒。原因Hands 模型输出的 handedness 是基于「画面中人自身的左右」来标注的。视频画面如果不做镜像处理人举起右手时在图像坐标里这只手出现在画面左侧模型按图像内容判断就可能标成 Left。镜面场景则相反人的左右和画面里的左右发生了翻转。解决如果是视频通话或自拍场景要做镜像显示先对帧做水平翻转再送进模型这样显示和识别结果就一致了。如果是普通场景你需要知道系统里「左右」用在哪里如果是让用户看到自己用镜像如果是让后台程序做动作语义判断比如判断举的是左手还是右手不能用镜像而且要按照身体的全局朝向把影像坐标系转换到人体坐标系。具体做法是取 Pose 输出的左右肩坐标算出身体朝向再根据手相对身体的位置来修正左右标签。纯靠 Hands 自带的 label 做业务判断几乎一定会出问题。4.4 static_image_mode 用错场景视频里关键点疯狂抖动现象视频流里一个人安静坐着头部和手的关键点却在小幅高频抖动像开了抖动特效有时候明明没动关键点却在几个位置之间跳变。原因这是典型的把 static_image_modeTrue 用在视频流里的后果。静态图模式每帧都做全量检测帧与帧之间没有时序关联检测框的微小波动直接反映到关键点上就会变成肉眼可见的抖动。跟踪模式下模型会参考上一帧结果做平滑抖动量能小一个量级。解决视频流场景统一用 static_image_modeFalse并显式设置 min_tracking_confidence 参数默认 0.5 够用。如果抖动仍然明显可以在代码侧对关键点坐标做一阶低通滤波也就是把当前帧坐标和上一帧坐标按 0.7 比 0.3 的权重混合。这招对姿态和手部都管用但注意混合系数不能太小否则动作响应会有明显的迟滞感。我把这种事后平滑看作最后一道保险栓如果模型本身的跟踪模式已经稳定就不要再叠一层避免过度平滑把快速动作吃掉。4.5 中文路径图片读不进来OpenCV 与操作系统编码的冲突现象cv2.imread 的图片路径里带了中文返回值总是 None图片显示为空换英文路径一切正常。原因OpenCV 的 imread 底层用的是 C 的文件读取接口不处理操作系统层面的 Unicode 编码中文路径在 Windows 上尤其容易直接失败。这是 OpenCV 的历史遗留问题跟 MediaPipe 本身无关但做项目时文件路径经常带中文名所以踩到的人不少。解决不要用 cv2.imread 直接读中文路径改用 numpy 和 cv2.imdecode 组合import cv2 import numpy as np def imread_unicode(filepath): # 用 numpy 从字节流读文件再交给 cv2 解码绕开编码问题 data np.fromfile(filepath, dtypenp.uint8) return cv2.imdecode(data, cv2.IMREAD_COLOR) image imread_unicode(姿态数据/实验_01.jpg)这段代码的思路是先用 numpy 的 fromfile 以字节方式读入整个文件此时文件内容已经是二进制数组跟路径编码无关了再交给 cv2.imdecode 去解析图像格式。这样处理之后中文目录和中文文件名都能正常读取我在处理批量数据集时一般直接封装这个函数统一调用能省掉不少无谓的排查时间。注意反过来写文件时也有同样的问题cv2.imwrite 写中文路径也会失败解决办法是用 cv2.imencode 先编码成字节流再用 tofile 写入套路和读取一致。5. 让检测跑得更快FPS 优化与关键点数据落地5.1 分辨率、置信度阈值与推理频率三合一链路的性能调整参数三合一检测的性能瓶颈基本固定在这三个旋钮上输入分辨率、置信度阈值、推理频率。它们各自影响检测结果的不同侧面组合起来才是一条完整的调优路径。输入分辨率对 MediaPipe 这类模型来说不是越高越好。模型内部会先把图像缩放到固定尺寸再推理你送 1080p 的帧进去它也得先缩小白白浪费了缩放耗时而关键点精度并不会因此显著提升。我一般把摄像头分辨率设在 640×480这是性价比很高的档位。如果业务确实需要看远处的小目标比如三四米外的手部动作再考虑升到 1280×720但这时候 CPU 占用会明显上去。min_detection_confidence 这个参数是检测阶段的闸门调高它误检变少但漏检会增加调低它召回率提升但容易把背景噪声当成目标。我通常用 0.5 作为起步值然后根据真实场景微调如果现场光线差、人动得快降低到 0.4 能救回一些检测如果误检多到影响业务逻辑就往上提到 0.6 或 0.7。注意不要低于 0.3再低就是拿稳定性和性能换那一点点召回不划算。推理频率的错峰是性能优化里最容易见效的一招。三个模型不一定要每帧都跑人脸和姿势是全局信息每帧跑手部隔 2~3 帧跑一次用最近一次结果回填。因为姿势模型已经把人体框出来了手的位置变化都可以通过姿态的腕部点粗估两帧之间的手部误差通常不超过一个手掌宽度对大多数交互和计数场景完全够用。这三个参数的调整顺序我建议是先固定分辨率再调 confidence最后再动推理频率。分辨率影响一切confidence 只影响检测边界推理频率是最后的手段。不要一上来就隔帧跑那样丢了精度还不容易定位问题。5.2 关键点坐标归一化从模型输出到业务数据的转换MediaPipe 输出的 landmark 坐标是归一化的浮点数x、y 在 0~1 之间表示相对图像宽高的比例z 是相对深度的估计值。这个设计让推理结果跟输入分辨率无关同一段视频在不同分辨率下跑出来的 landmark 数值一致方便做清洗和比对。但实际写业务逻辑时往往需要把归一化坐标还原成像素坐标或者按自己的需求存储。下面这段代码把 Pose 的关键点转成 numpy 数组并保存为 CSV是后续做动作分析前的标准预处理步骤import numpy as np import cv2 import mediapipe as mp mp_pose mp.solutions.pose pose mp_pose.Pose(static_image_modeTrue, model_complexity1) def pose_to_array(results, frame_width, frame_height): 把 MediaPipe 的 Pose 结果转成 (33, 3) 的数组前两列是像素坐标第三列是相对深度 if not results.pose_landmarks: return None pts [] for lm in results.pose_landmarks.landmark: x lm.x * frame_width y lm.y * frame_height z lm.z pts.append([x, y, z]) return np.array(pts) image cv2.imread(test.jpg) image_rgb cv2.cvtColor(image, cv2.COLOR_BGR2RGB) results pose.process(image_rgb) h, w image.shape[:2] pts pose_to_array(results, w, h) if pts is not None: # 保存为 CSV表头标注每一列的含义 np.savetxt(pose_landmarks.csv, pts, delimiter,, headerx,y,z, comments) print(f已保存 {pts.shape[0]} 个关键点坐标)这段代码的核心是把归一化坐标乘以图像的宽和高还原为像素坐标z 保持不变。第三列 z 是模型预测的相对深度值单位不是米而在多个关节之间具有相对意义z 越大代表离镜头越远。你如果要做关节角度的计算直接用 x、y 像素坐标算二维角度就够了z 主要用在需要区分肢体前后关系的场景比如判断手臂是向前伸还是向侧面平举。保存成 CSV 只是数据落地的起点我一般会在此基础上继续加工把每一帧的 33×3 数组拼接成时间序列再按时间窗提取特征比如肘关节角度的滑动平均值、腕部坐标的位移速度。这些时序特征才是动作识别模型真正消费的输入。5.3 坐标平滑的正确姿势防抖但别拖影landmark 序列里的抖动分为两类一类是检测器本身的随机游走幅度小、频率高另一类是目标在快速运动时检测结果出现跳变幅度大、偶尔丢失一帧。两类问题处理方式不同。小幅度高频抖动适合用指数移动平均EMA平滑。公式是 smoothed alpha * current (1 - alpha) * previousalpha 取 0.3 到 0.5 之间。alpha 越大越跟手alpha 越小越平滑我常用 0.4 起步。大幅度跳变适合用中值滤波或丢失帧补齐。如果某一帧检测不到手不要直接输出空数据而是沿用上一帧结果并做一个简单的速度外推。补帧逻辑可以写成一个轻量函数当前帧位置 上一帧位置 (上一帧位置 - 上上一帧位置)。这个一阶线性外推对打羽毛球、抬手这类动作够用但在突然转向的动作里会存在轻微过冲用的时候注意观察。平滑处理最怕的就是过度alpha 调到 0.1 以下后你会发现手已经抬起来了屏幕上关键点还在原处磨蹭这种拖影感在交互场景里比抖动更让人难受。平滑只解决检测噪声问题不解决模型本身丢目标的问题后者要靠前面说的 ROI 引导和阈值调整来做。6. 从检测到应用把三合一结果用起来的三个方向检测本身不产生价值关键点落到具体业务里才算闭环。我按实际落地的频率整理三个方向每个方向都可以直接基于前面的代码延展。第一个方向是专注度分析用的是 FaceMesh 的关键点序列。通过 EAR 判断眨眼频率和闭眼时长通过鼻尖和两只耳朵的连线角度估算头部朝向如果头部持续偏转超过 30 度且眨眼频率显著下降就可以判定为专注度下降。这个思路在在线教育、远程监考、驾驶疲劳提醒里都适用。落地时注意每 15 秒做一次统计窗不要用单帧下结论单帧误判率太高。第二个方向是动作计数与姿态纠正用的是 Pose 的关节序列。统计深蹲次数时只需要计算髋关节、膝关节、踝关节三点形成的夹角当角度从接近 180 度连续下降到小于 90 度再回到 180 度计一次完整动作。俯卧撑、引体向上同理只是换关节组合。这套逻辑的实现成本很低但需要处理动作速度差异同样的角度变化快速做完和慢速做完的时间窗不同计数逻辑里要加一个时间容忍度参数否则会漏计或重计。第三个方向是手势交互用的是 Hands 的关键点序列。识别数字 1 到 5 的规则很简单统计除拇指外四个手指中伸直的数量加上拇指的状态。食指和中指伸直判定为 V 字手势在界面翻页场景里很常用。更复杂的可以识别点击动作也就是某个指尖在短时间内的位移变化和速度曲线模拟鼠标点击。手势可以在两帧内完成识别没有明显延迟感适合做演示翻页、缩放控制的替代方案。三个方向里我踩过最深的坑是「先做了识别再想业务逻辑」。曾经有段时间我把姿态、手势、人脸全部识别出来并展示在画面上视觉效果很炫可到了交付阶段发现业务侧根本不知道拿这些坐标干什么。后来我调整了顺序先定义清楚业务需要什么动作特征再倒推需要哪几个关键点然后才去配置模型。模型选型和参数调整都是跟着业务需求走的先有动作定义再有关键点选择最后才有模型配置。每次接新项目我都提醒自己先想清楚这一步能省掉大量返工的时间。希望这篇笔记能帮你把这条路走顺。本文还有配套的精品资源点击获取
用 Python 和 MediaPipe 实现人脸、姿态、手势三合一实时检测
简介一份面向Python及计算机视觉学习者的实战教程围绕MediaPipe框架讲解如何调用预训练模型实时完成面部关键点、手部跟踪与全身姿态估计。教程从环境依赖安装、网络摄像头视频流读取讲起逐步覆盖面部检测、Holistic模型下的多部位地标绘制并配有可直接运行的示例代码、效果说明和应用场景分析如手势控制、健身指导、AR交互整体结构清晰适合计算机视觉入门者快速上手也方便有经验的开发者做原型验证。文档还梳理了各模型的适用场景面部关键点可用于表情分析手部跟踪服务于手势交互全身姿态估计应用于动作比对。资源包共1个docx文档体积约16KB轻量便于下载阅读。已有357人学习浏览文档中对MediaPipe跨平台特性、预训练模型能力及代码实现均有讲解是一份可操作性强、重点突出的技术笔记。1. 用 Python 和 MediaPipe 做三合一姿态检测先从一次翻车说起摄像头前面站着一个人想让程序实时说出他有没有抬手、扭头、眨眼——这个需求听起来不难但真上手时会发现靠 OpenCV 凭空算关键点根本是玄学肤色分割在复杂背景下一碰就碎帧率掉到个位数一顿操作下来连「手在哪」都稳定不了。后来换用 MediaPipe才把这条链路走通。MediaPipe 是 Google 开源的机器学习推理框架内置了人脸网格、姿势估计和手部关键点三套预训练模型Python 调用非常直接CPU 上就能跑到实时帧率。这篇笔记就把「怎么用 Python 把三套检测串起来、参数怎么设、哪些地方容易翻车」一次讲透给正准备做行为分析、交互控制或动作纠正的从业者一条能直接复现的路径。2. 为什么选 MediaPipe方案对比与最小环境搭建2.1 三套模型分别解决什么问题人脸、姿态、手部关键点MediaPipe 在 Python 侧最常用的三件套是 FaceMesh、Pose 和 Hands它们各自解决的是完全不同的检测任务。FaceMesh 输出 468 个人脸关键点覆盖眉毛、眼睛、嘴唇、面部轮廓甚至瞳孔位置。它不是为了做人脸识别那是 FaceNet 那类模型的活而是给出「脸在画面里长什么样」的稠密几何描述。基于这 468 个点你可以算眼睛开合度、头部朝向、嘴部动作这些是专注度分析、疲劳提醒、表情驱动类应用的基础。Pose 基于 BlazePose 架构输出 33 个身体关键点从鼻子、肩膀、肘、腕一路到脚踝。它定位的是「人的骨架」不是人形框。有了骨架坐标可以算肘关节角度、判断深蹲幅度、识别跌倒姿态这是动作计数、健身纠正、安防异常行为检测里最常用的输入。Hands 输出每只手 21 个关键点并且能区分左右手。它内部是两段式管线先用一个轻量 palm detector 在整图上找到手掌位置再在裁剪区域里精确定位 21 个关键点。这意味着手部检测比人体姿态更依赖「手在画面里够不够大」。三套模型的输出结构很统一都是 normalized landmark0~1 浮点数格式一致是它们能拼进同一条推理链路的关键前提。2.2 MediaPipe 与 OpenPose、YOLO-pose 的边界实时单机场景谁更合适从业者常在这三个方案之间犹豫我先说结论实时单机、CPU 优先、跨平台选 MediaPipe追求学术级精度、有多卡 GPU 资源考虑 OpenPose已经重度依赖 YOLO 生态、需要目标框和关键点同时输出YOLO-pose 更顺手。OpenPose 是姿态估计领域的老牌方案关键点定义细致精度上限高但它对算力的要求是另一个量级原版在 CPU 上跑单人实时几乎不现实通常需要 CUDA 加速部署成本明显更高。如果你的业务是离线批处理、对精度极度敏感它才有优势。YOLO-pose 把关键点检测做成了目标检测的附属输出每个检测框自带对应关键点。这种方案在「画面里有多人、需要先框人再取点」的语义下很自然模型权重也轻。但它的关键点数量通常是人体的 17 点或 28 点版本手部、面部细节远不如 MediaPipe 细做手势或面部动作分析时不够用。MediaPipe 的优势恰恰在工程落地上模型小、推理快、CPU 可跑官方还同时维护 Python 和移动端接口。代价是精度上限不如学术方案关键点偶尔会抖动。对绝大多数实时交互、行为判断类的产品需求来说这个精度足够了而且省下来的部署成本是实打实的。2.3 最小依赖清单与安装验证Python 环境、mediapipe 安装、跑通第一段代码安装这一步本身不难但环境搭配上有一些需要注意的地方。建议用 Python 3.9~3.11 的 64 位环境新版本 mediapipe 对 Python 版本的支持有明确上限装之前先确认一下自己环境里的 Python 版本避免遇到 wheel 不匹配的报错。# 创建虚拟环境Windows / Linux / macOS 通用 python -m venv mp_env # Windows 激活 mp_env\Scripts\activate # Linux / macOS 激活 # source mp_env/bin/activate # 安装核心依赖 pip install mediapipe opencv-python numpy # 验证安装 python -c import mediapipe as mp; print(mp.__version__)这段命令先建了一个独立的虚拟环境这是为了避免 mediapipe 和项目的其他包互相污染依赖。pip install 一行把三样东西装齐mediapipe 本身、opencv-python 用来读摄像头和图像处理、numpy 用来做数组运算。最后一句验证命令会打印出版本号看到输出就说明基本环境没问题。如果打印失败大多数情况是 Python 版本超出 wheel 支持范围换一个 3.10 左右的版本基本能解决。装完库之后先用一张静态图做冒烟测试比直接上摄像头好排错。下面这段代码读入本地图片跑一次姿势检测并打印出关键点数量import cv2 import mediapipe as mp mp_pose mp.solutions.pose pose mp_pose.Pose(static_image_modeTrue, model_complexity1) image cv2.imread(test.jpg) image_rgb cv2.cvtColor(image, cv2.COLOR_BGR2RGB) results pose.process(image_rgb) if results.pose_landmarks: print(f检测到 {len(results.pose_landmarks.landmark)} 个关键点) else: print(未检测到人体姿态) pose.close()这段代码的逻辑是把图像从 OpenCV 默认的 BGR 色彩空间转到 MediaPipe 要求的 RGB然后调用 process 方法推理。static_image_modeTrue 表示对单张静态图做完整检测model_complexity1 表示使用完整模型比 0 更准比 2 更快。最后记得调用 pose.close() 释放资源这是新手很容易漏掉的一步不释放的话在循环场景里会累积内存占用。3. 从单模型到三合一人脸、身体、手部检测的实现步骤3.1 人脸检测FaceMesh 的 468 关键点与注意力方向判断FaceMesh 在 Python 侧的接口设计得很简单初始化时调整好参数送入 RGB 帧就能拿到多张脸的 468 点坐标。实际业务里用得最多的不是全部 468 点而是眼睛周围那几个点——通过它们可以算出眼纵横比EAR用来判断睁眼还是闭眼。FaceMesh 初始化有三个关键参数static_image_mode 控制是静态图模式还是视频跟踪模式max_num_faces 限制一帧最多检测几张脸默认是 1业务场景经常需要调大min_detection_confidence 是检测阶段的最低置信度阈值默认 0.5调高会减少误检但可能漏掉模糊的小脸。对于视频流我一般强烈建议把 static_image_mode 设为 False让模型进入跟踪模式。跟踪模式不会每帧都做全图人脸检测而是基于上一帧的结果做局部跟踪速度更快、抖动也更小。代价是如果脸在画面里突然大幅移动或转侧跟踪可能丢失模型会重新启动全图检测。在实际产品里这通常比每帧全量检测的体验好得多。眨眼判断是 FaceMesh 最经典的应用核心是指标 EAREye Aspect Ratio。计算方式是用眼睛六个关键点中的两组垂直距离取平均再除以水平距离。人正常睁眼时 EAR 在 0.2~0.35 之间闭眼时会显著下降到 0.1 以下。按视频帧序列统计 EAR 的持续低值就能判断一次眨眼的开始和结束。持续低值超过某个时长比如 0.5 秒可以判为闭眼超过正常值这是疲劳驾驶提醒系统的常见做法。3.2 身体姿势检测Pose 的 33 关键点与骨架连线绘制Pose 模型用 BlazePose 算法输出 33 个关键点比 COCO 的 17 点多了面部区域和手脚的一些点实际做动作分析时信息更充分。它同样有两种使用模式静态图和视频跟踪参数上多了一个 model_complexity。model_complexity 是 Pose 独有的性能开关取值 0、1、2。0 是最轻量模型速度快但精度弱适合低功耗设备1 是平衡档大多数产品场景我会默认用 12 是最大模型精度最好但 CPU 推理耗时明显增加。在 PC 上跑 model_complexity2 还能接受在树莓派这类设备上就要谨慎了。绘制骨架线是调试阶段的刚需。MediaPipe 提供了现成的绘图工具把 Pose 输出的 landmark 按预设的连接关系画出来骨骼走向一目了然。但要注意传进去的图必须是 RGB 的如果你直接把 BGR 帧传过去绘制结果的颜色会偏蓝调看着很别扭。关键点绘制有一个容易被忽略的点landmark 坐标全部是归一化的浮点数范围在 0~1 之间表示相对于图像宽高的比例。绘图工具内部会自动换算成像素坐标。你如果要自己算关节角度也别忘了先乘上图像的宽和高再算几何关系否则角度数值会完全失真。3.3 手势识别Hands 的 21 关键点与左右手判定逻辑Hands 模型输出的 21 个点从手腕0 号点开始沿手掌到五个指尖分布。它在设计上有一个有意思的细节模型同时输出左右手标签但这个左右是基于「画面里的人自己的左右」来定义的不是基于观众视角。如果你直接把 label 当成观众视角的左右手在镜像画面里一定会反这在做手势交互时是典型的坑。Hands 初始化时有两个参数需要留意max_num_hands 控制一帧最多检测几只手默认是 2如果你要处理多人或者一人双手的特殊场景记得调大min_detection_confidence 默认 0.5新手往往会为了拉高检测率把它调低到 0.3 甚至 0.2结果误检大量增加背景里的晃动物体也被当成手。手部检测对目标大小非常敏感因为前置的 palm detector 是在缩略图上做检测的。手在画面里占的面积太小直接检测不到占得太大超出检测框范围关键点也会漏。这是一个需要靠部署经验来调的问题后面避坑章节会展开讲。手势的语义判断一般不用模型而是基于 21 个关键点的几何关系自己写规则判断手指伸直还是弯曲看的是指尖点到手腕的距离与该手指指根到手腕距离的比值判断握拳看五个指尖是否都贴近手掌中心。这套规则在大多数场景下够用而且逻辑透明、容易调试。3.4 把三个模型串进同一路视频帧同步推理与结果整合把三套模型拼进同一循环最直接的做法是每一帧都依次调用三个 process但这样 CPU 占用会比较高。更常见的做法是控制推理频率比如姿势检测每帧跑、手势检测每两帧跑一次画出上一帧的结果。下面这段代码演示了完整的整合流程import cv2 import mediapipe as mp mp_face_mesh mp.solutions.face_mesh mp_pose mp.solutions.pose mp_hands mp.solutions.hands mp_drawing mp.solutions.drawing_utils mp_drawing_styles mp.solutions.drawing_styles face_mesh mp_face_mesh.FaceMesh( static_image_modeFalse, max_num_faces1, min_detection_confidence0.5) pose mp_pose.Pose( static_image_modeFalse, model_complexity1, min_detection_confidence0.5, min_tracking_confidence0.5) hands mp_hands.Hands( static_image_modeFalse, max_num_hands2, min_detection_confidence0.5, min_tracking_confidence0.5) cap cv2.VideoCapture(0) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) frame_count 0 while cap.isOpened(): ret, frame cap.read() if not ret: break frame_count 1 frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) frame_rgb.flags.writeable False # 每帧跑人脸和姿势每 2 帧跑一次手势 face_results face_mesh.process(frame_rgb) pose_results pose.process(frame_rgb) if frame_count % 2 0: hand_results hands.process(frame_rgb) else: hand_results None # 绘制结果 if face_results.multi_face_landmarks: for face_landmarks in face_results.multi_face_landmarks: mp_drawing.draw_landmarks( imageframe, landmark_listface_landmarks, connectionsmp_face_mesh.FACEMESH_TESSELATION, landmark_drawing_specNone, connection_drawing_specmp_drawing_styles .get_default_face_mesh_tesselation_style()) if pose_results.pose_landmarks: mp_drawing.draw_landmarks( imageframe, landmark_listpose_results.pose_landmarks, connectionsmp_pose.POSE_CONNECTIONS, landmark_drawing_specmp_drawing_styles .get_default_pose_landmarks_style()) if hand_results and hand_results.multi_hand_landmarks: for hand_landmarks in hand_results.multi_hand_landmarks: mp_drawing.draw_landmarks( imageframe, landmark_listhand_landmarks, connectionsmp_hands.HAND_CONNECTIONS, landmark_drawing_specmp_drawing_styles .get_default_hand_landmarks_style(), connection_drawing_specmp_drawing_styles .get_default_hand_connections_style()) cv2.imshow(MediaPipe Multi-Task Detection, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()这段代码里有几个细节值得拆开说。frame_rgb.flags.writeable False 这一行是性能关键它告诉 numpy 这块内存不允许原地修改MediaPipe 内部就能跳过一些数据拷贝推理速度能快不少但代价是你不能再原地往 frame_rgb 上画图所以要画的时候得用原始 BGR 帧。这是官方惯例的坑点很多教程不提。手势检测隔帧执行的策略是有依据的Hands 的 palm detector 比较耗时而手部动作在相邻两帧之间变化通常不大隔一帧取一次结果完全够用。我用了 frame_count % 2 0 这个取模条件控制频率你可以随手改成 3 或 5观察一下帧率和精度的平衡点在哪里。绘制人脸网格用的是 FACEMESH_TESSELATION 连接关系这个是密集三角网格画出来很炫但视觉上会糊成一片。如果你只看眼睛或嘴部建议换成 FACEMESH_CONTOURS 或者自己挑几个关键点画视觉会清爽很多CPU 也能省一点。4. 实战避坑MediaPipe 三合一检测的 5 个高频问题4.1 CPU 占用居高不下三个模型一起跑风扇狂转现象代码跑起来后 CPU 占用直接冲到 80% 以上笔记本风扇声音明显变大帧率降到 10fps 以下画面肉眼可见地卡顿。原因三个模型默认都是每帧全量推理且输入分辨率如果按摄像头默认的 1280×720 甚至更高每个人脸、手势检测都要在较大画面上做缩放计算整个链路叠加起来的算力消耗非常可观。解决把摄像头分辨率强制设为 640×480 或更低这是最有效的一招检测精度损失很小但帧率提升明显再按前面的代码把 Hands 推理频率降为每 2~3 帧一次Pose 的 model_complexity 从 1 降到 0如果只是粗略判断姿态而不是做精细角度分析几乎无感知。做完这三步通常能把占用从 80% 压到 40% 以下。4.2 手一离远就检测不到小目标检测失效现象手在摄像头前 30 厘米内检测正常稍微往后一放手部关键点就消失了人在画面里站着手自然垂在身体两侧也时常检测不出来。原因Hands 模型的前置 palm detector 在缩略图上工作手在图像里占比小、纹理弱检测器在缩略图上容易把它漏掉。这是两段式管线在物理层面的局限不是代码写错。解决两个思路。一是做大手在画面里的成像面积可以物理上让摄像头离人更近或者在代码里把画面中手所在的 ROI 区域裁剪出来再送进 Hands 模型。二是给手部检测加引导利用 Pose 输出里手腕点的位置裁剪出以手腕为中心的方形区域放大后再检测这种方法效果比单纯调 confidence 阈值明显得多我在实际项目里用它把手部检测的有效距离从 30 厘米拉到 80 厘米左右。另外min_detection_confidence 不建议低于 0.5调太低会大面积误检背景里的杂志、键盘、纸团都可能被当成手。4.3 左手右手搞反了镜像与身体坐标的冲突现象画面里人举起右手程序输出的 label 是 Left或者对着镜子做测试左右手判断完全颠倒。原因Hands 模型输出的 handedness 是基于「画面中人自身的左右」来标注的。视频画面如果不做镜像处理人举起右手时在图像坐标里这只手出现在画面左侧模型按图像内容判断就可能标成 Left。镜面场景则相反人的左右和画面里的左右发生了翻转。解决如果是视频通话或自拍场景要做镜像显示先对帧做水平翻转再送进模型这样显示和识别结果就一致了。如果是普通场景你需要知道系统里「左右」用在哪里如果是让用户看到自己用镜像如果是让后台程序做动作语义判断比如判断举的是左手还是右手不能用镜像而且要按照身体的全局朝向把影像坐标系转换到人体坐标系。具体做法是取 Pose 输出的左右肩坐标算出身体朝向再根据手相对身体的位置来修正左右标签。纯靠 Hands 自带的 label 做业务判断几乎一定会出问题。4.4 static_image_mode 用错场景视频里关键点疯狂抖动现象视频流里一个人安静坐着头部和手的关键点却在小幅高频抖动像开了抖动特效有时候明明没动关键点却在几个位置之间跳变。原因这是典型的把 static_image_modeTrue 用在视频流里的后果。静态图模式每帧都做全量检测帧与帧之间没有时序关联检测框的微小波动直接反映到关键点上就会变成肉眼可见的抖动。跟踪模式下模型会参考上一帧结果做平滑抖动量能小一个量级。解决视频流场景统一用 static_image_modeFalse并显式设置 min_tracking_confidence 参数默认 0.5 够用。如果抖动仍然明显可以在代码侧对关键点坐标做一阶低通滤波也就是把当前帧坐标和上一帧坐标按 0.7 比 0.3 的权重混合。这招对姿态和手部都管用但注意混合系数不能太小否则动作响应会有明显的迟滞感。我把这种事后平滑看作最后一道保险栓如果模型本身的跟踪模式已经稳定就不要再叠一层避免过度平滑把快速动作吃掉。4.5 中文路径图片读不进来OpenCV 与操作系统编码的冲突现象cv2.imread 的图片路径里带了中文返回值总是 None图片显示为空换英文路径一切正常。原因OpenCV 的 imread 底层用的是 C 的文件读取接口不处理操作系统层面的 Unicode 编码中文路径在 Windows 上尤其容易直接失败。这是 OpenCV 的历史遗留问题跟 MediaPipe 本身无关但做项目时文件路径经常带中文名所以踩到的人不少。解决不要用 cv2.imread 直接读中文路径改用 numpy 和 cv2.imdecode 组合import cv2 import numpy as np def imread_unicode(filepath): # 用 numpy 从字节流读文件再交给 cv2 解码绕开编码问题 data np.fromfile(filepath, dtypenp.uint8) return cv2.imdecode(data, cv2.IMREAD_COLOR) image imread_unicode(姿态数据/实验_01.jpg)这段代码的思路是先用 numpy 的 fromfile 以字节方式读入整个文件此时文件内容已经是二进制数组跟路径编码无关了再交给 cv2.imdecode 去解析图像格式。这样处理之后中文目录和中文文件名都能正常读取我在处理批量数据集时一般直接封装这个函数统一调用能省掉不少无谓的排查时间。注意反过来写文件时也有同样的问题cv2.imwrite 写中文路径也会失败解决办法是用 cv2.imencode 先编码成字节流再用 tofile 写入套路和读取一致。5. 让检测跑得更快FPS 优化与关键点数据落地5.1 分辨率、置信度阈值与推理频率三合一链路的性能调整参数三合一检测的性能瓶颈基本固定在这三个旋钮上输入分辨率、置信度阈值、推理频率。它们各自影响检测结果的不同侧面组合起来才是一条完整的调优路径。输入分辨率对 MediaPipe 这类模型来说不是越高越好。模型内部会先把图像缩放到固定尺寸再推理你送 1080p 的帧进去它也得先缩小白白浪费了缩放耗时而关键点精度并不会因此显著提升。我一般把摄像头分辨率设在 640×480这是性价比很高的档位。如果业务确实需要看远处的小目标比如三四米外的手部动作再考虑升到 1280×720但这时候 CPU 占用会明显上去。min_detection_confidence 这个参数是检测阶段的闸门调高它误检变少但漏检会增加调低它召回率提升但容易把背景噪声当成目标。我通常用 0.5 作为起步值然后根据真实场景微调如果现场光线差、人动得快降低到 0.4 能救回一些检测如果误检多到影响业务逻辑就往上提到 0.6 或 0.7。注意不要低于 0.3再低就是拿稳定性和性能换那一点点召回不划算。推理频率的错峰是性能优化里最容易见效的一招。三个模型不一定要每帧都跑人脸和姿势是全局信息每帧跑手部隔 2~3 帧跑一次用最近一次结果回填。因为姿势模型已经把人体框出来了手的位置变化都可以通过姿态的腕部点粗估两帧之间的手部误差通常不超过一个手掌宽度对大多数交互和计数场景完全够用。这三个参数的调整顺序我建议是先固定分辨率再调 confidence最后再动推理频率。分辨率影响一切confidence 只影响检测边界推理频率是最后的手段。不要一上来就隔帧跑那样丢了精度还不容易定位问题。5.2 关键点坐标归一化从模型输出到业务数据的转换MediaPipe 输出的 landmark 坐标是归一化的浮点数x、y 在 0~1 之间表示相对图像宽高的比例z 是相对深度的估计值。这个设计让推理结果跟输入分辨率无关同一段视频在不同分辨率下跑出来的 landmark 数值一致方便做清洗和比对。但实际写业务逻辑时往往需要把归一化坐标还原成像素坐标或者按自己的需求存储。下面这段代码把 Pose 的关键点转成 numpy 数组并保存为 CSV是后续做动作分析前的标准预处理步骤import numpy as np import cv2 import mediapipe as mp mp_pose mp.solutions.pose pose mp_pose.Pose(static_image_modeTrue, model_complexity1) def pose_to_array(results, frame_width, frame_height): 把 MediaPipe 的 Pose 结果转成 (33, 3) 的数组前两列是像素坐标第三列是相对深度 if not results.pose_landmarks: return None pts [] for lm in results.pose_landmarks.landmark: x lm.x * frame_width y lm.y * frame_height z lm.z pts.append([x, y, z]) return np.array(pts) image cv2.imread(test.jpg) image_rgb cv2.cvtColor(image, cv2.COLOR_BGR2RGB) results pose.process(image_rgb) h, w image.shape[:2] pts pose_to_array(results, w, h) if pts is not None: # 保存为 CSV表头标注每一列的含义 np.savetxt(pose_landmarks.csv, pts, delimiter,, headerx,y,z, comments) print(f已保存 {pts.shape[0]} 个关键点坐标)这段代码的核心是把归一化坐标乘以图像的宽和高还原为像素坐标z 保持不变。第三列 z 是模型预测的相对深度值单位不是米而在多个关节之间具有相对意义z 越大代表离镜头越远。你如果要做关节角度的计算直接用 x、y 像素坐标算二维角度就够了z 主要用在需要区分肢体前后关系的场景比如判断手臂是向前伸还是向侧面平举。保存成 CSV 只是数据落地的起点我一般会在此基础上继续加工把每一帧的 33×3 数组拼接成时间序列再按时间窗提取特征比如肘关节角度的滑动平均值、腕部坐标的位移速度。这些时序特征才是动作识别模型真正消费的输入。5.3 坐标平滑的正确姿势防抖但别拖影landmark 序列里的抖动分为两类一类是检测器本身的随机游走幅度小、频率高另一类是目标在快速运动时检测结果出现跳变幅度大、偶尔丢失一帧。两类问题处理方式不同。小幅度高频抖动适合用指数移动平均EMA平滑。公式是 smoothed alpha * current (1 - alpha) * previousalpha 取 0.3 到 0.5 之间。alpha 越大越跟手alpha 越小越平滑我常用 0.4 起步。大幅度跳变适合用中值滤波或丢失帧补齐。如果某一帧检测不到手不要直接输出空数据而是沿用上一帧结果并做一个简单的速度外推。补帧逻辑可以写成一个轻量函数当前帧位置 上一帧位置 (上一帧位置 - 上上一帧位置)。这个一阶线性外推对打羽毛球、抬手这类动作够用但在突然转向的动作里会存在轻微过冲用的时候注意观察。平滑处理最怕的就是过度alpha 调到 0.1 以下后你会发现手已经抬起来了屏幕上关键点还在原处磨蹭这种拖影感在交互场景里比抖动更让人难受。平滑只解决检测噪声问题不解决模型本身丢目标的问题后者要靠前面说的 ROI 引导和阈值调整来做。6. 从检测到应用把三合一结果用起来的三个方向检测本身不产生价值关键点落到具体业务里才算闭环。我按实际落地的频率整理三个方向每个方向都可以直接基于前面的代码延展。第一个方向是专注度分析用的是 FaceMesh 的关键点序列。通过 EAR 判断眨眼频率和闭眼时长通过鼻尖和两只耳朵的连线角度估算头部朝向如果头部持续偏转超过 30 度且眨眼频率显著下降就可以判定为专注度下降。这个思路在在线教育、远程监考、驾驶疲劳提醒里都适用。落地时注意每 15 秒做一次统计窗不要用单帧下结论单帧误判率太高。第二个方向是动作计数与姿态纠正用的是 Pose 的关节序列。统计深蹲次数时只需要计算髋关节、膝关节、踝关节三点形成的夹角当角度从接近 180 度连续下降到小于 90 度再回到 180 度计一次完整动作。俯卧撑、引体向上同理只是换关节组合。这套逻辑的实现成本很低但需要处理动作速度差异同样的角度变化快速做完和慢速做完的时间窗不同计数逻辑里要加一个时间容忍度参数否则会漏计或重计。第三个方向是手势交互用的是 Hands 的关键点序列。识别数字 1 到 5 的规则很简单统计除拇指外四个手指中伸直的数量加上拇指的状态。食指和中指伸直判定为 V 字手势在界面翻页场景里很常用。更复杂的可以识别点击动作也就是某个指尖在短时间内的位移变化和速度曲线模拟鼠标点击。手势可以在两帧内完成识别没有明显延迟感适合做演示翻页、缩放控制的替代方案。三个方向里我踩过最深的坑是「先做了识别再想业务逻辑」。曾经有段时间我把姿态、手势、人脸全部识别出来并展示在画面上视觉效果很炫可到了交付阶段发现业务侧根本不知道拿这些坐标干什么。后来我调整了顺序先定义清楚业务需要什么动作特征再倒推需要哪几个关键点然后才去配置模型。模型选型和参数调整都是跟着业务需求走的先有动作定义再有关键点选择最后才有模型配置。每次接新项目我都提醒自己先想清楚这一步能省掉大量返工的时间。希望这篇笔记能帮你把这条路走顺。本文还有配套的精品资源点击获取
