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

Android 的姿勢地標偵測指南

MediaPipe Pose 地標工作可讓您偵測圖片或影片中的人體地標。您可以使用這項工作來識別關鍵主體位置、分析姿勢，以及將運動分類。這項工作採用的機器學習 (ML) 模型適用於單一圖片或影片工作會輸出圖片座標和 3D 世界座標中的身體姿勢地標。

您可以前往 GitHub 取得這些操作說明中提及的程式碼範例。如要進一步瞭解這項工作的功能、模型和設定選項，請參閱總覽。

程式碼範例

MediaPipe Tasks 範例程式碼是適用於 Android 的簡易實作地標應用程式。這個範例使用 Android 實體裝置的相機，偵測連續影片串流中的姿勢。應用程式也可以從裝置圖片庫偵測圖片和影片中的姿勢。

您可以將該應用程式做為建立自己的 Android 應用程式的基礎，或在修改現有應用程式時參照該應用程式。Pose Marker 範例程式碼由 GitHub 代管。

下載程式碼

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

如要下載範例程式碼，請按照下列步驟操作：

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

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

您可以選擇將 git 執行個體設為使用稀疏結帳功能，這樣您只有 Pose Landmarker 範例應用程式的檔案：
```
cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/pose_landmarker/android
```

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

重要元件

下列檔案包含這個姿勢地標應用程式的重要程式碼：

PoseLandmarkerHelper.kt：初始化姿勢地標工具，並處理模型及委派選取。
CameraFragment.kt：處理裝置相機，並處理圖片和影片輸入資料。
GalleryFragment.kt - 與 OverlayView 互動，以顯示輸出圖片或影片。
OverlayView.kt：實作偵測到姿勢的顯示畫面。

設定

本節說明設定開發環境及專門為使用 Posemarker 的程式碼專案的重要步驟。如需瞭解如何使用 MediaPipe 工作設定開發環境的一般資訊，包括平台版本需求，請參閱 Android 設定指南。

依附元件

「Pose Ranker」工作會使用 com.google.mediapipe:tasks-vision 程式庫。請將這個依附元件新增至 Android 應用程式的 build.gradle 檔案：

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

型號

MediaPipe Posemarker 工作需要與這項工作相容的已訓練模型組合。如要進一步瞭解 Pose Marker 可用的已訓練模型，請參閱工作總覽「模型」一節。

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

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

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

val modelName = "pose_landmarker_lite.task"
baseOptionsBuilder.setModelAssetPath(modelName)

建立工作

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

Pose Marker 支援下列輸入資料類型：靜態圖片、影片檔案和直播影片串流。建立工作時，您需要指定與輸入資料類型相對應的執行模式。選擇輸入資料類型的分頁標籤，瞭解如何建立工作。

圖片

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

val optionsBuilder = 
    poseLandmarker.poseLandmarkerOptions.builder()
        .setBaseOptions(baseOptionsBuilder.build())
        .setMinPoseDetectionConfidence(minPoseDetectionConfidence)
        .setMinTrackingConfidence(minPoseTrackingConfidence)
        .setMinPosePresenceConfidence(minposePresenceConfidence)
        .setNumPoses(maxNumPoses)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()
poseLandmarker = poseLandmarker.createFromOptions(context, options)

影片

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

val optionsBuilder = 
    poseLandmarker.poseLandmarkerOptions.builder()
        .setBaseOptions(baseOptionsBuilder.build())
        .setMinPoseDetectionConfidence(minPoseDetectionConfidence)
        .setMinTrackingConfidence(minPoseTrackingConfidence)
        .setMinPosePresenceConfidence(minposePresenceConfidence)
        .setNumPoses(maxNumPoses)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()
poseLandmarker = poseLandmarker.createFromOptions(context, options)

直播

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

val optionsBuilder = 
    poseLandmarker.poseLandmarkerOptions.builder()
        .setBaseOptions(baseOptionsBuilder.build())
        .setMinPoseDetectionConfidence(minPoseDetectionConfidence)
        .setMinTrackingConfidence(minPoseTrackingConfidence)
        .setMinPosePresenceConfidence(minposePresenceConfidence)
        .setNumPoses(maxNumPoses)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.LIVE_STREAM)

val options = optionsBuilder.build()
poseLandmarker = poseLandmarker.createFromOptions(context, options)

Pose Ranker 程式碼範例實作可讓使用者切換處理模式。這種做法會讓工作建立程式碼變得更加複雜，並且可能不適合您的用途。您可以在 PoseLandmarkerHelper.kt 檔案的 setupPoseLandmarker() 函式中看到此程式碼。

設定選項

這項工作的 Android 應用程式設定選項如下：

選項名稱	說明	值範圍	預設值
`runningMode`	設定工作的執行模式。共有三種模式： IMAGE：單一圖片輸入的模式。影片：影片已解碼影格的模式。 LIVE_STREAM：輸入資料串流 (例如攝影機) 的直播模式。在這個模式下，必須呼叫 resultListener 才能設定事件監聽器，以非同步方式接收結果。	{`IMAGE, VIDEO, LIVE_STREAM`}	`IMAGE`
`numposes`	姿勢地標可以偵測到的姿勢數量上限。	`Integer > 0`	`1`
`minPoseDetectionConfidence`	判定姿勢偵測作業成功所需的最低可信度分數。	`Float [0.0,1.0]`	`0.5`
`minPosePresenceConfidence`	在姿勢地標偵測中，姿勢狀態分數的最小可信度分數	`Float [0.0,1.0]`	`0.5`
`minTrackingConfidence`	要判定姿勢追蹤成功的可信度分數下限，	`Float [0.0,1.0]`	`0.5`
`outputSegmentationMasks`	是否要為偵測到的姿勢輸出區隔遮罩。	`Boolean`	`False`
`resultListener`	設定結果事件監聽器，就能在直播模式下以非同步方式接收地標結果。只能在執行模式設為 `LIVE_STREAM` 時使用	`ResultListener`	`N/A`
`errorListener`	設定選用的錯誤事件監聽器。	`ErrorListener`	`N/A`

準備資料

Posemarker 支援圖片、影片檔案和直播影片。工作會處理資料輸入的預先處理作業，包括調整大小、旋轉和值正規化。

以下程式碼示範如何傳送資料以進行處理。這些範例包含如何處理圖片、影片檔案和直播影片串流的資料。

圖片

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()

在 Posemarker 範例程式碼中，PoseLandmarkerHelper.kt 檔案會處理資料準備。

執行工作

視處理的資料類型而定，請使用該資料類型專屬的 poseLandmarker.detect...() 方法。針對個別圖片，請使用 detect()；針對影片檔案中的影格，請使用 detectForVideo()；針對影片串流，則使用 detectAsync()。在影片串流中執行偵測時，請務必在另一個執行緒上執行偵測，以免封鎖使用者的交錯執行緒。

以下程式碼範例顯示如何在不同的資料模式中執行 Pose Marker 的簡單範例：

圖片

val result = poseLandmarker.detect(mpImage)

影片

val timestampMs = i * inferenceIntervalMs

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

直播

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

poseLandmarker.detectAsync(mpImage, frameTime)

注意事項：

以影片模式或直播模式執行時，您必須提供 Pose Marker 工作的輸入影格時間戳記。
在圖片或影片模式中執行時，「Posemarker」工作會封鎖目前的執行緒，直到完成輸入圖片或影格的處理為止。為避免對使用者造成交互影響，請在背景執行緒中執行處理程序。
以直播模式執行時，「Pose 地標」工作會立即回傳，且不會封鎖目前的執行緒。每當它處理完輸入影格時，就會透過偵測結果叫用結果監聽器。

在 Pose Ranker 程式碼範例中，會在 PoseLandmarkerHelper.kt 檔案中定義 detect、detectForVideo 和 detectAsync 函式。

處理並顯示結果

Pose 地標 er 會在每次執行偵測時傳回 poseLandmarkerResult 物件。結果物件含有每個姿勢地標的座標。

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

PoseLandmarkerResult:
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : 0.129959
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
      visibility   : 0.999909
      presence     : 0.999958
    ... (33 landmarks per pose)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
      visibility   : 0.999976
      presence     : 0.999998
    ... (33 world landmarks per pose)
  SegmentationMasks:
    ... (pictured below)

輸出結果同時包含每個地標的正規化座標 (Landmarks) 和世界座標 (WorldLandmarks)。

輸出結果包含以下正規化座標 (Landmarks)：

x 和 y：地標座標介於 0.0 到 1.0 之間，依照圖片寬度 (x) 和高度 (y) 進行正規化。
z：地標深度，以臀部中間點為起點。值越小，地標與相機鏡頭越近。Z 規模使用的縮放比例與 x 大致相同。
visibility：地標在圖片中可見的可能性。

輸出結果包含以下世界座標 (WorldLandmarks)：

x、y 和 z：實際 3 維座標 (以公尺為單位)，以臀部中間點做為起點。
visibility：地標在圖片中可見的可能性。

下圖以視覺化方式呈現工作輸出內容：

選用的區隔遮罩代表每個像素屬於偵測到人員的可能性。下圖是工作輸出的區隔遮罩：

Posemarker 範例程式碼會示範如何顯示工作傳回的結果，詳情請參閱 OverlayView 類別。