Mit der Aufgabe „MediaPipe-Gestenerkennung“ können Sie Handgesten 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 in Android-Apps verwenden. Das in dieser Anleitung beschriebene Codebeispiel ist auf GitHub verfügbar.
In der Web-Demo können Sie sich diese Aufgabe in Aktion ansehen. Weitere Informationen zu den Funktionen, Modellen und Konfigurationsoptionen dieser Aufgabe finden Sie in der Übersicht.
Codebeispiel
Der Beispielcode für MediaPipe Tasks ist eine einfache Implementierung einer App zur Gestenerkennung für Android. In diesem Beispiel wird die Kamera eines physischen Android-Geräts verwendet, um kontinuierlich Handgesten zu erkennen. Es können auch Bilder und Videos aus der Gerätegalerie verwendet werden, um Gesten statisch zu erkennen.
Sie können die App als Ausgangspunkt für Ihre eigene Android-App verwenden oder darauf zurückgreifen, wenn Sie eine vorhandene App ändern. Der Beispielcode für die Gestenerkennung wird auf GitHub gehostet.
Code herunterladen
In der folgenden Anleitung erfahren Sie, wie Sie mit dem git-Befehlszeilentool eine lokale Kopie des Beispielcodes erstellen.
So laden Sie den Beispielcode herunter:
- Klonen Sie das Git-Repository mit dem folgenden Befehl:
git clone https://github.com/google-ai-edge/mediapipe-samples
- Optional können Sie die Git-Instanz für die Verwendung einer dünnbesetzten Kasse konfigurieren, sodass Sie nur die Dateien für die Beispielanwendung für die Gestenerkennung haben:
cd mediapipe git sparse-checkout init --cone git sparse-checkout set examples/gesture_recognizer/android
Nachdem Sie eine lokale Version des Beispielcodes erstellt haben, können Sie das Projekt in Android Studio importieren und die App ausführen. Eine Anleitung dazu finden Sie im Einrichtungsleitfaden für Android.
Schlüsselkomponenten
Die folgenden Dateien enthalten den erforderlichen Code für diese Beispiel-App für die Handgestenerkennung:
- GestureRecognizerHelper.kt: Initialisiert die Gestenerkennung, verarbeitet das Modell und delegiert die Auswahl.
- MainActivity.kt: Implementiert die Anwendung und ruft
GestureRecognizerHelper
undGestureRecognizerResultsAdapter
auf. - GestureRecognizerResultsAdapter.kt: Bearbeitet und formatiert die Ergebnisse.
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 Android.
Abhängigkeiten
Für die Aufgabe zur Bewegungserkennung wird die Bibliothek com.google.mediapipe:tasks-vision
verwendet. Füge diese Abhängigkeit in die Datei build.gradle
deiner Android-App ein:
dependencies {
implementation 'com.google.mediapipe:tasks-vision:latest.release'
}
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 in Ihrem Projektverzeichnis:
<dev-project-root>/src/main/assets
Geben Sie den Pfad des Modells innerhalb des Parameters ModelAssetPath
an. Im Beispielcode wird das Modell in der Datei GestureRecognizerHelper.kt
definiert:
baseOptionBuilder.setModelAssetPath(MP_RECOGNIZER_TASK)
Aufgabe erstellen
Die Aufgabe „MediaPipe-Gestenerkennung“ verwendet die Funktion createFromOptions()
, um sie einzurichten. Die Funktion createFromOptions()
akzeptiert Werte für die Konfigurationsoptionen. Weitere Informationen zu Konfigurationsoptionen finden Sie unter Konfigurationsoptionen.
Die Bewegungserkennung unterstützt drei Eingabedatentypen: Standbilder, Videodateien und Live-Videostreams. Beim Erstellen der Aufgabe müssen Sie den Ausführungsmodus angeben, der Ihrem Eingabedatentyp entspricht. Wählen Sie den Tab für Ihren Eingabedatentyp aus, um zu sehen, wie Sie die Aufgabe erstellen und die Inferenz ausführen.
Bild
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK) val baseOptions = baseOptionBuilder.build() val optionsBuilder = GestureRecognizer.GestureRecognizerOptions.builder() .setBaseOptions(baseOptions) .setMinHandDetectionConfidence(minHandDetectionConfidence) .setMinTrackingConfidence(minHandTrackingConfidence) .setMinHandPresenceConfidence(minHandPresenceConfidence) .setRunningMode(RunningMode.IMAGE) val options = optionsBuilder.build() gestureRecognizer = GestureRecognizer.createFromOptions(context, options)
Video
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK) val baseOptions = baseOptionBuilder.build() val optionsBuilder = GestureRecognizer.GestureRecognizerOptions.builder() .setBaseOptions(baseOptions) .setMinHandDetectionConfidence(minHandDetectionConfidence) .setMinTrackingConfidence(minHandTrackingConfidence) .setMinHandPresenceConfidence(minHandPresenceConfidence) .setRunningMode(RunningMode.VIDEO) val options = optionsBuilder.build() gestureRecognizer = GestureRecognizer.createFromOptions(context, options)
Livestream
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK) val baseOptions = baseOptionBuilder.build() val optionsBuilder = GestureRecognizer.GestureRecognizerOptions.builder() .setBaseOptions(baseOptions) .setMinHandDetectionConfidence(minHandDetectionConfidence) .setMinTrackingConfidence(minHandTrackingConfidence) .setMinHandPresenceConfidence(minHandPresenceConfidence) .setResultListener(this::returnLivestreamResult) .setErrorListener(this::returnLivestreamError) .setRunningMode(RunningMode.LIVE_STREAM) val options = optionsBuilder.build() gestureRecognizer = GestureRecognizer.createFromOptions(context, options)
Durch die Implementierung des Beispielcodes für die Bewegungserkennung können Nutzer zwischen den Verarbeitungsmodi wechseln. Dadurch wird der Code zur Aufgabenerstellung komplizierter und ist für Ihren Anwendungsfall möglicherweise nicht geeignet. Sie finden diesen Code in der Funktion setupGestureRecognizer()
in der Datei GestureRecognizerHelper.kt
.
Konfigurationsoptionen
Diese Aufgabe umfasst die folgenden Konfigurationsoptionen für Android-Apps:
Option | Beschreibung | Wertebereich | Standardwert | |
---|---|---|---|---|
runningMode |
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 |
|
numHands |
Die maximale Anzahl von Händen kann von GestureRecognizer erkannt werden.
|
Any integer > 0 |
1 |
|
minHandDetectionConfidence |
Der Mindestkonfidenzwert für die Handerkennung, um im Handflächenerkennungsmodell als erfolgreich zu gelten. | 0.0 - 1.0 |
0.5 |
|
minHandPresenceConfidence |
Der minimale Konfidenzwert für die Handpräsenz im Modell zur Erkennung von Handmarkierungen. Wenn im Video- und Livestream-Modus der Bewegungserkennung der Konfidenzwert für die Anwesenheitserkennung vom Modell für Handmarkierungen unter diesem Grenzwert liegt, wird das Handflächenerkennungsmodell ausgelöst. Andernfalls wird ein leichter Algorithmus zur Handverfolgung verwendet, um die Position der Hand(en) für die nachfolgende Erkennung von Sehenswürdigkeiten zu bestimmen. | 0.0 - 1.0 |
0.5 |
|
minTrackingConfidence |
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 Streammodus der Bewegungserkennung die Bewegungserkennung fehlschlägt, löst die Bewegungserkennung die Handerkennung aus, wenn das Tracking fehlschlägt. Andernfalls wird die Handerkennung übersprungen. | 0.0 - 1.0 |
0.5 |
|
cannedGesturesClassifierOptions |
Optionen zum Konfigurieren des Verhaltens des Klassifikators für gespeicherte Gesten. Vordefinierte Touch-Gesten sind ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"] |
|
|
|
customGesturesClassifierOptions |
Optionen zum Konfigurieren des Verhaltens des benutzerdefinierten Gestenklassifikators. |
|
|
|
resultListener |
Legt den Ergebnis-Listener so fest, dass er die Klassifizierungsergebnisse asynchron empfängt, wenn sich die Gestenerkennung im Livestream-Modus befindet.
Kann nur verwendet werden, wenn der Laufmodus auf LIVE_STREAM festgelegt ist |
ResultListener |
– | – |
errorListener |
Legt einen optionalen Fehler-Listener fest. | ErrorListener |
– | – |
Daten vorbereiten
Die Bewegungserkennung kann für Bilder, Videodateien und Livestreams verwendet werden. Die Aufgabe übernimmt die Vorverarbeitung der Dateneingabe, einschließlich Größenanpassung, Rotation und Wertnormalisierung.
Der folgende Code zeigt, wie Daten zur Verarbeitung übergeben werden. Sie enthalten Details zur Verarbeitung von Daten aus Bildern, Videodateien und Live-Videostreams.
Bild
import com.google.mediapipe.framework.image.BitmapImageBuilder import com.google.mediapipe.framework.image.MPImage // Convert the input Bitmap object to an MPImage object to run inference val mpImage = BitmapImageBuilder(image).build()
Video
import com.google.mediapipe.framework.image.BitmapImageBuilder import com.google.mediapipe.framework.image.MPImage val argb8888Frame = if (frame.config == Bitmap.Config.ARGB_8888) frame else frame.copy(Bitmap.Config.ARGB_8888, false) // Convert the input Bitmap object to an MPImage object to run inference val mpImage = BitmapImageBuilder(argb8888Frame).build()
Livestream
import com.google.mediapipe.framework.image.BitmapImageBuilder import com.google.mediapipe.framework.image.MPImage // Convert the input Bitmap object to an MPImage object to run inference val mpImage = BitmapImageBuilder(rotatedBitmap).build()
Im Beispielcode für die Gestenerkennung wird die Datenvorbereitung in der Datei GestureRecognizerHelper.kt
ausgeführt.
Task ausführen
Die Gestenerkennung verwendet die Funktionen recognize
, recognizeForVideo
und recognizeAsync
, 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. Diese Beispiele enthalten Details zum Umgang mit Daten aus Bildern, Videodateien und Live-Videostreams.
Bild
val result = gestureRecognizer?.recognize(mpImage)
Video
val timestampMs = i * inferenceIntervalMs gestureRecognizer?.recognizeForVideo(mpImage, timestampMs) ?.let { recognizerResult -> resultList.add(recognizerResult) }
Livestream
val mpImage = BitmapImageBuilder(rotatedBitmap).build() val frameTime = SystemClock.uptimeMillis() gestureRecognizer?.recognizeAsync(mpImage, frameTime)
Wichtige Hinweise:
- Im Video- oder Livestreammodus müssen Sie auch den Zeitstempel des Eingabeframes für die Aufgabe zur Gestenerkennung bereitstellen.
- Im Bild- oder Videomodus blockiert die Aufgabe zur Bewegungserkennung den aktuellen Thread, bis die Verarbeitung des Eingabebilds oder ‐frames abgeschlossen ist. Führen Sie die Verarbeitung in einem Hintergrundthread aus, damit die Benutzeroberfläche nicht blockiert wird.
- 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 mit der Verarbeitung eines weiteren Frames beschäftigt ist, wird der neue Eingabe-Frame von der Aufgabe ignoriert.
Im Beispielcode für die Gestenerkennung werden die Funktionen recognize
, recognizeForVideo
und recognizeAsync
in der Datei GestureRecognizerHelper.kt
definiert.
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
- 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.
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:
Im Beispielcode für die Gestenerkennung werden die Ergebnisse von der Klasse GestureRecognizerResultsAdapter
in der Datei GestureRecognizerResultsAdapter.kt
verarbeitet.