MediaPipe Hands Python调用hands.process()缺失multi_hand_world_landmarks报错

核心原因排查 #

1. 版本不匹配 #

multi_hand_world_landmarks 是MediaPipe 0.8.9版本才新增的返回字段，如果你本地安装的MediaPipe版本低于该版本，SolutionOutputs 类的定义中本身就没有这个字段，直接调用必然触发AttributeError。

• 排查命令：pip show mediapipe
• 修复命令：pip install --upgrade mediapipe

2. 未检测到有效手部 #

当输入图像中没有符合模型置信度阈值的手部时，返回结果会自动省略所有手部相关字段，包括multi_hand_landmarks、multi_hand_world_landmarks、multi_handedness三个字段都会同时不存在，并非只有世界坐标字段缺失。
访问前必须做存在性判断，示例代码：

import cv2
import mediapipe as mp

mp_hands = mp.solutions.hands
hands = mp_hands.Hands()

img = cv2.imread('test.jpg')
img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
results = hands.process(img_rgb)

# 先判断字段是否存在再访问
if results.multi_hand_world_landmarks:
    for landmarks in results.multi_hand_world_landmarks:
        # 处理3D世界坐标逻辑
        print(landmarks)

相关疑问澄清 #

该字段的返回不需要特殊图像背景，也不需要额外的深度输入。multi_hand_world_landmarks的3D米制坐标是模型内部根据2D关键点和通用手部比例推算得到的，只要版本正确、图像中检测到符合置信度的手部，就会正常返回。

内容的提问来源于stack exchange，提问作者Vladimir Ilyin