隆重推出 LiteRT：Google 為裝置端 AI (舊稱 TensorFlow Lite) 打造的高效能執行階段。

本頁面由 Cloud Translation API 翻譯而成。

Android 手部地標偵測指南

MediaPipe Hand Landmarker 工作可讓您偵測圖片中的手部地標。本操作說明將說明如何在 Android 應用程式中使用手勢標記工具。您可以在 GitHub 上找到這些操作說明中所述的程式碼範例。

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

程式碼範例

MediaPipe Tasks 範例程式碼是 Android 版手勢標記應用程式的簡單實作方式。這個範例會使用實體 Android 裝置的相機，持續偵測手部地標，也可以使用裝置相片庫中的圖片和影片，以靜態方式偵測手部地標。

您可以使用這個應用程式做為自有 Android 應用程式的起點，或是在修改現有應用程式時參考這個應用程式。手勢標記範例程式碼託管於 GitHub。

下載程式碼

以下操作說明說明如何使用 git 指令列工具，建立範例程式碼的本機副本。

下載程式碼範例：

使用下列指令複製 Git 存放區：

git clone https://github.com/google-ai-edge/mediapipe-samples

您可以選擇將 Git 例項設定為使用稀疏檢查，這樣就只會取得手勢標記範例應用程式的檔案：
```
cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/hand_landmarker/android
```

建立本機版本的範例程式碼後，您可以將專案匯入 Android Studio 並執行應用程式。如需操作說明，請參閱 Android 設定指南。

重要元件

下列檔案包含這項手勢地標偵測範例應用程式的關鍵程式碼：

HandLandmarkerHelper.kt - 初始化手部地標偵測器，並處理模型和委派選取作業。
MainActivity.kt：實作應用程式，包括呼叫 HandLandmarkerHelper。

設定

本節將說明設定開發環境和程式碼專案的關鍵步驟，以便使用手勢標記器。如要進一步瞭解如何設定開發環境以使用 MediaPipe 工作，包括平台版本需求，請參閱 Android 設定指南。

依附元件

手部標記器工作會使用 com.google.mediapipe:tasks-vision 程式庫。將這個依附元件新增至 Android 應用程式的 build.gradle 檔案：

dependencies {
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

型號

MediaPipe Hand Landmarker 工作需要訓練過的模型套件，且必須與此工作相容。如要進一步瞭解手部標記器可用的訓練模型，請參閱工作總覽的「模型」一節。

選取並下載模型，並儲存在專案目錄中：

<dev-project-root>/src/main/assets

在 ModelAssetPath 參數中指定模型的路徑。在程式碼範例中，模型是在 HandLandmarkerHelper.kt 檔案中定義：

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

建立工作

MediaPipe Hand Landmarker 工作會使用 createFromOptions() 函式設定工作。createFromOptions() 函式會接受設定選項的值。如要進一步瞭解設定選項，請參閱「設定選項」。

手勢標記器支援 3 種輸入資料類型：靜態圖片、影片檔案和即時串流。建立工作時，您需要指定與輸入資料類型相對應的執行模式。請選擇對應於輸入資料類型的分頁，瞭解如何建立工作並執行推論。

圖片

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

影片

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

直播

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

手部標記範例程式碼實作可讓使用者切換處理模式。這個方法會使建立工作程式的程式碼變得更複雜，可能不適合您的用途。您可以在 HandLandmarkerHelper.kt 檔案的 setupHandLandmarker() 函式中看到這段程式碼。

設定選項

此工作提供下列 Android 應用程式設定選項：

選項名稱	說明	值範圍	預設值
`runningMode`	設定工作執行模式。共有三種模式： IMAGE：單一圖片輸入模式。 VIDEO：影片解碼影格模式。 LIVE_STREAM：輸入資料 (例如來自攝影機的資料) 的直播模式。在這個模式中，必須呼叫 resultListener，才能設定事件監聽器，以非同步方式接收結果。	{`IMAGE, VIDEO, LIVE_STREAM`}	`IMAGE`
`numHands`	手部地標偵測器偵測到的手部數量上限。	`Any integer > 0`	`1`
`minHandDetectionConfidence`	在手掌偵測模型中，手部偵測的最低信賴分數，才會視為成功。	`0.0 - 1.0`	`0.5`
`minHandPresenceConfidence`	手部地標偵測模型中手部存在分數的最低可信度分數。在影片模式和直播模式中，如果手勢地標模型的手勢存在可信度分數低於此閾值，手勢地標偵測器就會觸發手掌偵測模型。否則，輕量手勢追蹤演算法會判斷手的位置，以便後續的標記偵測。	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	手部追蹤系統判定為成功的最低可信度分數。這是目前影格和上一個影格中手的定界框交併比閾值。在 Hand Landmarker 的影片模式和串流模式中，如果追蹤失敗，Hand Landmarker 會觸發手部偵測。否則系統會略過手勢偵測。	`0.0 - 1.0`	`0.5`
`resultListener`	在手部標記處於即時串流模式時，將結果事件監聽器設為以非同步方式接收偵測結果。只有在執行模式設為 `LIVE_STREAM` 時才適用	不適用	不適用
`errorListener`	設定選用的錯誤監聽器。	不適用	不適用

準備資料

手部標記辨識器可用於圖片、影片檔案和直播影片。這個工作會處理資料輸入預先處理作業，包括調整大小、旋轉和值規格化。

以下程式碼示範如何將資料交由處理。這些範例包含如何處理圖片、影片檔案和即時影片串流的資料。

圖片

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(image).build()

影片

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

val argb8888Frame =
    if (frame.config == Bitmap.Config.ARGB_8888) frame
    else frame.copy(Bitmap.Config.ARGB_8888, false)

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(argb8888Frame).build()

直播

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(rotatedBitmap).build()

在手勢標記範例程式碼中，資料準備作業會在 HandLandmarkerHelper.kt 檔案中處理。

執行工作

視您使用的資料類型而定，請使用該資料類型專屬的 HandLandmarker.detect...() 方法。請將 detect() 用於個別圖片、detectForVideo() 用於影片檔案中的影格，以及 detectAsync() 用於影片串流。在影片串流上執行偵測作業時，請務必在個別執行緒上執行偵測作業，以免阻斷使用者介面執行緒。

以下程式碼範例提供簡單的範例，說明如何在這些不同資料模式下執行手部標記器：

圖片

val result = handLandmarker?.detect(mpImage)

影片

val timestampMs = i * inferenceIntervalMs

handLandmarker?.detectForVideo(mpImage, timestampMs)
    ?.let { detectionResult ->
        resultList.add(detectionResult)
    }

直播

val mpImage = BitmapImageBuilder(rotatedBitmap).build()
val frameTime = SystemClock.uptimeMillis()

handLandmarker?.detectAsync(mpImage, frameTime)

注意事項：

在影片模式或直播模式中執行時，您也必須向手勢標記器工作提供輸入影格時間戳記。
在圖片或影片模式下執行時，手勢標記器工作會阻斷目前的執行緒，直到處理完輸入圖片或影格為止。為避免阻斷使用者介面，請在背景執行緒中執行處理作業。
在直播模式下執行時，手部標記器工作不會阻斷目前的執行緒，而是立即傳回。每次處理完輸入影格後，它都會使用偵測結果叫用結果監聽器。如果在手勢標記器工作忙於處理其他影格時呼叫偵測函式，工作會忽略新的輸入影格。

在 Hand Landmarker 範例程式碼中，detect、detectForVideo 和 detectAsync 函式是在 HandLandmarkerHelper.kt 檔案中定義。

處理及顯示結果

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)

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

豎起大拇指的手，並標示出手的骨骼結構

手部地標程式碼範例說明如何顯示工作傳回的結果，詳情請參閱 OverlayView 類別。