Phát hiện, theo dõi và phân loại đối tượng bằng mô hình phân loại tuỳ chỉnh trên Android

Khi bạn truyền một hình ảnh đến Bộ công cụ học máy, Bộ công cụ này sẽ phát hiện tối đa 5 đối tượng trong hình ảnh cùng với vị trí của từng đối tượng trong hình ảnh. Khi phát hiện các đối tượng trong luồng video, mỗi đối tượng sẽ có một mã nhận dạng riêng biệt mà bạn có thể dùng để theo dõi đối tượng từ khung hình này sang khung hình khác.

Bạn có thể sử dụng mô hình phân loại hình ảnh tuỳ chỉnh để phân loại các đối tượng được phát hiện. Hãy tham khảo Các mô hình tuỳ chỉnh bằng Bộ công cụ học máy để biết hướng dẫn về các yêu cầu về khả năng tương thích của mô hình, nơi tìm các mô hình được huấn luyện trước và cách huấn luyện các mô hình của riêng bạn.

Có hai cách để tích hợp một mô hình tuỳ chỉnh. Bạn có thể gói mô hình bằng cách đặt mô hình đó vào thư mục tài sản của ứng dụng hoặc bạn có thể tải mô hình đó xuống một cách linh hoạt từ Cloud Storage. Bảng sau đây so sánh hai lựa chọn này.

Dùng thử

• Hãy xem ứng dụng bắt đầu nhanh về thị giác để biết ví dụ về cách sử dụng mô hình đi kèm và ứng dụng bắt đầu nhanh về AutoML để biết ví dụ về cách sử dụng mô hình được lưu trữ.
• Hãy xem ứng dụng trình diễn Material Design để biết cách triển khai API này từ đầu đến cuối.

Trước khi bắt đầu

1. Thêm các phần phụ thuộc cho thư viện Android của Bộ công cụ học máy vào tệp gradle cấp ứng dụng của mô-đun, thường là app/build.gradle.kts:

   Để gói một mô hình với ứng dụng của bạn:

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

2. Nếu bạn muốn tải một mô hình xuống từ Cloud Storage cho Firebase, hãy đảm bảo rằng bạn thêm Firebase vào dự án Android (nếu chưa thực hiện). Bạn không bắt buộc phải làm việc này khi gói mô hình.

1. Tải mô hình

Bạn có thể tải mô hình từ một nguồn được gói cục bộ hoặc một nguồn được lưu trữ từ xa.

Định cấu hình nguồn mô hình cục bộ

Cách gói mô hình với ứng dụng của bạn:

1. Sao chép tệp mô hình (thường kết thúc bằng .tflite hoặc .lite) vào thư mục assets/ của ứng dụng. (Trước tiên, bạn có thể cần tạo thư mục bằng cách nhấp chuột phải vào thư mục app/, sau đó nhấp vào New > Folder > Assets Folder (Mới > Thư mục > Thư mục thành phần)).

2. Tạo một đối tượng LocalModel, chỉ định đường dẫn đến tệp mô hình:

   Kotlin

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

   Java

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

Định cấu hình nguồn mô hình được lưu trữ từ xa

Để sử dụng mô hình được lưu trữ từ xa, bạn phải tải tệp mô hình xuống bộ nhớ cục bộ của thiết bị bằng logic ứng dụng của riêng mình, rồi tải tệp đó dưới dạng mô hình cục bộ. Bạn nên sử dụng Cloud Storage cho Firebase để lưu trữ mô hình. Để biết thông tin chi tiết về cách triển khai, hãy xem Hướng dẫn di chuyển Firebase ML sang Cloud Storage.

2. Định cấu hình trình phát hiện đối tượng

Sau khi định cấu hình các nguồn mô hình, hãy định cấu hình trình phát hiện đối tượng cho trường hợp sử dụng của bạn bằng một đối tượng CustomObjectDetectorOptions. Bạn có thể thay đổi các chế độ cài đặt sau:

API phát hiện và theo dõi đối tượng được tối ưu hoá cho 2 trường hợp sử dụng cốt lõi sau:

• Phát hiện và theo dõi trực tiếp đối tượng nổi bật nhất trong khung ngắm của camera.
• Phát hiện nhiều đối tượng trong một hình ảnh tĩnh.

Cách định cấu hình API cho các trường hợp sử dụng này bằng một mô hình được gói cục bộ:

// 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)

// 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);

Nếu có một mô hình được lưu trữ từ xa, bạn sẽ phải kiểm tra để đảm bảo mô hình đó đã được tải xuống trước khi chạy.

Mặc dù bạn chỉ phải xác nhận điều này trước khi chạy trình phát hiện, nhưng nếu có cả mô hình được lưu trữ từ xa và mô hình được gói cục bộ, thì bạn nên thực hiện bước kiểm tra này khi khởi tạo trình phát hiện hình ảnh: tạo trình phát hiện từ mô hình từ xa nếu mô hình đó đã được tải xuống và từ mô hình cục bộ nếu không.

val modelFile = File(context.cacheDir, "my_remote_model.tflite")

val model = if (modelFile.exists()) {
    // Use the downloaded model if available
    LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
} else {
    // Fall back to the bundled model
    LocalModel.Builder().setAssetFilePath("model.tflite").build()
}

val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(model)
        .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

val objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions)

File modelFile = new File(context.getCacheDir(), "my_remote_model.tflite");

LocalModel model;
if (modelFile.exists()) {
    // Use the downloaded model if available
    model = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
} else {
    // Fall back to the bundled model
    model = new LocalModel.Builder().setAssetFilePath("model.tflite").build();
}

CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(model)
                .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

ObjectDetector objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions);

Nếu chỉ có một mô hình được lưu trữ từ xa, bạn nên tắt chức năng liên quan đến mô hình (ví dụ: làm mờ hoặc ẩn một phần giao diện người dùng) cho đến khi xác nhận rằng mô hình đã được tải xuống.

val localFile = File(context.cacheDir, "my_remote_model.tflite")
if (localFile.exists()) {
    // Model is already cached, initialize immediately
    initializeDetector(localFile)
} else {
    // Model is not yet available, show loading UI and start download
    showLoadingUI()
    val storage = Firebase.storage
    val modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite")
    modelRef.getFile(localFile)
        .addOnSuccessListener {
            // Download complete, initialize the detector
            hideLoadingUI()
            initializeDetector(localFile)
        }
        .addOnFailureListener {
            // Handle download error
            showErrorUI()
        }
}

private fun initializeDetector(modelFile: File) {
    val localModel = LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
    val customObjectDetectorOptions = CustomObjectDetectorOptions.Builder(localModel)
            .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
            .enableClassification()
            .build()
    val objectDetector = ObjectDetection.getClient(customObjectDetectorOptions)
    // Enable ML-related UI features here
    enableMLFeatures(objectDetector)
}

File localFile = new File(context.getCacheDir(), "my_remote_model.tflite");
if (localFile.exists()) {
    // Model is already cached, initialize immediately
    initializeDetector(localFile);
} else {
    // Model is not yet available, show loading UI and start download
    showLoadingUI();
    FirebaseStorage storage = FirebaseStorage.getInstance();
    StorageReference modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite");
    modelRef.getFile(localFile)
        .addOnSuccessListener(new OnSuccessListener<FileDownloadTask.TaskSnapshot>() {
            @Override
            public void onSuccess(FileDownloadTask.TaskSnapshot taskSnapshot) {
                // Download complete, initialize the detector
                hideLoadingUI();
                initializeDetector(localFile);
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception exception) {
                // Handle download error
                showErrorUI();
            }
        });
}

private void initializeDetector(File modelFile) {
    LocalModel localModel = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
    CustomObjectDetectorOptions customObjectDetectorOptions =
            new CustomObjectDetectorOptions.Builder(localModel)
                    .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                    .enableClassification()
                    .build();
    ObjectDetector objectDetector = ObjectDetection.getClient(customObjectDetectorOptions);
    // Enable ML-related UI features here
    enableMLFeatures(objectDetector);
}

3. Chuẩn bị hình ảnh đầu vào

Bạn có thể tạo một đối tượng InputImage từ nhiều nguồn, mỗi nguồn được giải thích bên dưới.

Sử dụng media.Image

Để tạo một đối tượng InputImage từ một đối tượng media.Image, chẳng hạn như khi bạn chụp ảnh bằng camera của thiết bị, hãy truyền đối tượng media.Image và độ xoay của hình ảnh đến InputImage.fromMediaImage().

Nếu bạn sử dụng thư viện CameraX, các lớp OnImageCapturedListener và ImageAnalysis.Analyzer sẽ tính giá trị xoay cho bạn.

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
            // ...
        }
    }
}

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
          // ...
        }
    }
}

Nếu không dùng thư viện máy ảnh cho biết độ xoay của hình ảnh, bạn có thể tính độ xoay đó từ độ xoay của thiết bị và hướng của cảm biến camera trong thiết bị:

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

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;
}

Sau đó, hãy truyền đối tượng media.Image và giá trị độ xoay đến InputImage.fromMediaImage():

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

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

Sử dụng URI tệp

Để tạo một đối tượng InputImage từ một URI tệp, hãy truyền ngữ cảnh ứng dụng và URI tệp đến InputImage.fromFilePath(). Điều này hữu ích khi bạn dùng ý định ACTION_GET_CONTENT để nhắc người dùng chọn một hình ảnh trong ứng dụng thư viện của họ.

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

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

Sử dụng ByteBuffer hoặc ByteArray

Để tạo một đối tượng InputImage từ ByteBuffer hoặc ByteArray, trước tiên, hãy tính độ xoay của hình ảnh như mô tả trước đó cho đầu vào media.Image. Sau đó, hãy tạo đối tượng InputImage bằng vùng đệm hoặc mảng, cùng với chiều cao, chiều rộng, định dạng mã hoá màu và độ xoay của hình ảnh:

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

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

Sử dụng Bitmap

Để tạo một đối tượng InputImage từ một đối tượng Bitmap, hãy khai báo như sau:

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

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

Hình ảnh được biểu thị bằng một đối tượng Bitmap cùng với độ xoay.

4. Chạy trình phát hiện đối tượng

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

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

5. Xem thông tin về các đối tượng được gắn nhãn

Nếu lệnh gọi đến process() thành công, một danh sách DetectedObject sẽ được truyền đến trình nghe thành công.

Mỗi DetectedObject đều chứa các thuộc tính sau:

// 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
    }
}

// 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();
  }
}

Đảm bảo trải nghiệm chất lượng cao cho người dùng

Để mang lại trải nghiệm tốt nhất cho người dùng, hãy làm theo các nguyên tắc sau trong ứng dụng của bạn:

• Việc phát hiện đối tượng thành công phụ thuộc vào độ phức tạp về hình ảnh của đối tượng. Để được phát hiện, các đối tượng có ít đặc điểm thị giác có thể cần chiếm một phần lớn hơn trong hình ảnh. Bạn nên hướng dẫn người dùng cách ghi lại thông tin đầu vào phù hợp với loại đối tượng mà bạn muốn phát hiện.
• Khi sử dụng tính năng phân loại, nếu muốn phát hiện các đối tượng không thuộc các danh mục được hỗ trợ, hãy triển khai quy trình xử lý đặc biệt cho các đối tượng không xác định.

Ngoài ra, hãy xem ứng dụng minh hoạ Material Design của Bộ công cụ học máy và bộ sưu tập Các mẫu Material Design cho các tính năng dựa trên học máy.

Cải thiện hiệu suất

• Khi sử dụng chế độ truyền phát trực tiếp trong một ứng dụng theo thời gian thực, đừng sử dụng nhiều tính năng phát hiện đối tượng vì hầu hết các thiết bị sẽ không thể tạo ra tốc độ khung hình phù hợp.

• Nếu bạn sử dụng API Camera hoặc camera2, hãy điều tiết các lệnh gọi đến trình phát hiện. Nếu có một khung video mới trong khi trình phát hiện đang chạy, hãy thả khung đó. Hãy xem lớp VisionProcessorBase trong ứng dụng mẫu bắt đầu nhanh để biết ví dụ.
• Nếu bạn sử dụng API CameraX, hãy đảm bảo rằng chiến lược giảm áp suất được đặt thành giá trị mặc định ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Điều này đảm bảo rằng mỗi lần chỉ có một hình ảnh được gửi để phân tích. Nếu có nhiều hình ảnh được tạo ra khi trình phân tích đang bận, thì những hình ảnh đó sẽ tự động bị loại bỏ và không được đưa vào hàng đợi để phân phối. Sau khi hình ảnh đang được phân tích bị đóng bằng cách gọi ImageProxy.close(), hình ảnh mới nhất tiếp theo sẽ được phân phối.
• Nếu bạn dùng kết quả của trình phát hiện để phủ đồ hoạ lên hình ảnh đầu vào, trước tiên, hãy lấy kết quả từ Bộ công cụ học máy, sau đó kết xuất hình ảnh và lớp phủ trong một bước. Thao tác này chỉ kết xuất vào bề mặt hiển thị một lần cho mỗi khung đầu vào. Hãy xem các lớp CameraSourcePreview và GraphicOverlay trong ứng dụng mẫu bắt đầu nhanh để biết ví dụ.
• Nếu bạn sử dụng API Camera2, hãy chụp ảnh ở định dạng ImageFormat.YUV_420_888. Nếu bạn sử dụng API Camera cũ, hãy chụp ảnh ở định dạng ImageFormat.NV21.