Vous pouvez utiliser ML Kit pour reconnaître des entités dans une image et les étiqueter. Cette API est compatible avec un large éventail de modèles de classification d'images personnalisés. Reportez-vous à 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 l'étiquetage d'images à des modèles personnalisés: en regroupant le pipeline dans votre application ou en utilisant un pipeline dégroupé qui dépend des services Google Play. Si vous sélectionnez le pipeline sans bundle, la taille de votre application sera réduite. Pour en savoir plus, consultez le tableau ci-dessous.
Groupée | Sans groupe | |
---|---|---|
Nom de la bibliothèque | com.google.mlkit:image-labeling-custom | com.google.android.gms:play-services-mlkit-image-labeling-custom |
Implémentation | Le pipeline est associé de manière statique à votre application au moment de la compilation. | Le pipeline est téléchargé dynamiquement via les services Google Play. |
Taille d'application | Augmentation de la taille d'environ 3,8 Mo. | Augmentation de la taille d'environ 200 Ko. |
Délai d'initialisation | Le pipeline est disponible immédiatement. | Vous devrez peut-être attendre le téléchargement du pipeline avant de la première utilisation. |
Étape du cycle de vie de l'API | Disponibilité générale (DG) | Bêta |
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 ces 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é.
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 (généralement
app/build.gradle
). 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.2' }
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' }
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 votre application 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 pipeline au moment de l'installation ou ne demandez pas de téléchargement explicite, le pipeline 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.
Ajoutez la dépendance
linkFirebase
si vous souhaitez télécharger un modèle de manière dynamique à partir de Firebase:Pour télécharger un modèle de manière dynamique à partir de Firebase, ajoutez la dépendance
linkFirebase
:dependencies { // ... // Image labeling feature with model downloaded from Firebase implementation 'com.google.mlkit:image-labeling-custom:17.0.2' // Or use the dynamically downloaded pipeline in Google Play Services // implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta5' 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 RemoteModel
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.
Configurer l'étiqueteur d'images
Après avoir configuré les sources de votre modèle, créez un objet ImageLabeler
à partir de l'une d'elles.
Les options suivantes sont disponibles :
Options | |
---|---|
confidenceThreshold
|
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é. |
maxResultCount
|
Nombre maximal d'étiquettes à renvoyer. Si cette règle n'est pas configurée, la valeur par défaut (10) est utilisée. |
Si vous ne disposez que d'un modèle groupé localement, créez simplement un étiqueteur à partir de votre objet LocalModel
:
Kotlin
val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel) .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build() val labeler = ImageLabeling.getClient(customImageLabelerOptions)
Java
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 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 n'ayez à le confirmer qu'avant d'exécuter l'étiqueteur, 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 de l'étiqueteur d'images: créez un étiqueteur à partir du modèle distant s'il a été téléchargé, et à partir du modèle local dans le cas contraire.
Kotlin
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener { isDownloaded -> val optionsBuilder = if (isDownloaded) { CustomImageLabelerOptions.Builder(remoteModel) } else { CustomImageLabelerOptions.Builder(localModel) } val options = optionsBuilder .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build() val labeler = ImageLabeling.getClient(options) }
Java
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(Boolean isDownloaded) { CustomImageLabelerOptions.Builder optionsBuilder; if (isDownloaded) { optionsBuilder = new CustomImageLabelerOptions.Builder(remoteModel); } else { optionsBuilder = new CustomImageLabelerOptions.Builder(localModel); } CustomImageLabelerOptions options = optionsBuilder .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 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. } });
2. Préparer l'image d'entrée
Ensuite, pour chaque image à laquelle vous souhaitez ajouter un libellé, créez un objetInputImage
à partir de cette image. L'étiqueteur d'image fonctionne plus rapidement lorsque vous utilisez une Bitmap
ou, si vous utilisez l'API appareil2, un YUV_420_888 media.Image
, ce qui est recommandé dans la mesure du possible.
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.
3. Exécuter l'étiqueteur d'images
Pour étiqueter des objets dans une image, transmettez l'objet image
à la méthode process()
de ImageLabeler
.
Kotlin
labeler.process(image) .addOnSuccessListener { labels -> // Task completed successfully // ... } .addOnFailureListener { e -> // Task failed with an exception // ... }
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 // ... } });
4. Obtenir des informations sur les entités étiquetées
Si l'opération d'étiquetage d'image aboutit, une liste d'objetsImageLabel
est transmise à l'écouteur de réussite. Chaque objet ImageLabel
représente un élément étiqueté dans l'image. Vous pouvez obtenir la description textuelle de chaque étiquette (si disponible dans les métadonnées du fichier de modèle TensorFlow Lite), le score de confiance et l'indice. Exemple :
Kotlin
for (label in labels) { val text = label.text val confidence = label.confidence val index = label.index }
Java
for (ImageLabel label : labels) { String text = label.getText(); float confidence = label.getConfidence(); int index = label.getIndex(); }
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'API
Camera
oucamera2
, limitez les appels à l'étiqueteur d'images. Si une nouvelle image de la vidéo devient disponible pendant l'exécution de l'étiqueteur d'images, 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 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 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
.