Ajouter un libellé aux images avec un modèle personnalisé sur Android

Vous pouvez utiliser ML Kit pour reconnaître des entités dans une image et leur attribuer des étiquettes. Cette API est compatible avec un large éventail de modèles de classification d'images personnalisés. Reportez-vous à la section Modèles personnalisés avec ML Kit pour obtenir des conseils sur les exigences de compatibilité des modèles, où trouver les modèles pré-entraînés et comment entraîner vos propres modèles.

Il existe deux manières d'intégrer l'étiquetage d'images à des modèles personnalisés: en regroupant le pipeline dans votre application ou en utilisant un pipeline non groupé qui dépend des services Google Play. Si vous sélectionnez le pipeline non groupé, votre application sera plus petite. Pour en savoir plus, consultez le tableau ci-dessous.

Vous pouvez intégrer un modèle personnalisé de deux manières: en le plaçant dans le dossier des éléments de votre application ou en le téléchargeant de manière dynamique à partir de Firebase. Le tableau suivant compare ces deux options.

Essayer

• Consultez le guide de démarrage rapide avec Vision pour découvrir un exemple d'utilisation du modèle groupé et l'application de démarrage rapide avec AutoML pour découvrir un exemple d'utilisation du modèle hébergé.

Avant de commencer

1. Dans le fichier build.gradle au niveau du projet, veillez à inclure le dépôt Maven de Google dans les sections buildscript et allprojects.

2. Ajoutez les dépendances des bibliothèques Android ML Kit au fichier Gradle de votre module, généralement app/build.gradle. Choisissez l'une des dépendances suivantes en fonction de vos besoins:

   Pour regrouper le pipeline avec votre application:

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

   Pour utiliser le pipeline dans les services 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. Si vous choisissez d'utiliser le pipeline dans les services Google Play, vous pouvez configurer votre application pour qu'elle le télécharge automatiquement sur l'appareil après son installation depuis le Play Store. Pour ce faire, ajoutez la déclaration suivante au fichier AndroidManifest.xml de votre application:

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

   Vous pouvez également vérifier explicitement la disponibilité du pipeline et demander un téléchargement via l'API ModuleInstallClient des services Google Play.

   Si vous n'activez pas les téléchargements au moment de l'installation ou si vous demandez un téléchargement explicite, le pipeline est téléchargé la première fois que vous exécutez l'étiqueteur. Les requêtes que vous effectuez avant la fin du téléchargement ne produisent aucun résultat.

4. Ajoutez la dépendance linkFirebase si vous souhaitez télécharger dynamiquement un modèle à partir de Firebase:

   Pour télécharger un modèle de manière dynamique depuis Firebase, ajoutez la dépendance 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. Si vous souhaitez télécharger un modèle, assurez-vous d'ajouter Firebase à votre projet Android, si ce n'est pas déjà fait. Cela n'est pas obligatoire lorsque vous regroupez le modèle.

1. Charger le modèle

Configurer une source de modèle local

Pour empaqueter le modèle avec votre application:

1. Copiez le fichier de modèle (qui se termine généralement par .tflite ou .lite) dans le dossier assets/ de votre application. (Vous devrez peut-être commencer par créer le dossier en effectuant un clic droit sur le dossier app/, puis en cliquant sur Nouveau > Dossier > Dossier d'éléments).

2. Ajoutez ensuite les éléments suivants au fichier build.gradle de votre application pour vous assurer que Gradle ne compresse pas le fichier de modèle lors de la création de l'application:

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

   Le fichier de modèle sera inclus dans le package de l'application et disponible pour ML Kit en tant qu'élément brut.

3. Créez l'objet LocalModel en spécifiant le chemin d'accès au fichier de modèle:

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

Configurer une source de modèle hébergée par Firebase

Pour utiliser le modèle hébergé à distance, créez un objet RemoteModel par FirebaseModelSource en spécifiant le nom que vous avez attribué au modèle lors de sa publication:

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

Démarrez ensuite la tâche de téléchargement du modèle en spécifiant les conditions dans lesquelles vous souhaitez autoriser le téléchargement. Si le modèle ne se trouve pas sur l'appareil ou si une version plus récente du modèle est disponible, la tâche le télécharge de manière asynchrone à partir de 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.
            }
        });

De nombreuses applications démarrent la tâche de téléchargement dans leur code d'initialisation, mais vous pouvez le faire à tout moment avant d'avoir besoin d'utiliser le modèle.

Configurer l'étiqueteur d'images

Après avoir configuré les sources de votre modèle, créez un objet ImageLabeler à partir de l'une d'entre elles.

Les options suivantes sont disponibles :

Si vous ne disposez que d'un modèle groupé localement, créez un étiqueteur à partir de votre objet 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);

Si vous possédez un modèle hébergé à distance, vous devez vérifier qu'il a été téléchargé avant de l'exécuter. Vous pouvez vérifier l'état de la tâche de téléchargement du modèle à l'aide de la méthode isModelDownloaded() de l'outil de gestion de modèles.

Bien que vous n'ayez besoin de le confirmer qu'avant d'exécuter l'étiqueteur, si vous disposez à la fois d'un modèle hébergé à distance et d'un modèle groupé localement, il peut être judicieux d'instancier l'étiqueteur d'images en créant un étiqueteur à partir du modèle distant s'il a été téléchargé, ou à partir du modèle local.

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

Si vous ne disposez que d'un modèle hébergé à distance, vous devez désactiver les fonctionnalités liées au modèle (par exemple, griser ou masquer une partie de votre interface utilisateur) jusqu'à ce que vous confirmiez que le modèle a été téléchargé. Pour ce faire, vous pouvez associer un écouteur à la méthode download() du gestionnaire de modèles:

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. Préparer l'image d'entrée

Vous pouvez créer un objet InputImage à partir de différentes sources, chacune étant expliquée ci-dessous.

Utiliser un media.Image

Pour créer un objet InputImage à partir d'un objet media.Image, par exemple lorsque vous enregistrez une image à partir de l'appareil photo d'un appareil, transmettez l'objet media.Image et la rotation de l'image à InputImage.fromMediaImage().

Si vous utilisez la bibliothèque CameraX, les classes OnImageCapturedListener et ImageAnalysis.Analyzer calculent la valeur de rotation pour vous.

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

Si vous n'utilisez pas de bibliothèque de caméras qui indique le degré de rotation de l'image, vous pouvez la calculer à partir du degré de rotation et de l'orientation du capteur de l'appareil:

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

Transmettez ensuite l'objet media.Image et la valeur du degré de rotation à InputImage.fromMediaImage():

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

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

Utiliser un URI de fichier

Pour créer un objet InputImage à partir d'un URI de fichier, transmettez le contexte d'application et l'URI de fichier à InputImage.fromFilePath(). Cela est utile lorsque vous utilisez un intent ACTION_GET_CONTENT pour inviter l'utilisateur à sélectionner une image dans son application de galerie.

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

Utiliser un ByteBuffer ou ByteArray

Pour créer un objet InputImage à partir d'un objet ByteBuffer ou ByteArray, vous devez d'abord calculer le degré de rotation de l'image comme décrit précédemment pour l'entrée media.Image. Créez ensuite l'objet InputImage avec le tampon ou le tableau, ainsi que la hauteur, la largeur, le format d'encodage des couleurs et le degré de rotation de l'image:

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

Utiliser un Bitmap

Pour créer un objet InputImage à partir d'un objet Bitmap, effectuez la déclaration suivante:

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

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

L'image est représentée par un objet Bitmap avec des degrés de rotation.

3. Exécuter l'étiqueteur d'images

Pour ajouter des étiquettes aux objets d'une image, transmettez l'objet image à la méthode process() de 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. Obtenir des informations sur les entités étiquetées

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

Conseils pour améliorer les performances en temps réel

Si vous souhaitez ajouter des étiquettes aux images dans une application en temps réel, suivez ces consignes pour obtenir les meilleures fréquences d'images:

• Si vous utilisez l'API Camera ou camera2, limitez les appels à l'étiqueteur d'images. Si un nouveau cadre vidéo est disponible pendant l'exécution de l'étiqueteur, déposez-le. Consultez la classe VisionProcessorBase dans l'exemple d'application de démarrage rapide pour obtenir un exemple.
• Si vous utilisez l'API CameraX, assurez-vous que la stratégie de contre-pression est définie sur sa valeur par défaut ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Ainsi, une seule image à la fois sera envoyée pour analyse. Si d'autres images sont produites lorsque l'analyseur est occupé, elles seront supprimées automatiquement et ne seront pas mises en file d'attente pour la diffusion. Une fois que l'image analysée est fermée en appelant ImageProxy.close(), la prochaine image la plus récente est diffusée.
• Si vous utilisez la sortie de l'étiqueteur d'images pour superposer des graphiques sur l'image d'entrée, commencez par obtenir le résultat de ML Kit, puis effectuez le rendu de l'image et de la superposition en une seule étape. Il ne s'affiche à la surface d'affichage qu'une seule fois pour chaque image d'entrée. Consultez les classes CameraSourcePreview et GraphicOverlay dans l'exemple d'application de démarrage rapide pour obtenir un exemple.
• Si vous utilisez l'API Camera2, enregistrez des images au format ImageFormat.YUV_420_888. Si vous utilisez l'ancienne API Camera, enregistrez des images au format ImageFormat.NV21.