Lorsque vous transmettez une image à ML Kit, il détecte jusqu'à cinq objets dans l'image, ainsi que la position de chaque objet dans l'image. Lors de la détection d'objets dans des flux vidéo, chaque objet possède un identifiant unique que vous pouvez utiliser pour suivre l'objet d'une image à l'autre.
Vous pouvez utiliser un modèle de classification d'images personnalisé pour classer les objets détectés. Consultez la page 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'éléments de votre application ou le télécharger dynamiquement à partir de Firebase. Le tableau suivant compare les deux options.
Modèle groupé | Modèle hébergé |
---|---|
Le modèle fait partie de l'APK de votre application, ce qui augmente sa taille. | Le modèle ne fait pas partie de votre APK. Il est hébergé en l'important dans Firebase Machine Learning. |
Le modèle est disponible immédiatement, même lorsque l'appareil Android est hors connexion | Le modèle est téléchargé à la demande |
Aucun projet Firebase n'est nécessaire | Nécessite un projet Firebase |
Vous devez republier votre application pour mettre à jour le modèle. | Déployer les mises à jour du modèle sans republier votre application |
Aucun test A/B intégré | Tests A/B faciles avec Firebase Remote Config |
Essayer
- Consultez l'application de démarrage rapide Vision pour obtenir un exemple d'utilisation du modèle groupé, et l'application de démarrage rapide automl pour un exemple d'utilisation du modèle hébergé.
- Consultez l'application Material Design Showcase pour une implémentation de bout en bout de cette API.
Avant de commencer
Dans le fichier
build.gradle
au niveau du projet, veillez à inclure le dépôt Maven de Google dans les sectionsbuildscript
etallprojects
.Ajoutez les dépendances des bibliothèques Android de ML Kit au fichier Gradle au niveau de l'application de votre module, qui est généralement
app/build.gradle
:Pour regrouper un modèle dans votre application:
dependencies { // ... // Object detection & tracking feature with custom bundled model implementation 'com.google.mlkit:object-detection-custom:17.0.2' }
Pour télécharger un modèle de manière dynamique à partir de Firebase, ajoutez la dépendance
linkFirebase
:dependencies { // ... // Object detection & tracking feature with model downloaded // from firebase implementation 'com.google.mlkit:object-detection-custom:17.0.2' implementation 'com.google.mlkit:linkfirebase:17.0.0' }
Si vous souhaitez télécharger un modèle, assurez-vous d'ajouter Firebase à votre projet Android, si ce n'est pas déjà fait. Cette opération n'est pas nécessaire lorsque vous regroupez le modèle.
1. Charger le modèle
Configurer une source de modèle locale
Pour regrouper le modèle avec votre application:
Copiez le fichier de modèle (se terminant généralement par
.tflite
ou.lite
) dans le dossierassets/
de votre application. (Vous devrez peut-être d'abord créer le dossier en effectuant un clic droit sur le dossierapp/
, puis en cliquant sur Nouveau > Dossier > Dossier d'éléments.)Ensuite, ajoutez les éléments suivants au fichier
build.gradle
de votre application pour vous assurer que Gradle ne compresse pas le fichier de modèle lors de la compilation de l'application:android { // ... aaptOptions { noCompress "tflite" // or noCompress "lite" } }
Le fichier de modèle sera inclus dans le package de l'application et mis à la disposition de ML Kit en tant qu'élément brut.
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 file path to model file) // or .setUri(URI to model file) .build()
Java
LocalModel localModel = new LocalModel.Builder() .setAssetFilePath("model.tflite") // or .setAbsoluteFilePath(absolute file path to model file) // or .setUri(URI to model file) .build();
Configurer une source de modèle hébergée par Firebase
Pour utiliser le modèle hébergé à distance, créez un objet CustomRemoteModel
dans FirebaseModelSource
, en spécifiant le nom que vous avez attribué au modèle lorsque vous l'avez publié:
Kotlin
// Specify the name you assigned in the Firebase console. val remoteModel = CustomRemoteModel .Builder(FirebaseModelSource.Builder("your_model_name").build()) .build()
Java
// Specify the name you assigned in the Firebase console. CustomRemoteModel remoteModel = new CustomRemoteModel .Builder(new FirebaseModelSource.Builder("your_model_name").build()) .build();
Lancez ensuite la tâche de téléchargement du modèle en spécifiant les conditions dans lesquelles vous souhaitez autoriser le téléchargement. Si le modèle ne se trouve pas sur l'appareil ou si une version plus récente du modèle est disponible, la tâche télécharge le modèle de manière asynchrone à partir de Firebase:
Kotlin
val downloadConditions = DownloadConditions.Builder() .requireWifi() .build() RemoteModelManager.getInstance().download(remoteModel, downloadConditions) .addOnSuccessListener { // Success. }
Java
DownloadConditions downloadConditions = new DownloadConditions.Builder() .requireWifi() .build(); RemoteModelManager.getInstance().download(remoteModel, downloadConditions) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(@NonNull Task task) { // Success. } });
De nombreuses applications lancent la tâche de téléchargement dans leur code d'initialisation, mais vous pouvez le faire à tout moment avant de devoir utiliser le modèle.
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:
Paramètres du détecteur d'objets | |
---|---|
Mode de détection |
STREAM_MODE (par défaut) | SINGLE_IMAGE_MODE
Dans Dans |
Détecter et suivre plusieurs objets |
false (par défaut) | true
Permet de détecter et de suivre jusqu'à cinq objets ou uniquement l'objet le plus visible (par défaut). |
Classer des objets |
false (par défaut) | true
Indique si les objets détectés doivent être classés à l'aide du modèle de classificateur personnalisé fourni. Pour utiliser votre modèle de classification personnalisé, vous devez définir la valeur sur |
Seuil de confiance de la classification |
Score de confiance minimal des étiquettes détectées. Si cette règle n'est pas configurée, tout seuil de classification spécifié par les métadonnées du modèle sera utilisé. Si le modèle ne contient aucune métadonnée ou si les métadonnées ne spécifient pas de seuil de classificateur, un seuil par défaut de 0,0 sera utilisé. |
Nombre maximal d'étiquettes par objet |
Nombre maximal d'étiquettes par objet que le détecteur renvoie. Si cette règle n'est pas configurée, la valeur par défaut (10) est utilisée. |
L'API de détection et de suivi des objets est optimisée pour ces deux principaux cas d'utilisation:
- Détection et suivi en direct de l'objet le plus proéminent dans le viseur de l'appareil photo.
- Détection de plusieurs objets à partir d'une image statique.
Pour configurer l'API pour ces cas d'utilisation avec un modèle groupé localement:
Kotlin
// 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)
Java
// 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 devez vérifier qu'il a été téléchargé avant de l'exécuter. Vous pouvez vérifier l'état de la tâche de téléchargement du modèle à l'aide de la méthode isModelDownloaded()
du gestionnaire de modèles.
Bien que vous deviez seulement confirmer cela avant d'exécuter le détecteur, si vous disposez à la fois d'un modèle hébergé à distance et d'un modèle groupé 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é, ou à partir du modèle local.
Kotlin
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener { isDownloaded -> val optionsBuilder = if (isDownloaded) { CustomObjectDetectorOptions.Builder(remoteModel) } else { CustomObjectDetectorOptions.Builder(localModel) } val customObjectDetectorOptions = optionsBuilder .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE) .enableClassification() .setClassificationConfidenceThreshold(0.5f) .setMaxPerObjectLabelCount(3) .build() val objectDetector = ObjectDetection.getClient(customObjectDetectorOptions) }
Java
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(Boolean isDownloaded) { CustomObjectDetectorOptions.Builder optionsBuilder; if (isDownloaded) { optionsBuilder = new CustomObjectDetectorOptions.Builder(remoteModel); } else { optionsBuilder = new CustomObjectDetectorOptions.Builder(localModel); } CustomObjectDetectorOptions customObjectDetectorOptions = optionsBuilder .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 interface utilisateur) jusqu'à ce que vous confirmiez le téléchargement du modèle. Pour ce faire, associez un écouteur à la méthode download()
du gestionnaire de modèles:
Kotlin
RemoteModelManager.getInstance().download(remoteModel, conditions) .addOnSuccessListener { // Download complete. Depending on your app, you could enable the ML // feature, or switch from the local model to the remote model, etc. }
Java
RemoteModelManager.getInstance().download(remoteModel, conditions) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(Void v) { // Download complete. Depending on your app, you could enable // the ML feature, or switch from the local model to the remote // model, etc. } });
3. Préparer l'image d'entrée
Créez un objetInputImage
à partir de votre image.
Le détecteur d'objets s'exécute directement à partir d'un Bitmap
, d'un ByteBuffer
NV21 ou d'un media.Image
YUV_420_888. Il est recommandé de construire un InputImage
à partir de ces sources si vous disposez d'un accès direct à l'une d'entre elles. Si vous créez un InputImage
à partir d'autres sources, nous gérerons la conversion en interne à votre place, et cette opération pourra s'avérer moins efficace.
Vous pouvez créer un objet InputImage
à partir de différentes sources, chacune 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 avec 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'appareils 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 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 }
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)
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 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() }
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
, 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:
Kotlin
val image = InputImage.fromByteBuffer( byteBuffer, /* image width */ 480, /* image height */ 360, rotationDegrees, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 ) // Or: val image = InputImage.fromByteArray( byteArray, /* image width */ 480, /* image height */ 360, rotationDegrees, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 )
Java
InputImage image = InputImage.fromByteBuffer(byteBuffer, /* image width */ 480, /* image height */ 360, rotationDegrees, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 ); // Or: InputImage image = InputImage.fromByteArray( byteArray, /* image width */480, /* image height */360, rotation, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 );
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)
Java
InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
L'image est représentée par un objet Bitmap
accompagné de degrés de rotation.
4. Exécuter le détecteur d'objets
Kotlin
objectDetector .process(image) .addOnFailureListener(e -> {...}) .addOnSuccessListener(results -> { for (detectedObject in results) { // ... } });
Java
objectDetector .process(image) .addOnFailureListener(e -> {...}) .addOnSuccessListener(results -> { for (DetectedObject detectedObject : results) { // ... } });
5. Obtenir des informations sur les objets étiquetés
Si l'appel de process()
aboutit, une liste de DetectedObject
est transmise à l'écouteur de réussite.
Chaque DetectedObject
contient les propriétés suivantes:
Cadre de délimitation | Rect qui indique la position de l'objet dans l'image. |
||||||
ID de suivi | Entier qui identifie l'objet dans toutes les images. Null en SINGLE_IMAGE_MODE. | ||||||
Étiquettes |
|
Kotlin
// 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 } }
Java
// 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(); } }
Assurer une expérience utilisateur optimale
Pour une expérience utilisateur optimale, suivez ces consignes dans votre application:
- La réussite de la détection d'objets dépend de la complexité visuelle de l'objet. Pour être détectés, les objets dotés d'un petit nombre de caractéristiques visuelles devront peut-être occuper une plus grande partie de l'image. Vous devez fournir aux utilisateurs des conseils sur la capture 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 correctement aux catégories compatibles, mettez en œuvre un traitement spécial pour les objets inconnus.
Consultez également l'application de présentation ML Kit Material Design et la collection Modèles de Material Design pour les fonctionnalités basées sur le machine learning.
Amélioration des performances
Si vous souhaitez utiliser la détection d'objets dans une application en temps réel, suivez ces consignes pour obtenir les meilleures fréquences d'images:Lorsque vous utilisez le mode streaming dans une application en temps réel, n'ayez pas recours à la détection d'objets multiples, car la plupart des appareils ne sont pas en mesure de produire des fréquences d'images adéquates.
- Si vous utilisez l'API
Camera
oucamera2
, limitez les appels au détecteur. Si une nouvelle image vidéo devient disponible pendant que le détecteur est en cours d'exécution, déposez l'image. Consultez la classeVisionProcessorBase
dans l'exemple d'application de démarrage rapide pour un exemple. - Si vous utilisez l'API
CameraX
, assurez-vous que la stratégie de contre-pression est définie sur sa valeur par défautImageAnalysis.STRATEGY_KEEP_ONLY_LATEST
. Cela garantit qu'une seule image à la fois sera envoyée pour analyse. Si d'autres images sont produites lorsque l'analyseur est occupé, elles sont automatiquement supprimées et ne sont pas mises en file d'attente pour la diffusion. Une fois l'image en cours d'analyse fermée en appelant ImageProxy.close(), la dernière image suivante est diffusée. - Si vous utilisez la sortie du détecteur 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. La surface d'affichage n'est affichée qu'une seule fois pour chaque image d'entrée. Consultez les classes
CameraSourcePreview
etGraphicOverlay
dans l'exemple d'application de démarrage rapide pour voir un exemple. - 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 formatImageFormat.NV21
.