mediapipe-usage

用途

本技能用于指导在 Web 环境使用 Google MediaPipe Pose Landmarker，依赖 @mediapipe/tasks-vision 库（来自 liuchiawei/agent-skills，技能标识 mediapipe-usage）。主要面向需要在浏览器中实现姿态地标检测的场景，例如单张图片分析或摄像头视频流的实时检测。

主要能力

安装与加载：通过 pnpm 安装 @mediapipe/tasks-vision，并在创建任务时从 CDN 解析 WASM。
创建姿态地标任务：使用 PoseLandmarker.createFromOptions(vision, options)，可配置 modelAssetPath（模型资源路径）、delegate（如 GPU，GPU 不可用时回退 CPU）、runningMode（IMAGE 或 VIDEO）、numPoses、minPoseDetectionConfidence、minPosePresenceConfidence、minTrackingConfidence 等。
运行模式：IMAGE 模式用于单张图片，调用 detect(image)；VIDEO 模式用于视频流，调用 detectForVideo(video, timestamp)。
结果结构：result.landmarks 为姿态数组，每个人为 33 个 NormalizedLandmark，含 x、y、z（归一化 0–1，z 为相对髋部中心的深度）与 visibility（0–1）；result.worldLandmarks 为可选的以米为单位的 3D 坐标，索引相同。单人场景使用 result.landmarks[0]。

使用方式

安装（推荐 pnpm）：

pnpm add @mediapipe/tasks-vision

解析 WASM：

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

创建 Pose Landmarker：

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, // 参见 reference.md 中的 lite/full/heavy URL
    delegate: "GPU", // 不可用时回退 CPU
  },
  runningMode: "VIDEO", // 单张图片用 "IMAGE"
  numPoses: 1,
  minPoseDetectionConfidence: 0.5,
  minPosePresenceConfidence: 0.5,
  minTrackingConfidence: 0.5,
});

运行（单张图片，runningMode 为 IMAGE）：

const result = poseLandmarker.detect(imageElement);

运行（视频/摄像头，runningMode 为 VIDEO）：在 requestAnimationFrame 循环中调用 detectForVideo(video, timestamp)，并按时间节流（例如帧间约 33ms）以避免过多计算：

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]; // 第一个人
      // 使用 landmarks
    }
  }
  requestAnimationFrame(detectLoop);
}
requestAnimationFrame(detectLoop);

实践模式

状态机：idle → loading（加载模型）→ ready（可开始）→ active（摄像头 + 检测）→ error。切换模型变体时，先关闭旧的 PoseLandmarker 实例再新建。
节流：仅当 performance.now() - lastFrameTime > 33（约 30 fps）时执行 detectForVideo，避免阻塞主线程。
平滑：对派生值（如俯仰、倾斜）应用平滑系数（如 0.3）减少抖动；使用死区（以度为单位）忽略微小移动。
置信度：使用每个地标的 visibility，忽略或降权低于阈值的点；辅助函数 getLandmark(landmarks, index, minConfidence) 仅当 visibility >= minConfidence 时返回该点。
手势：例如“双手前伸”可比较肩部与手腕的 z；“双手过顶”可比较手腕 y 与肩部 y。使用连续帧计数器实现开关（例如需要连续 N 帧处于某姿态才触发动作）。

清理

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

限制与缺失信息

资料未提供具体模型文件 URL、33 个地标索引与骨架连接细节、最小示例、骨架叠加、地标到控制的映射，这些需查阅 reference.md 与 examples.md。官方文档指向 Pose Landmarker Web JS 与 Web 设置指南。资料中未提及收费、价格、平台限制或其他未列出的功能。

技能介绍

用途

主要能力

使用方式

实践模式

清理

限制与缺失信息