Anleitung zur Bewegungserkennung für Android

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:

1. Klonen Sie das Git-Repository mit dem folgenden Befehl:

   git clone https://github.com/google-ai-edge/mediapipe-samples
   

2. 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 und GestureRecognizerResultsAdapter 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.

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)
    

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)
    

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:

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.

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

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

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.

val result = gestureRecognizer?.recognize(mpImage)
    

val timestampMs = i * inferenceIntervalMs

gestureRecognizer?.recognizeForVideo(mpImage, timestampMs)
    ?.let { recognizerResult ->
        resultList.add(recognizerResult)
    }
    

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- 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:

Im Beispielcode für die Gestenerkennung werden die Ergebnisse von der Klasse GestureRecognizerResultsAdapter in der Datei GestureRecognizerResultsAdapter.kt verarbeitet.