Mit der Aufgabe „MediaPipe Hand Landmarker“ können Sie die Markierungen der Hände in einem Bild erkennen. In dieser Anleitung erfahren Sie, wie Sie den Hand Landmarker mit Python verwenden. Das in dieser Anleitung beschriebene Codebeispiel ist auf GitHub verfügbar.
Weitere Informationen zu den Funktionen, Modellen und Konfigurationsoptionen dieser Aufgabe finden Sie in der Übersicht.
Codebeispiel
Der Beispielcode für Hand Landmarker bietet eine vollständige Implementierung dieser Aufgabe in Python zu Referenzzwecken. Mit diesem Code können Sie diese Aufgabe testen und mit dem Erstellen Ihres eigenen Handortserkennungsdetektors beginnen. Sie können den Beispielcode von Hand Landmarker mithilfe Ihres Webbrowsers aufrufen, ausführen und bearbeiten.
Einrichtung
In diesem Abschnitt werden die wichtigsten Schritte zum Einrichten Ihrer Entwicklungsumgebung und Programmierprojekte speziell für die Verwendung von Hand Landmarker 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
Die MediaPipe Hand Landmark-Aufgabe erfordert das MediaPipe-PyPI-Paket. Sie können diese Abhängigkeiten folgendermaßen installieren und importieren:
$ python -m pip install mediapipe
Importe
Importieren Sie die folgenden Klassen, um auf die Aufgabenfunktionen für Hand-Markierungen zuzugreifen:
import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision
Modell
Die MediaPipe Hand Landmark-Aufgabe erfordert ein trainiertes Modell, das mit dieser Aufgabe kompatibel ist. Weitere Informationen zu verfügbaren trainierten Modellen für Hand Landmarker 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'
Verwenden Sie den model_asset_path
-Parameter des BaseOptions
-Objekts, um den Pfad des zu verwendenden Modells anzugeben. Ein Codebeispiel finden Sie im nächsten Abschnitt.
Aufgabe erstellen
Die MediaPipe Hand Landmark-Aufgabe verwendet die Funktion create_from_options
, um die Aufgabe einzurichten. Die Funktion create_from_options
akzeptiert Werte, die von Konfigurationsoptionen 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 Livestreams.
Bild
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. # ...
Video
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. # ...
Livestream
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. # ...
Ein vollständiges Beispiel für das Erstellen einer Handmarkierung zur Verwendung mit einem Bild finden Sie im Codebeispiel.
Konfigurationsoptionen
Diese Aufgabe bietet die folgenden Konfigurationsoptionen für Python-Anwendungen:
Option | Beschreibung | Wertebereich | Standardwert |
---|---|---|---|
running_mode |
Legt den Ausführungsmodus für die Task fest. Es gibt drei Modi: IMAGE: Der Modus für Einzelbildeingaben. VIDEO: Der Modus für decodierte Frames eines Videos. LIVE_STREAM: Der Modus für einen Livestream der Eingabedaten, z. B. von einer Kamera. In diesem Modus muss resultListener aufgerufen werden, um einen Listener einzurichten, der die Ergebnisse asynchron empfängt. |
{IMAGE, VIDEO, LIVE_STREAM } |
IMAGE |
num_hands |
Die maximale Anzahl der Hände, die vom Hand-Ortserkennungserkennung erkannt wurden. | Any integer > 0 |
1 |
min_hand_detection_confidence |
Der Mindestkonfidenzwert für die Handerkennung, um im Handflächenerkennungsmodell als erfolgreich zu gelten. | 0.0 - 1.0 |
0.5 |
min_hand_presence_confidence |
Der minimale Konfidenzwert für den Wert der Handpräsenz im Modell zur Erkennung von Handmarkierungen. Wenn im Video- und Livestreammodus der Konfidenzwert zur Anwesenheit des Hand-Markierungsmodells unter diesem Grenzwert liegt, löst Hand Landmarker das Handflächenerkennungsmodell aus. Andernfalls ermittelt ein einfacher Algorithmus zur Handverfolgung die Position der Hand(en) für nachfolgende Erkennungen von Sehenswürdigkeiten. | 0.0 - 1.0 |
0.5 |
min_tracking_confidence |
Der Mindestkonfidenzwert, der für eine erfolgreiche Verfolgung der Handzeichen erforderlich ist. Dies ist der IoU-Grenzwert des Begrenzungsrahmens zwischen Händen im aktuellen und im letzten Frame. Wenn im Video- und Stream-Modus der Hand-Markdown-Funktion das Tracking fehlschlägt, löst diese Funktion die Handerkennung aus. Andernfalls wird die Handerkennung übersprungen. | 0.0 - 1.0 |
0.5 |
result_callback |
Legt den Ergebnis-Listener so fest, dass die Erkennungsergebnisse asynchron empfangen werden, wenn sich der Hand-Marker im Livestream-Modus befindet.
Gilt nur, wenn der Laufmodus auf LIVE_STREAM eingestellt ist |
– | – |
Daten vorbereiten
Bereiten Sie Ihre Eingabe als Bilddatei oder NumPy-Array vor und konvertieren Sie sie in ein mediapipe.Image
-Objekt. Wenn Ihre Eingabe eine Videodatei oder ein Livestream über eine Webcam ist, können Sie eine externe Bibliothek wie OpenCV verwenden, um Ihre Eingabeframes als NumPy-Arrays zu laden.
Bild
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)
Video
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)
Livestream
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 Hand-Markierungsfunktion verwendet die Funktionen detect, detect_for_video und detect_async, um Inferenzen auszulösen. Bei der Erkennung von Handmarkierungen umfasst dies die Vorverarbeitung der Eingabedaten, die Erkennung von Händen im Bild und die Erkennung von Handmarkierungen.
Der folgende Code zeigt, wie die Verarbeitung mit dem Aufgabenmodell ausgeführt wird.
Bild
# 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)
Video
# 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)
Livestream
# 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)
Wichtige Hinweise:
- Im Video- oder Livestreammodus müssen Sie außerdem in der Aufgabe „Hand Landmarker“ den Zeitstempel des Eingabeframes angeben.
- Bei Ausführung im Bild- oder Videomodell blockiert die Aufgabe „Hand Landmarker“ den aktuellen Thread, bis die Verarbeitung des Eingabebilds oder ‐frames abgeschlossen ist.
- Im Livestreammodus blockiert die Hand-Markierungsaufgabe den aktuellen Thread nicht, sondern wird sofort zurückgegeben. Jedes Mal, wenn ein Eingabeframe verarbeitet wurde, ruft er seinen Ergebnis-Listener mit dem Erkennungsergebnis auf. Wenn die Erkennungsfunktion aufgerufen wird, während die Hand-Markierungsaufgabe mit der Verarbeitung eines anderen Frames beschäftigt ist, ignoriert die Aufgabe den neuen Eingabe-Frame.
Ein vollständiges Beispiel für die Ausführung einer Handmarkierung auf einem Bild finden Sie im Codebeispiel.
Ergebnisse verarbeiten und anzeigen
Der Hand Landmarker generiert für jeden Erkennungslauf ein Hand-Landmarker-Ergebnisobjekt. Das Ergebnisobjekt enthält Orientierungspunkte in den Bildkoordinaten, Handmarkierungen in Weltkoordinaten und die Händigkeit(links/rechts) der erkannten Hände.
Im Folgenden sehen Sie ein Beispiel für die Ausgabedaten dieser Aufgabe:
Die HandLandmarkerResult
-Ausgabe enthält drei Komponenten. Jede Komponente ist ein Array, wobei jedes Element die folgenden Ergebnisse für eine einzelne erkannte Hand enthält:
Händigkeit
Die Händigkeit gibt an, ob die erkannten Hände Links- oder Rechtshänder sind.
Landmarken
Es gibt 21 Landschaftsmarkierungen, die jeweils aus
x
-,y
- undz
-Koordinaten bestehen. Die Koordinatenx
undy
werden entsprechend der Bildbreite bzw. -höhe auf [0,0, 1,0] normalisiert. Diez
-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 vonz
wird ungefähr gleich groß wie beix
verwendet.Sehenswürdigkeiten der Welt
Die 21 Sehenswürdigkeiten sind ebenfalls in Weltkoordinaten dargestellt. Jede Sehenswürdigkeit besteht aus
x
,y
undz
. Diese stellen reale 3D-Koordinaten in Metern mit dem Ursprung im geometrischen Mittelpunkt des Hand dar.
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)
Die folgende Abbildung zeigt eine Visualisierung der Aufgabenausgabe:
Der Beispielcode für Hand-Markierungen zeigt, wie die von der Aufgabe zurückgegebenen Ergebnisse angezeigt werden. Weitere Informationen finden Sie im Code-Beispiel.