Panduan deteksi penanda pose untuk iOS

Tugas Penanda Pose memungkinkan Anda mendeteksi penanda tubuh manusia dalam gambar atau video. Anda dapat menggunakan tugas ini untuk mengidentifikasi lokasi tubuh utama, menganalisis postur, dan mengategorikan gerakan. Tugas ini menggunakan model machine learning (ML) yang berfungsi dengan satu gambar atau video. Tugas ini menghasilkan penanda pose tubuh dalam koordinat gambar dan dalam koordinat dunia 3 dimensi.

Petunjuk ini menunjukkan cara menggunakan Pose Landmarker dengan aplikasi iOS. Contoh kode yang dijelaskan dalam petunjuk ini tersedia di GitHub.

Anda dapat melihat cara kerja tugas ini dengan melihat Demo web ini. Untuk informasi selengkapnya tentang kemampuan, model, dan opsi konfigurasi tugas ini, lihat Ringkasan.

Contoh kode

Kode contoh MediaPipe Tasks adalah implementasi dasar aplikasi Pose Landmarker untuk iOS. Contoh ini menggunakan kamera di perangkat iOS fisik untuk mendeteksi mendeteksi pose dalam streaming video berkelanjutan. Aplikasi ini juga dapat mendeteksi pose dalam gambar dan video dari galeri perangkat.

Anda dapat menggunakan aplikasi ini sebagai titik awal untuk aplikasi iOS Anda sendiri, atau merujuknya saat mengubah aplikasi yang ada. Kode contoh Pose Landmarker dihosting di GitHub.

Mendownload kode

Petunjuk berikut menunjukkan cara membuat salinan lokal contoh kode menggunakan alat command line git.

Untuk mendownload kode contoh:

1. Clone repositori git menggunakan perintah berikut:

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

2. Secara opsional, konfigurasikan instance git Anda untuk menggunakan checkout jarang, sehingga Anda hanya memiliki file untuk aplikasi contoh Pose Landmarker:

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

Setelah membuat versi lokal kode contoh, Anda dapat menginstal library tugas MediaPipe, membuka project menggunakan Xcode, dan menjalankan aplikasi. Untuk petunjuk, lihat Panduan Penyiapan untuk iOS.

Komponen utama

File berikut berisi kode penting untuk aplikasi contoh Pose Landmarker:

• PoseLandmarkerService.swift: Melakukan inisialisasi penanda, menangani pemilihan model, dan menjalankan inferensi pada data input.
• CameraViewController: Mengimplementasikan UI untuk mode input feed kamera live dan memvisualisasikan titik penanda.
• MediaLibraryViewController.swift: Mengimplementasikan UI untuk mode input file gambar diam dan video serta memvisualisasikan penanda.

Penyiapan

Bagian ini menjelaskan langkah-langkah utama untuk menyiapkan lingkungan pengembangan dan project kode untuk menggunakan Pose Landmarker. Untuk informasi umum tentang cara menyiapkan lingkungan pengembangan untuk menggunakan tugas MediaPipe, termasuk persyaratan versi platform, lihat Panduan penyiapan untuk iOS.

Dependensi

Pose Landmarker menggunakan library MediaPipeTasksVision, yang harus diinstal menggunakan CocoaPods. Library ini kompatibel dengan aplikasi Swift dan Objective-C, serta tidak memerlukan penyiapan khusus bahasa tambahan.

Untuk petunjuk menginstal CocoaPods di macOS, lihat panduan penginstalan CocoaPods. Untuk mengetahui petunjuk cara membuat Podfile dengan pod yang diperlukan untuk aplikasi Anda, lihat Menggunakan CocoaPods.

Tambahkan pod MediaPipeTasksVision di Podfile menggunakan kode berikut:

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

Jika aplikasi Anda menyertakan target pengujian unit, lihat Panduan Penyiapan untuk iOS guna mendapatkan informasi tambahan tentang cara menyiapkan Podfile.

Model

Tugas MediaPipe Pose Landmarker memerlukan paket terlatih yang kompatibel dengan tugas ini. Untuk mengetahui informasi selengkapnya tentang model terlatih yang tersedia untuk Pose Landmarker, lihat bagian Model ringkasan tugas.

Gunakan skrip download_models.sh untuk mendownload model dan menambahkannya ke direktori project Anda menggunakan Xcode. Untuk petunjuk cara menambahkan file ke project Xcode, lihat Mengelola file dan folder di project Xcode.

Gunakan properti BaseOptions.modelAssetPath untuk menentukan jalur ke model dalam app bundle Anda. Untuk contoh kode, lihat bagian berikutnya.

Membuat tugas

Anda dapat membuat tugas Pose Landmarker dengan memanggil salah satu penginisialisasinya. Penginisialisasi PoseLandmarker(options:) menerima nilai untuk opsi konfigurasi.

Jika tidak memerlukan Pose Landmarker yang diinisialisasi dengan opsi konfigurasi kustom, Anda dapat menggunakan penginisialisasi PoseLandmarker(modelPath:) untuk membuat Pose Landmarker dengan opsi default. Untuk informasi selengkapnya tentang opsi konfigurasi, lihat Ringkasan Konfigurasi.

Tugas Pose Landmarker mendukung 3 jenis data input: gambar diam, file video, dan streaming video live. Secara default, PoseLandmarker(modelPath:) melakukan inisialisasi tugas untuk gambar diam. Jika Anda ingin tugas diinisialisasi untuk memproses file video atau streaming video live, gunakan PoseLandmarker(options:) untuk menentukan mode video atau live stream yang berjalan. Mode live stream juga memerlukan opsi konfigurasi poseLandmarkerLiveStreamDelegate tambahan, yang memungkinkan Pose Landmarker mengirimkan hasil deteksi penanda pose ke delegasi secara asinkron.

Pilih tab yang sesuai dengan mode operasi Anda untuk melihat cara membuat tugas dan menjalankan inferensi.

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

Catatan: Jika Anda menggunakan mode video atau mode live stream, Pose Landmarker menggunakan pelacakan untuk menghindari pemicuan model deteksi telapak tangan di setiap frame, yang membantu mengurangi latensi.

Opsi konfigurasi

Tugas ini memiliki opsi konfigurasi berikut untuk aplikasi iOS:

Konfigurasi livestream

Jika mode berjalan disetel ke live stream, Pose Landmarker memerlukan opsi konfigurasi poseLandmarkerLiveStreamDelegate tambahan, yang memungkinkan Pose Landmarker memberikan hasil deteksi penanda pose secara asinkron. Delegasi harus mengimplementasikan metode poseLandmarker(_:didFinishDetection:timestampInMilliseconds:error:), yang dipanggil Pose Landmarker setelah memproses hasil dari melakukan deteksi landmark pose pada setiap frame.

Menyiapkan data

Anda perlu mengonversi gambar atau frame input menjadi objek MPImage sebelum meneruskannya ke Pose Landmarker. MPImage mendukung berbagai jenis format gambar iOS, dan dapat menggunakannya dalam mode berjalan apa pun untuk inferensi. Untuk informasi selengkapnya tentang MPImage, lihat MPImage API.

Pilih format gambar iOS berdasarkan kasus penggunaan dan mode operasi yang diperlukan aplikasi Anda.MPImage menerima format gambar iOS UIImage, CVPixelBuffer, dan CMSampleBuffer.

UIImage

Format UIImage sangat cocok untuk mode operasi berikut:

• Gambar: gambar dari app bundle, galeri pengguna, atau sistem file yang diformat sebagai gambar UIImage dapat dikonversi menjadi objek MPImage.

• Video: gunakan AVAssetImageGenerator untuk mengekstrak frame video ke format CGImage, lalu konversikan ke gambar 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];
    

Contoh ini menginisialisasi MPImage dengan orientasi UIImage.Orientation.Up default. Anda dapat menginisialisasi MPImage dengan salah satu nilai UIImage.Orientation yang didukung. Pose Landmarker tidak mendukung orientasi yang dicerminkan seperti .upMirrored, .downMirrored, .leftMirrored, .rightMirrored.

Untuk mengetahui informasi selengkapnya tentang UIImage, lihat Dokumentasi Developer Apple UIImage.

CVPixelBuffer

Format CVPixelBuffer sangat cocok untuk aplikasi yang menghasilkan frame dan menggunakan framework CoreImage iOS untuk pemrosesan.

Format CVPixelBuffer sangat cocok untuk mode operasi berikut:

• Gambar: aplikasi yang menghasilkan gambar CVPixelBuffer setelah beberapa pemrosesan menggunakan framework CoreImage iOS dapat dikirim ke Pose Landmarker dalam mode operasi gambar.

• Video: frame video dapat dikonversi ke format CVPixelBuffer untuk pemrosesan, lalu dikirim ke Pose Landmarker dalam mode video.

• livestream: aplikasi yang menggunakan kamera iOS untuk membuat frame dapat dikonversi ke format CVPixelBuffer untuk diproses sebelum dikirim ke Pose Landmarker dalam mode livestream.

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

Untuk mengetahui informasi selengkapnya tentang CVPixelBuffer, lihat Dokumentasi Developer Apple CVPixelBuffer.

CMSampleBuffer

Format CMSampleBuffer menyimpan sampel media dari jenis media yang seragam, dan sangat cocok untuk mode berjalan live stream. Frame live dari kamera iOS dikirim secara asinkron dalam format CMSampleBuffer oleh iOS 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];
    

Untuk mengetahui informasi selengkapnya tentang CMSampleBuffer, lihat Dokumentasi Developer Apple CMSampleBuffer.

Menjalankan tugas

Untuk menjalankan Pose Landmarker, gunakan metode detect() yang khusus untuk mode berjalan yang ditetapkan:

• Gambar diam: detect(image:)
• Video: detect(videoFrame:timestampInMilliseconds:)
• Livestream: detectAsync(image:timestampInMilliseconds:)

Contoh kode berikut menunjukkan contoh sederhana cara menjalankan Pose Landmarker dalam berbagai mode operasi ini:

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

Contoh kode Pose Landmarker menunjukkan implementasi setiap mode ini secara lebih mendetail detect(image:), detect(videoFrame:timestampInMilliseconds:), dan detectAsync(image:timestampInMilliseconds:). Kode contoh memungkinkan pengguna beralih di antara mode pemrosesan yang mungkin tidak diperlukan untuk kasus penggunaan Anda.

Perhatikan hal berikut:

• Saat berjalan dalam mode video atau mode live stream, Anda juga harus memberikan stempel waktu frame input ke tugas Pose Landmarker.

• Saat berjalan dalam mode gambar atau video, tugas Pose Landmarker akan memblokir thread saat ini hingga selesai memproses gambar atau frame input. Untuk menghindari pemblokiran thread saat ini, jalankan pemrosesan di thread latar belakang menggunakan framework Dispatch atau NSOperation iOS.

• Saat berjalan dalam mode live stream, tugas Pose Landmarker akan segera ditampilkan dan tidak memblokir thread saat ini. Metode ini memanggil metode poseLandmarker(_:didFinishDetection:timestampInMilliseconds:error:) dengan hasil penanda pose setelah memproses setiap frame input. Pose Landmarker memanggil metode ini secara asinkron di antrean pengiriman serial khusus. Untuk menampilkan hasil di antarmuka pengguna, kirimkan hasil ke antrean utama setelah memproses hasilnya. Jika fungsi detectAsync dipanggil saat tugas Pose Landmarker sibuk memproses frame lain, Pose Landmarker akan mengabaikan frame input baru.

Menangani dan menampilkan hasil

Setelah menjalankan inferensi, tugas Pose Landmarker akan menampilkan PoseLandmarkerResult yang berisi koordinat untuk setiap penanda pose.

Berikut adalah contoh data output dari tugas ini:

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)

Output-nya berisi koordinat ternormalisasi (Landmarks) dan koordinat dunia (WorldLandmarks) untuk setiap penanda.

Output berisi koordinat ternormalisasi berikut (Landmarks):

• x dan y: Koordinat penanda yang dinormalisasi antara 0,0 dan 1,0 berdasarkan lebar (x) dan tinggi (y) gambar.

• z: Kedalaman penanda, dengan kedalaman di titik tengah pinggul sebagai asal. Makin kecil nilainya, makin dekat penanda ke kamera. Magnitudo z menggunakan skala yang kira-kira sama dengan x.

• visibility: Kemungkinan penanda terlihat dalam gambar.

Output berisi koordinat dunia berikut (WorldLandmarks):

• x, y, dan z: Koordinat 3 dimensi dunia nyata dalam meter, dengan titik tengah pinggul sebagai asal.

• visibility: Kemungkinan penanda terlihat dalam gambar.

Gambar berikut menunjukkan visualisasi output tugas:

Topeng segmentasi opsional mewakili kemungkinan setiap piksel milik orang yang terdeteksi. Gambar berikut adalah mask segmentasi dari output tugas:

Kode contoh Pose Landmarker menunjukkan cara menampilkan hasil Pose Landmarker.