Memberi label pada gambar dengan model kustom di Android

Ada dua cara untuk mengintegrasikan pemberian label gambar dengan model kustom: dengan memaketkan pipeline sebagai bagian dari aplikasi Anda, atau dengan menggunakan pipeline yang tidak dipaketkan yang bergantung pada layanan Google Play. Jika Anda memilih pipeline yang tidak dipaketkan, ukuran aplikasi Anda akan lebih kecil. Lihat tabel berikut untuk mengetahui detailnya.

Ada dua cara untuk mengintegrasikan model kustom: memaketkan model dengan memasukkannya ke dalam folder aset aplikasi, atau mendownloadnya secara dinamis dari Firebase. Tabel berikut membandingkan kedua opsi ini.

Cobalah

• Lihat aplikasi panduan memulai vision untuk contoh penggunaan model yang dipaketkan dan aplikasi panduan memulai automl untuk contoh penggunaan model yang dihosting.

Sebelum memulai

1. Dalam file build.gradle.kts level project, pastikan Anda memasukkan repositori Maven Google di bagian buildscript dan allprojects.

2. Tambahkan dependensi untuk library Android ML Kit ke file gradle level aplikasi modul Anda, biasanya app/build.gradle.kts. Pilih salah satu dependensi berikut berdasarkan kebutuhan Anda:

   Untuk memaketkan pipeline dengan aplikasi Anda:

   dependencies {
     // ...
     // Use this dependency to bundle the pipeline with your app
     implementation("com.google.mlkit:image-labeling-custom:17.0.3")
   }
   

   Untuk menggunakan pipeline di layanan Google Play:

   dependencies {
     // ...
     // Use this dependency to use the dynamically downloaded pipeline in Google Play services
     implementation("com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta5")
   }
   

3. Jika Anda memilih untuk menggunakan pipeline di layanan Google Play, Anda dapat mengonfigurasi aplikasi agar mendownload pipeline secara otomatis ke perangkat setelah aplikasi diinstal dari Google Play Store. Untuk melakukannya, tambahkan deklarasi berikut ke file AndroidManifest.xml aplikasi Anda:

   <application ...>
       ...
       <meta-data
           android:name="com.google.mlkit.vision.DEPENDENCIES"
           android:value="custom_ica" />
       <!-- To use multiple downloads: android:value="custom_ica,download2,download3" -->
   </application>
   

   Anda juga dapat memeriksa ketersediaan pipeline secara eksplisit dan meminta download melalui layanan Google Play ModuleInstallClient API.

   Jika Anda tidak mengaktifkan download pipeline waktu-instal atau meminta download eksplisit, pipeline akan didownload saat pertama kali Anda menjalankan pemberi label. Permintaan yang Anda buat sebelum download selesai tidak akan menghasilkan hasil.

4. Jika Anda ingin mendownload model menggunakan Cloud Storage untuk Firebase, pastikan Anda menambahkan Firebase ke project Android, jika belum melakukannya. Langkah ini tidak diperlukan jika Anda memaketkan model.

1. Memuat model

Anda dapat memuat model dari sumber yang dipaketkan secara lokal atau sumber yang dihosting dari jarak jauh.

Mengonfigurasi sumber model lokal

Untuk memaketkan model dengan aplikasi Anda:

1. Salin file model (biasanya diakhiri dengan .tflite atau .lite) ke folder assets/ aplikasi Anda. (Anda mungkin perlu membuat folder terlebih dahulu dengan mengklik kanan folder app/, lalu mengklik Baru > Folder > Folder Aset).

2. Buat objek LocalModel dengan menentukan jalur ke file model:

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

Mengonfigurasi sumber model yang dihosting dari jarak jauh

Untuk menggunakan model yang dihosting dari jarak jauh, Anda harus mendownload file model ke penyimpanan lokal perangkat menggunakan logika aplikasi Anda sendiri, lalu memuatnya sebagai model lokal. Sebaiknya gunakan Cloud Storage untuk Firebase guna menghosting model. Untuk mengetahui detail implementasi, lihat panduan migrasi Firebase ML ke Cloud Storage.

Mengonfigurasi pemberi label gambar

Setelah mengonfigurasi sumber model, buat objek ImageLabeler dari salah satunya.

Tersedia opsi-opsi berikut:

Jika hanya memiliki model yang dipaketkan secara lokal, cukup buat pemberi label dari objek LocalModel:

val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build()
val labeler = ImageLabeling.getClient(customImageLabelerOptions)

CustomImageLabelerOptions customImageLabelerOptions =
        new CustomImageLabelerOptions.Builder(localModel)
            .setConfidenceThreshold(0.5f)
            .setMaxResultCount(5)
            .build();
ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);

Jika Anda memiliki model yang dihosting dari jarak jauh, Anda harus memeriksa apakah model tersebut sudah didownload sebelum menjalankannya.

Meskipun hanya perlu memastikan hal ini sebelum menjalankan pemberi label, jika Anda memiliki model yang dihosting dari jarak jauh dan model yang dipaketkan secara lokal, mungkin pemeriksaan ini perlu dilakukan saat membuat instance pemberi label gambar: buat pemberi label dari model jarak jauh jika model tersebut telah didownload, dan dari model lokal jika belum didownload.

val modelFile = File(context.cacheDir, "my_downloaded_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 options = CustomImageLabelerOptions.Builder(model)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build()
val labeler = ImageLabeling.getClient(options)

File modelFile = new File(context.getCacheDir(), "my_downloaded_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();
}
CustomImageLabelerOptions options = new CustomImageLabelerOptions.Builder(model)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build();
ImageLabeler labeler = ImageLabeling.getClient(options);

Jika Anda hanya memiliki model yang dihosting dari jarak jauh, Anda harus menonaktifkan fungsionalitas terkait model, misalnya membuat sebagian UI berwarna abu-abu atau menyembunyikannya, hingga Anda mengonfirmasi model tersebut telah didownload.

val localFile = File(context.cacheDir, "my_remote_model.tflite")
if (localFile.exists()) {
    initializeLabeler(localFile)
} else {
    showLoadingUI()
    val storage = Firebase.storage
    val modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite")
    modelRef.getFile(localFile)
        .addOnSuccessListener {
            hideLoadingUI()
            initializeLabeler(localFile)
        }
        .addOnFailureListener {
            showErrorUI()
        }
}

private fun initializeLabeler(modelFile: File) {
    val localModel = LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
    val options = CustomImageLabelerOptions.Builder(localModel).build()
    val labeler = ImageLabeling.getClient(options)
    enableMLFeatures(labeler)
}

File localFile = new File(context.getCacheDir(), "my_remote_model.tflite");
if (localFile.exists()) {
    initializeLabeler(localFile);
} else {
    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) {
                hideLoadingUI();
                initializeLabeler(localFile);
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception exception) {
                showErrorUI();
            }
        });
}

private void initializeLabeler(File modelFile) {
    LocalModel localModel = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
    CustomImageLabelerOptions options = new CustomImageLabelerOptions.Builder(localModel).build();
    ImageLabeler labeler = ImageLabeling.getClient(options);
    enableMLFeatures(labeler);
}

2. Menyiapkan gambar input

Anda dapat membuat InputImage objek dari beberapa sumber, yang masing-masing langkahnya dijelaskan di bawah.

Menggunakan media.Image

Untuk membuat objek InputImage dari objek media.Image, seperti saat mengambil gambar dari kamera perangkat, teruskan objek media.Image dan rotasi gambar ke InputImage.fromMediaImage().

Jika Anda menggunakan library CameraX, class OnImageCapturedListener dan ImageAnalysis.Analyzer menghitung nilai rotasi untuk Anda.

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

Jika Anda tidak menggunakan library kamera yang memberi derajat rotasi gambar, Anda dapat menghitungnya dari derajat rotasi perangkat dan orientasi sensor kamera pada perangkat:

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

Kemudian, teruskan objek media.Image dan nilai derajat rotasi ke InputImage.fromMediaImage():

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

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

Menggunakan URI file

Untuk membuat objek dari URI file, teruskan konteks aplikasi dan URI file ke InputImage.fromFilePath().InputImage Hal ini berguna saat Anda menggunakan intent ACTION_GET_CONTENT untuk meminta pengguna memilih gambar dari aplikasi galeri mereka.

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

Menggunakan ByteBuffer atau ByteArray

Untuk membuat objek InputImage dari ByteBuffer atau ByteArray, pertama-tama hitung derajat rotasi gambar seperti yang dijelaskan sebelumnya untuk input media.Image. Kemudian, buat objek InputImage dengan buffer atau array, beserta tinggi, lebar, format encoding warna, dan derajat rotasi gambar:

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

Menggunakan Bitmap

Untuk membuat objek InputImage dari objek Bitmap, buat deklarasi berikut:

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

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

Gambar direpresentasikan oleh objek Bitmap bersama dengan derajat rotasi.

3. Menjalankan pemberi label gambar

Untuk memberi label pada objek dalam gambar, teruskan objek image ke metode process() ImageLabeler.

labeler.process(image)
        .addOnSuccessListener { labels ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }
ImageLabelingActivity.kt

labeler.process(image)
        .addOnSuccessListener(new OnSuccessListener<List<ImageLabel>>() {
            @Override
            public void onSuccess(List<ImageLabel> labels) {
                // Task completed successfully
                // ...
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });
ImageLabelingActivity.java

4. Mendapatkan informasi tentang entity berlabel

for (label in labels) {
    val text = label.text
    val confidence = label.confidence
    val index = label.index
}
ImageLabelingActivity.kt

for (ImageLabel label : labels) {
    String text = label.getText();
    float confidence = label.getConfidence();
    int index = label.getIndex();
}
ImageLabelingActivity.java

Tips untuk meningkatkan performa real-time

Jika Anda ingin memberikan label pada gambar dalam aplikasi real-time, ikuti panduan ini untuk mencapai frekuensi gambar terbaik:

• Jika Anda menggunakan Camera atau camera2 API, batasi panggilan ke pemberi label gambar. Jika frame video baru tersedia saat pemberi label gambar sedang berjalan, hapus frame tersebut. Lihat class VisionProcessorBase dalam aplikasi contoh panduan memulai untuk digunakan sebagai contoh.
• Jika Anda menggunakan CameraX API, pastikan strategi backpressure ditetapkan ke nilai default ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Hal ini menjamin hanya satu gambar yang akan dikirimkan untuk analisis dalam satu waktu. Jika lebih banyak gambar dihasilkan saat penganalisis sedang sibuk, gambar tersebut akan otomatis dihapus dan tidak diantrekan untuk pengiriman. Setelah gambar yang dianalisis ditutup dengan memanggil ImageProxy.close(), gambar terbaru berikutnya akan dikirimkan.
• Jika Anda menggunakan output pemberi label pada gambar untuk menempatkan grafis pada gambar input, pertama-tama dapatkan hasilnya dari ML Kit, lalu render gambar dan tempatkan grafis dalam satu langkah. Hal ini hanya merender ke permukaan tampilan hanya sekali untuk setiap frame input. Lihat class CameraSourcePreview dan GraphicOverlay dalam aplikasi contoh panduan memulai untuk digunakan sebagai contoh.
• Jika Anda menggunakan Camera2 API, ambil gambar dalam ImageFormat.YUV_420_888 format. Jika Anda menggunakan Camera API versi lama, ambil gambar dalam ImageFormat.NV21 format.