Guide sur l'intégration d'images pour iOS

La tâche MediaPipe Image Embedder vous permet de convertir les données d'image en représentation numérique pour effectuer des tâches de traitement d'image liées au ML, telles que la comparaison de la similarité de deux images.

L'exemple de code décrit dans ces instructions est disponible sur GitHub. Pour voir cette tâche en action, regardez cette démonstration Web. Pour en savoir plus sur les fonctionnalités, les modèles et les options de configuration de cette tâche, consultez la section Présentation.

Exemple de code

L'exemple de code MediaPipe Tasks est une implémentation de base d'une application d'intégration d'images pour iOS. L'exemple utilise l'appareil photo d'un appareil iOS physique pour intégrer des images en continu et peut également exécuter l'outil d'intégration sur des fichiers image de la galerie de l'appareil.

Vous pouvez utiliser l'application comme point de départ pour votre propre application iOS ou vous y référer lorsque vous modifiez une application existante. L'exemple de code de l'outil d'intégration d'images est hébergé sur GitHub.

Télécharger le code

Les instructions suivantes vous expliquent comment créer une copie locale de l'exemple de code à l'aide de l'outil de ligne de commande git.

Pour télécharger l'exemple de code:

1. Clonez le dépôt Git à l'aide de la commande suivante :

   git clone https://github.com/google-ai-edge/mediapipe-samples
   

2. Vous pouvez également configurer votre instance git pour utiliser un "checkout sparse" afin de n'avoir que les fichiers de l'exemple d'application Image Embedder:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/image_embedder/ios
   

Après avoir créé une version locale de l'exemple de code, vous pouvez installer la bibliothèque de tâches MediaPipe, ouvrir le projet à l'aide de Xcode et exécuter l'application. Pour obtenir des instructions, consultez le guide de configuration pour iOS.

Composants clés

Les fichiers suivants contiennent le code essentiel de l'application exemple d'Image Embedder:

• ImageEmbedderService.swift : initialise l'outil Image Embedder, gère la sélection du modèle et exécute l'inférence sur les données d'entrée.
• CameraViewController.swift : implémente l'UI pour le mode d'entrée du flux de caméra en direct et visualise les résultats.
• MediaLibraryViewController.swift : implémente l'interface utilisateur pour le mode de saisie d'image fixe et visualise les résultats.

Configuration

Cette section décrit les étapes clés à suivre pour configurer votre environnement de développement et vos projets de code afin d'utiliser Image Embedder. Pour obtenir des informations générales sur la configuration de votre environnement de développement pour utiliser les tâches MediaPipe, y compris les exigences concernant les versions de la plate-forme, consultez le guide de configuration pour iOS.

Dépendances

Image Embedder utilise la bibliothèque MediaPipeTasksVision, qui doit être installée à l'aide de CocoaPods. La bibliothèque est compatible avec les applications Swift et Objective-C, et ne nécessite aucune configuration supplémentaire spécifique à la langue.

Pour savoir comment installer CocoaPods sur macOS, consultez le guide d'installation de CocoaPods. Pour savoir comment créer un Podfile avec les pods nécessaires à votre application, consultez la section Utiliser CocoaPods.

Ajoutez le pod MediaPipeTasksVision dans le Podfile à l'aide du code suivant :

target 'MyImageEmbedderApp' do
  use_frameworks!
  pod 'MediaPipeTasksVision'
end

Si votre application inclut des cibles de test unitaire, consultez le guide de configuration pour iOS pour en savoir plus sur la configuration de votre Podfile.

Modèle

La tâche d'encapsulation d'image MediaPipe nécessite un modèle entraîné compatible avec cette tâche. Pour en savoir plus sur les modèles entraînés disponibles pour Image Embedder, consultez la section Modèles.

Sélectionnez et téléchargez un modèle, puis ajoutez-le au répertoire de votre projet à l'aide de Xcode. Pour savoir comment ajouter des fichiers à votre projet Xcode, consultez Gérer les fichiers et les dossiers dans votre projet Xcode.

Utilisez la propriété BaseOptions.modelAssetPath pour spécifier le chemin d'accès au modèle dans votre app bundle.

Créer la tâche

Vous pouvez créer la tâche d'intégration d'images en appelant l'un de ses initialisateurs. L'initialiseur ImageEmbedder(options:) accepte les valeurs des options de configuration.

Si vous n'avez pas besoin d'initialiser d'un intégrateur d'images avec des options de configuration personnalisées, vous pouvez utiliser l'initialiseur ImageEmbedder(modelPath:) pour créer un intégrateur d'images avec les options par défaut. Pour en savoir plus sur les options de configuration, consultez la page Présentation de la configuration.

La tâche d'insertion d'images accepte trois types de données d'entrée: les images fixes, les fichiers vidéo et les flux vidéo en direct. Par défaut, ImageEmbedder(modelPath:) initialise une tâche pour les images fixes. Si vous souhaitez que votre tâche soit initialisée pour traiter des fichiers vidéo ou des flux vidéo en direct, utilisez ImageEmbedder(options:) pour spécifier le mode d'exécution de la vidéo ou du streaming en direct. Le mode de diffusion en direct nécessite également l'option de configuration imageEmbedderLiveStreamDelegate supplémentaire, qui permet à l'outil d'intégration d'images de transmettre les résultats d'intégration d'images au délégué de manière asynchrone.

Choisissez l'onglet correspondant à votre mode d'exécution pour découvrir comment créer la tâche et exécuter l'inférence.

Swift

import MediaPipeTasksVision

let modelPath = Bundle.main.path(
  forResource: "model",
  ofType: "tflite")

let options = ImageEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.quantize = true
options.l2Normalize = true

let imageEmbedder = try ImageEmbedder(options: options)
    

import MediaPipeTasksVision

let modelPath = Bundle.main.path(
  forResource: "model",
  ofType: "tflite")

let options = ImageEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.quantize = true
options.l2Normalize = true

let imageEmbedder = try ImageEmbedder(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `ImageEmbedderLiveStreamDelegate` protocol and
// implements the method that the image embedder calls once it finishes
// embedding each input frame.
class ImageEmbedderResultProcessor: NSObject, ImageEmbedderLiveStreamDelegate {

  func imageEmbedder(
    _ imageEmbedder: ImageEmbedder,
    didFinishEmbedding result: ImageEmbedderResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the image embedder result or errors here.

  }
}

let modelPath = Bundle.main.path(
  forResource: "model",
  ofType: "tflite")

let options = ImageEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.quantize = true
options.l2Normalize = true

// Assign an object of the class to the `imageEmbedderLiveStreamDelegate`
// property.
let processor = ImageEmbedderResultProcessor()
options.imageEmbedderLiveStreamDelegate = processor

let imageEmbedder = try ImageEmbedder(options: options)
    

Objective-C

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPImageEmbedderOptions *options = [[MPPImageEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.quantize = YES;
options.l2Normalize = YES;

MPPImageEmbedder *imageEmbedder =
  [[MPPImageEmbedder alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPImageEmbedderOptions *options = [[MPPImageEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.quantize = YES;
options.l2Normalize = YES;

MPPImageEmbedder *imageEmbedder =
  [[MPPImageEmbedder alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPImageEmbedderLiveStreamDelegate` protocol
// and implements the method that the image embedder calls once it finishes
// embedding each input frame.
@interface APPImageEmbedderResultProcessor : NSObject 

@end

@implementation APPImageEmbedderResultProcessor

-   (void)imageEmbedder:(MPPImageEmbedder *)imageEmbedder
    didFinishEmbeddingWithResult:(MPPImageEmbedderResult *)imageEmbedderResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the image embedder result or errors here.

}

@end

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPImageEmbedderOptions *options = [[MPPImageEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.quantize = YES;
options.l2Normalize = YES;

// Assign an object of the class to the `imageEmbedderLiveStreamDelegate`
// property.
APPImageEmbedderResultProcessor *processor =
  [APPImageEmbedderResultProcessor new];
options.imageEmbedderLiveStreamDelegate = processor;

MPPImageEmbedder *imageEmbedder =
  [[MPPImageEmbedder alloc] initWithOptions:options error:nil];
    

Options de configuration

Cette tâche comporte les options de configuration suivantes pour les applications iOS:

Lorsque le mode d'exécution est défini sur "streaming en direct", l'outil d'intégration d'images nécessite l'option de configuration imageEmbedderLiveStreamDelegate supplémentaire, qui lui permet de fournir des résultats d'intégration d'images de manière asynchrone. Le délégué doit implémenter la méthode imageEmbedder(_:didFinishEmbedding:timestampInMilliseconds:error:), que l'outil d'intégration d'images appelle après avoir traité les résultats de l'intégration de chaque frame d'image d'entrée.

Préparer les données

Vous devez convertir l'image ou le cadre d'entrée en objet MPImage avant de la transmettre à l'intégrateur d'images. MPImage est compatible avec différents types de formats d'images iOS et peut les utiliser dans n'importe quel mode d'exécution pour l'inférence. Pour en savoir plus sur MPImage, consultez l'API MPImage.

Choisissez un format d'image iOS en fonction de votre cas d'utilisation et du mode d'exécution requis par votre application.MPImage accepte les formats d'image iOS UIImage, CVPixelBuffer et CMSampleBuffer.

UIImage

Le format UIImage est adapté aux modes d'exécution suivants :

• Images: les images d'un bundle d'application, d'une galerie utilisateur ou d'un système de fichiers au format UIImage peuvent être converties en objet MPImage.

• Vidéos : utilisez AVAssetImageGenerator pour extraire les images vidéo au format CGImage, puis les convertir en images UIImage.

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(uiImage: image)
    

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
    

L'exemple initialise un MPImage avec l'orientation par défaut UIImage.Orientation.Up. Vous pouvez initialiser un MPImage avec l'une des valeurs UIImage.Orientation compatibles. L'outil d'intégration d'images n'est pas compatible avec les orientations en miroir telles que .upMirrored, .downMirrored, .leftMirrored et .rightMirrored.

Pour plus d'informations sur UIImage, consultez la documentation pour les développeurs Apple sur UIImage.

CVPixelBuffer

Le format CVPixelBuffer est adapté aux applications qui génèrent des frames et utilisent le framework CoreImage iOS pour le traitement.

Le format CVPixelBuffer est adapté aux modes d'exécution suivants :

• Images: les applications qui génèrent des images CVPixelBuffer après un traitement à l'aide du framework CoreImage d'iOS peuvent être envoyées à l'intégrateur d'images en mode d'exécution d'images.

• Vidéos: les images vidéo peuvent être converties au format CVPixelBuffer pour le traitement, puis envoyées à l'outil d'intégration d'images en mode vidéo.

• diffusion en direct: les applications qui utilisent une caméra iOS pour générer des images peuvent être converties au format CVPixelBuffer pour le traitement avant d'être envoyées à l'outil d'intégration d'images en mode diffusion en direct.

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(pixelBuffer: pixelBuffer)
    

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
    

Pour en savoir plus sur CVPixelBuffer, consultez la documentation pour les développeurs Apple sur CVPixelBuffer.

CMSampleBuffer

Le format CMSampleBuffer stocke des échantillons multimédias d'un type uniforme et convient bien au mode de diffusion en direct. Les images en direct des caméras iOS sont transmises de manière asynchrone au format CMSampleBuffer par AVCaptureVideoDataOutput sur iOS.

// Obtain a CMSampleBuffer.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(sampleBuffer: sampleBuffer)
    

// Obtain a `CMSampleBuffer`.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithSampleBuffer:sampleBuffer error:nil];
    

Pour en savoir plus sur CMSampleBuffer, consultez la documentation pour les développeurs Apple sur CMSampleBuffer.

Exécuter la tâche

Pour exécuter l'outil d'intégration d'images, utilisez la méthode embed() spécifique au mode d'exécution attribué:

• Image fixe : embed(image:)
• Vidéo : embed(videoFrame:timestampInMilliseconds:)
• Diffusion en direct : embedAsync(image:timestampInMilliseconds:)

Les exemples de code suivants montrent comment exécuter Image Embedder dans ces différents modes d'exécution:

Swift

let result = try imageEmbedder.embed(image: image)
    

let result = try imageEmbedder.embed(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try imageEmbedder.embedAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

MPPImageEmbedderResult *result =
  [imageEmbedder embedImage:image error:nil];
    

MPPImageEmbedderResult *result =
  [imageEmbedder embedVideoFrame:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

BOOL success =
  [imageEmbedder embedAsyncImage:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

L'exemple de code de l'intégrateur d'images montre les implémentations de chacun de ces modes plus en détail embed(image:), embed(videoFrame:timestampInMilliseconds:) et embedAsync(image:timestampInMilliseconds:). L'exemple de code permet à l'utilisateur de basculer entre les modes de traitement, ce qui n'est peut-être pas nécessaire pour votre cas d'utilisation.

Veuillez noter les points suivants :

• Lors de l'exécution en mode vidéo ou en mode diffusion en direct, vous devez également fournir l'horodatage de l'image d'entrée à la tâche de l'intégrateur d'images.

• Lorsqu'elle s'exécute en mode image ou vidéo, la tâche Image Embedder bloque le thread actuel jusqu'à ce qu'elle ait terminé de traiter l'image ou le frame d'entrée. Pour éviter de bloquer le thread actuel, exécutez le traitement dans un thread en arrière-plan à l'aide des frameworks iOS Dispatch ou NSOperation. Si votre application est créée à l'aide de Swift, vous pouvez également utiliser la concurrencialité Swift pour l'exécution de threads en arrière-plan.

• Lorsqu'elle s'exécute en mode diffusion en direct, la tâche d'intégration d'images renvoie immédiatement et ne bloque pas le thread en cours. Elle appelle la méthode imageEmbedder(_:didFinishEmbedding:timestampInMilliseconds:error:) avec les résultats, après avoir intégré chaque trame d'entrée. L'outil d'intégration d'images appelle cette méthode de manière asynchrone sur une file d'attente de distribution série dédiée. Pour afficher les résultats dans l'interface utilisateur, distribuez-les dans la file d'attente principale après le traitement. Si la fonction embedAsync est appelée lorsque la tâche d'intégration d'images est occupée à traiter un autre frame, l'outil d'intégration d'images ignore le nouveau frame d'entrée.

Gérer et afficher les résultats

Lors de l'exécution de l'inférence, l'outil d'encapsulation d'images renvoie un objet ImageEmbedderResult contenant une liste d'embeddings (à virgule flottante ou à quantification scalaire) pour l'image d'entrée.

Voici un exemple des données de sortie de cette tâche :

ImageEmbedderResult:
  Embedding #0 (sole embedding head):
    float_embedding: {0.0, 0.0, ..., 0.0, 1.0, 0.0, 0.0, 2.0}
    head_index: 0

Ce résultat a été obtenu en encapsulant l'image suivante:

Vous pouvez comparer la similarité de deux représentations vectorielles continues à l'aide de la fonction ImageEmbedder.cosineSimilarity.

let similarity = try ImageEmbedder.cosineSimilarity(
  embedding1: result.embeddingResult.embeddings[0],
  embedding2: otherResult.embeddingResult.embeddings[0])
    

NSNumber *similarity = [MPPImageEmbedder
      cosineSimilarityBetweenEmbedding1:result.embeddingResult.embeddings[0]
                          andEmbedding2:otherResult.embeddingResult.embeddings[0]
                                  error:nil];