Melabeli gambar dengan model kustom di Android

Anda dapat menggunakan ML Kit untuk mengenali entity dalam gambar dan melabelinya. API ini mendukung berbagai model klasifikasi gambar kustom. Lihat Model kustom dengan ML Kit untuk panduan tentang persyaratan kompatibilitas model, tempat untuk menemukan model terlatih, dan cara melatih model Anda sendiri.

Ada dua cara untuk mengintegrasikan pelabelan 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, aplikasi Anda akan lebih kecil. Lihat tabel di bawah ini untuk detailnya.

	Paket	Tidak Dipaketkan
Nama library	com.google.mlkit:image-labeling-custom	com.google.android.gms:play-services-mlkit-image-labeling-custom
Penerapan	Pipeline ditautkan secara statis ke aplikasi Anda pada waktu build.	Pipeline didownload secara dinamis melalui Layanan Google Play.
Ukuran aplikasi	Bertambah sekitar 3,8 MB.	Bertambah sekitar 200 KB.
Waktu inisialisasi	Pipeline segera tersedia.	Mungkin perlu menunggu pipeline didownload sebelum penggunaan pertama.
Tahap siklus proses API	Ketersediaan Umum (GA)	Beta

Catatan: Versi pelabelan gambar yang tidak dipaketkan dengan model kustom saat ini ditawarkan dalam versi beta, yang berarti cara tersebut mungkin berubah sehingga tidak kompatibel dengan versi sebelumnya dan tidak tunduk pada SLA atau kebijakan penghentian layanan.

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

Model Paket	Model yang Dihosting
Model merupakan bagian dari APK aplikasi, yang akan menambah ukurannya.	Model ini bukan bagian dari APK Anda. Domain dihosting dengan mengupload ke Firebase Machine Learning.
Model akan langsung tersedia, bahkan saat perangkat Android sedang offline	Model didownload sesuai permintaan
Tidak memerlukan project Firebase	Memerlukan project Firebase
Anda harus memublikasikan ulang aplikasi untuk memperbarui model	Update model dapat dikirim tanpa memublikasikan ulang aplikasi
Tidak ada pengujian A/B bawaan	Pengujian A/B yang mudah dengan Firebase Remote Config

Cobalah

• Lihat aplikasi panduan memulai visi untuk contoh penggunaan model yang dipaketkan dan aplikasi panduan memulai AutoML untuk mengetahui contoh penggunaan model yang dihosting.

Sebelum memulai

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

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

   Untuk memaketkan pipeline dengan aplikasi:

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

   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-beta4'
   }
   

3. Jika memilih untuk menggunakan pipeline di Layanan Google Play, Anda dapat mengonfigurasi aplikasi agar otomatis mendownload pipeline ke perangkat setelah aplikasi diinstal dari 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 ModuleInstallClient API layanan Google Play.

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

4. Tambahkan dependensi linkFirebase jika Anda ingin mendownload model dari Firebase secara dinamis:

   Untuk mendownload model dari Firebase secara dinamis, tambahkan dependensi linkFirebase:

   dependencies {
     // ...
     // Image labeling feature with model downloaded from Firebase
     implementation 'com.google.mlkit:image-labeling-custom:17.0.1'
     // Or use the dynamically downloaded pipeline in Google Play Services
     // implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta4'
     implementation 'com.google.mlkit:linkfirebase:17.0.0'
   }
   

5. Jika ingin mendownload model, pastikan Anda menambahkan Firebase ke project Android, jika belum melakukannya. Langkah ini tidak diperlukan jika Anda memaketkan model.

1. Memuat model

Mengonfigurasi sumber model lokal

Untuk memaketkan model dengan aplikasi:

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

2. Kemudian, tambahkan hal berikut ini ke file build.gradle aplikasi untuk memastikan agar Gradle tidak mengompresi file model saat mem-build aplikasi:

   android {
       // ...
       aaptOptions {
           noCompress "tflite"
           // or noCompress "lite"
       }
   }
   

   File model akan disertakan ke dalam paket aplikasi dan tersedia untuk ML Kit sebagai aset mentah.

   Catatan: mulai dari plugin Android Gradle versi 4.1, .tflite akan ditambahkan ke daftar noKompresi secara default dan sudah tidak diperlukan lagi.

3. Buat objek LocalModel, dengan menentukan jalur ke file model:

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

   Catatan: Aplikasi yang menargetkan Android 11 (API level 30) tidak dapat lagi mengakses file dari penyimpanan eksternal karena Update penyimpanan di Android 11.
   Catatan: jika Anda memiliki model yang dilatih dengan AutoML Vision Edge di Firebase (bukan Google Cloud), hal di atas mungkin tidak berfungsi. Ikuti panduan migrasi untuk mendapatkan petunjuk.

Mengonfigurasi sumber model yang dihosting Firebase

Untuk menggunakan model yang dihosting dari jarak jauh, buat objek RemoteModel dengan FirebaseModelSource, dengan menentukan nama yang ditetapkan pada model saat memublikasikannya:

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

Kemudian, mulai tugas download model dengan menentukan kondisi yang Anda inginkan untuk mengizinkan download. Jika model tidak ada di perangkat, atau jika versi model yang lebih baru tersedia, tugas ini akan mendownload model dari Firebase secara asinkron:

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

Banyak aplikasi memulai tugas download dalam kode inisialisasinya, tetapi Anda dapat melakukannya kapan saja sebelum menggunakan model.

Mengonfigurasi pemberi label gambar

Setelah mengonfigurasi sumber model, buat objek ImageLabeler dari salah satu sumber tersebut.

Tersedia opsi-opsi berikut:

Opsi
confidenceThreshold	Skor keyakinan minimum label yang terdeteksi. Jika tidak disetel, nilai minimum pengklasifikasi apa pun yang ditentukan oleh metadata model akan digunakan. Jika model tidak berisi metadata apa pun atau metadata tidak menentukan batas pengklasifikasi, nilai minimum default 0,0 akan digunakan.
maxResultCount	Jumlah maksimum label untuk ditampilkan. Jika tidak disetel, nilai default 10 akan digunakan.

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

Kotlin

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

Java

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. Anda dapat memeriksa status tugas download model menggunakan metode isModelDownloaded() pengelola model.

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 ada baiknya untuk melakukan pemeriksaan ini 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.

Kotlin

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener { isDownloaded ->
    val optionsBuilder =
        if (isDownloaded) {
            CustomImageLabelerOptions.Builder(remoteModel)
        } else {
            CustomImageLabelerOptions.Builder(localModel)
        }
    val options = optionsBuilder
                  .setConfidenceThreshold(0.5f)
                  .setMaxResultCount(5)
                  .build()
    val labeler = ImageLabeling.getClient(options)
}

Java

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(Boolean isDownloaded) {
                CustomImageLabelerOptions.Builder optionsBuilder;
                if (isDownloaded) {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(remoteModel);
                } else {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(localModel);
                }
                CustomImageLabelerOptions options = optionsBuilder
                    .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. Anda dapat melakukannya dengan menambahkan pemroses ke metode download() pengelola model:

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

2. Persiapkan gambar input

Selanjutnya, untuk setiap gambar yang ingin Anda beri label, buat objek InputImage dari gambar Anda. Pemberi label pada gambar berfungsi optimal jika Anda menggunakan Bitmap atau, jika Anda menggunakan camera2 API, media.Image YUV_420_888, yang direkomendasikan jika memungkinkan.

Anda dapat membuat objek InputImage dari berbagai sumber, yang masing-masing akan dijelaskan di bawah ini.

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.

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

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

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

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

Kotlin

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

Java

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

Menggunakan URI file

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

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

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 buffering atau array, beserta tinggi, lebar, format encoding warna, dan derajat rotasi gambar:

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

Menggunakan Bitmap

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

Kotlin

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

Java

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.

Kotlin

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

Java

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

Catatan: Jika Anda menggunakan API CameraX, pastikan untuk menutup ImageProxy saat selesai menggunakannya, misalnya, dengan menambahkan OnCompleteListener ke Task yang ditampilkan dari metode process. Lihat class VisionProcessorBase di aplikasi contoh panduan memulai untuk mengetahui contohnya.

4. Mendapatkan informasi tentang entitas berlabel

Jika operasi pelabelan gambar berhasil, daftar objek ImageLabel akan diteruskan ke pemroses peristiwa sukses. Setiap objek ImageLabel mewakili sesuatu yang diberi label dalam gambar. Anda dapat memperoleh deskripsi teks setiap label (jika tersedia dalam metadata file model TensorFlow Lite), skor keyakinan, dan indeks. Contoh:

Kotlin

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

Java

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

Catatan: jika menggunakan model TensorFlow Lite yang tidak kompatibel dengan ML Kit, Anda akan mendapatkan MlKitException dengan kode error MlKitException#INVALID_ARGUMENT dan beberapa detail tentang alasan mengapa model tersebut tidak kompatibel. Baca bagian Persyaratan Kompatibilitas Model Kustom untuk mengetahui detailnya.

Tips untuk meningkatkan performa real-time

Jika ingin memberikan label pada gambar dalam aplikasi real-time, ikuti pedoman ini untuk mencapai kecepatan frame terbaik:

• Jika Anda menggunakan Camera atau camera2 API, throttle panggilan ke pemberi label gambar. Jika frame video baru tersedia saat pemberi label pada gambar sedang berjalan, hapus frame tersebut. Lihat class VisionProcessorBase di aplikasi contoh panduan memulai untuk mengetahui contohnya.
• Jika Anda menggunakan CameraX API, pastikan strategi backpressure ditetapkan ke nilai defaultnya ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Hal ini menjamin hanya satu gambar yang akan dikirim untuk dianalisis dalam satu waktu. Jika lebih banyak gambar dihasilkan saat analyzer sibuk, gambar tersebut akan dihapus secara otomatis dan tidak diantrekan untuk dikirim. 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. Tindakan ini hanya merender ke permukaan tampilan sekali untuk setiap frame input. Lihat class CameraSourcePreview dan GraphicOverlay di aplikasi contoh panduan memulai untuk mengetahui contohnya.
• Jika Anda menggunakan Camera2 API, ambil gambar dalam format ImageFormat.YUV_420_888. Jika Anda menggunakan Camera API versi lama, ambil gambar dalam format ImageFormat.NV21.