Étiquetez les images avec ML Kit sur Android

Vous pouvez utiliser ML Kit pour étiqueter les objets reconnus dans une image, à l'aide d'un modèle sur l'appareil ou d'un modèle cloud. Consultez la présentation pour en savoir plus sur les avantages de chaque approche.

Avant que tu commences

  1. Si vous ne l'avez pas déjà fait, ajoutez Firebase à votre projet Android .
  2. Ajoutez les dépendances des bibliothèques ML Kit Android au fichier Gradle de votre module (au niveau de l'application) (généralement app/build.gradle ): 
    apply plugin: 'com.android.application'
apply plugin: 'com.google.gms.google-services'

dependencies {
  // ...

  implementation 'com.google.firebase:firebase-ml-vision:24.0.3'
  implementation 'com.google.firebase:firebase-ml-vision-image-label-model:20.0.1'
}
  3. Facultatif mais recommandé : si vous utilisez l'API sur l'appareil, configurez votre application pour télécharger automatiquement le modèle ML sur l'appareil après l'installation de votre application à partir du Play Store.

    Pour ce faire, ajoutez la déclaration suivante au fichier AndroidManifest.xml de votre application :

    <application ...>
  ...
  <meta-data
      android:name="com.google.firebase.ml.vision.DEPENDENCIES"
      android:value="label" />
  <!-- To use multiple models: android:value="label,model2,model3" -->
</application>
    Si vous n'activez pas les téléchargements de modèles au moment de l'installation, le modèle sera téléchargé la première fois que vous exécuterez le détecteur sur l'appareil. Les requêtes que vous effectuez avant la fin du téléchargement ne produiront aucun résultat.

  4. Si vous souhaitez utiliser le modèle basé sur le cloud et que vous n'avez pas encore activé les API basées sur le cloud pour votre projet, faites-le maintenant :

    1. Ouvrez la page API du kit ML de la console Firebase.

    2. Si vous n'avez pas encore mis à niveau votre projet vers un plan tarifaire Blaze, cliquez sur Mettre à niveau pour le faire. (Vous serez invité à mettre à niveau uniquement si votre projet n'est pas sur le plan Blaze.)

      Seuls les projets de niveau Blaze peuvent utiliser des API basées sur le cloud.

    3. Si les API basées sur le cloud ne sont pas déjà activées, cliquez sur Activer les API basées sur le cloud .

    Si vous souhaitez utiliser uniquement le modèle sur appareil, vous pouvez ignorer cette étape.

Vous êtes maintenant prêt à étiqueter des images à l'aide d'un modèle sur appareil ou d'un modèle basé sur le cloud.

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

Créez un objet FirebaseVisionImage à partir de votre image. L'étiqueteuse d'image s'exécute plus rapidement lorsque vous utilisez un Bitmap ou, si vous utilisez l'API camera2, un media.Image au format JPEG, qui sont recommandés lorsque cela est possible.

  • Pour créer un objet FirebaseVisionImage à partir d'un objet media.Image , par exemple lors de la capture d'une image à partir de la caméra d'un appareil, transmettez l'objet media.Image et la rotation de l'image à FirebaseVisionImage.fromMediaImage() .

    Si vous utilisez la bibliothèque CameraX , les classes OnImageCapturedListener et ImageAnalysis.Analyzer calculent la valeur de rotation pour vous, il vous suffit donc de convertir la rotation en l'une des constantes ROTATION_ de ML Kit avant d'appeler FirebaseVisionImage.fromMediaImage() :

    Java

    private class YourAnalyzer implements ImageAnalysis.Analyzer {

    private int degreesToFirebaseRotation(int degrees) {
        switch (degrees) {
            case 0:
                return FirebaseVisionImageMetadata.ROTATION_0;
            case 90:
                return FirebaseVisionImageMetadata.ROTATION_90;
            case 180:
                return FirebaseVisionImageMetadata.ROTATION_180;
            case 270:
                return FirebaseVisionImageMetadata.ROTATION_270;
            default:
                throw new IllegalArgumentException(
                        "Rotation must be 0, 90, 180, or 270.");
        }
    }

    @Override
    public void analyze(ImageProxy imageProxy, int degrees) {
        if (imageProxy == null || imageProxy.getImage() == null) {
            return;
        }
        Image mediaImage = imageProxy.getImage();
        int rotation = degreesToFirebaseRotation(degrees);
        FirebaseVisionImage image =
                FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
        // Pass image to an ML Kit Vision API
        // ...
    }
}

    Kotlin+KTX

    private class YourImageAnalyzer : ImageAnalysis.Analyzer {
    private fun degreesToFirebaseRotation(degrees: Int): Int = when(degrees) {
        0 -> FirebaseVisionImageMetadata.ROTATION_0
        90 -> FirebaseVisionImageMetadata.ROTATION_90
        180 -> FirebaseVisionImageMetadata.ROTATION_180
        270 -> FirebaseVisionImageMetadata.ROTATION_270
        else -> throw Exception("Rotation must be 0, 90, 180, or 270.")
    }

    override fun analyze(imageProxy: ImageProxy?, degrees: Int) {
        val mediaImage = imageProxy?.image
        val imageRotation = degreesToFirebaseRotation(degrees)
        if (mediaImage != null) {
            val image = FirebaseVisionImage.fromMediaImage(mediaImage, imageRotation)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

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

    Java

    private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 90);
    ORIENTATIONS.append(Surface.ROTATION_90, 0);
    ORIENTATIONS.append(Surface.ROTATION_180, 270);
    ORIENTATIONS.append(Surface.ROTATION_270, 180);
}

/**
 * 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, Context context)
        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);

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360;

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    int result;
    switch (rotationCompensation) {
        case 0:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            break;
        case 90:
            result = FirebaseVisionImageMetadata.ROTATION_90;
            break;
        case 180:
            result = FirebaseVisionImageMetadata.ROTATION_180;
            break;
        case 270:
            result = FirebaseVisionImageMetadata.ROTATION_270;
            break;
        default:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            Log.e(TAG, "Bad rotation value: " + rotationCompensation);
    }
    return result;
}
    VisionImage.java

    Kotlin+KTX

    private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 90)
    ORIENTATIONS.append(Surface.ROTATION_90, 0)
    ORIENTATIONS.append(Surface.ROTATION_180, 270)
    ORIENTATIONS.append(Surface.ROTATION_270, 180)
}
/**
 * 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, context: Context): 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)

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    val cameraManager = context.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    val result: Int
    when (rotationCompensation) {
        0 -> result = FirebaseVisionImageMetadata.ROTATION_0
        90 -> result = FirebaseVisionImageMetadata.ROTATION_90
        180 -> result = FirebaseVisionImageMetadata.ROTATION_180
        270 -> result = FirebaseVisionImageMetadata.ROTATION_270
        else -> {
            result = FirebaseVisionImageMetadata.ROTATION_0
            Log.e(TAG, "Bad rotation value: $rotationCompensation")
        }
    }
    return result
}
    VisionImage.kt

    Ensuite, passez l'objet media.Image et la valeur de rotation à FirebaseVisionImage.fromMediaImage() :

    Java

    FirebaseVisionImage image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
    VisionImage.java

    Kotlin+KTX

    val image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation)
    VisionImage.kt
  • Pour créer un objet FirebaseVisionImage à partir d'un URI de fichier, transmettez le contexte d'application et l'URI de fichier à FirebaseVisionImage.fromFilePath() . Ceci est utile lorsque vous utilisez une intention ACTION_GET_CONTENT pour inviter l'utilisateur à sélectionner une image dans son application de galerie.

    Java

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

    Kotlin+KTX

    val image: FirebaseVisionImage
try {
    image = FirebaseVisionImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}
    VisionImage.kt
  • Pour créer un objet FirebaseVisionImage à partir d'un ByteBuffer ou d'un tableau d'octets, calculez d'abord la rotation de l'image comme décrit ci-dessus pour l'entrée media.Image .

    Ensuite, créez un objet FirebaseVisionImageMetadata contenant la hauteur, la largeur, le format d'encodage des couleurs et la rotation de l'image :

    Java

    FirebaseVisionImageMetadata metadata = new FirebaseVisionImageMetadata.Builder()
        .setWidth(480)   // 480x360 is typically sufficient for
        .setHeight(360)  // image recognition
        .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
        .setRotation(rotation)
        .build();
    VisionImage.java

    Kotlin+KTX

    val metadata = FirebaseVisionImageMetadata.Builder()
        .setWidth(480) // 480x360 is typically sufficient for
        .setHeight(360) // image recognition
        .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
        .setRotation(rotation)
        .build()
    VisionImage.kt

    Utilisez le tampon ou le tableau et l'objet de métadonnées pour créer un objet FirebaseVisionImage :

    Java

    FirebaseVisionImage image = FirebaseVisionImage.fromByteBuffer(buffer, metadata);
// Or: FirebaseVisionImage image = FirebaseVisionImage.fromByteArray(byteArray, metadata);
    VisionImage.java

    Kotlin+KTX

    val image = FirebaseVisionImage.fromByteBuffer(buffer, metadata)
// Or: val image = FirebaseVisionImage.fromByteArray(byteArray, metadata)
    VisionImage.kt
  • Pour créer un objet FirebaseVisionImage à partir d'un objet Bitmap :

    Java

    FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);
    VisionImage.java

    Kotlin+KTX

    val image = FirebaseVisionImage.fromBitmap(bitmap)
    VisionImage.kt
    L'image représentée par l'objet Bitmap doit être droite, sans rotation supplémentaire requise.

2. Configurer et exécuter l'étiqueteuse d'image

Pour étiqueter des objets dans une image, transmettez l'objet FirebaseVisionImage à la méthode processImage de FirebaseVisionImageLabeler .

  1. Tout d'abord, obtenez une instance de FirebaseVisionImageLabeler .

    Si vous souhaitez utiliser l'étiqueteur d'images intégré à l'appareil :

    Java

    FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
    .getOnDeviceImageLabeler();

// Or, to set the minimum confidence required:
// FirebaseVisionOnDeviceImageLabelerOptions options =
//     new FirebaseVisionOnDeviceImageLabelerOptions.Builder()
//         .setConfidenceThreshold(0.7f)
//         .build();
// FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
//     .getOnDeviceImageLabeler(options);

    Kotlin+KTX

    val labeler = FirebaseVision.getInstance().getOnDeviceImageLabeler()

// Or, to set the minimum confidence required:
// val options = FirebaseVisionOnDeviceImageLabelerOptions.Builder()
//     .setConfidenceThreshold(0.7f)
//     .build()
// val labeler = FirebaseVision.getInstance().getOnDeviceImageLabeler(options)

    Si vous souhaitez utiliser l'éditeur d'étiquettes d'images cloud :

    Java

    FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
    .getCloudImageLabeler();

// Or, to set the minimum confidence required:
// FirebaseVisionCloudImageLabelerOptions options =
//     new FirebaseVisionCloudImageLabelerOptions.Builder()
//         .setConfidenceThreshold(0.7f)
//         .build();
// FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
//     .getCloudImageLabeler(options);

    Kotlin+KTX

    val labeler = FirebaseVision.getInstance().getCloudImageLabeler()

// Or, to set the minimum confidence required:
// val options = FirebaseVisionCloudImageLabelerOptions.Builder()
//     .setConfidenceThreshold(0.7f)
//     .build()
// val labeler = FirebaseVision.getInstance().getCloudImageLabeler(options)

  2. Ensuite, passez l'image à la méthode processImage() :

    Java

    labeler.processImage(image)
    .addOnSuccessListener(new OnSuccessListener<List<FirebaseVisionImageLabel>>() {
      @Override
      public void onSuccess(List<FirebaseVisionImageLabel> labels) {
        // Task completed successfully
        // ...
      }
    })
    .addOnFailureListener(new OnFailureListener() {
      @Override
      public void onFailure(@NonNull Exception e) {
        // Task failed with an exception
        // ...
      }
    });

    Kotlin+KTX

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

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

Si l'opération d'étiquetage d'image réussit, une liste d'objets FirebaseVisionImageLabel sera transmise à l'écouteur de réussite. Chaque objet FirebaseVisionImageLabel représente quelque chose qui a été étiqueté dans l'image. Pour chaque étiquette, vous pouvez obtenir la description textuelle de l'étiquette, son ID d'entité Knowledge Graph (si disponible) et le score de confiance de la correspondance. Par exemple:

Java

for (FirebaseVisionImageLabel label: labels) {
  String text = label.getText();
  String entityId = label.getEntityId();
  float confidence = label.getConfidence();
}

Kotlin+KTX

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

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 instructions pour obtenir les meilleures fréquences d'images :

  • Limiter les appels à l'étiqueteur d'images. Si une nouvelle image vidéo devient disponible pendant que l'étiqueteuse d'image est en cours d'exécution, supprimez l'image.
  • Si vous utilisez la sortie de l'étiqueteuse d'image pour superposer des graphiques sur l'image d'entrée, obtenez d'abord le résultat de ML Kit, puis affichez l'image et la superposition en une seule étape. Ce faisant, vous effectuez le rendu sur la surface d'affichage une seule fois pour chaque image d'entrée.

  • Si vous utilisez l'API Camera2, capturez des images au format ImageFormat.YUV_420_888 .

    Si vous utilisez l'ancienne API Camera, capturez les images au format ImageFormat.NV21 .

Prochaines étapes