Handbuch zur Gestenerkennung für Python

Mit der Aufgabe „MediaPipe-Gestenerkennung“ können Sie Gesten in Echtzeit erkennen und erhalten die Ergebnisse der erkannten Gesten und Markierungen der erkannten Hände. In dieser Anleitung erfahren Sie, wie Sie die Bewegungserkennung mit Python-Anwendungen verwenden.

Sie können sich diese Aufgabe in Aktion ansehen, indem Sie sich die Webdemo ansehen. Weitere Informationen zu den Funktionen, Modellen und Konfigurationsoptionen dieser Aufgabe finden Sie in der Übersicht.

Codebeispiel

Der Beispielcode für die Gestenerkennung enthält eine vollständige Implementierung dieser Aufgabe in Python. Mit diesem Code können Sie diese Aufgabe testen und mit dem Erstellen Ihrer eigenen Handgestenerkennung beginnen. Sie können den Beispielcode für die Bewegungserkennung nur über Ihren Webbrowser aufrufen, ausführen und bearbeiten.

Wenn Sie die Gestenerkennung für Raspberry Pi implementieren, verwenden Sie die Beispiel-App für Raspberry Pi.

Einrichtung

In diesem Abschnitt werden die wichtigsten Schritte zum Einrichten Ihrer Entwicklungsumgebung und Codeprojekte speziell für die Verwendung der Gestenerkennung beschrieben. Allgemeine Informationen zum Einrichten der Entwicklungsumgebung für die Verwendung von MediaPipe-Aufgaben, einschließlich der Anforderungen an die Plattformversion, finden Sie im Einrichtungsleitfaden für Python.

Pakete

Für die Aufgabe „MediaPipe-Gestenerkennung“ ist das PyPI-Paket „mediapipe“ erforderlich. Sie können diese Abhängigkeiten so installieren und importieren:

$ python -m pip install mediapipe

Importe

Importieren Sie die folgenden Klassen, um auf die Aufgabenfunktionen für die Gestenerkennung zuzugreifen:

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

Modell

Für die Aufgabe „MediaPipe-Gestenerkennung“ ist ein Bundle mit trainiertem Modell erforderlich, das mit dieser Aufgabe kompatibel ist. Weitere Informationen zu verfügbaren trainierten Modellen für die Gestenerkennung finden Sie in der Aufgabenübersicht im Abschnitt „Modelle“.

Wählen Sie das Modell aus, laden Sie es herunter und speichern Sie es dann in einem lokalen Verzeichnis:

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

Geben Sie den Pfad des Modells im Modellnamen-Parameter an, wie unten dargestellt:

base_options = BaseOptions(model_asset_path=model_path)

Aufgabe erstellen

Die Aufgabe „MediaPipe-Gestenerkennung“ verwendet die Funktion create_from_options, um die Aufgabe einzurichten. Die Funktion create_from_options akzeptiert Werte für Konfigurationsoptionen, die verarbeitet werden sollen. Weitere Informationen zu Konfigurationsoptionen finden Sie unter Konfigurationsoptionen.

Im folgenden Codebeispiel wird gezeigt, wie diese Aufgabe erstellt und konfiguriert wird.

Diese Beispiele zeigen auch die Variationen der Aufgabenkonstruktion für Bilder, Videodateien und Live-Videostreams.

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.
  # ...
    

Konfigurationsoptionen

Diese Aufgabe bietet die folgenden Konfigurationsoptionen für Python-Anwendungen:

Daten vorbereiten

Bereiten Sie die Eingabe als Bilddatei oder NumPy-Array vor und konvertieren Sie sie in ein mediapipe.Image-Objekt. Wenn es sich bei der Eingabe um eine Videodatei oder einen Livestream einer Webcam handelt, können Sie eine externe Bibliothek wie OpenCV verwenden, um Ihre Eingabeframes als NumPy-Arrays zu laden.

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)
    

Task ausführen

Die Bewegungserkennung verwendet die Funktionen „Erkennung“, „Erkennung_für_Video“ und „Erkennung“, um Inferenzen auszulösen. Für die Gestenerkennung umfasst dies die Vorverarbeitung von Eingabedaten, die Erkennung von Händen im Bild, das Erkennen von Handmarken sowie das Erkennen von Handgesten an den Orientierungspunkten.

Der folgende Code zeigt, wie die Verarbeitung mit dem Aufgabenmodell ausgeführt wird.

# 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)
    

Wichtige Hinweise:

• Im Video- oder Livestreammodus müssen Sie außerdem in der Aufgabe zur Gestenerkennung den Zeitstempel des Eingabeframes angeben.
• Bei Ausführung im Bild- oder Videomodell blockiert die Aufgabe zur Bewegungserkennung den aktuellen Thread, bis die Verarbeitung des Eingabebilds oder ‐frames abgeschlossen ist.
• Im Livestreammodus blockiert die Aufgabe zur Gestenerkennung den aktuellen Thread nicht, sondern wird sofort zurückgegeben. Sie ruft ihren Ergebnis-Listener mit dem Erkennungsergebnis immer dann auf, wenn die Verarbeitung eines Eingabe-Frames abgeschlossen ist. Wird die Erkennungsfunktion aufgerufen, während die Aufgabe zur Bewegungserkennung gerade mit der Verarbeitung eines weiteren Frames beschäftigt ist, wird der neue Eingabe-Frame von der Aufgabe ignoriert.

Ein vollständiges Beispiel für das Ausführen der Bewegungserkennung für ein Bild finden Sie im Codebeispiel.

Ergebnisse verarbeiten und anzeigen

Die Bewegungserkennung generiert für jeden Erkennungsdurchlauf ein Ergebnisobjekt für die Gestenerkennung. Das Ergebnisobjekt enthält Handmarkierungen in Bildkoordinaten, Handmarkierungen in Weltkoordinaten, Händigkeit(links/rechts) und Handgestenkategorien der erkannten Hände.

Im Folgenden sehen Sie ein Beispiel für die Ausgabedaten dieser Aufgabe:

Das Ergebnis-GestureRecognizerResult enthält vier Komponenten, wobei jede Komponente ein Array ist, in dem jedes Element das erkannte Ergebnis einer einzelnen erkannten Hand enthält.

• Händigkeit

  Die Händigkeit gibt an, ob die erkannten Hände Links- oder Rechtshänder sind.

• Gesten

  Die erkannten Gestenkategorien der erkannten Hände.

• Landmarken

  Es gibt 21 Landschaftsmarkierungen, die jeweils aus x-, y- und z-Koordinaten bestehen. Die Koordinaten x und y werden entsprechend der Bildbreite bzw. -höhe auf [0,0, 1,0] normalisiert. Die z-Koordinate stellt die Tiefe der Sehenswürdigkeit dar, wobei die Tiefe am Handgelenk als Ausgangspunkt dient. Je kleiner der Wert, desto näher liegt das Denkmal an der Kamera. Die Größe von z wird ungefähr gleich groß wie bei x verwendet.

• Sehenswürdigkeiten der Welt

  Die 21 Sehenswürdigkeiten sind ebenfalls in Weltkoordinaten dargestellt. Jede Sehenswürdigkeit besteht aus x, y und z. Diese stellen reale 3D-Koordinaten in Metern mit dem Ursprung im geometrischen Mittelpunkt des Hand dar.

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)

Die folgenden Bilder zeigen eine Visualisierung der Aufgabenausgabe:

Der Beispielcode für die Bewegungserkennung zeigt, wie die von der Aufgabe zurückgegebenen Erkennungsergebnisse angezeigt werden. Weitere Informationen finden Sie im Codebeispiel.