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

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Vous pouvez utiliser ML Kit pour reconnaître des entités dans une image et leur attribuer des étiquettes. Cette API est compatible avec de nombreux 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 façons d'intégrer des étiquettes 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.

GroupéeDégroupés
Nom de la bibliothèquecom.google.mlkit:image-labeling-customcom.google.android.gms:play-services-mlkit-image-labeling-custom
ImplémentationLe pipeline est associé à votre application de manière statique au moment de la compilation.Le pipeline est téléchargé de manière dynamique via les services Google Play.
Taille d'applicationAugmentation de la taille d'environ 3,8 Mo.Augmentation de la taille d'environ 200 Ko.
Délai d'initialisationLe pipeline est disponible immédiatement.Vous devrez peut-être attendre le téléchargement du pipeline avant d'utiliser cette fonction pour la première fois.
Phase du cycle de vie de l'APIDisponibilité générale (DG)Bêta

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 depuis Firebase. Le tableau suivant compare ces deux options.

Modèle groupé Modèle hébergé
Le modèle fait partie de l'APK de votre appli, qui augmente sa taille. Le modèle ne fait pas partie de votre APK. Elle est hébergée en important le modèle sur Firebase Machine Learning.
Le modèle est disponible immédiatement, même lorsque l'appareil Android est hors connexion. Le modèle est téléchargé à la demande
Pas besoin de projet Firebase Nécessite un projet Firebase
Vous devez republier votre application pour mettre à jour le modèle Transférer les mises à jour du modèle sans republier votre application
Aucun test A/B intégré Tests A/B faciles avec Firebase Remote Config

Avant de commencer

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

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

    Pour associer le pipeline à 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 le téléchargement via l'API InstallInstallClient des services Google Play.

    Si vous n'activez pas les téléchargements de pipelines 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 un modèle de manière dynamique depuis Firebase:

    Pour télécharger un modèle 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, veillez à ajouter Firebase à votre projet Android, si ce n'est pas déjà fait. Cela n'est pas nécessaire 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 d'abord créer le dossier en effectuant un clic droit sur le dossier app/, puis en cliquant sur Nouveau > Dossier > Dossier d'assets).

  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 en FirebaseModelSource spécifiant le nom que vous avez attribué au modèle lors de sa publication:

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

Ensuite, démarrez 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 n'est pas installé sur l'appareil ou qu'une version plus récente est disponible, la tâche le télécharge de manière asynchrone depuis Firebase:

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

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

Configurer l'étiqueteur d'images

Une fois vos sources de modèle configurées, créez un objet ImageLabeler à partir de l'une d'entre elles.

Les options suivantes sont disponibles :

Options
confidenceThreshold

Score de confiance minimal des libellés détectés. S'il n'est pas défini, tout seuil de classificateur spécifié par les métadonnées du modèle sera utilisé. Si le modèle ne contient aucune métadonnée ou si les métadonnées ne spécifient pas de seuil de classificateur, un seuil par défaut de 0.0 est utilisé.

maxResultCount

Nombre maximal d'étiquettes à renvoyer. Si ce champ n'est pas défini, la valeur par défaut de 10 sera utilisée.

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

Si vous disposez d'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() du gestionnaire de modèles.

Bien que vous n'ayez à vérifier que cela 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'effectuer cette vérification lors de l'instanciation de l'étiqueteur d'images. Pour ce faire, créez un étiqueteur à partir du modèle distant s'il a été téléchargé. Sinon, créez-le à partir du modèle distant.

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

Si vous ne disposez que d'un modèle hébergé à distance, vous devez désactiver ses fonctionnalités (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:

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

Ensuite, pour chaque image à laquelle vous souhaitez ajouter un libellé, créez un objet InputImage à partir de votre image. L'étiqueteur d'images s'exécute plus rapidement lorsque vous utilisez un Bitmap ou, si vous utilisez l'API camera2, un YUV_420_888 media.Image, qui est recommandé dans la mesure du possible.

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

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

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

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
}

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

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

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)

Java

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 de l'application et l'URI du 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.

Kotlin

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

Java

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

Utiliser un ByteBuffer ou un ByteArray

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

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);

Utiliser un Bitmap

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

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)

Java

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

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 libellés aux objets d'une image, transmettez l'objet image à la méthode ImageLabeler's process().

Kotlin

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

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

4. Obtenir des informations sur les entités étiquetées

Si l'opération d'étiquetage d'image aboutit, une liste d'objets ImageLabel est transmise à l'écouteur de réussite. Chaque objet ImageLabel représente un élément libellé dans l'image. Vous pouvez obtenir la description textuelle de chaque étiquette (si disponible dans les métadonnées du fichier de modèle TensorFlow Lite), le score de confiance et l'index. Exemple :

Kotlin

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

Java

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

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

Si vous souhaitez ajouter des étiquettes à des 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 une nouvelle image est disponible pendant l'exécution de l'étiquetage d'image, supprimez-la. Reportez-vous à 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. Une seule image sera ainsi fournie à des fins d'analyse. Si d'autres images sont produites lorsque l'analyseur est occupé, elles sont automatiquement supprimées et ne sont pas mises en file d'attente pour diffusion. Une fois l'image analysée fermée via l'appel de ImageProxy.close(), la dernière image suivante est diffusée.
  • Si vous utilisez le résultat de l'étiqueteur d'images pour superposer des images sur l'image d'entrée, récupérez d'abord le résultat de ML Kit, puis effectuez le rendu de l'image et de la superposition en une seule étape. Le rendu s'affiche une fois sur la surface d'affichage 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.