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

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

Android 手部地標偵測指南

MediaPipe 雙手地標工作可讓您偵測圖片中的手部地標。以下操作說明將為您示範如何搭配 Android 應用程式使用手部地標。如需本操作說明中所述的程式碼範例，請前往 GitHub。

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

程式碼範例

MediaPipe Tasks 程式碼範例是實作地標程式的簡易實作方式 App Engine 應用程式這個範例會使用實體 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 設定指南。

重要元件

以下檔案包含此手部地標的重要程式碼偵測應用程式範例：

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 雙手地標模型需要經過訓練且與執行這項工作如要進一步瞭解適用於手地標人員的已訓練模型，請參閱工作總覽的「模型」一節。

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

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

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

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

建立工作

MediaPipe Hand 標誌 er 工作會使用 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)

實作地標程式碼實作方式讓使用者可以在處理模式這種方法使得工作建立程式碼變得更加複雜，可能會不適合您的用途您可以在 setupHandLandmarker() 函式，用於 HandLandmarkerHelper.kt 檔案。

設定選項

這項工作有下列 Android 應用程式設定選項：

選項名稱	說明	值範圍	預設值
`runningMode`	設定任務的執行模式。在架構中模式：圖片：單一圖片輸入模式。 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`	要考慮手部追蹤的最低可信度分數成功。這是手中各部位的定界框 IoU 門檻目前的影格和最後一個影格在影片模式和串流模式中，手地標工 (如果追蹤失敗)，手地標人員會親自採買偵測。否則會略過手部偵測。	`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() 代表影片串流。當您對某個網路類型執行偵測時影片串流，請務必在另外的執行緒執行偵測，以免並封鎖使用者介面執行緒

以下程式碼範例顯示瞭如何執行「Hand Likeer」的簡單範例分別是

圖片

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。檔案。

處理及顯示結果

手地標人員為每個偵測產生一個手部地標結果物件此程序的第一步是將程式碼簽入執行所有單元測試的存放區中結果物件包含圖片座標中的手部地標、手部偵測出的世界座標和手部位置(左/右手) 。

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

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)

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

實作地標程式碼範例，示範如何顯示查看工作傳回的結果 OverlayView敬上類別，取得更多詳細資訊。