简介一款基于Google Mediapipe Holistic API的Python视频整体跟踪示例资源。面向计算机视觉初学者与Python开发者演示如何对视频中的人脸、手部、身体姿态进行联合检测与跟踪可应用于体育动作分析、虚拟现实交互、康复训练监测等场景也可作为人体姿态估计项目的入门参考。资源共2个文件包含一个Python脚本和一份Markdown说明文档压缩包仅2KB其中Python脚本负责读取视频并调用Mediapipe Holistic模型提取多维关键点Markdown文档提供环境配置、参数说明及简单用法指引。已有815人学习浏览。通过这份资源读者能获得一个简洁可运行的跟踪脚本了解用-i、-o、-f参数分别指定输入视频、输出结果与模型路径并在此基础上扩展实时姿态估计、离线视频分析或关键点可视化功能。整个实现轻量紧凑适合快速上手Mediapipe整体追踪流程对于希望快速体验Holistic能力的开发者是一份实用的起步示例。1. Mediapipe-Holistic-Tracking一个进程同时拿全身、双手、人脸关键点第一次在动作捕捉需求里把姿态、手部、人脸分开做三个模型轮流出关键点结果一帧画面处理完卡到没法聊。后来换用 Mediapipe-Holistic-Tracking一条推理管线同时拿到 33 个身体关键点、每只手 21 个关键点和 468 个脸部关键点Python 侧只需要传一帧 RGB 图就能从 process() 结果里取出三组坐标实时性和代码量都友好很多。它解决的核心问题是“全身协同分析”像健身计数、手语识别、虚拟形象驱动这类需要身体姿态和手部细节同时参与的场景用它最合适。适合已经会 OpenCV、想直接把骨架数据用起来的开发者。2. 底层原理与选型理由三套关键点怎么在一帧里同时出来2.1 级联检测架构身体区域决定了脸和手的搜索范围MediaPipe Holistic 并不是把三个模型并行拼在一起而是做了一次“级联推理Pipeline”先用 Pose 模型在整帧上做人体姿态估计拿到躯干和四肢关键点然后根据面部区域大致是头部 bounding box交给 Face Mesh 模型做密集网格回归再根据左右手腕关键点附近裁剪出两个手部 ROI分别交给 Hand Landmarks 模型。这个设计意味着手部模型不需要在全图搜索手只需要在手腕附近的小范围内做回归面部模型也不需要重新检测整张脸直接在 Pose 输出的头部区域做对齐。级联之后单帧计算量从“三次全图检测”降成“一次全图加两次小 ROI”这让它在 CPU 上也有机会跑出能用的帧率。也正因为这样Holistic 的“初始检测”环节几乎只由 Pose 完成。如果你把人完全移出画面再进来它会重新触发一次完整的 Pose 检测这一帧会有明显卡顿而正常追踪中它主要依赖上一帧的关键点做短时关联。理解这一点后面调 min_detection_confidence 和 min_tracking_confidence 时就不会一头雾水——前者控制重新检测的门槛后者控制追踪丢失的容忍度。还有一个很容易忽视的点手部 ROI 的裁剪取决于 Pose 输出的手腕关键点。一旦手腕不稳定后续手部追踪就跟着抖动。所以在 Holistic 里身体姿态的稳定性直接影响手部识别质量单独优化手部参数往往不如先稳定 Pose。2.2 输出数据结构三组 landmark 到底装了什么process() 返回的 results 对象里我常用这四个字段results.pose_landmarks33 个点对应人体主要关节比如 mp_holistic.PoseLandmark.LEFT_SHOULDER 就是左肩results.face_landmarks468 个点覆盖额头、眼睑、嘴唇、下巴等稠密网格results.left_hand_landmarks / results.right_hand_landmarks各 21 个点从手腕到大拇指到小指对应五个手指的关节每个点都是一个带 4 个属性的对象x、y 是归一化到 [0,1] 的坐标相对当前帧宽高z 是相对躯干中心的深度参考visibility 是可见性置信度。把 x、y 直接乘以图像宽高就得到像素坐标这是最常见的换算方式。z 轴并不是真实物理深度它约等于像素比例适合比较相对远近不适合做毫米级测量。visibility 这个字段在 Pose 上非常实用。当手背在身后、被遮挡或刚好出画时对应关键点的 visibility 会明显下降。做计数逻辑时直接用它过滤掉低置信度的帧比等坐标变成异常值再处理省心得多。取点时有个习惯要养成先判断对应 landmarks 是否为 None再访问 .landmark否则空对象上取索引直接抛异常。if results.pose_landmarks: left_shoulder results.pose_landmarks.landmark[ mp_holistic.PoseLandmark.LEFT_SHOULDER]2.3 为什么不分三个模型各调一遍性能与工程复杂度分别调用三个模型时Pose、FaceMesh、Hands 各自做一次全图预处理和检测同一帧里出现大量重复计算而且三个模型输出的坐标系统对齐很麻烦摄像头抖动、不同模型缺帧、关键点命名方式不一致写拼接代码的时间比调模型还长。Holistic 把三者的 ROI、坐标系、关键点连接关系统一在同一帧结果里省掉了最让人头疼的对齐环节。我在模拟项目X里做过简单对比分开调用三个模型跑一段 30 秒视频耗时比 Holistic 多出将近一倍而且还要额外处理“某个模型丢帧、另外两个没丢”的情况。Holistic 是三套关键点一起出现或一起缺失逻辑上好处理很多。下面这个表是我在选型时习惯做的对照方案模型数量ROI 复用坐标对齐工程成本分开调用3无各自全图检测需自行对齐高需处理缺帧Holistic3 级联复用 Pose 头部/手腕 ROI输出自带同一坐标系低直接读结果不过要明确Holistic 不是三个模型并行它是串行级联各自推理仍然消耗时间。如果你的目标只是单独识别人脸或单独追踪手势直接用独立模型往往更快更稳Holistic 的价值在于“三者都要且坐标系统一”。选型边界也要说清Holistic 默认只输出单人的关键点多人同框时它只能锁定置信度最高的目标如果项目要求同时捕捉两个人需要额外加目标跟踪或直接换多人姿态方案。它对手部精细纹理的识别也不如单独的手部模型毕竟手部 ROI 是从身体骨骼外推的画面里手部占的面积太小就会丢点。提示Holistic 与独立模型使用同一套坐标系但 z 轴参考原点不同混合使用前先对齐。3. Python 环境搭建与最简可运行代码先把第一帧画出来3.1 依赖安装与版本选择MediaPipe 在 PyPI 上发布的安装包并不对所有 Python 版本一视同仁。常见的情况是 Python 3.12 或更新版本装不上官方包pip 只会提示找不到匹配版本。稳妥做法是先用 Conda 建一个 3.10 的干净环境再装conda create -n holistic python3.10 -y conda activate holistic pip install mediapipe opencv-python numpy安装完用一行命令快速验证python -c import mediapipe as mp; print(mp.__version__)能输出版本号就说明装好了。如果这里报错多半是 Python 版本太新或者镜像源里的 wheel 还没同步优先检查解释器版本而不是反复换镜像。另一个常见坑是某些旧版本 numpy 会和 mediapipe 的 protobuf 冲突装完 mediapipe 后尽量让 pip 自己解析依赖不要手动锁定 numpy 版本。如果只是想快速验证功能Python 3.8 或 3.9 的现成环境也能直接用关键是避开 3.12 及更新版本。3.2 初始化参数每个旋钮的实际效果下面这段是 Holistic 初始化的典型写法import mediapipe as mp mp_holistic mp.solutions.holistic holistic mp_holistic.Holistic( static_image_modeFalse, # 视频流模式启用帧间追踪 model_complexity1, # 0最快 1均衡 2最准 smooth_landmarksTrue, # 开启关键点平滑减少抖动 min_detection_confidence0.5, # 初始检测阈值低于则重新检测 min_tracking_confidence0.5 # 追踪阈值低于则断开跟踪 )static_image_mode 这个参数最容易被误解。设为 False 时Holistic 认为你在处理连续视频帧会尝试沿用上一帧的关键点位置来追踪当前帧计算量更小设为 True 时它对每一帧都做完整初始检测适合批量处理图片。视频流里误设为 True 后帧率会掉一半以上这也是很多开发者抱怨“代码照着文档写却跑不动”的原因之一。model_complexity 直接影响神经网络规模。复杂度为 0 时肢体关键点在侧面姿势下容易偏移调到 2 时精度最好但 CPU 上基本跑不动。我的建议是先固定 1如果发现特定动作识别不准再针对性地降分辨率或升复杂度而不是上来就拉满。min_detection_confidence 和 min_tracking_confidence 是一对容易混淆的参数。简单说前者决定“找不到人时多大把握才重新检测”后者决定“追踪过程中多大把握才继续跟踪”。视频流里把前者调高可以避免人未完全入画就乱跳后者调低可以让目标短暂遮挡后仍然跟得住。这些参数的另一个作用是控制 CPU 占用项目早期调试阶段建议把画面分辨率调低等逻辑验证完再逐步拉高避免一上来就被性能问题带偏方向。3.3 从摄像头读帧到画出三套关键点import cv2 mp_drawing mp.solutions.drawing_utils cap cv2.VideoCapture(0) while cap.isOpened(): ok, frame cap.read() if not ok: break # 水平翻转让画面像照镜子一样避免左右手反直觉 frame cv2.flip(frame, 1) # MediaPipe 要求 RGB 输入OpenCV 默认是 BGR rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results holistic.process(rgb) # 画身体骨架 if results.pose_landmarks: mp_drawing.draw_landmarks( frame, results.pose_landmarks, mp_holistic.POSE_CONNECTIONS, mp_drawing.DrawingSpec(color(0, 255, 0), thickness2), mp_drawing.DrawingSpec(color(255, 255, 255), thickness1)) # 画面部网格只画轮廓可以省掉不少渲染开销 if results.face_landmarks: mp_drawing.draw_landmarks( frame, results.face_landmarks, mp_holistic.FACEMESH_CONTOURS, landmark_drawing_specNone, connection_drawing_specmp_drawing.DrawingSpec( color(0, 255, 255), thickness1)) # 画左右手关键点 for hand_landmarks in (results.left_hand_landmarks, results.right_hand_landmarks): if not hand_landmarks: continue mp_drawing.draw_landmarks( frame, hand_landmarks, mp_holistic.HAND_CONNECTIONS, mp_drawing.DrawingSpec(color(255, 0, 0), thickness2), mp_drawing.DrawingSpec(color(255, 255, 0), thickness1)) cv2.imshow(Holistic Demo, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows() holistic.close()这段代码的逻辑分四层读帧、预处理、推理、绘制。预处理最容易被忽略的是颜色空间OpenCV 读出来是 BGR直接丢给 process() 会让关键点整体偏移且没有任何报错这是典型的翻车点。绘制时每个 DrawingSpec 分别控制关键点圆点和连接线的粗细与颜色如果只想画骨架不画密集网格把 face_landmarks 的绘制块注释掉即可。参数说明waitKey(1) 里的 1 表示每帧等待 1 毫秒这样视频能实时刷新如果写成 waitKey(0)画面会冻结只有按键才会继续。holistic.close() 用于释放模型内部资源放在循环结束后调用就好不需要在每帧里执行。如果黑窗口能弹出来但画面里没有任何骨架先别急着怀疑参数打印一行确认检测结果print(pose:, results.pose_landmarks is not None, face:, results.face_landmarks is not None)如果全是 False说明摄像头前没检测到人或者画面太暗、离镜头太远。多数情况下把人物放到画面中央、保持正常光照就解决了。3.4 静态图片批处理没有摄像头也能验证管道import glob holistic mp_holistic.Holistic(static_image_modeTrue) for img_path in glob.glob(data/*.jpg): img cv2.imread(img_path) rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) results holistic.process(rgb) if results.pose_landmarks: mp_drawing.draw_landmarks( img, results.pose_landmarks, mp_holistic.POSE_CONNECTIONS) out_path img_path.replace(data/, out/) cv2.imwrite(out_path, img) print(processed, img_path)批处理时记得把 static_image_mode 设为 True让每张图片独立检测不受上一张图影响。之前有开发者把默认的 False 直接拿去跑图片目录结果第一张图检测成功后后续图片沿用了第一张图的追踪状态大多数图片只返回部分关键点看起来就像模型失效了其实只是模式没切换。输出目录要先建好cv2.imwrite 不会自动创建文件夹。4. 实战拆解用关节夹角做深蹲计数器从坐标到业务逻辑4.1 归一化坐标换算与角度计算拿到 landmark 后第一步往往不是画点而是算关节角度。以深蹲为例需要判断大腿与小腿的折叠程度。我们用臀部、膝盖、脚踝三个关键点计算膝关节夹角import math def calc_angle(a, b, c): 以 b 为顶点计算向量 ba 与 bc 的夹角返回角度0~360。 a/b/c 是 landmark 对象只需要用 x/y 字段。 ang math.degrees( math.atan2(c.y - b.y, c.x - b.x) - math.atan2(a.y - b.y, a.x - b.x) ) if ang 0: ang 360 return ang hip results.pose_landmarks.landmark[mp_holistic.PoseLandmark.RIGHT_HIP] knee results.pose_landmarks.landmark[mp_holistic.PoseLandmark.RIGHT_KNEE] ankle results.pose_landmarks.landmark[mp_holistic.PoseLandmark.RIGHT_ANKLE] knee_angle calc_angle(hip, knee, ankle)atan2 差值计算先求两条边的方向角再相减能规避单条边斜率无穷大的情况比直接用余弦定理更稳定。站立时这个角度接近 170180 度半蹲降到约 100 度完整深蹲会到 70 度以下。注意这只是 2D 投影角度如果人侧对着摄像头或髋关节被遮挡数值会偏离所以计数逻辑里要留阈值缓冲。4.2 用 visibility 过滤不可靠关键点容易忽略的一个问题是身体部分出画后MediaPipe 仍可能给出外推坐标看起来正常但 visibility 掉得很低。不做过滤的话会出现人在画面外“凭空蹲了两下”的诡异计数。vis min(knee.visibility, hip.visibility, ankle.visibility) if vis 0.6: # 关键点不可靠跳过这一帧 return我会把髋、膝、踝三个关键点的 visibility 同时检查取最小值做判断。手部关键点的 visibility 波动更大阈值可以放宽到 0.5否则正常手势下也容易跳帧。4.3 三段式状态机计数避免阈值抖动直接对角度设阈值会有一个经典问题角度在阈值附近来回抖一次深蹲被数成三四次。解决方法是用状态机只有完整走完“站立 - 下蹲 - 站立”的序列才计数一次class SquatCounter: def __init__(self, down_th100, up_th160): self.down_th down_th self.up_th up_th self.state stand self.count 0 def update(self, knee_angle, visibility): if visibility 0.6: return self.count if self.state stand and knee_angle self.down_th: self.state squat elif self.state squat and knee_angle self.up_th: self.count 1 self.state stand return self.count counter SquatCounter() count counter.update(knee_angle, vis)这个逻辑的要点状态必须先进入 squat再回到 stand才计数一次。如果只蹲一半就站起来状态机不会错误累加。down_th 和 up_th 之间留了 60 度缓冲窗口比单阈值稳定得多。实际测试时完整深蹲的计数准确率能到九成以上但如果是半程深蹲、单侧发力这些变体需要单独调阈值。还有一种做法是加入时间窗口要求下蹲状态至少持续 3 帧才切换能进一步过滤噪声。4.4 把计数结果写进画面与 CSV 日志在帧上叠加文本可以让现场调试非常直观cv2.putText(frame, fSquat: {count}, (30, 60), cv2.FONT_HERSHEY_SIMPLEX, 1.5, (0, 255, 0), 2)为了后续标定阈值我会把每帧的角度和可见性写入 CSVwith open(angles.csv, w, newline) as f: writer csv.writer(f) writer.writerow([frame, knee_angle, visibility]) # 循环内 writer.writerow([frame_id, knee_angle, vis])导入到 Excel 里画出角度曲线能直观看到蹲下和站直的拐点再回来调 down_th、up_th 就不用靠感觉猜了。4.5 同一套逻辑移植到手臂动作深蹲用的膝角逻辑可以直接移植到手部动作只需要换关键点组合。比如做哑铃弯举使用肩、肘、腕三个点算肘关节角shoulder results.pose_landmarks.landmark[mp_holistic.PoseLandmark.LEFT_SHOULDER] elbow results.pose_landmarks.landmark[mp_holistic.PoseLandmark.LEFT_ELBOW] wrist results.pose_landmarks.landmark[mp_holistic.PoseLandmark.LEFT_WRIST] elbow_angle calc_angle(shoulder, elbow, wrist)站立放松时肘角约 170 度弯举到顶时约 3040 度。状态机里的 down_th 和 up_th 改成 45 和 150 即可复用。诀窍是任何动作只要抽象成“一个主关节的角度变化 一个状态机”就能套到 Holistic 的任意关键点上这也是这个库在快速原型阶段最好用的原因。5. 避坑与常见问题排查六个让我熬夜修的问题5.1 Python 3.12 装不上 mediapipe现象pip install mediapipe 直接提示找不到匹配的 wheel换镜像源也无济于事。原因MediaPipe 的二进制包更新滞后于 Python 小版本新解释器环境下没有对应新版的构建。解决回退到 Python 3.10 或 3.11用 Conda 单独建环境。检查是否安装成功时优先看 import mediapipe 是否报错而不是只盯 pip 输出。在项目里我习惯把 Python 版本写进 requirements.txt 的注释里避免后来接手的人在新环境上卡住。5.2 CPU 推理速度过慢视频像幻灯片现象普通笔记本跑摄像头实时流只有每秒三四帧画面严重滞后骨架一卡一卡的。原因默认输入分辨率可能是摄像头最大输出 1280x720 或更高再叠加 model_complexity2即使级联 ROI 也扛不住。解决先把输入画面缩到 640x480 再送入 process()。降低 model_complexity 到 1 或 0。若还卡砍掉面部网格绘制只保留 Pose 与手部。Holistic 的最佳应用边界是“够用就好”不是“最准就好”性能优化优先于参数调优。5.3 手部关键点频繁消失现象手伸到镜头前晃几下left_hand_landmarks 时有时无代码里一访问就报错。原因手部 ROI 依赖手腕 Pose 关键点手腕一抖或手部纹理不明显追踪就断光线偏暗时更严重。解决min_detection_confidence 调到 0.7min_tracking_confidence 保持 0.4 左右给追踪多一些容忍度。代码里对左右手始终做 None 判断不要在没检测到时直接访问 .landmark。打光均匀之后手部丢失概率会明显下降。5.4 左右手画出来是反的现象人举起右手画面上骨架却是左手手部坐标也和直觉相反。原因摄像头预览本身是镜像画面代码没有做水平翻转导致坐标左右互换。解决在送进 process() 之前先执行 frame cv2.flip(frame, 1) 再转 RGB。注意顺序一定不能反先翻转再转颜色空间。如果你用的是已经镜像过的视频流就不用再翻一次否则会二次镜像。5.5 smooth_landmarks 导致动作有延迟现象快速挥手、跳跃时骨架像被橡皮筋拉住跟不上实际动作。原因smooth_landmarks 对关键点做了时序平滑稳定性和响应速度天然互相制约。解决慢动作、瑜伽、需要展示的场合开 True快速运动识别、游戏交互开 False。如果要两头兼顾可以自己用一阶低通滤波做平滑把延迟控制在两帧以内。这个参数不是玄学它是响应速度与稳定性的直接取舍。5.6 画面里出现第二个人时关键点会跳人现象两个人先后走进画面骨架一会锁在这个人身上一会跳到另一个人身上。原因Holistic 内置的是单人体姿态模型多人时它只选择置信度最高的目标而选择策略在不同角度下会摇摆。解决限定单人进入感兴趣区域。简单做法是用 OpenCV 裁剪出一个矩形 ROI把画面外的人排除掉或者提示用户站在画面中央。如果项目必须支持多人就需要换用专门的多人姿态方案不要在 Holistic 上硬扛。6. 进阶技巧把 Holistic 关键点导出为 JSON接进自己的工具链当项目进入数据收集阶段我需要把每帧的关键点落盘方便后面做动作分类或回放。写一个通用转换函数import json def holistic_to_dict(results, frame_w, frame_h): def convert(lm_list): if not lm_list: return [] return [{ x: round(lm.x * frame_w, 2), y: round(lm.y * frame_h, 2), z: round(lm.z * frame_w, 2), v: round(lm.visibility, 3) } for lm in lm_list.landmark] return { pose: convert(results.pose_landmarks), face: convert(results.face_landmarks), left_hand: convert(results.left_hand_landmarks), right_hand: convert(results.right_hand_landmarks) }z 轴换算时用 frame_w 做缩放基准是因为 MediaPipe 的 z 值约以 x 为参照单位保持统一即可。保存时一帧一个 JSON 文件之后拿 Python 的 json 模块读回来就能复现动作曲线。如果要实时预览已保存的动作把 JSON 里的坐标乘回原图宽高画点就行。这个模块的结构很干净动作分类、阈值标定都可以直接消费这份数据我在模拟项目X里就用这套 JSON 做小样本动作分类省去和视频编解码打交道的时间。如果要做更高吞吐的实时应用另一个技巧是把 process() 挪到独立线程主线程只负责读帧和显示import threading, queue frame_queue queue.Queue(maxsize2) def inference_worker(): while True: item frame_queue.get() if item is None: break frame, frame_id item rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results holistic.process(rgb) data holistic_to_dict(results, frame.shape[1], frame.shape[0]) # 把 data 交给存储或计数逻辑 t threading.Thread(targetinference_worker, daemonTrue) t.start()这个做法的关键是用有界队列制造背压maxsize2 可以防止主线程无限塞帧把内存打爆。当时我把摄像头读帧和推理逻辑写在一个循环里分辨率一高就卡在 IO 上拆开之后帧率提升明显但要注意队列满时主动丢帧避免延迟越积越大。从那以后我每次拿到一段视频素材都先强制走一遍“小分辨率 JSON 导出”确认关键点有没有跟丢、角度曲线是否平滑再往下做业务逻辑。这个习惯帮我省了好几次返工希望帮到你。本文还有配套的精品资源点击获取