Guide de reconnaissance de gestes pour Python

La tâche de reconnaissance des gestes MediaPipe vous permet de reconnaître les gestes de la main en temps réel et fournit les résultats de reconnaissance des gestes de la main et les repères de la main des mains détectées. Ces instructions vous expliquent comment utiliser le détecteur de gestes avec des applications Python.

Pour voir cette tâche en action, consultez la démo 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 pour le détecteur de gestes fournit une implémentation complète de cette tâche en Python à titre de référence. Ce code vous aide à tester cette tâche et à commencer à créer votre propre système de reconnaissance des gestes. Vous pouvez afficher, exécuter et modifier l'exemple de code du détecteur de gestes à l'aide de votre navigateur Web.

Si vous implémentez le détecteur de gestes pour Raspberry Pi, consultez l'application exemple pour Raspberry Pi.

Configuration

Cette section décrit les étapes clés à suivre pour configurer votre environnement de développement et vos projets de code spécifiquement pour utiliser le détecteur de gestes. 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 la version de la plate-forme, consultez le guide de configuration pour Python.

Colis

La tâche de reconnaissance des gestes MediaPipe nécessite le package PyPI mediapipe. Vous pouvez installer et importer ces dépendances avec les commandes suivantes:

$ python -m pip install mediapipe

Importations

Importez les classes suivantes pour accéder aux fonctions de tâche du détecteur de gestes:

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

Modèle

La tâche de reconnaissance des gestes MediaPipe nécessite un bundle de modèle entraîné compatible avec cette tâche. Pour en savoir plus sur les modèles entraînés disponibles pour le détecteur de gestes, consultez la section Modèles de la présentation de la tâche.

Sélectionnez et téléchargez le modèle, puis stockez-le dans un répertoire local:

model_path = '/absolute/path/to/gesture_recognizer.task'

Spécifiez le chemin d'accès au modèle dans le paramètre "Nom du modèle", comme indiqué ci-dessous:

base_options = BaseOptions(model_asset_path=model_path)

Créer la tâche

La tâche de reconnaissance des gestes MediaPipe utilise la fonction create_from_options pour configurer la tâche. La fonction create_from_options accepte les valeurs des options de configuration à gérer. Pour en savoir plus sur les options de configuration, consultez la section Options de configuration.

Le code suivant montre comment créer et configurer cette tâche.

Ces exemples montrent également les variations de la construction de la tâche pour les images, les fichiers vidéo et les diffusions vidéo en direct.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the image mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the video mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
GestureRecognizerResult = mp.tasks.vision.GestureRecognizerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the live stream mode:
def print_result(result: GestureRecognizerResult, output_image: mp.Image, timestamp_ms: int):
    print('gesture recognition result: {}'.format(result))

options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

Options de configuration

Cette tâche propose les options de configuration suivantes pour les applications Python:

Préparer les données

Préparez votre entrée en tant que fichier image ou tableau numpy, puis convertissez-la en objet mediapipe.Image. Si votre entrée est un fichier vidéo ou un flux en direct à partir d'une webcam, vous pouvez utiliser une bibliothèque externe telle que OpenCV pour charger vos frames d'entrée en tant que tableaux numpy.

import mediapipe as mp

# Load the input image from an image file.
mp_image = mp.Image.create_from_file('/path/to/image')

# Load the input image from a numpy array.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to load the input video.

# Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS
# You’ll need it to calculate the timestamp for each frame.

# Loop through each frame in the video using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to start capturing from the webcam.

# Create a loop to read the latest frame from the camera using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

Exécuter la tâche

L'outil de reconnaissance des gestes utilise les fonctions recognize, recognize_for_video et recognize_async pour déclencher des inférences. Pour la reconnaissance des gestes, cela implique de prétraiter les données d'entrée, de détecter les mains dans l'image, de détecter les points de repère des mains et de reconnaître les gestes des mains à partir des points de repère.

Le code suivant montre comment exécuter le traitement avec le modèle de tâche.

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the image mode.
gesture_recognition_result = recognizer.recognize(mp_image)
    

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the video mode.
gesture_recognition_result = recognizer.recognize_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform gesture recognition.
# The results are accessible via the `result_callback` provided in
# the `GestureRecognizerOptions` object.
# The gesture recognizer must be created with the live stream mode.
recognizer.recognize_async(mp_image, frame_timestamp_ms)
    

Veuillez noter les points suivants :

• Lorsque vous exécutez le mode vidéo ou le mode diffusion en direct, vous devez également fournir à la tâche de reconnaissance des gestes le code temporel du frame d'entrée.
• Lors de l'exécution dans le modèle d'image ou de vidéo, la tâche de reconnaissance des gestes bloque le thread actuel jusqu'à ce qu'elle ait terminé de traiter l'image ou le frame d'entrée.
• Lorsqu'elle s'exécute en mode diffusion en direct, la tâche du détecteur de gestes ne bloque pas le thread en cours, mais renvoie immédiatement. Il appelle son écouteur de résultats avec le résultat de la reconnaissance chaque fois qu'il a terminé le traitement d'un frame d'entrée. Si la fonction de reconnaissance est appelée lorsque la tâche du détecteur de gestes est occupée à traiter un autre frame, la tâche ignore le nouveau frame d'entrée.

Pour obtenir un exemple complet d'exécution d'un détecteur de gestes sur une image, consultez l'exemple de code.

Gérer et afficher les résultats

Le détecteur de gestes génère un objet de résultat de détection de gestes pour chaque exécution de la reconnaissance. L'objet résultat contient des repères de main en coordonnées d'image, des repères de main en coordonnées mondiales, une latéralité(main gauche/droite) et des 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 généré contient quatre composants, et chaque composant est un tableau, où chaque élément contient le résultat détecté d'une seule main détectée.

• Main dominante

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

• Gestes

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

• Points de repère

  Il existe 21 repères de la main, chacun composé de coordonnées x, y et z. Les coordonnées x et y sont normalisées à [0,0, 1,0] par la largeur et la hauteur de l'image, respectivement. La coordonnée z représente la profondeur du repère, la profondeur au poignet étant l'origine. Plus la valeur est faible, plus le repère est proche de la caméra. L'ampleur de z utilise à peu près la même échelle que x.

• Monuments du monde

  Les 21 repères de la main sont également présentés en coordonnées mondiales. Chaque repère est composé de x, y et z, qui représentent des coordonnées 3D réelles en mètres, avec l'origine 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 présentent une visualisation de la sortie de la tâche:

L'exemple de code du détecteur de gestes montre comment afficher les résultats de reconnaissance renvoyés par la tâche. Pour en savoir plus, consultez l'exemple de code.