mediapipe-usage

Google MediaPipe の使い方（Web／Pose Landmarker）

クイックスタート

1. @mediapipe/tasks-vision をインストールし、WASM を CDN から解決します
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 モデル（lite／full／heavy）の URL です。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 座標です（任意、インデックスは同じです）。
• 1 人の場合は result.landmarks[0] を使用します。

実用的なパターン（ノウハウ）

• 状態マシン：idle → loading（モデルを読み込み）→ ready（開始可能）→ active（ウェブカメラ＋検出）→ error。モデルの種類を切り替えるときは、古い PoseLandmarker インスタンスを閉じてから新しいものを作成します。
• スロットル：メインスレッドのブロックを避けるため、performance.now() - lastFrameTime > 33（約 30 fps）の場合にのみ detectForVideo を実行します。
• 平滑化：ジッターを軽減するため、派生値（pitch、bank）に平滑化係数（例：0.3）を適用します。小さな動きを無視するには、デッドゾーン（角度単位）を使用します。
• 信頼度：各ランドマークの visibility を使用し、しきい値を下回る点は無視するか、重みを下げます。ヘルパー：getLandmark(landmarks, index, minConfidence) は、visibility >= minConfidence の場合にのみ点を返します。
• ジェスチャー：例：「手を前に出す」は肩と手首の z を比較し、「手を頭上に上げる」は手首の y と肩の y を比較します。切り替え操作には連続フレームカウンターを使用します（例：アクションを実行する前に、ポーズを N フレーム維持することを要求します）。

クリーンアップ

• ウェブカメラを停止する：stream.getTracks().forEach(t => t.stop())。
• タスクを解放する：処理が完了したとき、または新しいインスタンスを作成する前に poseLandmarker.close() を呼び出します。

追加リソース

• 33 個のランドマークの全インデックスとスケルトンの接続については、reference.md を参照してください
• 最小限のサンプル、スケルトンのオーバーレイ、ランドマークから操作へのマッピングについては、examples.md を参照してください
• 公式ドキュメント：Pose Landmarker Web JS、Web 用セットアップガイド