mediapipe-usage

Google MediaPipe 用法（Web / Pose Landmarker）

快速开始

1. 安装 @mediapipe/tasks-vision，从 CDN 加载 WASM
2. 使用 createFromOptions 创建 PoseLandmarker
3. 单张图像使用 detect()，视频流则在经过限流的 requestAnimationFrame 循环中使用 detectForVideo()

设置

安装（建议使用 pnpm）：

pnpm add @mediapipe/tasks-vision

**WASM 根目录：**创建任务时从 CDN 加载 vision tasks：

const vision = await FilesetResolver.forVisionTasks(
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm",
);

创建 Pose Landmarker 任务

使用 PoseLandmarker.createFromOptions(vision, options)：

import { PoseLandmarker, FilesetResolver } from "@mediapipe/tasks-vision";

const vision = await FilesetResolver.forVisionTasks(
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm",
);

const poseLandmarker = await PoseLandmarker.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: modelUrl, // see reference.md for lite/full/heavy URLs
    delegate: "GPU", // falls back to CPU if unavailable
  },
  runningMode: "VIDEO", // or "IMAGE" for single image
  numPoses: 1,
  minPoseDetectionConfidence: 0.5,
  minPosePresenceConfidence: 0.5,
  minTrackingConfidence: 0.5,
});

• runningMode：单张图像使用 IMAGE → 调用 detect(image)。视频流使用 VIDEO → 调用 detectForVideo(video, timestamp)。
• baseOptions.modelAssetPath：.task 模型的 URL（lite / full / heavy）。URL 见 reference.md。
• delegate：优先使用 "GPU"；某些环境会回退到 CPU。

运行任务

单张图像（runningMode IMAGE）：

const result = poseLandmarker.detect(imageElement);

视频 / 网络摄像头（runningMode VIDEO）：

在 requestAnimationFrame 循环中调用 detectForVideo(video, timestamp)。按时间限流（例如每帧间隔约 33 ms），以避免过度处理：

let lastFrameTime = 0;
function detectLoop() {
  const now = performance.now();
  if (video.readyState >= 2 && now - lastFrameTime > 33) {
    lastFrameTime = now;
    const result = poseLandmarker.detectForVideo(video, now);
    if (result.landmarks?.length) {
      const landmarks = result.landmarks[0]; // first person
      // use landmarks
    }
  }
  requestAnimationFrame(detectLoop);
}
requestAnimationFrame(detectLoop);

结果结构

• result.landmarks：姿势数组；每个姿势都是 NormalizedLandmark[]（33 个点）。每个关键点包含：x、y、z（归一化值 0–1；z 表示相对于髋部中心的深度）、visibility（0–1）。
• result.worldLandmarks：可选的以米为单位的 3D 坐标（索引相同）。
• 单人场景：使用 result.landmarks[0]。

实用模式（经验技巧）

• 状态机：idle → loading（加载模型）→ ready（可以启动）→ active（网络摄像头 + 检测）→ error。切换模型变体时，关闭旧的 PoseLandmarker 实例并创建新实例。
• 限流：仅当 performance.now() - lastFrameTime > 33 时运行 detectForVideo（约 30 fps），以避免阻塞主线程。
• 平滑处理：对派生值（pitch、bank）应用平滑系数（例如 0.3）以减少抖动；使用死区（以度为单位）忽略微小移动。
• 置信度：使用每个关键点的 visibility；忽略或降低低于阈值的点的权重。辅助函数：getLandmark(landmarks, index, minConfidence)，仅在 visibility >= minConfidence 时返回该点。
• 手势：例如，“双手向前” = 比较肩部与手腕的 z 值；“双手举过头顶” = 比较手腕与肩部的 y 值。使用连续帧计数器控制切换（例如，姿势保持 N 帧后才触发操作）。

清理

• 停止网络摄像头：stream.getTracks().forEach(t => t.stop())。
• 释放任务：完成后或创建新实例前调用 poseLandmarker.close()。

更多资源

• 完整的 33 个关键点索引和骨架连接见 reference.md
• 最小示例、骨架叠加和关键点到控制项的映射见 examples.md
• 官方文档：Pose Landmarker Web JS、Web 设置指南