Étiqueter des images avec un modèle personnalisé sur Android

Il existe deux façons d'intégrer le libellé d'images avec des modèles personnalisés : en regroupant le pipeline dans votre application ou en utilisant un pipeline non regroupé 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.

Il existe deux façons d'intégrer un modèle personnalisé : regrouper le modèle en le plaçant dans le dossier d'éléments de votre application ou le télécharger dynamiquement depuis Firebase. Le tableau suivant compare ces deux options.

Essayer

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

Avant de commencer

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

2. Ajoutez les dépendances pour les bibliothèques Android ML Kit au fichier Gradle au niveau de l'application de votre module, qui est généralement app/build.gradle.kts. 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.3")
   }
   

   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-beta5")
   }
   

3. Si vous choisissez d'utiliser le pipeline dans les services Google Play, vous pouvez configurer votre application pour qu'elle télécharge automatiquement le pipeline 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="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 ModuleInstallClient des services Google Play.

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

4. Si vous souhaitez télécharger un modèle à l'aide de Cloud Storage for Firebase, assurez-vous d'ajouter Firebase à votre projet Android, si ce n'est pas déjà fait. Cette étape n'est pas nécessaire lorsque vous regroupez le modèle.

1. Charger le modèle

Vous pouvez charger le modèle à partir d'une source groupée localement ou d'une source hébergée à distance.

Configurer une source de modèle local

Pour regrouper 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 créer le dossier en effectuant un clic droit sur le dossier app/, puis en cliquant sur Nouveau > Dossier > Dossier d'éléments.)

2. Créez un 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 path to model file)
           // or .setUri(URI to model file)
           .build()

   Java

   LocalModel localModel =
       new LocalModel.Builder()
           .setAssetFilePath("model.tflite")
           // or .setAbsoluteFilePath(absolute path to model file)
           // or .setUri(URI to model file)
           .build();

Configurer une source de modèle hébergée à distance

Pour utiliser le modèle hébergé à distance, vous devez télécharger le fichier du modèle dans le stockage local de l'appareil à l'aide de votre propre logique d'application, puis le charger en tant que modèle local. Nous vous recommandons d'utiliser Cloud Storage pour Firebase pour héberger un modèle. Pour plus d'informations sur l'implémentation, consultez le guide de migration de Firebase ML vers Cloud Storage.

Configurer l'outil d'étiquetage d'images

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

Les options suivantes sont disponibles :

Si vous ne disposez que d'un modèle groupé localement, créez simplement un outil de libellisation à 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 disposez d'un modèle hébergé à distance, vous devrez vérifier qu'il a été téléchargé avant de l'exécuter.

Bien que vous n'ayez à confirmer cela qu'avant d'exécuter le module de classification, si vous disposez à la fois d'un modèle hébergé à distance et d'un modèle fourni localement, il peut être judicieux d'effectuer cette vérification lors de l'instanciation du module de classification d'images : créez un module de classification à partir du modèle distant s'il a été téléchargé, et à partir du modèle local dans le cas contraire.

val modelFile = File(context.cacheDir, "my_downloaded_model.tflite")
val model = if (modelFile.exists()) {
    // Use the downloaded model if available
    LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
} else {
    // Fall back to the bundled model
    LocalModel.Builder().setAssetFilePath("model.tflite").build()
}
val options = CustomImageLabelerOptions.Builder(model)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build()
val labeler = ImageLabeling.getClient(options)

File modelFile = new File(context.getCacheDir(), "my_downloaded_model.tflite");
LocalModel model;
if (modelFile.exists()) {
    // Use the downloaded model if available
    model = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
} else {
    // Fall back to the bundled model
    model = new LocalModel.Builder().setAssetFilePath("model.tflite").build();
}
CustomImageLabelerOptions options = new CustomImageLabelerOptions.Builder(model)
    .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 UI) jusqu'à ce que vous confirmiez que le modèle a été téléchargé.

val localFile = File(context.cacheDir, "my_remote_model.tflite")
if (localFile.exists()) {
    initializeLabeler(localFile)
} else {
    showLoadingUI()
    val storage = Firebase.storage
    val modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite")
    modelRef.getFile(localFile)
        .addOnSuccessListener {
            hideLoadingUI()
            initializeLabeler(localFile)
        }
        .addOnFailureListener {
            showErrorUI()
        }
}

private fun initializeLabeler(modelFile: File) {
    val localModel = LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
    val options = CustomImageLabelerOptions.Builder(localModel).build()
    val labeler = ImageLabeling.getClient(options)
    enableMLFeatures(labeler)
}

File localFile = new File(context.getCacheDir(), "my_remote_model.tflite");
if (localFile.exists()) {
    initializeLabeler(localFile);
} else {
    showLoadingUI();
    FirebaseStorage storage = FirebaseStorage.getInstance();
    StorageReference modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite");
    modelRef.getFile(localFile)
        .addOnSuccessListener(new OnSuccessListener<FileDownloadTask.TaskSnapshot>() {
            @Override
            public void onSuccess(FileDownloadTask.TaskSnapshot taskSnapshot) {
                hideLoadingUI();
                initializeLabeler(localFile);
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception exception) {
                showErrorUI();
            }
        });
}

private void initializeLabeler(File modelFile) {
    LocalModel localModel = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
    CustomImageLabelerOptions options = new CustomImageLabelerOptions.Builder(localModel).build();
    ImageLabeler labeler = ImageLabeling.getClient(options);
    enableMLFeatures(labeler);
}

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

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 vous indique 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 la caméra dans 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 de l'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 un ByteArray

Pour créer un objet InputImage à partir d'un ByteBuffer ou d'un ByteArray, commencez par 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 ainsi que par des degrés de rotation.

3. Exécuter l'outil d'étiquetage d'images

Pour libeller des objets dans 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 libellé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 libeller 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 au module de classification d'images. Si une nouvelle image vidéo devient disponible pendant l'exécution du module de classification d'images, supprimez l'image. Pour obtenir un exemple, consultez la classe VisionProcessorBase dans l'application exemple du guide 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 envoyée à la fois pour analyse. 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 diffusion. Une fois l'image analysée fermée en appelant ImageProxy.close(), la dernière image suivante sera fournie.
• Si vous utilisez la sortie du détecteur de libellés d'image pour superposer des éléments graphiques sur l'image d'entrée, obtenez d'abord le résultat de ML Kit, puis affichez l'image et superposez-la en une seule étape. Cela permet d'afficher 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, capturez les images au format ImageFormat.YUV_420_888. Si vous utilisez l'ancienne API Camera, capturez les images au format ImageFormat.NV21.