Android 的姿勢地標偵測指南

MediaPipe Pose Landmarker 工作可讓您在圖片或影片中偵測人體地標。您可以使用這項工作來找出身體的重要位置、分析姿勢，以及分類動作。這項工作會使用機器學習 (ML) 模型，這些模型可處理單張圖片或影片。這項工作會以圖片座標和 3D 世界座標輸出人體姿勢地標。

您可以在 GitHub 上找到這些操作說明中所述的程式碼範例。如要進一步瞭解這項工作的功能、模型和設定選項，請參閱總覽。

程式碼範例

MediaPipe Tasks 範例程式碼是 Android 版 Pose Landmarker 應用程式的簡單實作方式。本範例會使用實體 Android 裝置上的相機，在連續的影片串流中偵測姿勢。應用程式也可以偵測裝置相片庫中的圖片和影片姿勢。

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

下載程式碼

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

下載程式碼範例：

  1. 使用下列指令複製 Git 存放區：
    git clone https://github.com/google-ai-edge/mediapipe-samples
  2. 您可以選擇將 Git 例項設定為使用稀疏檢查，這樣您就只會取得 Pose Landmarker 範例應用程式的檔案：
    cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/pose_landmarker/android

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

重要元件

以下檔案包含此姿勢地標示範例應用程式的重要程式碼：

設定

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

依附元件

姿勢地標任務會使用 com.google.mediapipe:tasks-vision 程式庫。請將這個依附元件新增至 Android 應用程式的 build.gradle 檔案：

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

型號

MediaPipe Pose Landmarker 工作需要與此工作相容的已訓練模型套件。如要進一步瞭解可用訓練模型的姿勢地標，請參閱任務總覽的「模型」一節。

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

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

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

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

建立工作

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

姿勢地標支援下列輸入資料類型：靜態圖片、影片檔案和即時影像串流。建立工作時，您需要指定相應於輸入資料類型的執行模式。請選擇輸入資料類型的分頁，瞭解如何建立工作。

圖片

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)

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

設定選項

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

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

IMAGE：單一圖片輸入模式。

VIDEO：影片解碼影格模式。

LIVE_STREAM：輸入資料 (例如來自攝影機的資料) 的直播模式。 在這個模式中，必須呼叫 resultListener，才能設定事件監聽器，以非同步方式接收結果。		 {IMAGE, VIDEO, LIVE_STREAM} IMAGE
numposes Pose Landmarker 可偵測的姿勢數量上限。 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 在 Pose Landmarker 處於即時串流模式時，將結果事件監聽器設為以非同步方式接收地標結果。只有在執行模式設為 LIVE_STREAM 時，才能使用 ResultListener N/A
errorListener 設定選用的錯誤監聽器。 ErrorListener N/A

準備資料

Pose Landmarker 可用於圖片、影片檔案和直播影片串流。這個工作會處理資料輸入預先處理作業，包括調整大小、旋轉和值規格化。

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

圖片

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

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

執行工作

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

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

圖片

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)

注意事項：

  • 在影片模式或直播模式中執行時，您必須向姿勢地標任務提供輸入影格時間戳記。
  • 在圖片或影片模式下執行時，姿勢地標器工作會阻斷目前的執行緒，直到處理完輸入圖片或影格為止。為避免阻斷使用者插入，請在背景執行緒中執行處理作業。
  • 在直播模式下執行時，姿勢地標作業會立即傳回，且不會封鎖目前的執行緒。每次處理完輸入影格時，它都會使用偵測結果叫用結果事件監聽器。

在姿勢地標示器範例程式碼中，detect、detectForVideo 和 detectAsync 函式是在 PoseLandmarkerHelper.kt 檔案中定義。

處理及顯示結果

Pose Landmarker 會針對每次偵測作業傳回 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：以圖片寬度 (x) 和高度 (y) 為基準，將地標座標正規化為介於 0.0 和 1.0 之間的值。

  • z：地標深度，以臀部中點的深度做為原點。值越小，地標離相機越近。z 的大小會使用與 x 大致相同的比例。

  • visibility：地標在圖片中顯示的可能性。

輸出內容包含下列世界座標 (WorldLandmarks)：

  • x、y 和 z：以公尺為單位的實際 3D 座標，以臀部中點做為原點。

  • visibility：地標在圖片中顯示的可能性。

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

一名女子正在打坐冥想。她的姿勢以線框標示，指出四肢和軀幹的位置

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

上一個圖片的區隔遮罩，勾勒出女性的形狀

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