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

在 Android 上使用自訂分類模型來偵測、追蹤及分類物件

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

將圖片傳送至 ML Kit 時，模型最多可偵測圖片中的五個物件以及每個物件在圖片中的位置。偵測中的物件時影片串流，每個物件都有專屬 ID，可用來追蹤每個影格都不成問題

您可以利用自訂圖片分類模型，將屬於。請參閱「使用 ML Kit 自訂模型」一文我們對於模型相容性需求的指引、如何找到預先訓練模型以及如何訓練自有模型

整合自訂模型的方式有兩種。您可以將模型將檔案放入應用程式的素材資源資料夾，或者可以透過動態方式下載。下表比較這兩種選項。

套裝組合模型	託管模型
這個模型是應用程式 APK 的一部分，會增加其大小。	這個模型並非 APK 的一部分。這是由上傳至 Firebase 機器學習
可立即使用型號，即使 Android 裝置離線也沒問題	模型會隨選下載
不需要 Firebase 專案	需要 Firebase 專案
您必須重新發布應用程式才能更新模型	不必重新發布應用程式即可推送模型更新
沒有內建 A/B 測試	使用 Firebase 遠端設定輕鬆進行 A/B 測試

立即試用

請參閱視覺快速入門導覽課程應用程式查看隨附模型的使用範例 automl 快速入門導覽課程應用程式託管模型的使用範例
請參閱 Material Design 展示區應用程式，瞭解這個 API 的端對端實作。

事前準備

請務必在專案層級的 build.gradle 檔案中納入位於 buildscript 和的 Google Maven 存放區 allprojects 個版面。

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

將模型與應用程式綁定：

dependencies {
  // ...
  // Object detection & tracking feature with custom bundled model
  implementation 'com.google.mlkit:object-detection-custom:17.0.2'
}

如要從 Firebase 動態下載模型，請新增 linkFirebase 依附元件：

dependencies {
  // ...
  // Object detection & tracking feature with model downloaded
  // from firebase
  implementation 'com.google.mlkit:object-detection-custom:17.0.2'
  implementation 'com.google.mlkit:linkfirebase:17.0.0'
}

如要下載模型，請務必將 Firebase 新增至您的 Android 專案，如果尚未建立當您要組合模型時，不必做出任何動作。

1. 載入模型

設定本機模型來源

將模型與應用程式組合如下：

將模型檔案 (通常結尾為 .tflite 或 .lite) 複製到應用程式的 assets/資料夾。(您可能需要先建立資料夾，在 app/ 資料夾上按一下滑鼠右鍵，然後點選 新增 >資料夾 >素材資源資料夾)。
接著，請將以下內容新增至應用程式的 build.gradle 檔案，確保 Gradle 不會在建構應用程式時壓縮模型檔案：
```
android {
    // ...
    aaptOptions {
        noCompress "tflite"
        // or noCompress "lite"
    }
}
```
模型檔案將包含在應用程式套件中，並可供 ML Kit 使用做為原始素材資源

注意： 自 Android Gradle 外掛程式 4.1 版起，.tflite 將改為 .tflite 已預設新增至 noCompress 清單，不再需要上述方法。

建立 LocalModel 物件，指定模型檔案的路徑：

Kotlin

val localModel = LocalModel.Builder()
        .setAssetFilePath("model.tflite")
        // or .setAbsoluteFilePath(absolute file path to model file)
        // or .setUri(URI to model file)
        .build()

Java

LocalModel localModel =
    new LocalModel.Builder()
        .setAssetFilePath("model.tflite")
        // or .setAbsoluteFilePath(absolute file path to model file)
        // or .setUri(URI to model file)
        .build();

設定 Firebase 託管的模型來源

如要使用遠端託管模型，請建立 CustomRemoteModel 物件： FirebaseModelSource，指定您在建立模型時指派模型的名稱已發布：

Kotlin

// Specify the name you assigned in the Firebase console.
val remoteModel =
    CustomRemoteModel
        .Builder(FirebaseModelSource.Builder("your_model_name").build())
        .build()

Java

// Specify the name you assigned in the Firebase console.
CustomRemoteModel remoteModel =
    new CustomRemoteModel
        .Builder(new FirebaseModelSource.Builder("your_model_name").build())
        .build();

接著，啟動模型下載工作，並指定在您要允許下載的應用程式。如果裝置上沒有該型號，或者是新型號就能以非同步方式下載該模型建立 Vertex AI 模型

Kotlin

val downloadConditions = DownloadConditions.Builder()
    .requireWifi()
    .build()
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
    .addOnSuccessListener {
        // Success.
    }

Java

DownloadConditions downloadConditions = new DownloadConditions.Builder()
        .requireWifi()
        .build();
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(@NonNull Task task) {
                // Success.
            }
        });

許多應用程式會在初始化程式碼中啟動下載工作，但您這個模型會在您需要使用模型前執行

2. 設定物件偵測工具

設定模型來源後，請設定物件偵測工具針對 CustomObjectDetectorOptions 物件的用途建構應用程式。您可以變更以下設定：

物件偵測器設定
偵測模式	`STREAM_MODE` (預設) \|`SINGLE_IMAGE_MODE` 在 `STREAM_MODE` (預設) 中，物件偵測工具會執行低延遲，但可能產生不完整的結果 (例如未指定定界框或類別標籤) 每個回呼函式的保留時間。此外，在「`STREAM_MODE`」中：偵測工具會指派追蹤 ID 給物件，您可以用來跨影格追蹤物件使用此模式追蹤或低延遲的重要時機觀看串流影片在 `SINGLE_IMAGE_MODE` 中，物件偵測工具會傳回會測量物件的定界框。如果發生以下情況：也會啟用分類功能方塊和類別標籤因此可能更長的時間偵測。此外，在 `SINGLE_IMAGE_MODE`，未指派追蹤 ID。使用因此若延遲時間不重要且也不想處理但只有部分結果
偵測並追蹤多個物件	`false` (預設) \|`true` 偵測及追蹤最多五個物件明顯的物件 (預設)。
將物件分類	`false` (預設) \|`true` 是否使用提供的和自訂分類器模型使用自訂分類您必須先將這個參數設為 `true`
分類可信度門檻	偵測到標籤的最低可信度分數。如果未設定系統會使用模型中繼資料指定的分類器門檻。如果模型未包含任何中繼資料，或中繼資料不包含指定分類器門檻，預設門檻為 0.0
每個物件的標籤數量上限	偵測工具的每個物件標籤數量上限傳回。如未設定，系統會使用預設值 10。

物件偵測及追蹤 API 已針對這兩種核心用途進行最佳化案件：

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

如要使用本機封裝模型設定這些用途的 API：

Kotlin

// Live detection and tracking
val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(localModel)
        .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE)
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

// Multiple object detection in static images
val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(localModel)
        .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableMultipleObjects()
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

val objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions)

Java

// Live detection and tracking
CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(localModel)
                .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE)
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

// Multiple object detection in static images
CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(localModel)
                .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableMultipleObjects()
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

ObjectDetector objectDetector =
    ObjectDetection.getClient(customObjectDetectorOptions);

如果您使用的是遠端託管的模型，則須檢查該模型是否已執行前已下載完成您可以查看模型下載狀態工作使用模型管理員的 isModelDownloaded() 方法。

雖然您不必在執行偵測工具前確認同時擁有遠端託管和本機封裝模型要在將圖片偵測工具例項化時執行這項檢查，您可以建立一個從遠端模型下載反之。

Kotlin

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener { isDownloaded ->
    val optionsBuilder =
        if (isDownloaded) {
            CustomObjectDetectorOptions.Builder(remoteModel)
        } else {
            CustomObjectDetectorOptions.Builder(localModel)
        }
    val customObjectDetectorOptions = optionsBuilder
            .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
            .enableClassification()
            .setClassificationConfidenceThreshold(0.5f)
            .setMaxPerObjectLabelCount(3)
            .build()
    val objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions)
}

Java

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener(new OnSuccessListener() {
        @Override
        public void onSuccess(Boolean isDownloaded) {
            CustomObjectDetectorOptions.Builder optionsBuilder;
            if (isDownloaded) {
                optionsBuilder = new CustomObjectDetectorOptions.Builder(remoteModel);
            } else {
                optionsBuilder = new CustomObjectDetectorOptions.Builder(localModel);
            }
            CustomObjectDetectorOptions customObjectDetectorOptions = optionsBuilder
                .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();
            ObjectDetector objectDetector =
                ObjectDetection.getClient(customObjectDetectorOptions);
        }
});

如果只有遠端託管的模型，請停用模型相關或隱藏部分 UI，直到您確認模型已下載完成附加監聽器即可複製到模型管理工具的 download() 方法：

Kotlin

RemoteModelManager.getInstance().download(remoteModel, conditions)
    .addOnSuccessListener {
        // Download complete. Depending on your app, you could enable the ML
        // feature, or switch from the local model to the remote model, etc.
    }

Java

RemoteModelManager.getInstance().download(remoteModel, conditions)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(Void v) {
              // Download complete. Depending on your app, you could enable
              // the ML feature, or switch from the local model to the remote
              // model, etc.
            }
        });

3. 準備輸入圖片

從您的圖片建立 InputImage 物件。物件偵測工具會直接從 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 物件和旋轉角度表示。

4. 執行物件偵測工具

Kotlin

objectDetector
    .process(image)
    .addOnFailureListener(e -> {...})
    .addOnSuccessListener(results -> {
        for (detectedObject in results) {
          // ...
        }
    });

Java

objectDetector
    .process(image)
    .addOnFailureListener(e -> {...})
    .addOnSuccessListener(results -> {
        for (DetectedObject detectedObject : results) {
          // ...
        }
    });

注意：如果您使用的是 CameraX API，請務必在使用完畢後關閉 ImageProxy。例如，將 OnCompleteListener 新增至Task process 方法。詳情請參閱 VisionProcessorBase 類別的範例。

5. 取得加上標籤的物件相關資訊

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

每個 DetectedObject 都包含下列屬性：

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

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

標籤

標籤說明	標籤的文字說明。只有在 TensorFlow 的情況下才會傳回 Lite 模型的中繼資料包含標籤說明。
標籤索引	此標籤在分類器。
標籤可信度	物件分類的可信度值。

Kotlin

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (detectedObject in results) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
      val text = label.text
      val index = label.index
      val confidence = label.confidence
    }
}

Java

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (DetectedObject detectedObject : results) {
  Rect boundingBox = detectedObject.getBoundingBox();
  Integer trackingId = detectedObject.getTrackingId();
  for (Label label : detectedObject.getLabels()) {
    String text = label.getText();
    int index = label.getIndex();
    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 上使用自訂分類模型來偵測、追蹤及分類物件

立即試用

事前準備

1. 載入模型

設定本機模型來源

Kotlin

Java

設定 Firebase 託管的模型來源

Kotlin

Java

Kotlin

Java

2. 設定物件偵測工具

Kotlin

Java

Kotlin

Java

Kotlin

Java

3. 準備輸入圖片

使用 media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

使用檔案 URI

Kotlin

Java

使用 ByteBuffer 或 ByteArray

Kotlin

Java

使用 Bitmap

Kotlin

Java

4. 執行物件偵測工具

Kotlin

Java

5. 取得加上標籤的物件相關資訊

Kotlin

Java

確保良好的使用者體驗

提升效能

使用 `media.Image`

使用 `ByteBuffer` 或 `ByteArray`

使用 `Bitmap`