このページは Cloud Translation API によって翻訳されました。

手のランドマーク検出ガイド（ウェブ用）

MediaPipe の手のランドマークタスクでは、画像内の手のランドマークを検出できます。ここでは、ウェブアプリと JavaScript アプリで手のランドマークツールを使用する方法について説明します。

このタスクの機能、モデル、構成オプションの詳細については、概要をご覧ください。

サンプルコード

ご参考までに、手のランドマークツールのサンプルコードは、このタスクの完全な実装を JavaScript で実現しています。このコードは、このタスクをテストし、独自の手のランドマーク検出アプリの作成を開始する際に役立ちます。ウェブブラウザを使用して、手のランドマークのサンプルコードを表示、実行、編集できます。

セットアップ

このセクションでは、特に手のランドマークツールを使用するための開発環境をセットアップする主な手順について説明します。プラットフォームのバージョン要件など、ウェブと JavaScript の開発環境の設定に関する一般的な情報については、ウェブの設定ガイドをご覧ください。

JavaScript パッケージ

手のランドマークコードは MediaPipe @mediapipe/tasks-vision NPM パッケージから入手できます。これらのライブラリは、プラットフォームの設定ガイドの手順に沿って検索してダウンロードできます。

必要なパッケージは、次のコマンドを使用して NPM でインストールできます。

npm install @mediapipe/tasks-vision

コンテンツ配信ネットワーク（CDN）サービスを介してタスクコードをインポートする場合は、HTML ファイルの <head> タグに次のコードを追加します。

<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
    crossorigin="anonymous"></script>
</head>

モデル

MediaPipe Hand Landscapeer タスクには、このタスクと互換性のあるトレーニング済みモデルが必要です。手のランドマーク用のトレーニング済みモデルの詳細については、タスクの概要のモデルセクションをご覧ください。

モデルを選択してダウンロードし、プロジェクトディレクトリに保存します。

<dev-project-root>/app/shared/models/

タスクを作成する

手のランドマークの createFrom...() 関数のいずれかを使用して、推論を実行するタスクを準備します。トレーニング済みモデルファイルへの相対パスまたは絶対パスを指定して、createFromModelPath() 関数を使用します。モデルがすでにメモリに読み込まれている場合は、createFromModelBuffer() メソッドを使用できます。

次のコード例は、createFromOptions() 関数を使用してタスクをセットアップする方法を示しています。createFromOptions 関数を使用すると、構成オプションを使用してハンドランドマークャーをカスタマイズできます。構成オプションの詳細については、構成オプションをご覧ください。

次のコードは、カスタムオプションを使用してタスクをビルドして構成する方法を示しています。

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "hand_landmarker.task"
      },
      numHands: 2
    });

構成オプション

このタスクには、ウェブアプリケーションと JavaScript アプリケーション用の次の構成オプションがあります。

オプション名	説明	値の範囲	デフォルト値
`runningMode`	タスクの実行モードを設定します。モードは 2 つあります。 IMAGE: 単一の画像入力のモード。 VIDEO: 動画のデコードされたフレーム、または入力データのライブストリーム（カメラなど）のモード。	{`IMAGE, VIDEO`}	`IMAGE`
`numHands`	手のランドマーク検出機能で検出される手の最大数。	`Any integer > 0`	`1`
`minHandDetectionConfidence`	手のひら検出モデルで手の検出が成功したとみなすための最小信頼スコア。	`0.0 - 1.0`	`0.5`
`minHandPresenceConfidence`	手のランドマーク検出モデルにおける手の存在スコアの最小信頼スコア。動画モードとライブストリームモードでは、手のランドマークモデルからの手の存在信頼スコアがこのしきい値を下回った場合、手のひら検出モデルがトリガーされます。それ以外の場合は、軽量のハンドトラッキングアルゴリズムが、後続のランドマーク検出で使用する手の位置を決定します。	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	成功とみなされる、ハンドトラッキングの最小信頼スコア。これは、現在のフレームと最後のフレームの手の間の境界ボックスの IoU しきい値です。手のマーカーの動画モードとストリームモードでは、トラッキングが失敗すると、手のマーカーが手の検出をトリガーします。それ以外の場合は、手の検出はスキップされます。	`0.0 - 1.0`	`0.5`

データの準備

手のランドマークは、ホストブラウザでサポートされている任意の形式の画像内の手のランドマークを検出できます。このタスクは、サイズ変更、回転、値の正規化など、データ入力の前処理も処理します。動画から手のランドマークを検出するには、API を使用して一度に 1 フレームずつすばやく処理し、フレームのタイムスタンプを使用して、動画内で手のランドマークがいつ発生したかを判断します。

タスクを実行する

手のランドマークツールは、detect()（実行モード image）と detectForVideo()（実行モード video）のメソッドを使用して推論をトリガーします。このタスクはデータを処理し、手のランドマークの検出を試み、その結果を報告します。

手のランドマークの detect() メソッドと detectForVideo() メソッドの呼び出しは同期的に実行され、ユーザーインターフェースのスレッドをブロックします。デバイスのカメラからの動画フレームから手のランドマークが検出されると、検出が行われるたびにメインスレッドがブロックされます。これを防ぐには、ウェブワーカーを実装して detect() メソッドと detectForVideo() メソッドを別のスレッドで実行します。

次のコードは、タスクモデルを使用して処理を実行する方法を示しています。

画像

const image = document.getElementById("image") as HTMLImageElement;
const handLandmarkerResult = handLandmarker.detect(image);

動画

await handLandmarker.setOptions({ runningMode: "video" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const detections = handLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

手のランドマークタスクの実行の完全な実装については、コードサンプルをご覧ください。

結果を処理して表示する

手のランドマークは、検出の実行ごとに手のランドマークの結果オブジェクトを生成します。結果オブジェクトには、画像座標に手のランドマーク、世界座標に手のランドマーク、検出された手の利き手（左手と右手）が含まれます。

このタスクからの出力データの例を次に示します。

HandLandmarkerResult の出力には、3 つのコンポーネントが含まれます。各コンポーネントは配列です。各要素には、検出された 1 つの手について、次の結果が含まれます。

利き手

利き手は、検出された手が左手か右手かを表します。
ランドマーク

21 個の手のランドマークがあり、それぞれ x、y、z 座標で構成されています。x 座標と y 座標は、それぞれ画像の幅と高さによって [0.0, 1.0] に正規化されます。z 座標はランドマークの深さを表し、手首の深度を原点とします。値が小さいほど、ランドマークがカメラに近くなります。z の大きさは、x とほぼ同じスケールを使用します。
世界の名所

21 の手のランドマークも世界座標で表示されます。各ランドマークは x、y、z で構成され、手の幾何学的中心を原点とする実際の 3D 座標をメートル単位で表します。

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : -3.41E-7
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
    ... (21 landmarks for a hand)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
    ... (21 world landmarks for a hand)

次の図は、タスク出力を可視化したものです。

手のランドマークのサンプルコードは、タスクから返された結果を表示する方法を示しています（コードサンプルを参照）。