MediaPipe 手部追踪迁移：Hand Landmarker 完整落地指南

MediaPipe 手部追踪迁移Hand Landmarker 完整落地指南【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipeMediaPipe 手部追踪迁移是给还在用旧版Hands方案的开发者准备的2023 年 3 月MediaPipe 把 Hands 改名为 Hand Landmarker 并搬进 Tasks 架构旧接口不再演进。本文按改哪几处讲清升级路径并给出双平台能跑的代码。先判断要不要迁不迁会失去什么旧版mp.solutions.hands.Hands目前依然可用但它的功能上限已经封顶没有实时流模式拿不到分级的置信度控制也选不了高精度或轻量模型。Hand Landmarker 是mediapipe.tasks下的独立任务模块模型需要自己提供子图如何拆分可以看 模块目录。如果你的业务涉及摄像头实时流、或要按设备档位切换模型迁移基本是必选项如果只是离线跑静态图且代码稳定可以先不急着动。一张表看懂新旧 API 的 4 个改动位置要动手的位置旧 Hands API新 Hand Landmarkerimportmp.solutions.hands核心类Handsmediapipe.tasks.python.vision核心类HandLandmarker模型加载模型随 wheel 内置无需配置BaseOptions里显式传 .tflite 路径参数传递构造函数直接给static_image_mode、max_num_hands等填一个HandLandmarkerOptions对象再建实例结果处理process()同步返回配drawing_utils绘制IMAGE/VIDEO 同步返回HandLandmarkerResultLIVE_STREAM 走result_callback模型文件共两个hand_landmark_full.tflite高精度与hand_landmark_lite.tflite轻量构建清单见 BUILD 文件。最小改动迁移路径4 个动作一次改完升级依赖先锁定 MediaPipe ≥0.9.0Tasks 的 Python 接口从 0.9.0 开始提供先升级再动手pip install mediapipe --upgrade模型文件放哪显式指定 full 还是 lite新 API 不再内置模型需要自行下载对应 .tflite 放进工程目录。初始化前先断言路径别等运行时才报模型文件不存在import os model_path hand_landmark_full.tflite # 移动端建议换 hand_landmark_lite.tflite assert os.path.exists(model_path), f模型文件不存在: {model_path}换掉 Hands 的初始化换成 HandLandmarker下面这组是全文唯一一处完整的新旧对照注释里写了每处为什么改# 旧写法Hands import cv2 import mediapipe as mp hands mp.solutions.hands.Hands( # 旧类参数直接塞构造函数 static_image_modeFalse, max_num_hands2, min_detection_confidence0.5) results hands.process(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))# 新写法Hand Landmarker import mediapipe as mp from mediapipe.tasks import python from mediapipe.tasks.python import vision # 新 API 统一在 tasks.vision 下 base_options python.BaseOptions( model_asset_pathhand_landmark_full.tflite) # 为什么新 API 不带内置模型 options vision.HandLandmarkerOptions( base_optionsbase_options, running_modevision.RunningMode.VIDEO, # 为什么替代 static_image_mode num_hands2, min_hand_detection_confidence0.5) with vision.HandLandmarker.create_from_options(options) as landmarker: mp_image mp.Image(image_formatmp.ImageFormat.SRGB, datargb_image) results landmarker.detect_for_video( mp_image, timestamp_msts_ms) # 为什么视频模式必须带毫秒时间戳参数、方法的完整定义在 Python 实现里可以核对。参数逐个翻译阈值怎么对应static_image_mode→running_mode从布尔扩成 IMAGE / VIDEO / LIVE_STREAM 三选一。max_num_hands→num_hands含义不变。min_detection_confidence→min_hand_detection_confidence手部检测器置信度。min_tracking_confidence名字不变继续管跟踪稳定性。新增min_hand_presence_confidence手部存在阈值与上面两项配合控制稳定性。想一步把稳定性拉上来可以这样写options vision.HandLandmarkerOptions( base_optionsbase_options, min_hand_detection_confidence0.7, # 对应旧的 min_detection_confidence min_hand_presence_confidence0.7, # 新增手部存在阈值 min_tracking_confidence0.7) # 跟踪稳定性双平台落地Python 实时摄像头示例实时场景用 LIVE_STREAM 模式detect_async提交帧结果从result_callback回来。下面这段可直接运行import cv2 import mediapipe as mp from mediapipe.tasks import python from mediapipe.tasks.python import vision MODEL hand_landmark_full.tflite def on_result(result: vision.HandLandmarkerResult, image: mp.Image, timestamp_ms: int) - None: print(f{timestamp_ms} ms: 检测到 {len(result.hand_landmarks)} 只手) options vision.HandLandmarkerOptions( base_optionspython.BaseOptions(model_asset_pathMODEL), running_modevision.RunningMode.LIVE_STREAM, # 实时流必须用此模式 num_hands2, min_hand_detection_confidence0.5, result_callbackon_result) # LIVE_STREAM 模式必须给回调 landmarker vision.HandLandmarker.create_from_options(options) cap cv2.VideoCapture(0) t0 cv2.getTickCount() / cv2.getTickFrequency() while cap.isOpened(): ok, frame cap.read() if not ok: break rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) now_ms int((cv2.getTickCount() / cv2.getTickFrequency() - t0) * 1000) # 时间戳用真实流逝的毫秒数不能只自增 1 landmarker.detect_async( mp.Image(image_formatmp.ImageFormat.SRGB, datargb), now_ms) cv2.imshow(Hand Landmarker, cv2.flip(frame, 1)) if cv2.waitKey(5) 0xFF 27: break cap.release() cv2.destroyAllWindows()Android 侧记住三件事命名空间变化新类在com.google.mediapipe.tasks.vision包下类名HandLandmarker参考 Java 实现旧 Solutions 的调用方式不再适用。初始化方式与 Python 一致先构造含模型路径的 Options 对象再由 options 建实例.tflite 要打进 assets 资源。时间戳视频模式调用都要带毫秒时间戳跟踪器靠它关联前后帧iOS 侧对应的MPPHandLandmarker见 头文件在detectVideoFrame时同样要求传时间戳。自检清单交付前过一遍这 6 项 ✅模型路径真实存在且 full / lite 与目标平台匹配。running_mode与输入类型一致静态图 IMAGE、视频文件 VIDEO、摄像头 LIVE_STREAM。LIVE_STREAM 模式下已设置result_callback否则创建实例时校验直接失败。VIDEO 模式下每帧传入单调递增的毫秒时间戳。num_hands按业务上限设置别依赖默认值 1。低端设备上换了 lite 模型或把输入缩到 640×480 再送检。行动清单读完就可以做的 4 件事pip install mediapipe --upgrade把版本固定在 ≥0.9.0。下载 full/lite 两个模型用os.path.exists验证路径。代码里的Hands全部换成HandLandmarker参数按前面的映射逐项翻译。实时场景切到 LIVE_STREAM 加回调按清单逐条自测后再上线。Hand Landmarker 与人脸、姿态等任务共用同一套 Tasks 任务架构这套迁移打法可以直接平移到其他视觉模块上一次学会处处能用。【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考