ウェブ用ジェスチャー認識ガイド

MediaPipe Gesture Recognizer タスクを使用すると、ハンド ジェスチャーをリアルタイムで認識し、認識されたハンド ジェスチャーの結果と、検出された手のハンドマークを取得できます。ここでは、ウェブアプリと JavaScript アプリで Gesture Recognizer を使用する方法について説明します。

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

サンプルコード

ジェスチャー認識ツールのサンプルコードには、このタスクの完全な 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.mjs"
    crossorigin="anonymous"></script>
</head>

モデル

MediaPipe ジェスチャー認識ツールタスクには、このタスクと互換性のあるトレーニング済みモデルが必要です。ジェスチャー認識ツールで使用可能なトレーニング済みモデルの詳細については、タスクの概要のモデルのセクションをご覧ください。

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

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

タスクを作成する

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

次のコード例は、createFromOptions() 関数を使用してタスクを設定する方法を示しています。createFromOptions 関数を使用すると、構成オプションでジェスチャー認識ツールをカスタマイズできます。構成オプションの詳細については、構成オプションをご覧ください。

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

// Create task for image file processing:
const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm "
);
const gestureRecognizer = await GestureRecognizer.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: "https://storage.googleapis.com/mediapipe-tasks/gesture_recognizer/gesture_recognizer.task"
  },
  numHands: 2
});

構成オプション

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

オプション名 説明 値の範囲 デフォルト値
runningMode タスクの実行モードを設定します。モードは 2 つあります。

IMAGE: 単一の画像入力のモード。

VIDEO: 動画のデコードされたフレーム、またはカメラなどの入力データのライブ ストリームのモード。		 {IMAGE, VIDEO} IMAGE
num_hands 検出できる手の最大数は GestureRecognizer で確認できます。 Any integer > 0 1
min_hand_detection_confidence 手の検出が手のひら検出モデルで成功とみなされるための最小信頼度スコア。 0.0 - 1.0 0.5
min_hand_presence_confidence 手のランドマーク検出モデルにおける手の存在スコアの最小信頼スコア。ジェスチャー認識ツールの動画モードとライブ配信モードでは、手のランドマーク モデルから得られた手の存在の信頼スコアがこのしきい値を下回ると、手のひら検出モデルがトリガーされます。それ以外の場合は、軽量なハンド トラッキング アルゴリズムを使用して、後続のランドマーク検出のために手の位置を特定します。 0.0 - 1.0 0.5
min_tracking_confidence ハンド トラッキングが成功とみなされるための最小の信頼スコア。これは、現在のフレームと最後のフレームの手の間の境界ボックス IoU しきい値です。Gesture Recognizer の動画モードとストリームモードでは、トラッキングが失敗すると、Gesture Recognizer が手の検出をトリガーします。それ以外の場合、手の検出はスキップされます。 0.0 - 1.0 0.5
canned_gestures_classifier_options 定型ジェスチャー分類子の動作を構成するためのオプション。定型ジェスチャーは ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"]
です。
  • 表示名の言語 / 地域: TFLite モデル メタデータで指定された表示名に使用する言語 / 地域（指定されている場合）。
  • 最大結果数: 返される上位スコアの分類結果の最大数。0 未満の場合、利用可能なすべての結果が返されます。
  • スコアしきい値: 結果が拒否されるスコア。0 に設定すると、利用可能なすべての結果が返されます。
  • カテゴリの許可リスト: カテゴリ名の許可リスト。空でない場合、カテゴリがこのセットに含まれていない分類結果はフィルタで除外されます。denylist とは相互に排他的です。
  • カテゴリの拒否リスト: カテゴリ名の拒否リスト。空でない場合、カテゴリがこのセットに含まれる分類結果は除外されます。許可リストとは相互に排他的です。
    		•
    • 表示名の言語 / 地域: any string
    • 最大結果数: any integer
    • スコアのしきい値: 0.0-1.0
    • カテゴリの許可リスト: vector of strings
    • カテゴリの拒否リスト: vector of strings
    • 表示名の言語 / 地域: "en"
    • 最大結果数: -1
    • スコアのしきい値: 0
    • カテゴリの許可リスト: 空
    • カテゴリの拒否リスト: 空
    custom_gestures_classifier_options カスタム ジェスチャー分類子の動作を構成するためのオプション。
  • 表示名の言語 / 地域: TFLite モデル メタデータで指定された表示名に使用する言語 / 地域（指定されている場合）。
  • 最大結果数: 返される上位スコアの分類結果の最大数。0 未満の場合、利用可能なすべての結果が返されます。
  • スコアしきい値: 結果が拒否されるスコア。0 に設定すると、利用可能なすべての結果が返されます。
  • カテゴリの許可リスト: カテゴリ名の許可リスト。空でない場合、カテゴリがこのセットに含まれていない分類結果はフィルタで除外されます。denylist とは相互に排他的です。
  • カテゴリの拒否リスト: カテゴリ名の拒否リスト。空でない場合、カテゴリがこのセットに含まれる分類結果は除外されます。許可リストとは相互に排他的です。
    		•
    • 表示名の言語 / 地域: any string
    • 最大結果数: any integer
    • スコアのしきい値: 0.0-1.0
    • カテゴリの許可リスト: vector of strings
    • カテゴリの拒否リスト: vector of strings
    • 表示名の言語 / 地域: "en"
    • 最大結果数: -1
    • スコアのしきい値: 0
    • カテゴリの許可リスト: 空
    • カテゴリの拒否リスト: 空

    データの準備

    Gesture Recognizer は、ホストブラウザでサポートされている任意の形式の画像内のジェスチャーを認識できます。このタスクは、サイズ変更、回転、値の正規化など、データ入力の前処理も処理します。動画内のジェスチャーを認識するには、API を使用して 1 フレームずつすばやく処理し、フレームのタイムスタンプを使用して、動画内でジェスチャーが発生したタイミングを特定します。

    タスクを実行する

    ジェスチャー認識ツールは、recognize()（実行モード 'image'）メソッドと recognizeForVideo()（実行モード 'video'）メソッドを使用して推論をトリガーします。タスクはデータを処理し、手のジェスチャーの認識を試み、結果をレポートします。

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

    画像

    const image = document.getElementById("image") as HTMLImageElement;
const gestureRecognitionResult = gestureRecognizer.recognize(image);

    動画

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

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

  if (video.currentTime !== lastVideoTime) {
    const gestureRecognitionResult = gestureRecognizer.recognizeForVideo(video);
    processResult(gestureRecognitionResult);
    lastVideoTime = video.currentTime;
  }

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

    ジェスチャー認識ツールの recognize() メソッドと recognizeForVideo() メソッドの呼び出しは同期的に実行され、ユーザー インターフェース スレッドをブロックします。デバイスのカメラからの動画フレームでジェスチャーを認識する場合、各認識でメインスレッドがブロックされます。これを防ぐには、ウェブ ワーカーを実装して、別のスレッドで recognize() メソッドと recognizeForVideo() メソッドを実行します。

    ジェスチャー認識ツールタスクの実行の実装例については、サンプルをご覧ください。

    結果を処理して表示する

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

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

    結果の GestureRecognizerResult には 4 つのコンポーネントが含まれ、各コンポーネントは配列です。各要素には、検出された 1 つの手の検出結果が含まれます。

    • 利き手

      利き手は、検出された手が左手か右手かを表します。

    • ジェスチャー

      検出された手の認識されたジェスチャー カテゴリ。

    • ランドマーク

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

    • 世界の名所

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

    GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  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)

    次の画像は、タスク出力の可視化を示しています。

    親指を立てている手の骨格構造がマッピングされた手

    ジェスチャー認識ツールタスクの作成の実装の詳細については、サンプルをご覧ください。