Guide de détection des points de repère manuels pour Python

La tâche MediaPipe Hand Landmarker vous permet de détecter les points de repère des mains dans une image. Ces instructions vous expliquent comment utiliser Hand Markerer avec Python. L'exemple de code décrit dans ces instructions est disponible sur GitHub.

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 pour Hand Landmarker 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 détecteur de repères manuels. Vous pouvez afficher, exécuter et modifier l'exemple de code du repère manuel à l'aide de votre navigateur Web.

Si vous implémentez Hand Markerer 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 Hand Landmarker. 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 concernant les versions de la plate-forme, consultez le guide de configuration pour Python.

Colis

La tâche MediaPipe Hand Landmarker nécessite le package PyPI mediapipe. Vous pouvez installer et importer ces dépendances à l'aide des éléments suivants:

$ python -m pip install mediapipe

Importations

Importez les classes suivantes pour accéder aux fonctions de la tâche de repère de la main:

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

Modèle

La tâche de repère de la main 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 Hand Landmarker, 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'

Utilisez le paramètre model_asset_path de l'objet BaseOptions pour spécifier le chemin d'accès au modèle à utiliser. Pour obtenir un exemple de code, consultez la section suivante.

Créer la tâche

La tâche MediaPipe Hand Markerer utilise la fonction create_from_options pour la configurer. La fonction create_from_options accepte les valeurs que les options de configuration doivent 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 la diffusion en direct.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the image mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the video mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
HandLandmarkerResult = mp.tasks.vision.HandLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the live stream mode:
def print_result(result: HandLandmarkerResult, output_image: mp.Image, timestamp_ms: int):
    print('hand landmarker result: {}'.format(result))

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

Pour obtenir un exemple complet de création d'un repère de main à utiliser avec une image, consultez l'exemple de code.

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 une diffusion en direct depuis 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

Le repère de main utilise les fonctions detect, detect_for_video et detect_async pour déclencher des inférences. Pour la détection des points de repère des mains, vous devez prétraiter les données d'entrée, et détecter les mains dans l'image et les points de repère des mains.

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

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the image mode.
hand_landmarker_result = landmarker.detect(mp_image)
    

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the video mode.
hand_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform hand landmarks detection.
# The results are accessible via the `result_callback` provided in
# the `HandLandmarkerOptions` object.
# The hand landmarker must be created with the live stream mode.
landmarker.detect_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 repère manuel 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 repère manuel bloque le thread actuel jusqu'à ce qu'il 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 de repère de la main ne bloque pas le thread actuel, mais renvoie immédiatement. Il appelle son écouteur de résultats avec le résultat de la détection chaque fois qu'il a terminé le traitement d'un frame d'entrée. Si la fonction de détection est appelée lorsque la tâche Hand Markerer est occupée à traiter une autre image, la tâche ignore la nouvelle trame d'entrée.

Pour obtenir un exemple complet d'exécution d'un repère de main sur une image, consultez l'exemple de code.

Gérer et afficher les résultats

Le repère de la main génère un objet de résultat de repère de la main pour chaque exécution de détection. L'objet résultat contient des repères de main en coordonnées d'image, des repères de main en coordonnées mondiales et la latéralité(main gauche/droite) des mains détectées.

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

La sortie HandLandmarkerResult contient trois composants. Chaque composant est un tableau, où chaque élément contient les résultats suivants pour une seule main détectée:

• Main dominante

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

• Points de repère

  Il y a 21 points de repère de main, chacun composé de coordonnées x, y et z. Les coordonnées x et y sont normalisées à [0.0, 1.0] respectivement par la largeur et la hauteur de l'image. 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. La magnitude 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.

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  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)

L'image suivante présente une visualisation de la sortie de la tâche :

L'exemple de code Hand Landmarker montre comment afficher les résultats renvoyés par la tâche. Pour en savoir plus, consultez l'exemple de code.