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

在 Android 上使用 ML Kit 偵測姿勢

ML Kit 提供兩種用於偵測姿勢的最佳化 SDK。

SDK 名稱	姿勢偵測	偵測偵測準確性
實作中	建構期間，程式碼和資產是以靜態方式連結至您的應用程式。	建構期間，程式碼和資產是以靜態方式連結至您的應用程式。
應用程式大小影響 (包括程式碼和素材資源)	約 10.1 MB	約 13.3 MB
成效	Pixel 3XL：約 30 FPS	Pixel 3XL：CPU 約 23 FPS，使用 GPU 約 30 FPS

立即體驗

如要查看此 API 的範例，請搭配範例應用程式。

事前準備

這個 API 需要 Android API 級別 19 以上的版本。請確認應用程式的建構檔案使用 19 以上的 minSdkVersion 值。

在專案層級的 build.gradle 檔案中，請務必將 Google 的 Maven 存放區加進 buildscript 和 allprojects 區段。

將 ML Kit Android 程式庫的依附元件新增至模組的應用程式層級 Gradle 檔案，通常為 app/build.gradle：

dependencies {
  // If you want to use the base sdk
  implementation 'com.google.mlkit:pose-detection:18.0.0-beta3'
  // If you want to use the accurate sdk
  implementation 'com.google.mlkit:pose-detection-accurate:18.0.0-beta3'
}

1. 建立 `PoseDetector` 的執行個體

`PoseDetector` 種付款方式

如要偵測圖片中的姿勢，請先建立 PoseDetector 的執行個體，並視需要指定偵測工具設定。

偵測模式

PoseDetector 會在兩種偵測模式下運作。請務必選擇符合用途的用途。

STREAM_MODE (預設): 姿勢偵測器會先偵測圖片中最顯眼的部分，然後執行姿勢偵測。在接下來的影格中，除非使用者被遮蔽，或不再有信心進行偵測，否則系統不會執行人員偵測步驟。姿勢偵測器會嘗試追蹤最顯眼的人，並傳回每次推論的姿勢。藉此降低延遲和順暢偵測。如要偵測影片串流中的姿勢，請使用這個模式。
SINGLE_IMAGE_MODE: 姿勢偵測器會偵測一個人，然後執行姿勢偵測。系統會針對每張圖片執行人為偵測步驟，因此延遲時間會較長，且不會追蹤個別使用者。對靜態圖片使用姿勢偵測時，請使用這個模式。

硬體設定

PoseDetector 支援多種硬體設定，可將效能最佳化：

CPU：僅使用 CPU 執行偵測工具
CPU_GPU：同時使用 CPU 和 GPU 執行偵測工具

建構偵測工具選項時，您可以使用 API setPreferredHardwareConfigs 來控制硬體選項。根據預設，所有硬體設定都會設為偏好的偏好設定。

ML Kit 會將每項設定的可用性、穩定性、正確性和延遲時間納入考量，並從偏好的設定中挑選最佳設定。如果沒有適用的偏好設定，系統就會自動使用 CPU 設定做為備用設定。在啟用任何加速功能之前，ML Kit 會以非阻塞的方式執行這些檢查和相關準備工作，因此很可能是使用者首次執行偵測工具時，就會使用 CPU。所有準備作業都完成後，最佳設定會在下列執行作業中使用。

setPreferredHardwareConfigs 的使用範例：

為了讓 ML Kit 挑選最合適的設定，請勿呼叫這個 API。
如果不想啟用任何加速功能，請傳入 CPU。
如果想使用 GPU 來卸載 CPU (即使速度可能較慢)，請僅在 CPU_GPU 中傳遞。

指定 pose 偵測工具選項：

Kotlin

// Base pose detector with streaming frames, when depending on the pose-detection sdk
val options = PoseDetectorOptions.Builder()
    .setDetectorMode(PoseDetectorOptions.STREAM_MODE)
    .build()

// Accurate pose detector on static images, when depending on the pose-detection-accurate sdk
val options = AccuratePoseDetectorOptions.Builder()
    .setDetectorMode(AccuratePoseDetectorOptions.SINGLE_IMAGE_MODE)
    .build()

Java

// Base pose detector with streaming frames, when depending on the pose-detection sdk
PoseDetectorOptions options =
   new PoseDetectorOptions.Builder()
       .setDetectorMode(PoseDetectorOptions.STREAM_MODE)
       .build();

// Accurate pose detector on static images, when depending on the pose-detection-accurate sdk
AccuratePoseDetectorOptions options =
   new AccuratePoseDetectorOptions.Builder()
       .setDetectorMode(AccuratePoseDetectorOptions.SINGLE_IMAGE_MODE)
       .build();

最後，建立 PoseDetector 的執行個體。傳遞您指定的選項：

Kotlin

val poseDetector = PoseDetection.getClient(options)

Java

PoseDetector poseDetector = PoseDetection.getClient(options);

2. 準備輸入圖片

如要偵測圖片中的姿勢，請透過 Bitmap、media.Image、ByteBuffer、位元組陣列或裝置上的檔案建立 InputImage 物件。然後，將 InputImage 物件傳遞至 PoseDetector。

針對姿勢偵測，請使用大小至少為 480x360 像素的圖片。如果您是即時偵測姿勢，並以這個最低解析度擷取影格，有助於縮短延遲時間。

您可以從不同來源建立 InputImage 物件，詳情請參閱下文。

使用 `media.Image`

如要從 media.Image 物件建立 InputImage 物件 (例如從裝置的相機擷取圖片時)，請將 media.Image 物件和圖片的旋轉傳遞至 InputImage.fromMediaImage()。

使用 CameraX 程式庫時，OnImageCapturedListener 和 ImageAnalysis.Analyzer 類別會為你計算旋轉值。

Kotlin

private class YourImageAnalyzer : ImageAnalysis.Analyzer {

    override fun analyze(imageProxy: ImageProxy) {
        val mediaImage = imageProxy.image
        if (mediaImage != null) {
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

    @Override
    public void analyze(ImageProxy imageProxy) {
        Image mediaImage = imageProxy.getImage();
        if (mediaImage != null) {
          InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees());
          // Pass image to an ML Kit Vision API
          // ...
        }
    }
}

如果未使用相機提供圖片旋轉角度的相機，則可以從裝置的旋轉角度和裝置相機感應器的方向進行計算：

Kotlin

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 0)
    ORIENTATIONS.append(Surface.ROTATION_90, 90)
    ORIENTATIONS.append(Surface.ROTATION_180, 180)
    ORIENTATIONS.append(Surface.ROTATION_270, 270)
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Throws(CameraAccessException::class)
private fun getRotationCompensation(cameraId: String, activity: Activity, isFrontFacing: Boolean): Int {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    val deviceRotation = activity.windowManager.defaultDisplay.rotation
    var rotationCompensation = ORIENTATIONS.get(deviceRotation)

    // Get the device's sensor orientation.
    val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360
    }
    return rotationCompensation
}MLKitVisionImage.kt

Java

private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 0);
    ORIENTATIONS.append(Surface.ROTATION_90, 90);
    ORIENTATIONS.append(Surface.ROTATION_180, 180);
    ORIENTATIONS.append(Surface.ROTATION_270, 270);
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
private int getRotationCompensation(String cameraId, Activity activity, boolean isFrontFacing)
        throws CameraAccessException {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
    int rotationCompensation = ORIENTATIONS.get(deviceRotation);

    // Get the device's sensor orientation.
    CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360;
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360;
    }
    return rotationCompensation;
}

然後將 media.Image 物件和旋轉角度值傳遞至 InputImage.fromMediaImage()：

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)MLKitVisionImage.kt

Java

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

使用檔案 URI

如要從檔案 URI 建立 InputImage 物件，請將應用程式結構定義和檔案 URI 傳遞至 InputImage.fromFilePath()。如果您使用 ACTION_GET_CONTENT 意圖提示使用者從圖片庫應用程式中選取圖片，這個方法就非常實用。

Kotlin

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}MLKitVisionImage.kt

Java

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

使用 `ByteBuffer` 或 `ByteArray`

如要從 ByteBuffer 或 ByteArray 建立 InputImage 物件，請先按照之前的 media.Image 輸入值計算圖片旋轉角度。接著，使用緩衝區或陣列建立 InputImage 物件，以及圖片的高度、寬度、顏色編碼格式和旋轉角度：

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);MLKitVisionImage.java

使用 `Bitmap`

如要從 Bitmap 物件建立 InputImage 物件，請進行以下宣告：

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)MLKitVisionImage.kt

Java

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);MLKitVisionImage.java

圖片會以 Bitmap 物件搭配旋轉角度表示。

3. 處理圖片

將事先準備的 InputImage 物件傳遞至 PoseDetector 的 process 方法。

Kotlin

Task<Pose> result = poseDetector.process(image)
       .addOnSuccessListener { results ->
           // Task completed successfully
           // ...
       }
       .addOnFailureListener { e ->
           // Task failed with an exception
           // ...
       }

Java

Task<Pose> result =
        poseDetector.process(image)
                .addOnSuccessListener(
                        new OnSuccessListener<Pose>() {
                            @Override
                            public void onSuccess(Pose pose) {
                                // Task completed successfully
                                // ...
                            }
                        })
                .addOnFailureListener(
                        new OnFailureListener() {
                            @Override
                            public void onFailure(@NonNull Exception e) {
                                // Task failed with an exception
                                // ...
                            }
                        });

注意：如果您使用的是 CameraX API，請務必在使用完成後關閉 ImageProxy，例如，將 OnCompleteListener 新增至 process 方法傳回的 Task 中。如需查看範例，請參閱快速入門導覽課程範例應用程式中的 VisionProcessorBase 類別。

4. 取得偵測到的姿勢相關資訊

如果系統在圖片中偵測到人物，姿勢偵測 API 會傳回具有 33 PoseLandmark 的 Pose 物件。

如果人物未完全收錄在圖片中，模型會指派缺少的影格座標，並提供低的 InFrameConfidence 值。

如果在頁框中未偵測到任何使用者，Pose 物件就不會包含 PoseLandmark。

Kotlin

// Get all PoseLandmarks. If no person was detected, the list will be empty
val allPoseLandmarks = pose.getAllPoseLandmarks()

// Or get specific PoseLandmarks individually. These will all be null if no person
// was detected
val leftShoulder = pose.getPoseLandmark(PoseLandmark.LEFT_SHOULDER)
val rightShoulder = pose.getPoseLandmark(PoseLandmark.RIGHT_SHOULDER)
val leftElbow = pose.getPoseLandmark(PoseLandmark.LEFT_ELBOW)
val rightElbow = pose.getPoseLandmark(PoseLandmark.RIGHT_ELBOW)
val leftWrist = pose.getPoseLandmark(PoseLandmark.LEFT_WRIST)
val rightWrist = pose.getPoseLandmark(PoseLandmark.RIGHT_WRIST)
val leftHip = pose.getPoseLandmark(PoseLandmark.LEFT_HIP)
val rightHip = pose.getPoseLandmark(PoseLandmark.RIGHT_HIP)
val leftKnee = pose.getPoseLandmark(PoseLandmark.LEFT_KNEE)
val rightKnee = pose.getPoseLandmark(PoseLandmark.RIGHT_KNEE)
val leftAnkle = pose.getPoseLandmark(PoseLandmark.LEFT_ANKLE)
val rightAnkle = pose.getPoseLandmark(PoseLandmark.RIGHT_ANKLE)
val leftPinky = pose.getPoseLandmark(PoseLandmark.LEFT_PINKY)
val rightPinky = pose.getPoseLandmark(PoseLandmark.RIGHT_PINKY)
val leftIndex = pose.getPoseLandmark(PoseLandmark.LEFT_INDEX)
val rightIndex = pose.getPoseLandmark(PoseLandmark.RIGHT_INDEX)
val leftThumb = pose.getPoseLandmark(PoseLandmark.LEFT_THUMB)
val rightThumb = pose.getPoseLandmark(PoseLandmark.RIGHT_THUMB)
val leftHeel = pose.getPoseLandmark(PoseLandmark.LEFT_HEEL)
val rightHeel = pose.getPoseLandmark(PoseLandmark.RIGHT_HEEL)
val leftFootIndex = pose.getPoseLandmark(PoseLandmark.LEFT_FOOT_INDEX)
val rightFootIndex = pose.getPoseLandmark(PoseLandmark.RIGHT_FOOT_INDEX)
val nose = pose.getPoseLandmark(PoseLandmark.NOSE)
val leftEyeInner = pose.getPoseLandmark(PoseLandmark.LEFT_EYE_INNER)
val leftEye = pose.getPoseLandmark(PoseLandmark.LEFT_EYE)
val leftEyeOuter = pose.getPoseLandmark(PoseLandmark.LEFT_EYE_OUTER)
val rightEyeInner = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE_INNER)
val rightEye = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE)
val rightEyeOuter = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE_OUTER)
val leftEar = pose.getPoseLandmark(PoseLandmark.LEFT_EAR)
val rightEar = pose.getPoseLandmark(PoseLandmark.RIGHT_EAR)
val leftMouth = pose.getPoseLandmark(PoseLandmark.LEFT_MOUTH)
val rightMouth = pose.getPoseLandmark(PoseLandmark.RIGHT_MOUTH)

Java

// Get all PoseLandmarks. If no person was detected, the list will be empty
List<PoseLandmark> allPoseLandmarks = pose.getAllPoseLandmarks();

// Or get specific PoseLandmarks individually. These will all be null if no person
// was detected
PoseLandmark leftShoulder = pose.getPoseLandmark(PoseLandmark.LEFT_SHOULDER);
PoseLandmark rightShoulder = pose.getPoseLandmark(PoseLandmark.RIGHT_SHOULDER);
PoseLandmark leftElbow = pose.getPoseLandmark(PoseLandmark.LEFT_ELBOW);
PoseLandmark rightElbow = pose.getPoseLandmark(PoseLandmark.RIGHT_ELBOW);
PoseLandmark leftWrist = pose.getPoseLandmark(PoseLandmark.LEFT_WRIST);
PoseLandmark rightWrist = pose.getPoseLandmark(PoseLandmark.RIGHT_WRIST);
PoseLandmark leftHip = pose.getPoseLandmark(PoseLandmark.LEFT_HIP);
PoseLandmark rightHip = pose.getPoseLandmark(PoseLandmark.RIGHT_HIP);
PoseLandmark leftKnee = pose.getPoseLandmark(PoseLandmark.LEFT_KNEE);
PoseLandmark rightKnee = pose.getPoseLandmark(PoseLandmark.RIGHT_KNEE);
PoseLandmark leftAnkle = pose.getPoseLandmark(PoseLandmark.LEFT_ANKLE);
PoseLandmark rightAnkle = pose.getPoseLandmark(PoseLandmark.RIGHT_ANKLE);
PoseLandmark leftPinky = pose.getPoseLandmark(PoseLandmark.LEFT_PINKY);
PoseLandmark rightPinky = pose.getPoseLandmark(PoseLandmark.RIGHT_PINKY);
PoseLandmark leftIndex = pose.getPoseLandmark(PoseLandmark.LEFT_INDEX);
PoseLandmark rightIndex = pose.getPoseLandmark(PoseLandmark.RIGHT_INDEX);
PoseLandmark leftThumb = pose.getPoseLandmark(PoseLandmark.LEFT_THUMB);
PoseLandmark rightThumb = pose.getPoseLandmark(PoseLandmark.RIGHT_THUMB);
PoseLandmark leftHeel = pose.getPoseLandmark(PoseLandmark.LEFT_HEEL);
PoseLandmark rightHeel = pose.getPoseLandmark(PoseLandmark.RIGHT_HEEL);
PoseLandmark leftFootIndex = pose.getPoseLandmark(PoseLandmark.LEFT_FOOT_INDEX);
PoseLandmark rightFootIndex = pose.getPoseLandmark(PoseLandmark.RIGHT_FOOT_INDEX);
PoseLandmark nose = pose.getPoseLandmark(PoseLandmark.NOSE);
PoseLandmark leftEyeInner = pose.getPoseLandmark(PoseLandmark.LEFT_EYE_INNER);
PoseLandmark leftEye = pose.getPoseLandmark(PoseLandmark.LEFT_EYE);
PoseLandmark leftEyeOuter = pose.getPoseLandmark(PoseLandmark.LEFT_EYE_OUTER);
PoseLandmark rightEyeInner = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE_INNER);
PoseLandmark rightEye = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE);
PoseLandmark rightEyeOuter = pose.getPoseLandmark(PoseLandmark.RIGHT_EYE_OUTER);
PoseLandmark leftEar = pose.getPoseLandmark(PoseLandmark.LEFT_EAR);
PoseLandmark rightEar = pose.getPoseLandmark(PoseLandmark.RIGHT_EAR);
PoseLandmark leftMouth = pose.getPoseLandmark(PoseLandmark.LEFT_MOUTH);
PoseLandmark rightMouth = pose.getPoseLandmark(PoseLandmark.RIGHT_MOUTH);

改善成效的訣竅

你的搜尋結果品質取決於輸入圖片的品質：

為讓 ML Kit 正確偵測姿勢，圖片中的人物角色應有足夠的像素資料；為獲得最佳效能，拍攝主體至少須為 256x256 像素。
如果您在即時應用程式中偵測姿勢，您也應該考慮輸入圖片的整體尺寸。小型圖片的處理速度更快，因此為了降低延遲，請盡量降低解析度以拍攝圖片，但請謹記上述解析度要求，並盡可能確保拍攝主體盡可能佔滿圖片中的比例。
圖片品質不佳可能會影響準確率。如果未收到可接受的結果，請要求使用者重新拍攝圖片。

如要在即時應用程式中使用姿勢偵測，請按照下列指南達成最佳影格速率：

使用基本姿勢偵測 SDK 和 STREAM_MODE。
建議以較低解析度拍攝圖片。另請注意，這個 API 的圖片尺寸規定。
如果使用 Camera 或 camera2 API，請將呼叫傳送至偵測工具。偵測器執行時，如果偵測到新的影片畫面，請捨棄影格。如需範例，請參閱快速入門導覽課程範例應用程式中的 VisionProcessorBase 類別。
如果您使用 CameraX API，請務必將背壓策略設為預設值 ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST。這只會傳送一張圖片進行分析。如果分析器忙碌時產生的更多圖片，系統會自動捨棄圖片，且不會排入佇列進行傳送。呼叫 ImageProxy.close() 關閉分析的圖片後，就會傳送下一張最新圖片。
如果您使用偵測工具的輸出內容在輸入圖片上疊加圖片，請先透過 ML Kit 取得結果，然後在單一步驟中顯示圖片和疊加層。每個輸入影格只會轉譯到一次顯示途徑。如需範例，請參閱快速入門導覽課程範例應用程式中的 CameraSourcePreview 和 GraphicOverlay 類別。
如果您使用 Camera2 API，請擷取 ImageFormat.YUV_420_888 格式的圖片。如果您使用舊版 Camera API，請擷取 ImageFormat.NV21 格式的圖片。

後續步驟

如何使用姿勢地標分類姿勢，請參閱「配色分類提示」。

在 Android 上使用 ML Kit 偵測姿勢

立即體驗

事前準備

1. 建立 PoseDetector 的執行個體

PoseDetector 種付款方式

偵測模式

硬體設定

Kotlin

Java

Kotlin

Java

2. 準備輸入圖片

使用 media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

使用檔案 URI

Kotlin

Java

使用 ByteBuffer 或 ByteArray

Kotlin

Java

使用 Bitmap

Kotlin

Java

3. 處理圖片

Kotlin

Java

4. 取得偵測到的姿勢相關資訊

Kotlin

Java

改善成效的訣竅

後續步驟

1. 建立 `PoseDetector` 的執行個體

`PoseDetector` 種付款方式

使用 `media.Image`

使用 `ByteBuffer` 或 `ByteArray`

使用 `Bitmap`