Przewodnik po wykrywaniu punktów orientacyjnych na iOS

Zadanie wykrywania punktów orientacyjnych w pozie pozwala wykrywać punkty orientacyjne ciała ludzkiego na obrazie lub filmie. Za pomocą tego zadania możesz identyfikować kluczowe części ciała, analizować postawę oraz kategoryzować ruchy. To zadanie korzysta z modeli systemów uczących się, które działają z pojedynczymi obrazami lub filmami. Zadanie generuje punkty orientacyjne pozycji ciała we współrzędnych obrazu i trójwymiarowych współrzędnych świata.

Z tych instrukcji dowiesz się, jak używać narzędzia do oznaczania pozycji w aplikacji na iOS. Przykład kodu opisany w tych instrukcjach jest dostępny na GitHub.

Aby zobaczyć, jak to zadanie działa w praktyce, obejrzyj to demo. Więcej informacji o możliwościach, modelach i opcjach konfiguracji związanych z tym zadaniem znajdziesz w sekcji Omówienie.

Przykładowy kod

Przykładowy kod MediaPipe Tasks to podstawowe wdrożenie aplikacji Pose Landmarker na iOS. Przykład wykorzystuje kamerę na fizycznym urządzeniu z iOS, aby wykrywać pozy w ciągłym strumieniu wideo. Aplikacja może też wykrywać pozy w obrazach i filmach z galerii urządzenia.

Możesz użyć tej aplikacji jako punktu wyjścia dla własnej aplikacji na iOS lub odwołać się do niej podczas modyfikowania istniejącej aplikacji. Przykładowy kod Pose Notebooker jest przechowywany na GitHub.

Pobieranie kodu

Poniższe instrukcje pokazują, jak utworzyć lokalną kopię przykładowego kodu za pomocą narzędzia wiersza poleceń git.

Aby pobrać przykładowy kod:

1. Sklonuj repozytorium git za pomocą tego polecenia:

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

2. Opcjonalnie możesz skonfigurować instancję git tak, aby wykorzystywała rozproszony proces płatności, dzięki czemu będziesz mieć tylko pliki przykładowej aplikacji Pose Notebooker:

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

Po utworzeniu lokalnej wersji przykładowego kodu możesz zainstalować bibliotekę zadań MediaPipe, otworzyć projekt za pomocą Xcode i uruchomić aplikację. Instrukcje znajdziesz w Przewodniku konfiguracji dla iOS.

Kluczowe komponenty

Te pliki zawierają kluczowy kod aplikacji przykładowej Pose Landmarker:

• PoseLandmarkerService.swift inicjalizuje punkt orientacyjny, obsługuje wybór modelu i wykonuje wnioskowanie na podstawie danych wejściowych.
• CameraViewController: implementuje interfejs użytkownika do obsługi trybu wprowadzania obrazu z kamery na żywo i wizualizuje punkty orientacyjne.
• MediaLibraryViewController.swift implementuje interfejs użytkownika dla trybu wprowadzania statycznych obrazów i plików wideo oraz wizualizuje punkty orientacyjne.

Konfiguracja

W tej sekcji znajdziesz najważniejsze czynności, które musisz wykonać, aby skonfigurować środowisko programistyczne i projekty kodu pod kątem użycia punktów orientacyjnych. Ogólne informacje o konfigurowaniu środowiska programistycznego do korzystania z zadań MediaPipe, w tym wymagania dotyczące wersji platformy, znajdziesz w przewodniku konfiguracji dla iOS.

Zależności

Pose Landmarker korzysta z biblioteki MediaPipeTasksVision, którą należy zainstalować za pomocą CocoaPods. Biblioteka jest zgodna z aplikacją w języku Swift i Objective-C i nie wymaga dodatkowej konfiguracji językowej.

Instrukcje instalacji CocoaPods na macOS znajdziesz w przewodniku instalacji CocoaPods. Instrukcje tworzenia Podfile z podstawowymi komponentami potrzebnymi do działania aplikacji znajdziesz w artykule Korzystanie z CocoaPods.

Dodaj pod MediaPipeTasksVision w tabeli Podfile przy użyciu tego kodu:

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

Jeśli Twoja aplikacja zawiera cele testów jednostkowych, dodatkowe informacje o konfigurowaniu Podfile znajdziesz w przewodniku konfiguracji na iOS.

Model

Zadanie MediaPipe Pose Landmarker wymaga przetrenowanego pakietu, który jest zgodny z tym zadaniem. Więcej informacji o dostępnych wytrenowanych modelach usługi Pose Landmarker znajdziesz w sekcji Modele w omówieniu zadania.

Użyj skryptu download_models.sh, aby pobrać modele i dodać je do katalogu projektu za pomocą Xcode. Instrukcje dodawania plików do projektu Xcode znajdziesz w artykule Zarządzanie plikami i folderami w projekcie Xcode.

Użyj właściwości BaseOptions.modelAssetPath, by określić ścieżkę do modelu w pakiecie aplikacji. Przykładowy kod znajdziesz w następnej sekcji.

Tworzenie zadania

Zadaniem tworzenia punktowania pozycji może być wywołanie jednego z inicjalizatorów. Inicjator PoseLandmarker(options:) akceptuje wartości opcji konfiguracji.

Jeśli nie potrzebujesz narzędzia do wykrywania punktów orientacyjnych pozy zainicjowanego za pomocą niestandardowych opcji konfiguracji, możesz użyć funkcji inicjalizującej PoseLandmarker(modelPath:), aby utworzyć narzędzie do wykrywania punktów orientacyjnych pozy z opcjami domyślnymi. Więcej informacji o opcjach konfiguracji znajdziesz w artykule Omówienie konfiguracji.

Zadanie dotyczące punktów orientacyjnych pozy obsługuje 3 typy danych wejściowych: zdjęcia, pliki wideo i transmisje na żywo. Domyślnie PoseLandmarker(modelPath:) inicjuje zadanie dotyczące obrazów statycznych. Jeśli chcesz zainicjować zadanie przetwarzania plików wideo lub transmisji wideo na żywo, użyj właściwości PoseLandmarker(options:), aby określić tryb działania wideo lub transmisji na żywo. Tryb transmisji na żywo wymaga też dodatkowej opcji konfiguracji poseLandmarkerLiveStreamDelegate, która umożliwia narzędziu Pose Landmarker asynchroniczne przesyłanie wyników wykrywania punktów orientacyjnych postawy do delegowanego procesu.

Aby dowiedzieć się, jak utworzyć zadanie i przeprowadzić wnioskowanie, wybierz kartę odpowiadającą trybowi działania.

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];
    

Uwaga: jeśli używasz trybu wideo lub transmisji na żywo, funkcja Pose Landmarker korzysta z śledzenia, aby uniknąć uruchamiania modelu wykrywania dłoni w każdym ujęciu. Pomaga to zmniejszyć opóźnienie.

Opcje konfiguracji

W tym zadaniu dostępne są te opcje konfiguracji aplikacji na iOS:

Konfiguracja transmisji na żywo

Gdy tryb działania jest ustawiony na transmisję na żywo, narzędzie do wykrywania punktów orientacyjnych pozy wymaga dodatkowej opcji konfiguracji poseLandmarkerLiveStreamDelegate, która umożliwia asynchroniczne dostarczanie wyników wykrywania punktów orientacyjnych pozy. Delegat musi implementować metodę poseLandmarker(_:didFinishDetection:timestampInMilliseconds:error:), którą wywołuje funkcja wykrywająca punkty orientacyjne pozy po przetworzeniu wyników wykrywania punktów orientacyjnych pozy w każdej klatce.

Przygotuj dane

Przed przekazaniem do funkcji wyszukiwania punktów orientacyjnych pozy musisz przekonwertować wejściowy obraz lub kadr na obiekt MPImage. MPImage obsługuje różne typy formatów obrazów iOS i może ich używać w dowolnym trybie działania do wnioskowania. Aby dowiedzieć się więcej o MPImage, zapoznaj się z informacjami o interfejsie MPImage API.

Wybierz format obrazu iOS na podstawie przypadku użycia i trybułu działania wymaganego przez aplikację. MPImage obsługuje formaty obrazów iOS UIImage, CVPixelBuffer i CMSampleBuffer.

UIImage

Format UIImage jest odpowiedni do tych trybów działania:

• Obrazy: obrazy z pakietu aplikacji, galerii użytkownika lub systemu plików sformatowane jako obrazy UIImage można przekształcić w obiekt MPImage.

• Filmy: użyj narzędzia AVAssetImageGenerator, aby wyodrębnić klatki wideo do formatu CGImage, a następnie przekonwertuj je na obrazy UIImage.

// 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];
    

Przykład inicjalizuje MPImage z domyślnym ułożeniem UIImage.Orientation.Up. Możesz zainicjować MPImage dowolną z obsługiwanych wartości UIImage.Orientation. Punkt orientacyjny pozycji nie obsługuje odbicia lustrzanego orientacji, np. .upMirrored, .downMirrored, .leftMirrored i .rightMirrored.

Więcej informacji o funkcji UIImage znajdziesz w dokumentacji dla deweloperów Apple dotyczącej interfejsu UIImage.

CVPixelBuffer

Format CVPixelBuffer jest odpowiedni dla aplikacji, które generują klatki i korzystają z ramy CoreImage na iOS do przetwarzania.

Format CVPixelBuffer jest odpowiedni do tych trybów działania:

• Obrazy: aplikacje, które generują obrazy CVPixelBuffer po przetworzeniu ich za pomocą interfejsu CoreImage w iOS, mogą wysyłać je do usługi Pose Landmarker w trybie uruchamiania obrazu.

• Filmy: klatki wideo można przekonwertować do formatu CVPixelBuffer w celu przetwarzania, a następnie wysłać do usługi Pose Landmarker w trybie wideo.

• transmisja na żywo: aplikacje korzystające z kamery iOS do generowania klatek mogą zostać przekonwertowane do formatu CVPixelBuffer w celu przetwarzania, zanim zostaną wysłane do usługi Pose Landmarker w trybie transmisji na żywo.

// 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];
    

Więcej informacji o funkcji CVPixelBuffer znajdziesz w dokumentacji dla deweloperów Apple (CVPixelBuffer).

CMSampleBuffer

Format CMSampleBuffer przechowuje próbki multimediów o jednolitym typie i jest odpowiedni do uruchamiania transmisji na żywo. Ramki na żywo z kamer iOS są asynchronicznie dostarczane w formacie CMSampleBuffer przez AVCaptureVideoDataOutput.

// 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];
    

Więcej informacji o CMSampleBuffer znajdziesz w dokumentacji CMSampleBuffer dla deweloperów Apple.

Uruchamianie zadania

Aby uruchomić narzędzie do wyznaczania punktów orientacyjnych w pozie, użyj metody detect() odpowiedniej dla przypisanego trybu działania:

• Statyczny obraz: detect(image:)
• Film: detect(videoFrame:timestampInMilliseconds:)
• Transmisja na żywo: detectAsync(image:timestampInMilliseconds:)

Poniższe przykłady kodu pokazują proste przykłady uruchamiania narzędzia Pose Landmarker w różnych trybach:

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];
    

Przykład kodu usługi Pose Landmarker pokazuje implementację każdego z tych trybów (detect(image:), detect(videoFrame:timestampInMilliseconds:) i detectAsync(image:timestampInMilliseconds:)) w szczegółach. Przykładowy kod umożliwia użytkownikowi przełączanie się między trybami przetwarzania, które mogą nie być wymagane w Twoim przypadku.

Pamiętaj:

• W trybie wideo lub transmisji na żywo musisz też podać sygnaturę czasową ramki wejściowej do zadania dotyczącego wyznaczenia punktów orientacyjnych pozy.

• W trybie obrazu lub filmu zadanie dotyczące punktów orientacyjnych pozy blokuje bieżący wątek, dopóki nie przetworzy podawanego obrazu lub ramki. Aby uniknąć blokowania bieżącego wątku, przeprowadź przetwarzanie w wątku tła za pomocą frameworków iOS Dispatch lub NSOperation.

• W trybie transmisji na żywo zadanie Pose Notebooker jest przywracane od razu i nie blokuje bieżącego wątku. Po przetworzeniu każdego wejściowego kadru wywołuje metodę poseLandmarker(_:didFinishDetection:timestampInMilliseconds:error:) z wynikiem zwracanym przez funkcję wyznaczania punktów orientacyjnych postawy. Landmarker pozycji wywołuje tę metodę asynchronicznie w dedykowanej kolejce wysyłania sekwencyjnego. Aby wyświetlić wyniki w interfejsie, prześlij je do kolejki głównej po przetworzeniu. Jeśli funkcja detectAsync zostanie wywołana, gdy zadanie dotyczące wyodrębniania punktów orientacyjnych pozy jest zajęte przetwarzaniem innego kadru, wyodrębnianie punktów orientacyjnych pozy zignoruje nowy klatka wejściowa.

Obsługa i wyświetlanie wyników

Po przeprowadzeniu wnioskowania zadanie wyszukiwania punktów orientacyjnych pozy zwraca PoseLandmarkerResult, które zawiera współrzędne każdego punktu orientacyjnego pozy.

Poniżej znajdziesz przykład danych wyjściowych z tego zadania:

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)

Dane wyjściowe zawierają zarówno znormalizowane współrzędne (Landmarks), jak i współrzędne globalne (WorldLandmarks) dla każdego punktu orientacyjnego.

Dane wyjściowe zawierają te sformatowane współrzędne (Landmarks):

• x i y: współrzędne punktu orientacyjnego znormalizowane w zakresie od 0,0 do 1,0 przez szerokość (x) i wysokość (y) obrazu.

• z: głębokość punktu orientacyjnego, której źródłem jest głębia w połowie bioder. Im mniejsza wartość, tym obiekt jest bliżej kamery. Wielkość z używa mniej więcej tej samej skali co x.

• visibility: prawdopodobieństwo, że punkt orientacyjny jest widoczny na zdjęciu.

Dane wyjściowe zawierają te współrzędne świata (WorldLandmarks):

• x, y i z: rzeczywiste trójwymiarowe współrzędne w metrach, ze środkiem osi bioder jako punktem początkowym.

• visibility: prawdopodobieństwo, że punkt orientacyjny jest widoczny na zdjęciu.

Na ilustracji poniżej widać wizualizację wyniku zadania:

Opcjonalna maska podziału na segmenty reprezentuje prawdopodobieństwo, że dany piksel należy do wykrytej osoby. Następujący obraz przedstawia maskę podziału na segmenty danych wyjściowych zadania:

Przykładowy kod usługi Pose Landmarker pokazuje, jak wyświetlać wyniki tej usługi.