MediaPipe项目中HandLandmarker与draw_landmarks的兼容性问题解析

问题背景

在使用MediaPipe的HandLandmarker进行手部关键点检测时，开发者可能会遇到一个常见问题：当尝试使用draw_landmarks函数可视化检测结果时，程序会抛出错误。这个问题主要出现在MacOS系统上，使用Python语言开发时。

问题现象

开发者在使用HandLandmarker检测手部关键点后，尝试使用draw_landmarks函数绘制检测结果时，会遇到两种不同类型的错误：

1. 第一种错误提示"AttributeError: 'list' object has no attribute 'landmark'"
2. 第二种错误提示"AttributeError: 'Landmark' object has no attribute 'HasField'"

这些错误表明，HandLandmarker返回的结果格式与draw_landmarks函数期望的输入格式不兼容。

问题根源

经过分析，这个问题主要有两个原因：

1. API版本不匹配：MediaPipe的任务API（Tasks API）和解决方案API（Solutions API）使用了不同的数据结构格式。HandLandmarker属于较新的任务API，而draw_landmarks函数最初是为解决方案API设计的。

2. Protobuf版本冲突：MediaPipe 0.10.11版本与Protobuf 5.x版本存在兼容性问题，导致数据类型转换失败。

解决方案

1. 正确的数据转换方法

要解决这个问题，需要将HandLandmarker返回的结果转换为draw_landmarks能够识别的格式。以下是推荐的解决方案：

from mediapipe import solutions
from mediapipe.framework.formats import landmark_pb2

def draw_landmarks_on_image(rgb_image, detection_result):
    hand_landmarks_list = detection_result.hand_landmarks
    annotated_image = np.copy(rgb_image)

    for idx in range(len(hand_landmarks_list)):
        hand_landmarks = hand_landmarks_list[idx]
        
        hand_landmarks_proto = landmark_pb2.NormalizedLandmarkList()
        hand_landmarks_proto.landmark.extend([
            landmark_pb2.NormalizedLandmark(x=landmark.x, y=landmark.y, z=landmark.z) 
            for landmark in hand_landmarks
        ])
        
        solutions.drawing_utils.draw_landmarks(
            annotated_image,
            hand_landmarks_proto,
            solutions.hands.HAND_CONNECTIONS,
            solutions.drawing_styles.get_default_hand_landmarks_style(),
            solutions.drawing_styles.get_default_hand_connections_style()
        )
    
    return annotated_image

2. 版本兼容性调整

如果上述方法仍然出现问题，可以尝试以下版本组合：

1. 降级MediaPipe到0.10.9版本，同时使用Protobuf 3.x
2. 升级到MediaPipe 0.10.10或0.10.11版本，同时使用Protobuf 5.x

完整示例代码

以下是经过验证可用的完整代码示例：

import cv2
import numpy as np
from mediapipe import Image, ImageFormat
from mediapipe.tasks.python.vision import HandLandmarker, HandLandmarkerOptions, RunningMode
from mediapipe.tasks.python import BaseOptions
from mediapipe import solutions
from mediapipe.framework.formats import landmark_pb2

def draw_landmarks_on_image(rgb_image, detection_result):
    hand_landmarks_list = detection_result.hand_landmarks
    annotated_image = np.copy(rgb_image)

    for idx in range(len(hand_landmarks_list)):
        hand_landmarks = hand_landmarks_list[idx]
        
        hand_landmarks_proto = landmark_pb2.NormalizedLandmarkList()
        hand_landmarks_proto.landmark.extend([
            landmark_pb2.NormalizedLandmark(x=landmark.x, y=landmark.y, z=landmark.z) 
            for landmark in hand_landmarks
        ])
        
        solutions.drawing_utils.draw_landmarks(
            annotated_image,
            hand_landmarks_proto,
            solutions.hands.HAND_CONNECTIONS,
            solutions.drawing_styles.get_default_hand_landmarks_style(),
            solutions.drawing_styles.get_default_hand_connections_style()
        )
    
    return annotated_image

# 配置HandLandmarker
base_options = BaseOptions(model_asset_path='hand_landmarker.task')
options = HandLandmarkerOptions(
    base_options=base_options,
    num_hands=2,
    min_hand_detection_confidence=0.1,
    min_tracking_confidence=0.1,
    running_mode=RunningMode.IMAGE
)
detector = HandLandmarker.create_from_options(options)

# 初始化摄像头
cap = cv2.VideoCapture(0)
if not cap.isOpened():
    print("无法打开摄像头")
    exit(1)

while True:
    success, frame = cap.read()
    if not success:
        break

    frame = cv2.flip(frame, 1)
    rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)

    # 处理图像
    mp_image = Image(image_format=ImageFormat.SRGB, data=rgb_frame)
    results = detector.detect(mp_image)

    # 绘制关键点
    if results:
        annotated_image = draw_landmarks_on_image(mp_image.numpy_view(), results)
        bgr_frame = cv2.cvtColor(annotated_image, cv2.COLOR_RGB2BGR)
        cv2.imshow("手部关键点检测", bgr_frame)

    if cv2.waitKey(1) & 0xFF == 27:  # ESC键退出
        break

cap.release()
cv2.destroyAllWindows()

总结

在使用MediaPipe进行手部关键点检测时，开发者需要注意新旧API之间的兼容性问题。通过正确转换数据类型和选择合适的版本组合，可以顺利实现手部关键点的检测和可视化。这个问题也提醒我们，在使用开源库时，要特别注意不同版本之间的兼容性，特别是在涉及数据序列化和反序列化的情况下。