MediaPipe 手部追踪 API 迁移完整指南：从 Hands 到 Hand Landmarker 的 4 个关键问题

MediaPipe 手部追踪 API 迁移完整指南从 Hands 到 Hand Landmarker 的 4 个关键问题【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipeMediaPipe 从 0.9.0 版本起把手部追踪能力从旧的mediapipe.solutions.hands方案整体迁到了新架构的 Hand Landmarker 任务上。对还在跑老版代码的人来说这次升级不像文档里写的那样顺滑模型不再内置、参数全部改名、运行方式也变了。这篇分享来自一次真实的迁移过程按动手时踩到的四个问题逐个拆解每个问题配了可以直接抄的写法。问题一模型文件去哪儿了老版Hands的模型打包在 wheel 里创建实例就能用。新版 Hand Landmarker 把模型加载的责任交给了开发者不显式给路径就起不来。这一步的报错信息很直白本质就一句话你需要自己准备一个.tflite文件并塞进BaseOptions。仓库里就有现成模型位于 mediapipe/modules/hand_landmark/ 目录下按精度分两档hand_landmark_full.tflite高精度版桌面端和精度敏感场景用它hand_landmark_lite.tflite轻量版适合手机端这类资源受限环境。环境准备一段搞定模型从仓库里取pip install mediapipe --upgrade git clone https://gitcode.com/GitHub_Trending/med/mediapipe拿不准路径对不对时先用os.path.exists断言一下比对着报错日志猜快得多import os model_path mediapipe/modules/hand_landmark/hand_landmark_full.tflite assert os.path.exists(model_path), f模型文件不存在: {model_path}问题二参数名对不上逐个对照第二个卡点是配置方式变了老版用构造函数直接传参新版要求先构造一个HandLandmarkerOptions对象。参数也不是简单改名有几项被拆分或新增逐个对照如下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_tracking_confidence。名字没变含义是跟踪成功所需的最低分数无对应项 →min_hand_presence_confidence。全新参数控制手部存在判定默认值在 hand_landmarker.py 的HandLandmarkerOptions里可以查到。问题三三种运行模式怎么选running_mode是新版最容易选错的参数三种模式对应三种输入节奏IMAGE一次一张静态图处理完即走。HandLandmarkerOptions的默认值就是它VIDEO逐帧喂视频解码帧必须传时间戳timestamp_ms结果同步返回LIVE_STREAM对接摄像头等实时流要求设置result_callback回调异步收结果创建时不传回调会直接校验失败。迁移时按输入源对号入座图片批处理用IMAGE本地视频文件用VIDEO在线流用LIVE_STREAM。老代码里的static_image_modeFalse大致等价于VIDEOTrue则对应IMAGE。问题四最小可运行示例长什么样下面是一组新旧写法对照老写法用来确认你要替换的对象新写法是一个能独立跑起来的最小示例。旧版 Hand Trackingimport cv2 import mediapipe as mp mp_hands mp.solutions.hands with mp_hands.Hands( static_image_modeFalse, max_num_hands2, min_detection_confidence0.5) as hands: results hands.process(cv2.cvtColor(image, cv2.COLOR_BGR2RGB)) if results.multi_hand_landmarks: for hand_landmarks in results.multi_hand_landmarks: mp.solutions.drawing_utils.draw_landmarks( image, hand_landmarks, mp_hands.HAND_CONNECTIONS)新版 Hand Landmarkerimport cv2 import mediapipe as mp from mediapipe.tasks import python from mediapipe.tasks.python import vision base_options python.BaseOptions( model_asset_pathmediapipe/modules/hand_landmark/hand_landmark_full.tflite) options vision.HandLandmarkerOptions( base_optionsbase_options, running_modevision.RunningMode.VIDEO, num_hands2, min_hand_detection_confidence0.5) with vision.HandLandmarker.create_from_options(options) as landmarker: mp_image mp.Image(image_formatmp.ImageFormat.SRGB, dataimage) results landmarker.detect_for_video(mp_image, timestamp_ms100) for hand_landmarks in results.hand_landmarks: for landmark in hand_landmarks: x int(landmark.x * image.shape[1]) y int(landmark.y * image.shape[0]) cv2.circle(image, (x, y), 5, (0, 255, 0), -1)两个细节值得留意一是新版的坐标是归一化的画点前要手动乘回像素尺寸二是实时流场景下把running_mode换成LIVE_STREAM用detector.detect_async(mp_image, timestamp)替代同步调用并在HandLandmarkerOptions里挂上result_callback即可。收尾迁移完成后的检查清单改完别急着合代码过一遍这几项再交付MediaPipe 版本已升到 0.9.0 及以上pip show mediapipe确认模型文件路径存在且full/lite选对了档位输入是图片、视频帧还是实时流running_mode与之匹配老代码里用到的每个阈值检测、跟踪、存在性都已在新选项中找到对应项特别是新增的min_hand_presence_confidence归一化坐标已按图像宽高还原成像素坐标用同一段测试视频对比新旧两版的关键点输出抖动和丢帧情况可接受。如果后续要继续深入可以翻一下 docs/solutions/hands.md 里对掌心检测 关键点预测这条两级流水线的描述理解跟踪策略后调参就不会只靠试错了。【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考