Panduan pengenalan gestur untuk iOS

Tugas Pengenal Gestur MediaPipe memungkinkan Anda mengenali gestur tangan secara real time, dan memberikan hasil gestur tangan yang dikenali dan penanda tangan dari tangan yang terdeteksi. Petunjuk ini menunjukkan cara menggunakan Pengenal Gestur dengan aplikasi iOS.

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

Contoh kode

Kode contoh Tugas MediaPipe adalah implementasi dasar aplikasi Pengenal Gestur untuk iOS. Contoh ini menggunakan kamera di perangkat iOS fisik untuk terus mendeteksi gestur tangan, dan juga dapat menggunakan gambar dan video dari galeri perangkat untuk mendeteksi gestur secara statis.

Anda dapat menggunakan aplikasi ini sebagai titik awal untuk aplikasi iOS Anda sendiri, atau merujuknya saat mengubah aplikasi yang ada. Kode contoh Pengenal Gestur 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. Jika ingin, konfigurasikan instance git Anda untuk menggunakan checkout sparse, sehingga Anda hanya memiliki file untuk aplikasi contoh Pengenal Gestur:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/gesture_recognizer/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 Pengenal Gestur:

• GestureRecognizerService.swift: Melakukan inisialisasi Pengenal Gestur, menangani pemilihan model, dan menjalankan inferensi pada data input.
• CameraViewController.swift: Mengimplementasikan UI untuk mode input feed kamera live dan memvisualisasikan hasilnya.
• MediaLibraryViewController.swift: Menerapkan UI untuk mode input file video dan gambar diam serta memvisualisasikan hasilnya.

Penyiapan

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

Dependensi

Pengenal Gestur menggunakan library MediaPipeTasksVision, yang harus diinstal menggunakan CocoaPods. Library ini kompatibel dengan aplikasi Swift dan Objective-C, dan 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 'MyGestureRecognizerApp' 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 Gesture Recognizer memerlukan model terlatih yang kompatibel dengan tugas ini. Untuk mengetahui informasi selengkapnya tentang model terlatih yang tersedia untuk Pengenal Gestur, lihat bagian Model ringkasan tugas.

Pilih dan download model, lalu tambahkan ke direktori project Anda menggunakan Xcode. Untuk mengetahui 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 Pengenal Gestur dengan memanggil salah satu penginisialisasinya. Penginisialisasi GestureRecognizer(options:) menerima nilai untuk opsi konfigurasi.

Jika tidak memerlukan Pengenal Gestur yang diinisialisasi dengan opsi konfigurasi yang disesuaikan, Anda dapat menggunakan penginisialisasi GestureRecognizer(modelPath:) untuk membuat Pengenal Gestur dengan opsi default. Untuk informasi selengkapnya tentang opsi konfigurasi, lihat Ringkasan Konfigurasi.

Tugas Pengenal Gestur mendukung 3 jenis data input: gambar diam, file video, dan streaming video live. Secara default, GestureRecognizer(modelPath:) melakukan inisialisasi tugas untuk gambar diam. Jika Anda ingin tugas diinisialisasi untuk memproses file video atau streaming video live, gunakan GestureRecognizer(options:) untuk menentukan mode operasi video atau live stream. Mode live stream juga memerlukan opsi konfigurasi gestureRecognizerLiveStreamDelegate tambahan, yang memungkinkan Pengenal Gestur mengirimkan hasil pengenalan gestur 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: "gesture_recognizer",
                                      ofType: "task")

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let gestureRecognizer = try GestureRecognizer(options: options)
    

import MediaPipeTasksVision

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

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let gestureRecognizer = try GestureRecognizer(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `GestureRecognizerLiveStreamDelegate` protocol and
// implements the method that the gesture recognizer calls once it finishes
// performing recognizing hand gestures in each input frame.
class GestureRecognizerResultProcessor: NSObject, GestureRecognizerLiveStreamDelegate {

  func gestureRecognizer(
    _ gestureRecognizer: GestureRecognizer,
    didFinishRecognition result: GestureRecognizerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the gesture recognizer result or errors here.

  }
}

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

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

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

let gestureRecognizer = try GestureRecognizer(options: options)
    

Objective-C

@import MediaPipeTasksVision;

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

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

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

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPGestureRecognizerLiveStreamDelegate` protocol
// and implements the method that the gesture recognizer calls once it finishes
// performing gesture recognition on each input frame.

@interface APPGestureRecognizerResultProcessor : NSObject 

@end

@implementation APPGestureRecognizerResultProcessor

-   (void)gestureRecognizer:(MPPGestureRecognizer *)gestureRecognizer
    didFinishRecognitionWithResult:(MPPGestureRecognizerResult *)gestureRecognizerResult
           timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                             error:(NSError *)error {

    // Process the gesture recognizer result or errors here.

}

@end

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

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

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

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

Opsi konfigurasi

Tugas ini memiliki opsi konfigurasi berikut untuk aplikasi iOS:

Jika mode berjalan disetel ke live stream, Pengenal Gestur memerlukan opsi konfigurasi gestureRecognizerLiveStreamDelegate tambahan, yang memungkinkan Pengenal Gestur memberikan hasil pengenalan gestur secara asinkron. Delegasi harus mengimplementasikan metode gestureRecognizer(_:didFinishRecognition:timestampInMilliseconds:error:), yang dipanggil Pengenal Gestur setelah memproses hasil dari melakukan pengenalan gestur pada setiap frame.

Menyiapkan data

Anda perlu mengonversi gambar atau frame input menjadi objek MPImage sebelum meneruskannya ke Pengenal Gestur. MPImage mendukung berbagai jenis format gambar iOS, dan dapat menggunakannya dalam mode berjalan apa pun untuk inferensi. Untuk mengetahui 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 berjalan 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. Pengenal Gestur 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 berjalan berikut:

• Gambar: aplikasi yang menghasilkan gambar CVPixelBuffer setelah beberapa pemrosesan menggunakan framework CoreImage iOS dapat dikirim ke Pengenal Gestur dalam mode pengoperasian gambar.

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

• livestream: aplikasi yang menggunakan kamera iOS untuk membuat frame dapat dikonversi ke format CVPixelBuffer untuk diproses sebelum dikirim ke Pengenal Gestur 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 operasi 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 Pengenal Gestur, gunakan metode recognize() khusus untuk mode lari yang ditetapkan:

• Gambar diam: recognize(image:)
• Video: recognize(videoFrame:timestampInMilliseconds:)
• Livestream: recognizeAsync(image:timestampInMilliseconds:)

Contoh kode berikut menunjukkan contoh dasar cara menjalankan Pengenal Gestur dalam berbagai mode operasi ini:

Swift

let result = try gestureRecognizer.recognize(image: image)
    

let result = try gestureRecognizer.recognize(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try gestureRecognizer.recognizeAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

  MPPGestureRecognizerResult *result =
    [gestureRecognizer recognizeImage:mppImage
                                error:nil];
    

MPPGestureRecognizerResult *result =
  [gestureRecognizer recognizeVideoFrame:image
                 timestampInMilliseconds:timestamp
                                   error:nil];
    

BOOL success =
  [gestureRecognizer recognizeAsyncImage:image
                 timestampInMilliseconds:timestamp
                                   error:nil];
    

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 Pengenal Gestur.

• Saat berjalan dalam mode gambar atau video, tugas Pengenal Gestur 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 Pengenal Gestur akan segera ditampilkan dan tidak memblokir thread saat ini. Metode ini memanggil metode gestureRecognizer(_:didFinishRecognition:timestampInMilliseconds:error:) dengan hasil pengenalan gestur setelah memproses setiap frame input. Pengenal Gestur memanggil metode ini secara asinkron di antrean pengiriman serial khusus. Untuk menampilkan hasil pada antarmuka pengguna, kirim hasil ke antrean utama setelah memproses hasilnya. Jika fungsi recognizeAsync dipanggil saat tugas Pengenal Gestur sedang sibuk memproses frame lain, Pengenal Gestur akan mengabaikan frame input baru.

Menangani dan menampilkan hasil

Setelah menjalankan inferensi, tugas Pengenal Gestur menampilkan GestureRecognizerResult yang berisi penanda tangan dalam koordinat gambar, penanda tangan dalam koordinat dunia, tangan dominan(tangan kiri/kanan), dan kategori gestur tangan dari tangan yang terdeteksi.

Berikut adalah contoh data output dari tugas ini:

GestureRecognizerResult yang dihasilkan berisi empat komponen, dan setiap komponen adalah array, dengan setiap elemen berisi hasil deteksi dari satu tangan yang terdeteksi.

• Tangan dominan

  Kecenderungan tangan menunjukkan apakah tangan yang terdeteksi adalah tangan kiri atau kanan.

• Gestur

  Kategori gestur yang dikenali dari tangan yang terdeteksi.

• Tempat terkenal

  Ada 21 penanda tangan, masing-masing terdiri dari koordinat x, y, dan z. Koordinat x dan y dinormalisasi ke [0,0, 1,0] berdasarkan lebar dan tinggi gambar. Koordinat z mewakili kedalaman penanda, dengan kedalaman di pergelangan tangan sebagai asal. Makin kecil nilainya, makin dekat titik penanda ke kamera. Besar z menggunakan skala yang kira-kira sama dengan x.

• Landmark Dunia

  Landmark 21 tangan juga ditampilkan dalam koordinat dunia. Setiap penanda geografis terdiri dari x, y, dan z, yang mewakili koordinat 3D dunia nyata dalam meter dengan asal di pusat geometris tangan.

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)

Gambar berikut menunjukkan visualisasi output tugas: