企业官网建设流程全解析

MediaPipe手部追踪迁移指南：从Hands到Hand Landmarker

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe

帮同事接摄像头做手部追踪，一跑就报 ModuleNotFoundError——他还在调老的 mp.solutions.hands 接口，而 MediaPipe 新版已经用 Hand Landmarker 把它替代了。这次迁移其实没那么大动静。

旧接口为啥退休了

老 Hands 是个"遗留方案"：模型内置在包里，参数就是构造函数那几个字段，想换个轻量模型、或者塞个自己训练的手部模型进去，基本没门。所以官方从 2023 年 3 月起把整个 Hands 解决方案标记为 Legacy，换成了任务化的 Hand Landmarker。变化主要在创建方式上：模型文件要显式传入，运行模式可选 IMAGE / VIDEO / LIVE_STREAM 三种。老接口只能同步等结果，新接口在实时流模式下还支持异步回调，这是老接口完全没有的能力。迁移背景的详细官方说明在 docs/solutions/hands.md 里，想确认版本线可以看一眼。

MediaPipe 手部追踪新旧参数速查 📦

• 核心类：Hands → HandLandmarker
• 导入路径：改成 tasks.python.vision
• max_num_hands → num_hands
• 检测置信度改名 min_hand_detection_confidence
• static_image_mode → running_mode（三选一）
• 模型不再内置，必须传 .tflite 路径

差异没想象中多，真正要改的就下面这几行。

改这两段就能跑 🔧

先说模型文件。子图定义在仓库 mediapipe/modules/hand_landmark/ 目录下，但模型文件本身不在仓库里，hand_landmark_full.tflite 要从官方模型资源页拿，下载链接就在上面提到的 hands.md 里，放到脚本旁边就行。注意新接口不读包内内置模型，不传路径会直接报错。

再说代码。老接口是"实例化就能 process"，新接口是"先给选项再创建"，要动的只有创建这一环。

# 改前：老 Hands 接口 import cv2, mediapipe as mp hands = mp.solutions.hands.Hands(max_num_hands=2) res = hands.process(frame_rgb) pts = res.multi_hand_landmarks

# 改后：Hand Landmarker 接口 from mediapipe.tasks import python from mediapipe.tasks.python import vision opts = vision.HandLandmarkerOptions( base_options=python.BaseOptions( model_asset_path="hand_landmark_full.tflite"), num_hands=2) lm = vision.HandLandmarker.create_from_options(opts) res = lm.detect(mp.Image(image_format=mp.ImageFormat.SRGB, data=frame_rgb)) pts = res.hand_landmarks

前后输入都是 RGB 图、输出都是关键点列表，后面的绘制代码一行不用动。关键点坐标是 0–1 的归一化值，画图时记得乘图像宽高。如果是视频帧场景，把 detect 换成 detect_for_video 并传入 timestamp_ms；要接实时摄像头，就把 running_mode 设为 LIVE_STREAM 并给出 result_callback，结果通过回调回来，不阻塞主循环。每个字段的默认值和含义都写在 mediapipe/tasks/python/vision/hand_landmarker.py 的 docstring 里，记不住参数名先翻它。

手抖了怎么办 👆

• 关键点抖动 → min_tracking_confidence 0.5 拉到 0.7
• 手时有时无 → min_hand_presence_confidence 0.5 拉到 0.7
• 第二只手抓不全 → num_hands 给 2，检测阈值降到 0.4

这三个阈值都挂在 HandLandmarkerOptions 上，改完重建实例就生效，不用动模型。

下一步：换自己训练的手部模型，搓一个手势控制器。

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe