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

在 Android 上使用 ML Kit 偵測及追蹤物件

您可以使用 ML Kit 偵測及追蹤連續影片畫面中的物件。

將圖片傳遞至 ML Kit 時，它會偵測圖片中最多五個物件，以及圖片中每個物件的位置。偵測影片串流中的物件時，每個物件都有專屬 ID，您可以用來追蹤各影格的物件。您也可以選擇啟用粗略的物件分類，將物件加上廣泛類別說明。

馬上試試

您可以試用範例應用程式，查看這個 API 的使用範例。
如需此 API 的端對端實作，請參閱 Material Design 展示應用程式。

事前準備

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

在專案層級的 build.gradle 檔案中，請務必在 buildscript 和 allprojects 區段中納入 Google 的 Maven 存放區。
將 ML Kit Android 程式庫的依附元件新增至模組的應用程式層級的 Gradle 檔案，通常為 app/build.gradle：
```
dependencies {
  // ...

  implementation 'com.google.mlkit:object-detection:17.0.1'

}
```

1. 設定物件偵測工具

如要偵測及追蹤物件，請先建立 ObjectDetector 的執行個體，並視需要指定要變更的偵測工具設定。

請使用 ObjectDetectorOptions 物件，根據您的用途設定物件偵測工具。您可以變更下列設定：

物件偵測器設定

偵測模式

物件偵測器設定
偵測模式	`STREAM_MODE` (預設) \| `SINGLE_IMAGE_MODE` 在 `STREAM_MODE` (預設) 中，物件偵測工具會在低延遲的情況下執行，但可能會在偵測工具的前幾次叫用時產生不完整的結果 (例如未指定的定界框或類別標籤)。此外，在 `STREAM_MODE` 中，偵測工具會將追蹤 ID 指派給物件，讓您用來跨影格追蹤物件。當您想追蹤物件，或覺得低延遲度很重要時 (例如即時處理影片串流)，請使用這個模式。在 `SINGLE_IMAGE_MODE` 中，物件偵測工具會在確定物件的定界框後傳回結果。如果您同時啟用分類功能，則在取得定界框和類別標籤後，系統會傳回結果。因此，偵測延遲時間可能會更長。此外，`SINGLE_IMAGE_MODE` 中不會指派追蹤 ID。如果延遲時間不重要，而且您不想處理部分結果，請使用這個模式。
偵測並追蹤多個物件	`false` (預設) \| `true` 可指定最多偵測及追蹤五個物件，還是僅偵測最顯眼的物件 (預設)。
將物件分類	`false` (預設) \| `true` 是否要將偵測到的物件歸類為粗略的類別。啟用後，物件偵測工具會將物件分為下列類別：時尚商品、食品、居家用品、地點和植物。

STREAM_MODE (預設) | SINGLE_IMAGE_MODE

在 STREAM_MODE (預設) 中，物件偵測工具會在低延遲的情況下執行，但可能會在偵測工具的前幾次叫用時產生不完整的結果 (例如未指定的定界框或類別標籤)。此外，在 STREAM_MODE 中，偵測工具會將追蹤 ID 指派給物件，讓您用來跨影格追蹤物件。當您想追蹤物件，或覺得低延遲度很重要時 (例如即時處理影片串流)，請使用這個模式。

在 SINGLE_IMAGE_MODE 中，物件偵測工具會在確定物件的定界框後傳回結果。如果您同時啟用分類功能，則在取得定界框和類別標籤後，系統會傳回結果。因此，偵測延遲時間可能會更長。此外，SINGLE_IMAGE_MODE 中不會指派追蹤 ID。如果延遲時間不重要，而且您不想處理部分結果，請使用這個模式。

偵測並追蹤多個物件

false (預設) | true

可指定最多偵測及追蹤五個物件，還是僅偵測最顯眼的物件 (預設)。

將物件分類

false (預設) | true

是否要將偵測到的物件歸類為粗略的類別。啟用後，物件偵測工具會將物件分為下列類別：時尚商品、食品、居家用品、地點和植物。

物件偵測和追蹤 API 已針對下列兩種核心用途進行最佳化：

在相機觀景窗中即時偵測及追蹤最顯眼的物件。
偵測靜態圖片中的多個物件。

如何針對這些用途設定 API：

Kotlin

// Live detection and tracking
val options = ObjectDetectorOptions.Builder()
        .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
        .enableClassification()  // Optional
        .build()

// Multiple object detection in static images
val options = ObjectDetectorOptions.Builder()
        .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableMultipleObjects()
        .enableClassification()  // Optional
        .build()

Java

// Live detection and tracking
ObjectDetectorOptions options =
        new ObjectDetectorOptions.Builder()
                .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
                .enableClassification()  // Optional
                .build();

// Multiple object detection in static images
ObjectDetectorOptions options =
        new ObjectDetectorOptions.Builder()
                .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableMultipleObjects()
                .enableClassification()  // Optional
                .build();

取得 ObjectDetector 的例項：

Kotlin

val objectDetector = ObjectDetection.getClient(options)

Java

ObjectDetector objectDetector = ObjectDetection.getClient(options);

2. 準備輸入圖片

如要偵測及追蹤物件，請將圖片傳遞至 ObjectDetector 執行個體的 process() 方法。

物件偵測工具會直接從 Bitmap、NV21 ByteBuffer 或 YUV_420_888 media.Image 執行。如果您能直接存取其中一個來源，建議從這些來源建構 InputImage。如果您從其他來源建構 InputImage，我們會在內部為您處理轉換，但效率可能會降低。

針對連續影片或圖片影格，執行下列操作：

您可以從不同來源建立 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. 處理圖片

將圖片傳遞至 process() 方法：

Kotlin

objectDetector.process(image)
    .addOnSuccessListener { detectedObjects ->
        // Task completed successfully
        // ...
    }
    .addOnFailureListener { e ->
        // Task failed with an exception
        // ...
    }

Java

objectDetector.process(image)
    .addOnSuccessListener(
        new OnSuccessListener<List<DetectedObject>>() {
            @Override
            public void onSuccess(List<DetectedObject> detectedObjects) {
                // 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. 取得偵測到的物件相關資訊

如果呼叫 process() 成功，系統會將 DetectedObject 清單傳遞至成功事件監聽器。

每個 DetectedObject 都包含下列屬性：

定界框 Rect，表示物件在圖片中的位置。

追蹤 ID 一個整數，可在圖片中識別物件。SINGLE_IMAGE_MODE 中有空值。

標籤

標籤說明	標籤的文字說明。這會是 `PredefinedCategory` 中定義的其中一個字串常數。
標籤索引	分類器支援的所有標籤中的標籤索引。這會是 `PredefinedCategory` 中定義的其中一個整數常數。
標籤可信度	物件分類的可信度值。

Kotlin

for (detectedObject in detectedObjects) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
        val text = label.text
        if (PredefinedCategory.FOOD == text) {
            ...
        }
        val index = label.index
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        val confidence = label.confidence
    }
}

Java

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (DetectedObject detectedObject : detectedObjects) {
    Rect boundingBox = detectedObject.getBoundingBox();
    Integer trackingId = detectedObject.getTrackingId();
    for (Label label : detectedObject.getLabels()) {
        String text = label.getText();
        if (PredefinedCategory.FOOD.equals(text)) {
            ...
        }
        int index = label.getIndex();
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        float confidence = label.getConfidence();
    }
}

確保良好的使用者體驗

為獲得最佳使用者體驗，請在應用程式中遵循以下規範：

是否成功偵測物件，取決於物件的視覺複雜度。為了偵測，如果物件只有少量視覺特徵，可能需要佔據較大的圖片部分。建議您向使用者提供指引，說明如何擷取可搭配想偵測的物件種類的輸入。
使用分類功能時，如果您想偵測未正常歸入支援類別的物件，請針對未知物件實作特殊處理。

此外，也請參閱 ML Kit Material Design 展示應用程式和 Material Design「機器學習輔助功能的模式」系列資源。

提升效能

如要在即時應用程式中使用物件偵測功能，請按照下列指南來達到最佳的影格速率：

在即時應用程式中使用串流模式時，請勿使用多個物件偵測，因為大多數裝置將無法產生適當的影格速率。
如果不需要分類功能，請停用分類功能。
如果使用 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. 設定物件偵測工具

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

確保良好的使用者體驗

提升效能

使用 `media.Image`

使用 `ByteBuffer` 或 `ByteArray`

使用 `Bitmap`