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

在 Android 上使用 ML Kit 偵測姿勢
透過集合功能整理內容你可以依據偏好儲存及分類內容。

ML Kit 提供兩個經過最佳化的姿勢偵測 SDK。

SDK 名稱	pose-detection	pose-detection-accurate
導入作業	程式碼和素材資源會在建構期間與應用程式建立靜態連結。	程式碼和素材資源會在建構期間與應用程式建立靜態連結。
應用程式大小影響 (包括程式碼和素材資源)	~10.1MB	~13.3MB
成效	Pixel 3 XL：約 30 FPS	Pixel 3XL：CPU 約 23 FPS、GPU 約 30 FPS

立即試用

請試用範例應用程式，瞭解這個 API 的使用範例。

事前準備

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

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

將 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-beta5'
  // If you want to use the accurate sdk
  implementation 'com.google.mlkit:pose-detection-accurate:18.0.0-beta5'
}

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 (即使 GPU 可能較慢)，請只傳入 CPU_GPU。

指定姿勢偵測器選項：

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

Java

Task result =
        poseDetector.process(image)
                .addOnSuccessListener(
                        new OnSuccessListener() {
                            @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，例如在 process 方法傳回的 Task 中新增 OnCompleteListener。如需範例，請參閱快速入門範例應用程式中的 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 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 準確偵測姿勢，圖片中的人物應包含足夠的像素資料；為求最佳效能，主體至少應為 256 x 256 像素。
如果您要在即時應用程式中偵測姿勢，也許也要考慮輸入圖片的整體尺寸。較小的圖片可加快處理速度，因此為了減少延遲時間，請以較低解析度拍攝圖片，但請注意上述解析度規定，並確保拍攝主體盡可能佔據圖片的大部分空間。
圖片對焦不佳也會影響準確度。如果您無法取得可接受的結果，請要求使用者重新拍攝圖片。

如果您想在即時應用程式中使用姿勢偵測功能，請按照下列指南取得最佳影格速率：

使用基礎姿勢偵測 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

提升成效的訣竅

後續步驟

在 Android 上使用 ML Kit 偵測姿勢
透過集合功能整理內容你可以依據偏好儲存及分類內容。

1. 建立 `PoseDetector` 的例項

`PoseDetector` 種付款方式

使用 `media.Image`

使用 `ByteBuffer` 或 `ByteArray`

使用 `Bitmap`