網頁版的手部地標偵測指南

MediaPipe 手部地標偵測器工作可偵測圖片中的手部地標。 這些操作說明將說明如何使用網頁和 JavaScript 應用程式的 Hand Landmarker。

如要進一步瞭解這項工作的能力、模型和設定選項，請參閱總覽。

程式碼範例

手部地標辨識器的範例程式碼提供 JavaScript 的完整實作方式，供您參考。這段程式碼可協助您測試這項工作，並開始建構自己的手部地標偵測應用程式。您只需使用網路瀏覽器，即可查看、執行及編輯手部地標偵測器範例。

設定

本節說明設定開發環境的主要步驟，以便使用 Hand Landmarker。如要瞭解如何設定網頁和 JavaScript 開發環境 (包括平台版本需求)，請參閱網頁設定指南。

JavaScript 套件

您可以透過 MediaPipe @mediapipe/tasks-vision NPM 套件取得 Hand Landmarker 程式碼。如要尋找及下載這些程式庫，請按照平台設定指南中的操作說明進行。

您可以使用下列指令，透過 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/

建立工作

使用其中一個 Hand Landmarker createFrom...() 函式，準備執行推論工作。使用 createFromModelPath() 函式，搭配訓練好的模型檔案的相對或絕對路徑。如果模型已載入記憶體，可以使用 createFromModelBuffer() 方法。

下方程式碼範例說明如何使用 createFromOptions() 函式設定工作。createFromOptions 函式可讓您使用設定選項自訂 Hand Landmarker。如要進一步瞭解設定選項，請參閱「設定選項」。

下列程式碼示範如何使用自訂選項建構及設定工作：

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "hand_landmarker.task"
      },
      numHands: 2
    });

設定選項

這項工作提供下列網頁和 JavaScript 應用程式的設定選項：

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

IMAGE：單一圖片輸入模式。

VIDEO：用於影片解碼影格的模式，或用於輸入資料的直播，例如來自攝影機的資料。		 {IMAGE, VIDEO} IMAGE
numHands 手部地標偵測器偵測到的手部數量上限。 Any integer > 0 1
minHandDetectionConfidence 手部偵測的最低信賴分數，手掌偵測模型會將此分數視為成功。 0.0 - 1.0 0.5
minHandPresenceConfidence 手部地標偵測模型中，手部存在分數的最低信賴分數。在「影片」模式和「直播」模式中，如果手部地標模型的手部存在信心分數低於這個門檻，Hand Landmarker 會觸發手掌偵測模型。否則，輕量型手勢追蹤演算法會判斷手部位置，以利後續偵測地標。 0.0 - 1.0 0.5
minTrackingConfidence 手勢追蹤的最低信賴分數，達到這個分數才算成功。這是目前影格和上一個影格之間的手部定界框 IoU 門檻。在手部地標的影片模式和串流模式中，如果追蹤失敗，手部地標會觸發手部偵測。否則系統會略過手部偵測。 0.0 - 1.0 0.5

準備資料

Hand Landmarker 可偵測主機瀏覽器支援的任何格式圖片中的手部地標。這項工作也會處理資料輸入預先處理作業，包括調整大小、旋轉和值正規化。如要在影片中偵測手部地標，可以使用 API 逐一快速處理影格，並根據影格的時間戳記，判斷手部地標在影片中出現的時間。

執行工作

手部地標模型會使用 detect() (執行模式為 image) 和 detectForVideo() (執行模式為 video) 方法觸發推論。這項工作會處理資料、嘗試偵測手部地標，然後回報結果。

呼叫 Hand Landmarker 的 detect() 和 detectForVideo() 方法會同步執行，並封鎖使用者介面執行緒。如果從裝置攝影機的影片影格中偵測到手部地標，每次偵測都會封鎖主要執行緒。如要避免這種情況，請實作網頁工作人員，在另一個執行緒上執行 detect() 和 detectForVideo() 方法。

以下程式碼示範如何使用工作模型執行處理作業：

圖片

const image = document.getElementById("image") as HTMLImageElement;
const handLandmarkerResult = handLandmarker.detect(image);

影片

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

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

  if (video.currentTime !== lastVideoTime) {
    const detections = handLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

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

如要更完整地瞭解如何執行 Hand Landmarker 工作，請參閱範例。

處理及顯示結果

Hand Landmarker 會為每次偵測作業產生手部地標結果物件。結果物件包含圖像座標中的手部地標、世界座標中的手部地標，以及偵測到的手部是左手/右手。

以下是這項工作的輸出資料範例：

HandLandmarkerResult 輸出內容包含三個元件。每個元件都是一個陣列，每個元素都包含單一偵測到的手部結果：

  • 慣用手

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

  • 地標

    共有 21 個手部地標，每個地標都由 x、y 和 z 座標組成。x 和 y 座標會分別根據圖片寬度和高度，正規化為 [0.0, 1.0]。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)

下圖顯示工作輸出內容的視覺化效果：

一隻手做出大拇指朝上的動作，並標示出手的骨骼結構

手部地標範例程式碼示範如何顯示工作傳回的結果，請參閱範例。