Leitfaden zur Erkennung von Positionsmarkierungen für iOS

Mit der Aufgabe „Markierungen für Körperhaltungen“ können Sie Markierungen für menschliche Körper in einem Bild oder Video erkennen. Mit dieser Aufgabe können Sie wichtige Körperstellen identifizieren, die Körperhaltung analysieren und Bewegungen kategorisieren. Bei dieser Aufgabe werden Modelle für maschinelles Lernen (ML) verwendet, die mit einzelnen Bildern oder Videos arbeiten. Die Aufgabe gibt Markierungen für die Körperhaltung in Bildkoordinaten und in dreidimensionalen Weltkoordinaten aus.

In dieser Anleitung wird beschrieben, wie Sie den Pose Landmarker mit iOS-Apps verwenden. Der in dieser Anleitung beschriebene Code ist auf GitHub verfügbar.

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

Codebeispiel

Der Beispielcode für MediaPipe Tasks ist eine grundlegende Implementierung einer Pose Landmarker App für iOS. In diesem Beispiel wird die Kamera eines physischen iOS-Geräts verwendet, um Posen in einem kontinuierlichen Videostream zu erkennen. Die App kann auch Posen in Bildern und Videos aus der Gerätegalerie erkennen.

Sie können die App als Ausgangspunkt für Ihre eigene iOS-App verwenden oder sich an ihr orientieren, wenn Sie eine vorhandene App ändern. Der Beispielcode für die Pose Landmarker-Funktion wird auf GitHub gehostet.

Code herunterladen

In der folgenden Anleitung wird beschrieben, wie Sie mit dem Befehlszeilentool git 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 Ihre Git-Instanz so konfigurieren, dass eine spärliche Überprüfung verwendet wird, sodass nur die Dateien für die Beispiel-App „Pose Landmarker“ vorhanden sind:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/pose_landmarker/ios/
   

Nachdem Sie eine lokale Version des Beispielcodes erstellt haben, können Sie die MediaPipe-Aufgabenbibliothek installieren, das Projekt mit Xcode öffnen und die App ausführen. Eine Anleitung finden Sie im Einrichtungsleitfaden für iOS.

Schlüsselkomponenten

Die folgenden Dateien enthalten den wichtigen Code für die Beispielanwendung Pose Landmarker:

• PoseLandmarkerService.swift: Initialisiert den Landmarker, übernimmt die Modellauswahl und führt Inferenzen auf die Eingabedaten aus.
• CameraViewController: Implementiert die Benutzeroberfläche für den Eingabemodus des Live-Kamerafeeds und visualisiert die Markierungen.
• MediaLibraryViewController.swift: Implementiert die Benutzeroberfläche für den Eingabemodus für Standbilder und Videodateien und visualisiert die Markierungen.

Einrichtung

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

Abhängigkeiten

Pose Landmarker verwendet die Bibliothek MediaPipeTasksVision, die mit CocoaPods installiert werden muss. Die Bibliothek ist sowohl mit Swift- als auch mit Objective-C-Apps kompatibel und erfordert keine zusätzliche sprachspezifische Einrichtung.

Eine Anleitung zum Installieren von CocoaPods unter macOS findest du in der Installationsanleitung für CocoaPods. Eine Anleitung zum Erstellen einer Podfile mit den erforderlichen Pods für Ihre App finden Sie unter CocoaPods verwenden.

Fügen Sie den Pod „MediaPipeTasksVision“ in der Datei Podfile mit dem folgenden Code hinzu:

target 'MyPoseLandmarkerApp' do
  use_frameworks!
  pod 'MediaPipeTasksVision'
end

Wenn Ihre App Unit-Testziele enthält, finden Sie im Einrichtungsleitfaden für iOS weitere Informationen zur Einrichtung Ihrer Podfile.

Modell

Für die MediaPipe-Aufgabe „Pose Landmarker“ ist ein trainiertes Paket erforderlich, das mit dieser Aufgabe kompatibel ist. Weitere Informationen zu verfügbaren trainierten Modellen für Poose Landmarker finden Sie in der Aufgabenübersicht im Abschnitt „Modelle“.

Verwenden Sie das download_models.sh-Script, um die Modelle herunterzuladen und sie mit Xcode Ihrem Projektverzeichnis hinzuzufügen. Eine Anleitung zum Hinzufügen von Dateien zu Ihrem Xcode-Projekt finden Sie unter Dateien und Ordner im Xcode-Projekt verwalten.

Verwenden Sie das Attribut BaseOptions.modelAssetPath, um den Pfad zum Modell in Ihrem App Bundle anzugeben. Ein Codebeispiel finden Sie im nächsten Abschnitt.

Aufgabe erstellen

Sie können die Aufgabe „Pose Landmarker“ erstellen, indem Sie einen ihrer Initialisierer aufrufen. Der PoseLandmarker(options:)-Initialisierer akzeptiert Werte für die Konfigurationsoptionen.

Wenn Sie keinen mit benutzerdefinierten Konfigurationsoptionen initialisierten Positions-Landmarker benötigen, können Sie mit dem PoseLandmarker(modelPath:)-Initialisierer einen Positions-Landmarker mit den Standardoptionen erstellen. Weitere Informationen zu Konfigurationsoptionen finden Sie unter Konfigurationsübersicht.

Die Aufgabe „Pose Landmarker“ unterstützt drei Eingabedatentypen: Standbilder, Videodateien und Livestreams. Standardmäßig initialisiert PoseLandmarker(modelPath:) eine Aufgabe für Standbilder. Wenn Sie möchten, dass Ihre Aufgabe für die Verarbeitung von Videodateien oder Live-Videostreams initialisiert wird, geben Sie mit PoseLandmarker(options:) den Ausführungsmodus für Video oder Livestream an. Für den Livestream-Modus ist außerdem die zusätzliche Konfigurationsoption poseLandmarkerLiveStreamDelegate erforderlich, mit der der Pose-Landmark-Detektor die Ergebnisse der Pose-Landmark-Erkennung asynchron an den Delegaten senden kann.

Wählen Sie den Tab für den aktuellen Ausführungsmodus aus, um zu erfahren, wie Sie die Aufgabe erstellen und die Inferenz ausführen.

Swift

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "pose_landmarker",
                                      ofType: "task")

let options = PoseLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.minPoseDetectionConfidence = minPoseDetectionConfidence
options.minPosePresenceConfidence = minPosePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numPoses = numPoses

let poseLandmarker = try PoseLandmarker(options: options)
    

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "pose_landmarker",
                                      ofType: "task")

let options = PoseLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.minPoseDetectionConfidence = minPoseDetectionConfidence
options.minPosePresenceConfidence = minPosePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numPoses = numPoses

let poseLandmarker = try PoseLandmarker(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `PoseLandmarkerLiveStreamDelegate` protocol and
// implements the method that the pose landmarker calls once it finishes
// performing pose landmark detection in each input frame.
class PoseLandmarkerResultProcessor: NSObject, PoseLandmarkerLiveStreamDelegate {

  func poseLandmarker(
    _ poseLandmarker: PoseLandmarker,
    didFinishDetection result: PoseLandmarkerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the pose landmarker result or errors here.

  }
}

let modelPath = Bundle.main.path(forResource: "pose_landmarker",
                                      ofType: "task")

let options = PoseLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.minPoseDetectionConfidence = minPoseDetectionConfidence
options.minPosePresenceConfidence = minPosePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numPoses = numPoses

// Assign an object of the class to the `poseLandmarkerLiveStreamDelegate`
// property.
let processor = PoseLandmarkerResultProcessor()
options.poseLandmarkerLiveStreamDelegate = processor

let poseLandmarker = try PoseLandmarker(options: options)
    

Objective-C

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"pose_landmarker"
                                                      ofType:@"task"];

MPPPoseLandmarkerOptions *options = [[MPPPoseLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.minPoseDetectionConfidence = minPoseDetectionConfidence;
options.minPosePresenceConfidence = minPosePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numPoses = numPoses;

MPPPoseLandmarker *poseLandmarker =
  [[MPPPoseLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"pose_landmarker"
                                                      ofType:@"task"];

MPPPoseLandmarkerOptions *options = [[MPPPoseLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.minPoseDetectionConfidence = minPoseDetectionConfidence;
options.minPosePresenceConfidence = minPosePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numPoses = numPoses;

MPPPoseLandmarker *poseLandmarker =
  [[MPPPoseLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPPoseLandmarkerLiveStreamDelegate` protocol
// and implements the method that the pose landmarker calls once it finishes
// performing pose landmarks= detection in each input frame.

@interface APPPoseLandmarkerResultProcessor : NSObject 

@end

@implementation APPPoseLandmarkerResultProcessor

-   (void)poseLandmarker:(MPPPoseLandmarker *)poseLandmarker
    didFinishDetectionWithResult:(MPPPoseLandmarkerResult *)poseLandmarkerResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the pose landmarker result or errors here.

}

@end

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"pose_landmarker"
                                                      ofType:@"task"];

MPPPoseLandmarkerOptions *options = [[MPPPoseLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.minPoseDetectionConfidence = minPoseDetectionConfidence;
options.minPosePresenceConfidence = minPosePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numPoses = numPoses;

// Assign an object of the class to the `poseLandmarkerLiveStreamDelegate`
// property.
APPPoseLandmarkerResultProcessor *processor =
  [APPPoseLandmarkerResultProcessor new];
options.poseLandmarkerLiveStreamDelegate = processor;

MPPPoseLandmarker *poseLandmarker =
  [[MPPPoseLandmarker alloc] initWithOptions:options error:nil];
    

Hinweis:Wenn Sie den Video- oder Livestream-Modus verwenden, verwendet der Pose Landmarker das Tracking, um zu vermeiden, dass das Modell zur Handerkennung bei jedem Frame ausgelöst wird. Dadurch wird die Latenz verringert.

Konfigurationsoptionen

Diese Aufgabe bietet die folgenden Konfigurationsoptionen für iOS-Apps:

Livestreamkonfiguration

Wenn der Laufmodus auf „Livestream“ gesetzt ist, benötigt der Pose Landmarker die zusätzliche Konfigurationsoption poseLandmarkerLiveStreamDelegate. Damit kann der Pose Landmarker die Ergebnisse der Pose-Markierungserkennung asynchron liefern. Der Delegate muss die Methode poseLandmarker(_:didFinishDetection:timestampInMilliseconds:error:) implementieren, die der Pose Landmarker aufruft, nachdem die Ergebnisse der Positionsmarkierungserkennung für jeden Frame verarbeitet wurden.

Daten vorbereiten

Sie müssen das Eingabebild oder den Frame in ein MPImage-Objekt konvertieren, bevor Sie es an den Pose Landmarker übergeben. MPImage unterstützt verschiedene Arten von iOS-Bildformaten und kann sie in jedem Betriebsmodus für die Inferenz verwenden. Weitere Informationen zu MPImage finden Sie in der MPImage API.

Wählen Sie ein iOS-Bildformat entsprechend Ihrem Anwendungsfall und dem erforderlichen Ausführungsmodus Ihrer Anwendung aus.MPImage unterstützt die iOS-Bildformate UIImage, CVPixelBuffer und CMSampleBuffer.

UIImage

Das UIImage-Format eignet sich gut für die folgenden Laufmodi:

• Bilder: Bilder aus einem App-Bundle, einer Nutzergalerie oder einem Dateisystem, das als UIImage-Bilder formatiert ist, können in ein MPImage-Objekt umgewandelt werden.

• Videos: Mit dem AVAssetImageGenerator können Sie Videoframes im CGImage-Format extrahieren und dann in UIImage-Bilder konvertieren.

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(uiImage: image)
    

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
    

Im Beispiel wird ein MPImage mit der Standardausrichtung UIImage.Orientation.Up initialisiert. Sie können ein MPImage mit einem beliebigen der unterstützten Werte von UIImage.Orientation initialisieren. Pose Landmarker unterstützt keine gespiegelten Ausrichtungen wie .upMirrored, .downMirrored, .leftMirrored und .rightMirrored.

Weitere Informationen zu UIImage finden Sie in der Entwicklerdokumentation UIImage für Apple.

CVPixelBuffer

Das CVPixelBuffer-Format eignet sich gut für Anwendungen, die Frames generieren und das iOS-CoreImage-Framework für die Verarbeitung verwenden.

Das CVPixelBuffer-Format eignet sich gut für die folgenden Laufmodi:

• Bilder: Apps, die nach einer Verarbeitung mit dem CoreImage-Framework von iOS CVPixelBuffer-Bilder generieren, können im Modus „Bild ausführen“ an den Pose-Landmarker gesendet werden.

• Videos: Videoframes können zur Verarbeitung in das CVPixelBuffer-Format konvertiert und dann im Videomodus an den Pose Landmarker gesendet werden.

• Livestream: Frames, die in Apps mit einer iOS-Kamera generiert werden, können zur Verarbeitung in das CVPixelBuffer-Format konvertiert werden, bevor sie im Livestream-Modus an den Pose Landmarker gesendet werden.

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(pixelBuffer: pixelBuffer)
    

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
    

Weitere Informationen zu CVPixelBuffer finden Sie in der Apple-Entwicklerdokumentation zu CVPixelBuffer.

CMSampleBuffer

Im CMSampleBuffer-Format werden Mediensamples eines einheitlichen Medientyps gespeichert. Es eignet sich gut für den Livestream-Ausführungsmodus. Live-Frames von iOS-Kameras werden von iOS AVCaptureVideoDataOutput asynchron im CMSampleBuffer-Format bereitgestellt.

// Obtain a CMSampleBuffer.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(sampleBuffer: sampleBuffer)
    

// Obtain a `CMSampleBuffer`.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithSampleBuffer:sampleBuffer error:nil];
    

Weitere Informationen zu CMSampleBuffer findest du in der CMSampleBuffer-Entwicklerdokumentation von Apple.

Aufgabe ausführen

Verwenden Sie zum Ausführen des Positions-Landmarks die für den zugewiesenen Ausführungsmodus spezifische detect()-Methode:

• Standbild: detect(image:)
• Video: detect(videoFrame:timestampInMilliseconds:)
• Livestream: detectAsync(image:timestampInMilliseconds:)

Die folgenden Codebeispiele zeigen einfache Beispiele für die Ausführung von Pose Landmarker in diesen verschiedenen Laufmodi:

Swift

let result = try poseLandmarker.detect(image: image)
    

let result = try poseLandmarker.detect(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try poseLandmarker.detectAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

MPPPoseLandmarkerResult *result =
  [poseLandmarker detectImage:image error:nil];
    

MPPPoseLandmarkerResult *result =
  [poseLandmarker detectVideoFrame:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

BOOL success =
  [poseLandmarker detectAsyncImage:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

Im Codebeispiel für die Pose-Markierung werden die Implementierungen der einzelnen Modi detect(image:), detect(videoFrame:timestampInMilliseconds:) und detectAsync(image:timestampInMilliseconds:) genauer erläutert. Mit dem Beispielcode kann der Nutzer zwischen Verarbeitungsmodi wechseln, die für Ihren Anwendungsfall möglicherweise nicht erforderlich sind.

Wichtige Hinweise:

• Wenn Sie die Funktion im Video- oder Livestream-Modus ausführen, müssen Sie der Aufgabe „Pose Landmarker“ auch den Zeitstempel des Eingabeframes angeben.

• Wenn die Funktion im Bild- oder Videomodus ausgeführt wird, blockiert die Aufgabe „Pose Landmarker“ den aktuellen Thread, bis die Verarbeitung des Eingabebilds oder ‑frames abgeschlossen ist. Um das Blockieren des aktuellen Threads zu vermeiden, führen Sie die Verarbeitung in einem Hintergrund-Thread mithilfe der iOS-Frameworks Dispatch oder NSOperation aus.

• Wenn die Ausführung im Livestream-Modus erfolgt, gibt die Aufgabe „Pose Landmarker“ sofort ein Ergebnis zurück und blockiert den aktuellen Thread nicht. Nach der Verarbeitung jedes Eingabeframes wird die Methode poseLandmarker(_:didFinishDetection:timestampInMilliseconds:error:) mit dem Ergebnis der Positionsmarkierung aufgerufen. Der Pose-Landmarker ruft diese Methode asynchron in einer speziellen seriellen Dispatch-Warteschlange auf. Übermitteln Sie die Ergebnisse nach Verarbeitung der Ergebnisse an die Hauptwarteschlange, um sie auf der Benutzeroberfläche anzuzeigen. Wenn die detectAsync-Funktion aufgerufen wird, während die Pose-Landmark-Aufgabe gerade einen anderen Frame verarbeitet, ignoriert der Pose-Landmark-Dienst den neuen Eingabeframe.

Ergebnisse verarbeiten und anzeigen

Nach der Ausführung der Identifikation gibt die Aufgabe „Pose Landmarker“ eine PoseLandmarkerResult zurück, die die Koordinaten für jede Positionsmarkierung enthält.

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

PoseLandmarkerResult:
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : 0.129959
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
      visibility   : 0.999909
      presence     : 0.999958
    ... (33 landmarks per pose)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
      visibility   : 0.999976
      presence     : 0.999998
    ... (33 world landmarks per pose)
  SegmentationMasks:
    ... (pictured below)

Die Ausgabe enthält sowohl normalisierte Koordinaten (Landmarks) als auch Weltkoordinaten (WorldLandmarks) für jedes Wahrzeichen.

Die Ausgabe enthält die folgenden normalisierten Koordinaten (Landmarks):

• x und y: Koordinaten des Wahrzeichens, die anhand der Bildbreite (x) und -höhe (y) auf 0,0 bis 1,0 normalisiert sind.

• z: Die Landmarkentiefe, wobei die Tiefe an der Mitte der Hüften als Ursprung dient. Je kleiner der Wert, desto näher befindet sich der Orientierungspunkt an der Kamera. Die Größe z hat ungefähr die gleiche Skala wie x.

• visibility: Die Wahrscheinlichkeit, dass das Wahrzeichen im Bild zu sehen ist.

Die Ausgabe enthält die folgenden Weltkoordinaten (WorldLandmarks):

• x, y und z: Dreidimensionale Koordinaten in Metern, die sich auf den Mittelpunkt der Hüften beziehen.

• visibility: Die Wahrscheinlichkeit, dass das Wahrzeichen im Bild zu sehen ist.

Die folgende Abbildung zeigt eine Visualisierung der Aufgabenausgabe:

Die optionale Segmentierungsmaske gibt an, wie wahrscheinlich es ist, dass jedes Pixel zu einer erkannten Person gehört. Das folgende Bild ist eine Segmentierungsmaske der Aufgabenausgabe:

Der Beispielcode für Pose Landmarker zeigt, wie die Ergebnisse des Pose Landmarker angezeigt werden.