Python 的手地標偵測指南

MediaPipe 雙手地標工作可讓您偵測圖片中的手部地標。 以下指示會示範如何搭配使用電腦手把與 Python。 如需上述操作說明中的程式碼範例，請參閱 GitHub。

進一步瞭解功能、模型和設定選項 請參閱總覽。

程式碼範例

這個例子提供了手部地標工具的 執行相關作業這個程式碼可協助您測試這項工作 開始自行打造手部地標偵測器您可以查看、執行 編輯 Hand Lander 程式碼範例 只要使用網路瀏覽器即可。

設定

本節說明設定開發環境的重要步驟，以及 專用的程式碼專案如需 設定開發環境以使用 MediaPipe 工作，包括： 平台版本需求，請參閱 Python 設定指南。

套件

MediaPipe Hand 地標 er 工作需要 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 Hand Landmarker 工作會使用 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 設定任務的執行模式。在架構中 模式：

圖片：單一圖片輸入模式。

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 物件如果輸入內容是影片檔案 或透過網路攝影機直播，可以使用如 OpenCV，會將輸入影格載入為 numpy 陣列。

圖片

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_for_video 和 Detection_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 輸出內容包含三個元件。每個元件都是陣列，其中每個元素包含下列單一偵測到的手部結果：

  • 慣用手設計

    慣用手代表偵測到的手是左手還是右手。

  • 地標

    共有 21 個手部地標，每個地標都由 x、y 和 z 座標組成。 x 和 y 座標會依照圖片寬度和 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)

下圖是工作輸出內容的視覺化呈現：

實作地標程式碼範例，示範如何顯示 查看工作傳回的結果 程式碼範例 。