Memberi label pada 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. Memohon lihat Model kustom dengan ML Kit untuk mendapatkan panduan tentang persyaratan kompatibilitas model, tempat 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 tidak terpaket yang bergantung pada di Layanan Google Play. Jika Anda memilih pipeline yang tidak dipaketkan, aplikasi Anda akan menjadi lebih kecil. Lihat tabel di bawah ini untuk 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 tersebut.

Cobalah

• Lihat aplikasi panduan memulai visi untuk contoh penggunaan model yang dipaketkan dan aplikasi panduan memulai automl untuk contoh penggunaan dari model yang di-host.

Sebelum memulai

1. Dalam file build.gradle level project, pastikan Anda menyertakan Repositori Maven Google di file buildscript dan allprojects.

2. Tambahkan dependensi untuk library Android ML Kit ke modul Anda gradle level aplikasi, yang biasanya adalah app/build.gradle. 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 memilih untuk menggunakan pipeline di Layanan Google Play, Anda dapat mengonfigurasi aplikasi untuk mendownload pipeline secara otomatis ke perangkat setelah aplikasi Anda diinstal dari Play Store. Untuk melakukannya, tambahkan 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 secara eksplisit memeriksa ketersediaan pipeline dan meminta download melalui ModuleInstallClient API layanan Google Play.

   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 pengunduhan selesai, tidak akan memberikan hasil.

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

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

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

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

1. Muat model

Mengonfigurasi sumber model lokal

Untuk memaketkan model dengan aplikasi Anda:

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

2. Lalu, tambahkan kode berikut ke file build.gradle aplikasi Anda untuk memastikan Gradle tidak mengompresi file model saat membangun aplikasi:

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

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

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

Mengonfigurasi sumber model yang dihosting Firebase

Untuk menggunakan model yang dihosting dari jarak jauh, buat objek RemoteModel dengan FirebaseModelSource, yang menetapkan nama yang Anda berikan pada model saat menerbitkannya:

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

// 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 izinkan untuk diunduh. Jika model tidak ada di perangkat, atau jika model versi baru yang tersedia, tugas ini akan mendownload dari Firebase:

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

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 Anda perlu menggunakan model.

Mengonfigurasi pemberi label gambar

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

Tersedia opsi-opsi berikut:

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

Meskipun Anda hanya perlu mengonfirmasi hal ini sebelum menjalankan pemberi label, jika Anda baik memiliki model yang dihosting dari jarak jauh maupun model yang dipaketkan secara lokal, masuk akal untuk melakukan pemeriksaan ini saat membuat instance pemberi label gambar: buat pemberi label dari model jarak jauh jika telah didownload, dan dari model model sebaliknya.

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

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 hanya memiliki model yang dihosting dari jarak jauh, Anda harus menonaktifkan model lainnya—misalnya, menyamarkan atau menyembunyikan sebagian UI—hingga Anda mengonfirmasi bahwa model telah didownload. Anda dapat melakukannya dengan menambahkan pemroses ke metode download() pengelola model:

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

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. Menyiapkan gambar input

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

Menggunakan media.Image

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

Jika Anda menggunakan library CameraX, OnImageCapturedListener dan Class ImageAnalysis.Analyzer menghitung nilai rotasi keamanan 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 pustaka kamera yang memberi derajat rotasi gambar, Anda bisa menghitungnya dari derajat rotasi perangkat dan orientasi kamera sensor di 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;
}

Lalu, 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 InputImage dari URI file, teruskan konteks aplikasi dan URI file ke InputImage.fromFilePath(). Hal ini berguna ketika Anda gunakan 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 InputImage dari ByteBuffer atau ByteArray, hitung gambar terlebih dahulu derajat rotasi seperti yang dijelaskan sebelumnya untuk input media.Image. Lalu, buat objek InputImage dengan buffer atau array, beserta elemen tinggi, lebar, format encoding warna, dan derajat rotasi:

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 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. Jalankan pemberi label gambar

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

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 entitas 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 untuk mencapai kecepatan frame terbaik:

• Jika Anda menggunakan Camera atau camera2 API, men-throttle panggilan ke pemberi label gambar. Jika video baru frame menjadi tersedia saat pemberi label gambar sedang berjalan, hapus bingkai. Lihat VisionProcessorBase dalam aplikasi contoh panduan memulai untuk digunakan sebagai contoh.
• Jika Anda menggunakan CameraX API, pastikan strategi tekanan balik ditetapkan ke nilai defaultnya ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Hal ini menjamin hanya satu gambar yang akan dikirimkan untuk analisis pada satu waktu. Jika lebih banyak gambar yang dihasilkan ketika penganalisis sedang sibuk, mereka akan dibuang secara otomatis dan tidak diantrekan pengiriman. Setelah gambar yang dianalisis ditutup dengan memanggil ImageProxy.close(), gambar terbaru berikutnya akan dikirim.
• Jika Anda menggunakan output pemberi label gambar untuk menempatkan grafis pada gambar input, pertama-tama dapatkan hasilnya dari ML Kit, lalu render gambar dan overlay dalam satu langkah. Tindakan ini merender ke permukaan tampilan hanya sekali untuk setiap {i>input frame<i}. Lihat CameraSourcePreview dan GraphicOverlay dalam aplikasi contoh panduan memulai sebagai contoh.
• Jika Anda menggunakan Camera2 API, ambil gambar dengan Format ImageFormat.YUV_420_888. Jika Anda menggunakan Camera API versi lama, ambil gambar dengan Format ImageFormat.NV21.