Étiqueter des images avec ML Kit sur Android

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

Fonctionnalité	Non groupée	Groupée
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 au moment de la compilation.
Taille de l'application	Augmentation de la taille d'environ 200 Ko.	Augmentation de la taille d'environ 5,7 Mo.
Délai d'initialisation	Vous devrez peut-être attendre le téléchargement du modèle avant de l'utiliser pour la première fois.	Le modèle est disponible immédiatement.

Essayer

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

Avant de commencer

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

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

Ajoutez les dépendances des bibliothèques Android ML Kit au fichier Gradle au niveau de l'application 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 avec votre application :

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

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

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 une fois qu'elle est installée 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" >
      
</application>
```
Vous pouvez également vérifier explicitement la disponibilité du modèle et demander le 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 ne demandez pas de 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 produisent aucun résultat.

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

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

Créez un InputImage objet à 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 media.Image YUV_420_888, qui sont recommandés lorsque cela est possible.

Vous pouvez créer un InputImage objet à 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 de bibliothèque d'appareil photo qui vous donne le degré de rotation de l'image, vous pouvez le calculer à partir du degré de rotation de l'appareil et de l'orientation du capteur de l'appareil photo dans 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 du 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 InputImage objet à 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()
}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 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 :

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 ainsi que par des degrés de rotation.

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

Pour étiqueter des objets dans une image, transmettez l'objet InputImage à la méthode process de l'ImageLabeler.

Commencez par obtenir une instance de ImageLabeler.

Si vous souhaitez utiliser l'étiqueteur d'images sur l'appareil, effectuez la déclaration suivante :

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

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 l'ImageProxy lorsque vous avez terminé de l'utiliser, par exemple en ajoutant un OnCompleteListener à la Task renvoyée 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'image réussit, 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 est compatible avec plus de 400 étiquettes différentes. Vous pouvez obtenir la description textuelle de chaque étiquette, son index parmi 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 étiqueter des images dans une application en temps réel, suivez ces consignes pour obtenir les meilleures fréquences d'images :

Si vous utilisez l' Camera ou l' camera2 API, limitez les appels à l'étiqueteur d'images. Si une nouvelle image vidéo devient disponible pendant l'exécution de l'étiqueteur d'images, supprimez l'image. 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. Cela garantit qu'une seule image sera fournie pour l'analyse à la fois. Si d'autres images sont produites lorsque l'analyseur est occupé, elles seront automatiquement supprimées et ne seront pas mises en file d'attente pour la livraison. Une fois que l'image analysée est fermée en appelant ImageProxy.close(), la dernière image sera fournie.
Si vous utilisez la sortie de l'étiqueteur d'images pour superposer des graphiques sur l'image d'entrée, obtenez d'abord le résultat de ML Kit, puis effectuez le rendu de l'image et la superposition en une seule étape. Le rendu n'est effectué qu'une seule fois sur la surface d'affichage pour chaque image 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, capturez des images au format ImageFormat.YUV_420_888 Si vous utilisez l'ancienne API Camera, capturez des images au ImageFormat.NV21 format.

Étiqueter des images avec ML Kit sur Android Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Essayer

Avant de commencer

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

Utiliser un media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

Utiliser un URI de fichier

Kotlin

Java

Utiliser un ByteBuffer ou un ByteArray

Kotlin

Java

Utiliser un Bitmap

Kotlin

Java

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

Kotlin

Java

Kotlin

Java

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

Kotlin

Java

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

Étiqueter des images avec ML Kit sur Android

Utiliser un `media.Image`

Utiliser un `ByteBuffer` ou un `ByteArray`

Utiliser un `Bitmap`