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 手勢辨識工作需要與這項工作相容的已訓練模型。如要進一步瞭解手勢辨識工具可用的已訓練模型,請參閱工作總覽一節。
選取並下載模型,然後將其儲存在專案目錄中:
<dev-project-root>/app/shared/models/
建立工作
使用其中一個手勢辨識工具 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 |
設定工作的執行模式。系統提供兩種模式: IMAGE:單一圖片輸入的模式。 影片:這種模式為影片中解碼的影格或即時輸入資料 (例如攝影機) 的直播。 |
{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 門檻。在影片模式和手勢辨識的串流模式下,如果追蹤失敗,手勢辨識工具會觸發手部偵測。否則系統會略過手部偵測。 | 0.0 - 1.0 |
0.5 |
canned_gestures_classifier_options |
設定罐頭手勢分類器行為的選項。罐頭手勢為 ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"] |
|
|
custom_gestures_classifier_options |
設定自訂手勢分類器行為的選項。 |
|
|
準備資料
手勢辨識工具能夠以主機瀏覽器支援的任何格式辨識圖片中的手勢。這項工作也會處理資料輸入預先處理,包括調整大小、旋轉和值正規化。如要識別影片中的手勢,您可以使用 API 一次快速處理一個影格,並使用影格的時間戳記來判斷手勢在影片中發生的時間。
執行工作
手勢辨識工具會使用 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()
方法發出的呼叫會同步執行,並封鎖使用者介面執行緒。如果您發現裝置相機影片影格中的手勢,每項辨識都會封鎖主執行緒。如要避免這種情況發生,您可以實作網路 worker,在其他執行緒上執行 recognize()
和 recognizeForVideo()
方法。
如要進一步瞭解如何執行手勢辨識工具工作,請參閱程式碼範例。
處理並顯示結果
手勢辨識工具會為每個辨識執行作業產生手勢偵測結果物件。結果物件包含圖片座標中的手繪地標、世界座標的手部地標、慣用手(左/右手),以及偵測到的手部手勢類別。
以下為這項工作的輸出資料範例:
產生的 GestureRecognizerResult
包含四個元件,每個元件都是陣列,其中每個元素都包含偵測到的一隻手的結果。
慣用手設計
慣用手是指偵測到的手是左手還是右手。
手勢
偵測到的手所辨識的手勢類別。
地標
有 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)
下圖以視覺化方式呈現工作輸出:
如要進一步瞭解如何建立手勢辨識工具工作,請參閱程式碼範例。