MediaPipe：谷歌的跨平台 ML 管道框架

bash pip install mediapipe

对于需要 GPU 支持的场景（当前主要为 Android/iOS/Web），Python 版本默认使用 CPU 推理，已足够满足多数桌面实时应用。若需在 Python 中启用 GPU 加速，可参考官方文档构建自定义库。

**验证安装：**
```python
import mediapipe as mp
print(mp.__version__)

如果你使用的是 Jupyter Notebook 或 Google Colab，可以通过 !pip install mediapipe 直接安装。注意：在某些 Notebook 环境中显示摄像头画面需要额外处理。

核心概念：图、计算器与数据包

理解 MediaPipe 的三大部件是高效开发的基础。

• 图 (Graph)：定义计算任务的拓扑结构，采用 Protocol Buffer 格式描述。MediaPipe 内置了多种标准图，如 HandTracking、PoseLandmarker。
• 计算器 (Calculator)：图中的每个节点，负责特定操作（如“图像缩放”、“模型推理”、“后处理”）。MediaPipe 提供了数百个预置计算器，例如 ImageCroppingCalculator、TfLiteInferenceCalculator。
• 数据包 (Packet)：沿图的边传输的时间序列数据，携带一个时间戳。数据类型可以是图像帧（ImageFrame）、归一化座标（NormalizedRect）、分类结果等。

运行机制：

1. 输入流（如摄像头帧）被打包为 Packet，送入图。
2. 调度器按拓扑顺序唤醒计算器，每收到一个 Packet 就执行一次处理。
3. 输出流收集最终结果，返回给应用。

这种设计天然支持多流同步（例如同时处理视频和音频），并能自动进行时间对齐。

实战：第一个手部关键点检测程序

我们以官方最受欢迎的 手部 Landmark 检测 为例，仅需十多行代码即可实时追踪 21 个 3D 手部关键点。

1. 导入库并初始化

import cv2
import mediapipe as mp

mp_hands = mp.solutions.hands
hands = mp_hands.Hands(
    static_image_mode=False,        # 输入为视频流
    max_num_hands=2,                # 最多检测两只手
    min_detection_confidence=0.7,   # 检测置信度阈值
    min_tracking_confidence=0.5     # 跟踪置信度阈值
)
mp_draw = mp.solutions.drawing_utils

2. 打开摄像头，处理每一帧

cap = cv2.VideoCapture(0)

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

    # BGR 转 RGB（MediaPipe 需要 RGB 输入）
    rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
    results = hands.process(rgb_frame)

    # 绘制检测结果
    if results.multi_hand_landmarks:
        for hand_landmarks in results.multi_hand_landmarks:
            # 绘制骨骼连线
            mp_draw.draw_landmarks(frame, hand_landmarks, mp_hands.HAND_CONNECTIONS)
            # 可自定义在每个关键点显示坐标
            for id, lm in enumerate(hand_landmarks.landmark):
                h, w, c = frame.shape
                cx, cy = int(lm.x * w), int(lm.y * h)
                cv2.circle(frame, (cx, cy), 5, (255,0,0), cv2.FILLED)

    cv2.imshow('Hand Tracking', frame)
    if cv2.waitKey(5) & 0xFF == 27:  # 按 ESC 退出
        break

cap.release()
cv2.destroyAllWindows()

代码解读：

• static_image_mode=False 会启用跟踪模型，在连续视频中更快更稳。
• landmarks 包含 21 个关键点的 x、y、z 坐标（归一化到 [0,1]），可直接映射回原图尺寸。
• 连接信息 HAND_CONNECTIONS 定义了手指骨骼的绘制顺序。
• 每只手还会提供 handedness 判断是左手还是右手。

进阶：理解其他预置模块

MediaPipe 不仅支持手部，还提供了一系列可直接使用的任务API。以下简要列出常用模块名称及用途，替换核心代码即可切换任务。

使用方式高度统一：

mp_pose = mp.solutions.pose
pose = mp_pose.Pose(min_detection_confidence=0.5, min_tracking_confidence=0.5)
result = pose.process(rgb_image)
if result.pose_landmarks:
    mp.solutions.drawing_utils.draw_landmarks(image, result.pose_landmarks, mp_pose.POSE_CONNECTIONS)