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

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

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

將圖片傳送至 ML Kit 時，模型最多可偵測圖片中的五個物件以及每個物件在圖片中的位置。偵測中的物件時影片串流，每個物件都有專屬 ID，可用來追蹤每個影格都不成問題您也可以視需要啟用粗略物件也就是將物件加上廣泛類別說明的標籤

立即試用

使用範例應用程式試試請查看此 API 的使用範例。
請參閱 Material Design 展示區應用程式，瞭解這個 API 的端對端實作。

事前準備

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

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

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

}
```

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 不同來源的 ANR 物件，說明如下。

使用 `media.Image`

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

如果您使用 CameraX 程式庫、OnImageCapturedListener 和 ImageAnalysis.Analyzer 類別會計算旋轉值不必確保憑證管理是否適當因為 Google Cloud 會為您管理安全性

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

如要建立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`

如要建立InputImage ByteBuffer 或 ByteArray 的物件，請先計算圖片與先前 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`

如要建立InputImage 物件中，Bitmap 物件，請做出以下宣告：

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 新增至Task process 方法。詳情請參閱 VisionProcessorBase 類別的範例。

4. 取得偵測到的物件相關資訊

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

每個 DetectedObject 都包含下列屬性：

定界框 Rect，指出物件在圖片。

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

標籤

標籤說明	標籤的文字說明。這個值會是其中一個 String `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();
    }
}

確保良好的使用者體驗

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

是否成功偵測物件，取決於物件的視覺複雜度。於不過，如果物體具有少量視覺特徵將圖片放大出來您應該向使用者提供以便擷取適用於目標物件種類的輸入資料。
使用分類功能時，您可以偵測不會下降的物件完整地新增至支援的類別，並針對不明狀況導入特殊處理如需儲存大量結構化物件建議使用 Cloud Bigtable

此外，也請參閱 ML Kit 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`