Étiqueter des images avec ML Kit sur Android

Vous pouvez utiliser ML Kit pour étiqueter des objets reconnus dans une image. Le modèle par défaut fourni avec ML Kit accepte plus de 400 étiquettes différentes.

Cette API est disponible à l'aide d'une bibliothèque non intégrée qui doit être téléchargée avant utilisation ou d'une bibliothèque groupée qui augmente la taille de votre application. Consultez ce guide pour en savoir plus sur les différences entre les deux options d'installation.

Caractéristique	Sans bundles	Regroupées
Implémentation	Le modèle est téléchargé de manière dynamique via les services Google Play.	Le modèle est lié de manière statique à votre modèle au moment de la compilation.
Taille d'application	Augmentation d'environ 200 Ko.	Augmentation de la taille d'environ 5,7 Mo
Délai d'initialisation	Vous devrez peut-être attendre que le modèle soit téléchargé pour la première utilisation.	Le modèle est disponible immédiatement

Essayer

• Testez l'application exemple pour voir un exemple d'utilisation de cette API.

Avant de commencer

Cette API nécessite l'API Android niveau 19 ou supérieur. Assurez-vous que le fichier de compilation de votre application utilise une valeur minSdkVersion égale ou supérieure à 19.

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, qui est généralement app/build.gradle. Choisissez l'une des dépendances suivantes en fonction de vos besoins:

   Pour regrouper le modèle et votre application:

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

   Pour utiliser le modèle dans les services Google Play:

   dependencies {
     // ...
     // Use this dependency to use the dynamically downloaded model in Google Play Services
     implementation 'com.google.android.gms:play-services-mlkit-image-labeling:16.0.8'
   }
   

3. Si vous choisissez d'utiliser le modèle dans les services Google Play, vous pouvez configurer votre application pour qu'elle télécharge automatiquement le modèle 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="ica" >
         <!-- To use multiple models: android:value="ica,model2,model3" -->
   </application>
   

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

   Si vous n'activez pas les téléchargements de modèles au moment de l'installation ou si vous demandez un téléchargement explicite, le modèle 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 génèrent aucun résultat.

Vous êtes maintenant prêt à étiqueter les images.

1. Préparer l'image d'entrée

Créez un objet InputImage à partir de votre image. L'étiqueteur d'images s'exécute plus rapidement lorsque vous utilisez un élément Bitmap ou, si vous utilisez l'API camera2, un élément 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 depuis 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 de bibliothèque de caméra qui fournit le degré de rotation de l'image, vous pouvez la calculer à partir du degré de rotation de l'appareil et de l'orientation du capteur de l'appareil:

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

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

Kotlin

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

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 de fichier à InputImage.fromFilePath(). Cela s'avère 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()
}
MLKitVisionImage.kt

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 ByteBuffer ou d'un ByteArray, calculez d'abord 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 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
)
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

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)
MLKitVisionImage.kt

Java

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

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

2. Configurer et exécuter l'étiqueteur d'images

Pour ajouter des libellés aux objets d'une image, transmettez l'objet InputImage à la méthode process de ImageLabeler.

1. Commencez par obtenir une instance de ImageLabeler.

   Si vous souhaitez utiliser l'étiqueteur d'images sur l'appareil, procédez comme suit:

Kotlin

// To use default options:
val labeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS)

// Or, to set the minimum confidence required:
// val options = ImageLabelerOptions.Builder()
//     .setConfidenceThreshold(0.7f)
//     .build()
// val labeler = ImageLabeling.getClient(options)
ImageLabelingActivity.kt

Java

// To use default options:
ImageLabeler labeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS);

// Or, to set the minimum confidence required:
// ImageLabelerOptions options =
//     new ImageLabelerOptions.Builder()
//         .setConfidenceThreshold(0.7f)
//         .build();
// ImageLabeler labeler = ImageLabeling.getClient(options);
ImageLabelingActivity.java

1. Transmettez ensuite l'image à la méthode process():

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

Remarque: Si vous utilisez l'API CameraX, veillez à fermer le ImageProxy lorsque vous avez fini de l'utiliser, par exemple en ajoutant un OnCompleteListener au Task renvoyé par la méthode process. Pour obtenir un exemple, consultez la classe VisionProcessorBase dans l'application exemple de démarrage rapide.

3. Obtenir des informations sur les objets étiquetés

Si l'opération d'étiquetage d'images aboutit, une liste d'objets ImageLabel est transmise à l'écouteur de réussite. Chaque objet ImageLabel représente un élément étiqueté dans l'image. Le modèle de base accepte plus de 400 étiquettes différentes. Vous pouvez obtenir la description textuelle de chaque étiquette, l'index de toutes les étiquettes compatibles avec le modèle et le score de confiance de la correspondance. Exemple :

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

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'images, déposez-le. Pour obtenir un exemple, consultez la classe VisionProcessorBase dans l'application exemple de démarrage rapide.
• 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 sera fournie à la fois 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 dernière image suivante est diffusée.
• Si vous utilisez la sortie de l'étiqueteur d'image pour superposer des éléments graphiques à l'image d'entrée, commencez par obtenir le résultat de ML Kit, puis affichez l'image et la superposition en une seule étape. Cela s'affiche sur la surface d'affichage une seule fois pour chaque frame d'entrée. Pour obtenir un exemple, consultez les classes CameraSourcePreview et GraphicOverlay dans l'application exemple de démarrage rapide.
• Si vous utilisez l'API Camera2, enregistrez des images au format ImageFormat.YUV_420_888. Si vous utilisez l'ancienne API Camera, capturez des images au format ImageFormat.NV21.