Guide de reconnaissance des gestes pour iOS

La tâche de reconnaissance de gestes MediaPipe vous permet de reconnaître des gestes de la main en temps réel et fournit les résultats et points de repère des gestes détectés. Ces instructions vous expliquent comment utiliser la reconnaissance de gestes avec les applications iOS.

Pour voir cette tâche en action, consultez la 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 présentation.

Exemple de code

L'exemple de code MediaPipe Tasks est une implémentation de base d'une application de reconnaissance de gestes pour iOS. L'exemple utilise la caméra d'un appareil iOS physique pour détecter en permanence les gestes de la main, et peut également utiliser des images et des vidéos de la galerie de l'appareil pour détecter des gestes de manière statique.

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 la reconnaissance de gestes 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, procédez comme suit:

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 éventuellement configurer votre instance Git pour utiliser le paiement creux afin de n'avoir que les fichiers de l'application exemple de reconnaissance de gestes:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/gesture_recognizer/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 crucial de l'exemple d'application de reconnaissance de gestes:

• GestureRecognizerService.swift: initialise l'outil de reconnaissance de gestes, 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'interface utilisateur pour le mode d'entrée du flux de la caméra en direct et visualise les résultats.
• MediaLibraryViewController.swift: met en œuvre l'interface utilisateur pour le mode d'entrée de fichier image fixe et vidéo, et affiche les résultats.

Préparation

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

Dépendances

L'outil de reconnaissance de gestes 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 spécifique au langage utilisé.

Pour savoir comment installer CocoaPods sous 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 fichier Podfile à l'aide du code suivant:

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

Si votre application inclut des cibles de tests unitaires, consultez le guide de configuration pour iOS afin d'obtenir des informations supplémentaires sur la configuration de votre Podfile.

Modèle

La tâche MediaPipe de reconnaissance de gestes 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 la reconnaissance de gestes, consultez la section Modèles de la présentation des tâches.

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 la page 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. Pour obtenir un exemple de code, consultez la section suivante.

Créer la tâche

Vous pouvez créer la tâche de reconnaissance de gestes en appelant l'un de ses initialiseurs. L'initialiseur GestureRecognizer(options:) accepte les valeurs pour les options de configuration.

Si vous n'avez pas besoin d'initialiser la reconnaissance de gestes avec des options de configuration personnalisées, vous pouvez utiliser l'initialiseur GestureRecognizer(modelPath:) pour créer une reconnaissance de gestes avec les options par défaut. Pour en savoir plus sur les options de configuration, consultez la section Présentation de la configuration.

La tâche de reconnaissance de gestes 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, GestureRecognizer(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 GestureRecognizer(options:) pour spécifier le mode d'exécution de la vidéo ou du streaming en direct. Le mode diffusion en direct nécessite également l'option de configuration gestureRecognizerLiveStreamDelegate supplémentaire, qui permet à l'outil de reconnaissance de gestes de fournir des résultats de reconnaissance de gestes au délégué de manière asynchrone.

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

Swift

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "gesture_recognizer",
                                      ofType: "task")

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let gestureRecognizer = try GestureRecognizer(options: options)
    

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "gesture_recognizer",
                                      ofType: "task")

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let gestureRecognizer = try GestureRecognizer(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `GestureRecognizerLiveStreamDelegate` protocol and
// implements the method that the gesture recognizer calls once it finishes
// performing recognizing hand gestures in each input frame.
class GestureRecognizerResultProcessor: NSObject, GestureRecognizerLiveStreamDelegate {

  func gestureRecognizer(
    _ gestureRecognizer: GestureRecognizer,
    didFinishRecognition result: GestureRecognizerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the gesture recognizer result or errors here.

  }
}

let modelPath = Bundle.main.path(
  forResource: "gesture_recognizer",
  ofType: "task")

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

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

let gestureRecognizer = try GestureRecognizer(options: options)
    

Objective-C

@import MediaPipeTasksVision;

NSString *modelPath =
  [[NSBundle mainBundle] pathForResource:@"gesture_recognizer"
                                  ofType:@"task"];

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

NSString *modelPath =
  [[NSBundle mainBundle] pathForResource:@"gesture_recognizer"
                                  ofType:@"task"];

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPGestureRecognizerLiveStreamDelegate` protocol
// and implements the method that the gesture recognizer calls once it finishes
// performing gesture recognition on each input frame.

@interface APPGestureRecognizerResultProcessor : NSObject 

@end

@implementation APPGestureRecognizerResultProcessor

-   (void)gestureRecognizer:(MPPGestureRecognizer *)gestureRecognizer
    didFinishRecognitionWithResult:(MPPGestureRecognizerResult *)gestureRecognizerResult
           timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                             error:(NSError *)error {

    // Process the gesture recognizer result or errors here.

}

@end

NSString *modelPath =
  [[NSBundle mainBundle] pathForResource:@"gesture_recognizer"
                                  ofType:@"task"];

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

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

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

Options de configuration

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

Lorsque le mode de fonctionnement est défini sur "Diffuser en direct", l'outil de reconnaissance de gestes nécessite l'option de configuration gestureRecognizerLiveStreamDelegate supplémentaire, qui permet à l'outil de reconnaissance de gestes de fournir des résultats de reconnaissance de gestes de manière asynchrone. Le délégué doit implémenter la méthode gestureRecognizer(_:didFinishRecognition:timestampInMilliseconds:error:), que l'outil de reconnaissance de gestes appelle après avoir traité les résultats de la reconnaissance de gestes sur chaque image.

Préparation des données

Vous devez convertir l'image ou le cadre d'entrée en objet MPImage avant de le transmettre à l'outil de reconnaissance de gestes. MPImage accepte différents types de formats d'image 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 convient bien aux modes d'exécution suivants:

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

• Vidéos: utilisez AVAssetImageGenerator pour extraire des images vidéo au format CGImage, puis convertissez-les 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 acceptées. La reconnaissance de gestes n'est pas compatible avec les orientations en miroir telles que .upMirrored, .downMirrored, .leftMirrored et .rightMirrored.

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

CVPixelBuffer

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

Le format CVPixelBuffer convient bien 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'outil de reconnaissance de gestes en mode d'exécution d'image.

• Vidéos: les images vidéo peuvent être converties au format CVPixelBuffer pour leur traitement, puis envoyées à la reconnaissance de gestes 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 à des fins de traitement avant d'être envoyées à la reconnaissance de gestes en mode de 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, reportez-vous à la documentation sur CVPixelBuffer pour les développeurs.

CMSampleBuffer

Le format CMSampleBuffer stocke des échantillons multimédias d'un même type. Il convient parfaitement au mode d'exécution de diffusion en direct. Les images en direct des appareils photo iOS sont diffusées de manière asynchrone au format CMSampleBuffer par AVCaptureVideoDataOutput d'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, reportez-vous à la documentation sur CMSampleBuffer pour les développeurs d'Apple.

Exécuter la tâche

Pour exécuter l'outil de reconnaissance de gestes, utilisez la méthode recognize() spécifique au mode d'exécution attribué:

• Image fixe: recognize(image:)
• Vidéo : recognize(videoFrame:timestampInMilliseconds:)
• Diffusion en direct : recognizeAsync(image:timestampInMilliseconds:)

Les exemples de code suivants illustrent des exemples de base d'exécution de la reconnaissance de gestes dans ces différents modes d'exécution:

Swift

let result = try gestureRecognizer.recognize(image: image)
    

let result = try gestureRecognizer.recognize(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try gestureRecognizer.recognizeAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

  MPPGestureRecognizerResult *result =
    [gestureRecognizer recognizeImage:mppImage
                                error:nil];
    

MPPGestureRecognizerResult *result =
  [gestureRecognizer recognizeVideoFrame:image
                 timestampInMilliseconds:timestamp
                                   error:nil];
    

BOOL success =
  [gestureRecognizer recognizeAsyncImage:image
                 timestampInMilliseconds:timestamp
                                   error:nil];
    

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 reconnaissance de gestes.

• En mode image ou vidéo, la tâche de reconnaissance de gestes bloque le thread actuel jusqu'à ce qu'il ait fini 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 Dispatch ou NSOperation d'iOS.

• Lors de l'exécution en mode diffusion en direct, la tâche de reconnaissance de gestes est renvoyée immédiatement et ne bloque pas le thread actuel. Il appelle la méthode gestureRecognizer(_:didFinishRecognition:timestampInMilliseconds:error:) avec le résultat de la reconnaissance de geste après le traitement de chaque frame d'entrée. L'outil de reconnaissance de gestes 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 les avoir traités. Si la fonction recognizeAsync est appelée lorsque la tâche de reconnaissance de gestes est occupée à traiter une autre image, l'outil de reconnaissance de gestes ignore le nouveau frame d'entrée.

Gérer et afficher les résultats

Lors de l'exécution de l'inférence, la tâche de reconnaissance de gestes renvoie un GestureRecognizerResult qui contient les points de repère de la main en coordonnées d'image, les points de repère de la main en coordonnées mondiales, la main dominante(main gauche/droite) et les catégories de gestes de la main des mains détectées.

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

Le GestureRecognizerResult obtenu contient quatre composants, chacun étant un tableau, où chaque élément contient le résultat détecté d'une seule main détectée.

• Main dominante

  La main dominante indique si les mains détectées sont des mains gauches ou droites.

• Gestes

  Catégories de gestes reconnus pour les mains détectées.

• Points de repère

  Il y a 21 points de repère pour les mains, chacun composé des coordonnées x, y et z. Les coordonnées x et y sont normalisées à [0,0, 1,0] en fonction de la largeur et de la hauteur de l'image, respectivement. La coordonnée z représente la profondeur du point de repère, la profondeur au niveau du poignet correspondant à l'origine. Plus la valeur est faible, plus le point de repère est proche de la caméra. La magnitude de z utilise à peu près la même échelle que x.

• Monuments internationaux

  Les points de repère des 21 mains sont également indiqués en coordonnées mondiales. Chaque point de repère est composé de x, y et z, représentant des coordonnées 3D réelles en mètres avec le point de départ au centre géométrique de la main.

GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : -3.41E-7
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
    ... (21 landmarks for a hand)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
    ... (21 world landmarks for a hand)

Les images suivantes montrent une visualisation du résultat de la tâche: