手勢辨識工作指南

一隻手做出大拇指朝上的動作，模型將此動作識別為「大拇指朝上」手勢，信心指數為 63%

MediaPipe 手勢辨識器工作可即時辨識手勢，並提供辨識出的手勢結果，以及偵測到的手部地標。您可以透過這項工作辨識使用者的特定手勢，並叫用與這些手勢對應的應用程式功能。

這項工作會使用機器學習 (ML) 模型處理圖像資料，並接受靜態資料或連續串流。這項工作會輸出圖像座標中的手部地標、世界座標中的手部地標、慣用手 (左/右手) 和多隻手的手勢類別。

立即試用！

開始使用

如要開始使用這項工作，請按照目標廣告平台的其中一份導入指南操作。這些平台專屬指南會逐步說明如何使用建議模型，基本實作這項工作，並提供建議設定選項的程式碼範例：

任務詳細資料

本節說明這項工作的能力、輸入內容、輸出內容和設定選項。

功能

  • 輸入圖片處理 - 處理包括圖片旋轉、調整大小、正規化和色彩空間轉換。
  • 分數門檻：根據預測分數篩選結果。
  • 標籤許可清單和拒絕清單：指定模型可辨識的手勢類別。
工作輸入內容 工作輸出內容
手勢辨識器接受下列其中一種資料類型的輸入：
  • 靜態圖片
  • 解碼的影片影格
  • 即時影像畫面
 手勢辨識器會輸出下列結果：
  • 手勢類別
  • 偵測到的手部慣用手
  • 圖片座標中偵測到的手部地標
  • 以世界座標表示偵測到的手部地標

設定選項

這項工作提供下列設定選項：

選項名稱 說明 值範圍 預設值
running_mode 設定工作執行模式。共有三種模式：

IMAGE：單一圖片輸入模式。

影片：影片解碼影格的模式。

LIVE_STREAM：輸入資料 (例如攝影機) 的直播模式。在此模式下，必須呼叫 resultListener 來設定事件監聽器，以非同步方式接收結果。		 {IMAGE, VIDEO, LIVE_STREAM} IMAGE
num_hands GestureRecognizer 最多可偵測到的手部數量。 Any integer > 0 1
min_hand_detection_confidence 手部偵測的最低信賴分數，手掌偵測模型會將此分數視為成功。 0.0 - 1.0 0.5
min_hand_presence_confidence 手部地標偵測模型中，手部存在分數的最低信賴分數。在 Gesture Recognizer 的「影片」模式和「直播」模式中，如果手部地標模型的手部存在信心分數低於這個門檻，就會觸發手掌偵測模型。否則，系統會使用輕量型手勢追蹤演算法，判斷手部位置，以利後續偵測地標。 0.0 - 1.0 0.5
min_tracking_confidence 手勢追蹤的最低信賴分數，達到這個分數才算成功。這是目前影格和上一個影格之間的手部定界框 IoU 門檻。在手勢辨識工具的「影片」模式和「串流」模式中，如果追蹤失敗，手勢辨識工具會觸發手部偵測。否則系統會略過手部偵測。 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，系統會傳回所有可用的結果。
  • 類別許可清單：類別名稱的許可清單。如果這個集合不為空，系統會篩除類別不在這個集合中的分類結果。與拒絕清單互斥。
  • 類別拒絕清單：類別名稱的拒絕清單。如果這個集合不為空，系統會篩除類別位於這個集合中的分類結果。與允許清單互斥。
    		•
    • 顯示名稱語言代碼：any string
    • 最多結果數：any integer
    • 分數門檻：0.0-1.0
    • 類別許可清單：vector of strings
    • 類別拒絕清單：vector of strings
    • 顯示名稱語言代碼："en"
    • 最多結果數：-1
    • 分數門檻：0
    • 類別許可清單：空白
    • 類別拒絕清單：空白
    custom_gestures_classifier_options 設定自訂手勢分類器行為的選項。
  • 顯示名稱語言代碼：如果有的話，用於透過 TFLite 模型中繼資料指定的顯示名稱。
  • 結果數上限：要傳回的最高分分類結果數上限。如果 < 0，則會傳回所有可用的結果。
  • 分數門檻：低於這個分數的結果會遭到拒絕。如果設為 0，系統會傳回所有可用的結果。
  • 類別許可清單：類別名稱的許可清單。如果這個集合不為空，系統會篩除類別不在這個集合中的分類結果。與拒絕清單互斥。
  • 類別拒絕清單：類別名稱的拒絕清單。如果這個集合不為空，系統會篩除類別位於這個集合中的分類結果。與允許清單互斥。
    		•
    • 顯示名稱語言代碼：any string
    • 最多結果數：any integer
    • 分數門檻：0.0-1.0
    • 類別許可清單：vector of strings
    • 類別拒絕清單：vector of strings
    • 顯示名稱語言代碼："en"
    • 最多結果數：-1
    • 分數門檻：0
    • 類別許可清單：空白
    • 類別拒絕清單：空白
    result_callback 設定結果事件監聽器，在手勢辨識器處於直播模式時，以非同步方式接收分類結果。只有在執行模式設為 LIVE_STREAM 時才能使用 ResultListener 不適用 不適用

    模型

    手勢辨識工具會使用模型套件，其中包含兩個預先封裝的模型套件：手部地標模型套件和手勢分類模型套件。地標模型會偵測手部和手部幾何形狀，手勢辨識模型則會根據手部幾何形狀辨識手勢。

    模型名稱 輸入形狀 量化類型 模型資訊卡 版本
    HandGestureClassifier 192 x 192、224 x 224 浮點數 16 資訊 最新

    這項工作也支援使用 Model Maker 修改模型套件。如要進一步瞭解如何使用 Model Maker 自訂模型來執行這項工作，請參閱「自訂手勢辨識器模型」頁面。

    手部地標模型套裝組合

    手部地標模型套件會偵測偵測到的手部區域內，21 個手部關節座標的關鍵點位置。模型訓練時使用了約 3 萬張真實圖片，以及多個在各種背景上疊加的合成手部模型。請參閱下方的 21 個地標定義：

    特定手部地標點的代碼

    手部地標模型套件包含手掌偵測模型和手部地標偵測模型。手掌偵測模型會從整張輸入圖片中找出雙手區域，而手部地標偵測模型則會在手掌偵測模型定義的裁剪手部圖片中找出地標。

    由於手掌偵測模型耗時許多，在影片模式或即時串流模式中，手勢辨識器會使用目前影格中偵測到的手部地標所定義的定界框，找出下一個影格中的手部區域。這樣可減少手勢辨識器觸發手掌偵測模型的次數。只有在手部地標模型無法再識別足夠的手部數量，或手勢追蹤失敗時，才會呼叫手掌偵測模型重新定位手部。

    手勢分類模型套件

    手勢分類模型套件可辨識下列常見手勢：

    0 - Unrecognized gesture, label: Unknown
1 - Closed fist, label: Closed_Fist
2 - Open palm, label: Open_Palm
3 - Pointing up, label: Pointing_Up
4 - Thumbs down, label: Thumb_Down
5 - Thumbs up, label: Thumb_Up
6 - Victory, label: Victory
7 - Love, label: ILoveYou

    如果模型偵測到手部，但無法辨識手勢，手勢辨識器會傳回「None」結果。如果模型未偵測到手部，手勢辨識器會傳回空白。

    手勢分類模型套件包含兩個步驟的神經網路管道，其中一個是手勢嵌入模型，另一個是手勢分類模型。詳情請參閱手勢分類模型資訊卡。

    手勢嵌入模型會將圖片特徵編碼為特徵向量，而分類模型則是輕量型手勢分類器，會將特徵向量做為輸入內容。提供的手勢分類模型套件包含罐頭手勢分類器，可偵測上述 7 種常見手勢。您可以訓練自己的自訂手勢分類器，擴充模型套件，辨識更多手勢。詳情請參閱下方的「自訂模型」一節。

    如果手勢辨識器同時使用預先建構的手勢分類器和自訂手勢分類器，且兩個分類器都辨識出相同類別的手勢，則會優先使用自訂手勢。如果只有一個手勢分類器辨識手勢，手勢辨識器會直接輸出辨識到的手勢。

    工作基準

    以下是根據上述預先訓練模型，針對整個管道設定的任務基準。延遲時間結果是 Pixel 6 使用 CPU / GPU 時的平均延遲時間。

    模型名稱 CPU 延遲 GPU 延遲
    GestureRecognizer 16.76 毫秒 20.87 毫秒

    自訂模型

    如要改善或變更這項工作提供的模型功能，可以使用 Model Maker 修改現有模型。搭配 MediaPipe 使用的自訂模型必須採用 .task 格式，也就是模型套件檔案。建議您先使用 Model Maker 修改這項工作提供的模型，再自行建構模型。

    如要進一步瞭解如何自訂這項工作的模型，請參閱「自訂手勢辨識器模型」。