Détecter, suivre et classer des objets avec un modèle de classification personnalisé sur Android

Lorsque vous transmettez une image à ML Kit, il détecte jusqu'à cinq objets dans l'image, ainsi que la position de chacun d'eux. Lors de la détection d'objets dans des flux vidéo, chaque objet est associé à un ID unique que vous pouvez utiliser pour le suivre d'une image à l'autre.

Vous pouvez utiliser un modèle de classification d'images personnalisé pour classer les objets détectés. Consultez Modèles personnalisés avec ML Kit pour obtenir des conseils sur les exigences de compatibilité des modèles, où trouver des modèles pré-entraînés et comment entraîner vos propres modèles.

Il existe deux façons d'intégrer un modèle personnalisé : vous pouvez regrouper le modèle en le plaçant dans le dossier d'assets de votre application, ou vous pouvez le télécharger de manière dynamique depuis Cloud Storage. Le tableau suivant compare les 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é.
• Consultez l'application de démonstration Material Design pour une implémentation de bout en bout de cette API.

Avant de commencer

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

   Pour regrouper un modèle avec votre application :

   dependencies {
     // ...
     // Object detection & tracking feature with custom bundled model
     implementation("com.google.mlkit:object-detection-custom:17.0.2")
   }
   

2. Si vous souhaitez télécharger un modèle depuis Cloud Storage pour 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.

2. Configurer le détecteur d'objets

Après avoir configuré vos sources de modèle, configurez le détecteur d'objets pour votre cas d'utilisation avec un objet CustomObjectDetectorOptions. Vous pouvez modifier les paramètres suivants :

L'API de détection et de suivi d'objets est optimisée pour ces deux cas d'utilisation principaux :

• Détection et suivi en direct de l'objet le plus visible dans le viseur de la caméra.
• Détection de plusieurs objets à partir d'une image statique.

Pour configurer l'API pour ces cas d'utilisation, avec un modèle fourni localement :

// Live detection and tracking
val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(localModel)
        .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE)
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

// Multiple object detection in static images
val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(localModel)
        .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableMultipleObjects()
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

val objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions)

// Live detection and tracking
CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(localModel)
                .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE)
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

// Multiple object detection in static images
CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(localModel)
                .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableMultipleObjects()
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

ObjectDetector objectDetector =
    ObjectDetection.getClient(customObjectDetectorOptions);

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 détecteur, 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 détecteur d'images : créez un détecteur à 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_remote_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 customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(model)
        .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

val objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions)

File modelFile = new File(context.getCacheDir(), "my_remote_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();
}

CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(model)
                .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

ObjectDetector objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions);

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()) {
    // Model is already cached, initialize immediately
    initializeDetector(localFile)
} else {
    // Model is not yet available, show loading UI and start download
    showLoadingUI()
    val storage = Firebase.storage
    val modelRef = storage.getReferenceFromUrl("gs://YOUR_BUCKET/path/to/model.tflite")
    modelRef.getFile(localFile)
        .addOnSuccessListener {
            // Download complete, initialize the detector
            hideLoadingUI()
            initializeDetector(localFile)
        }
        .addOnFailureListener {
            // Handle download error
            showErrorUI()
        }
}

private fun initializeDetector(modelFile: File) {
    val localModel = LocalModel.Builder().setAbsoluteFilePath(modelFile.absolutePath).build()
    val customObjectDetectorOptions = CustomObjectDetectorOptions.Builder(localModel)
            .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
            .enableClassification()
            .build()
    val objectDetector = ObjectDetection.getClient(customObjectDetectorOptions)
    // Enable ML-related UI features here
    enableMLFeatures(objectDetector)
}

File localFile = new File(context.getCacheDir(), "my_remote_model.tflite");
if (localFile.exists()) {
    // Model is already cached, initialize immediately
    initializeDetector(localFile);
} else {
    // Model is not yet available, show loading UI and start download
    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) {
                // Download complete, initialize the detector
                hideLoadingUI();
                initializeDetector(localFile);
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception exception) {
                // Handle download error
                showErrorUI();
            }
        });
}

private void initializeDetector(File modelFile) {
    LocalModel localModel = new LocalModel.Builder().setAbsoluteFilePath(modelFile.getAbsolutePath()).build();
    CustomObjectDetectorOptions customObjectDetectorOptions =
            new CustomObjectDetectorOptions.Builder(localModel)
                    .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                    .enableClassification()
                    .build();
    ObjectDetector objectDetector = ObjectDetection.getClient(customObjectDetectorOptions);
    // Enable ML-related UI features here
    enableMLFeatures(objectDetector);
}

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

4. Exécuter le détecteur d'objets

objectDetector
    .process(image)
    .addOnFailureListener(e -> {...})
    .addOnSuccessListener(results -> {
        for (detectedObject in results) {
          // ...
        }
    });

objectDetector
    .process(image)
    .addOnFailureListener(e -> {...})
    .addOnSuccessListener(results -> {
        for (DetectedObject detectedObject : results) {
          // ...
        }
    });

5. Obtenir des informations sur les objets libellés

Si l'appel à process() aboutit, une liste de DetectedObject est transmise à l'écouteur de réussite.

Chaque DetectedObject contient les propriétés suivantes :

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (detectedObject in results) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
      val text = label.text
      val index = label.index
      val confidence = label.confidence
    }
}

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (DetectedObject detectedObject : results) {
  Rect boundingBox = detectedObject.getBoundingBox();
  Integer trackingId = detectedObject.getTrackingId();
  for (Label label : detectedObject.getLabels()) {
    String text = label.getText();
    int index = label.getIndex();
    float confidence = label.getConfidence();
  }
}

Garantir une expérience utilisateur de qualité

Pour offrir la meilleure expérience utilisateur possible, suivez ces consignes dans votre application :

• La détection d'objets dépend de leur complexité visuelle. Pour être détectés, les objets avec un petit nombre de caractéristiques visuelles peuvent avoir besoin d'occuper une plus grande partie de l'image. Vous devez fournir aux utilisateurs des conseils sur la façon de capturer des entrées qui fonctionnent bien avec le type d'objets que vous souhaitez détecter.
• Lorsque vous utilisez la classification, si vous souhaitez détecter des objets qui ne correspondent pas exactement aux catégories acceptées, implémentez un traitement spécial pour les objets inconnus.

Consultez également l'application de démonstration ML Kit Material Design et la collection de modèles Material Design pour les fonctionnalités optimisées par le machine learning.

Amélioration des performances

• Lorsque vous utilisez le mode streaming dans une application en temps réel, n'utilisez pas la détection d'objets multiples, car la plupart des appareils ne seront pas en mesure de produire des fréquences d'images adéquates.

• Si vous utilisez les API Camera ou camera2, limitez les appels au détecteur. Si une nouvelle image vidéo devient disponible pendant l'exécution du détecteur, 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 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 la superposition en une seule étape. Le rendu est effectué 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'exemple d'application 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.