Python 用手のランドマーク検出ガイド

MediaPipe の手のランドマーカー タスクを使用すると、画像内の手のランドマークを検出できます。 ここでは Python でハンド ランドマーカーを使用する方法について説明します。「 この手順で説明するコードサンプルは、 GitHub。

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

サンプルコード

Handmark のサンプル コードは、これを完全に実装しています。 タスクを示しています。このコードは、このタスクをテストして、 独自のハンドランドマーク検出ツールの構築を始めました。特定のリソースを表示、実行、 編集 手のランドマークのサンプルコード できます。

セットアップ

このセクションでは、開発環境をセットアップする主な手順と ハンド ランドマーカーを使用するというコード プロジェクトがありました。一般的な情報については、 MediaPipe タスクを使用するための開発環境の設定 プラットフォーム バージョンの要件については、 Python のセットアップ ガイド

<ph type="x-smartling-placeholder">

パッケージ

MediaPipe ハンド ランドマーカー タスクには、mediapipe PyPI パッケージが必要です。 これらの依存関係は、次のコマンドでインストールしてインポートできます。

$ python -m pip install mediapipe

インポート

ハンド ランドマーカー タスクの関数にアクセスするには、次のクラスをインポートします。

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

モデル

MediaPipe のハンドランドマーカー タスクには、これと互換性のあるトレーニング済みモデルが必要です タスクを実行します。ハンド ランドマーク ツールで利用可能なトレーニング済みモデルについて詳しくは、以下をご覧ください。 タスクの概要のモデル セクションをご覧ください。

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

model_path = '/absolute/path/to/gesture_recognizer.task'

BaseOptions オブジェクトの model_asset_path パラメータを使用してパスを指定する モデルを定義します。コード例については、次のセクションをご覧ください。

タスクを作成する

MediaPipe のハンドランドマーカー タスクでは、create_from_options 関数を使用して以下を行います。 タスクを設定します。create_from_options 関数は値を受け入れる 処理する構成オプションを確認してくださいリソースの構成について 構成オプションをご覧ください。

次のコードは、このタスクをビルドして構成する方法を示しています。

これらのサンプルは、画像のタスク構成のバリエーションも示しています。 動画ファイル、ライブ ストリームです。

画像

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the image mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...

動画

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the video mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...

ライブ配信

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
HandLandmarkerResult = mp.tasks.vision.HandLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the live stream mode:
def print_result(result: HandLandmarkerResult, output_image: mp.Image, timestamp_ms: int):
    print('hand landmarker result: {}'.format(result))

options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...

画像で使用する手の地面マーカーを作成する詳細な例については、 コードサンプルをご覧ください。

構成オプション

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

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

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

VIDEO: 動画のデコードされたフレームのモード。

LIVE_STREAM: 入力のライブ配信のモード カメラからのデータなどです。このモードでは、resultListener は 結果を受け取るリスナーを設定するために呼び出されます。 使用できます。 		{IMAGE, VIDEO, LIVE_STREAM} IMAGE
num_hands 手のランドマーク検出機能で検出される手の最大数。 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 しきい値です。 現在のフレームと最後のフレームが表示されます。動画モードとストリーム モードでは、 手の地面マーカー（追跡がうまくいかなかった場合、手の地面マーカーが手を動かします） できます。それ以外の場合は、手の検出をスキップします。 0.0 - 1.0 0.5
result_callback 検出結果を受信する結果リスナーを設定する ライブ ストリーム モードのときに非同期で送信されます。 実行モードが LIVE_STREAM に設定されている場合にのみ適用されます なし なし

データの準備

入力を画像ファイルまたは numpy 配列として準備します。 mediapipe.Image オブジェクトに変換します。入力が動画ファイルの場合 ライブ ストリームで配信する場合、 入力フレームを numpy として読み込むための OpenCV あります

画像

import mediapipe as mp

# Load the input image from an image file.
mp_image = mp.Image.create_from_file('/path/to/image')

# Load the input image from a numpy array.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)

動画

import mediapipe as mp

# Use OpenCV’s VideoCapture to load the input video.

# Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS
# You’ll need it to calculate the timestamp for each frame.

# Loop through each frame in the video using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)

ライブ配信

import mediapipe as mp

# Use OpenCV’s VideoCapture to start capturing from the webcam.

# Create a loop to read the latest frame from the camera using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)

タスクを実行する

ハンド マーカーは、detect、detect_for_video、detect_async を使用して、 推論をトリガーできます手のランドマーク検出の場合 入力データの前処理、画像内の手の検出、手の検出 使用できます。

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

画像

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the image mode.
hand_landmarker_result = landmarker.detect(mp_image)

動画

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the video mode.
hand_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)

ライブ配信

# Send live image data to perform hand landmarks detection.
# The results are accessible via the `result_callback` provided in
# the `HandLandmarkerOptions` object.
# The hand landmarker must be created with the live stream mode.
landmarker.detect_async(mp_image, frame_timestamp_ms)

次の点にご留意ください。

  • 動画モードまたはライブ配信モードで実行する場合は、 ハンド ランドマーク タスクに入力フレームのタイムスタンプを提供します。
  • 画像モデルまたは動画モデルで実行すると、ハンド ランドマーク タスクが 入力画像の処理が完了するまで、現在のスレッドをブロックします。 クリックします。
  • ライブ ストリーム モードで実行している場合、手のランドマーク タスクがブロックされない すぐに戻ります。このメソッドは、 完了するたびに、その検出結果とともに 表示されます。手のランドマークが呼び出されたときに検出関数が呼び出された場合 タスクが別のフレームの処理でビジー状態の場合、タスクは新しい入力フレームを無視します。

画像に手の地面マーカーを配置する詳細な例については、 コードサンプルをご覧ください。

結果の処理と表示

ハンド ランドマーカーは、検出ごとにハンド ランドマーク結果オブジェクトを生成します あります。結果のオブジェクトには、画像座標の手のランドマーク、手のひら 検出された対象物の世界座標と利き手（左手/右手）のランドマーク できます。

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

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

  • 利き手

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

  • ランドマーク

    21 個のハンド ランドマークがあり、それぞれ x、y、z 座標で構成されています。「 x 座標と y 座標は、画像の幅と [0.0, 1.0] に正規化されます。 あります。z 座標はランドマークの深さを表します。 手首の奥行きが原点になります。値が小さいほど、 カメラに映し出されますz の大きさは、 x。

  • 世界の名所

    21 の針のランドマークも世界座標で示されています。各ランドマーク は x、y、z で構成されており、次の現実世界の 3D 座標を表します。 m を、手の幾何学的中心を原点とします。

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)

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

ハンド マーカーのサンプル コードでは、 結果については、 コードサンプル をご覧ください。