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 informasi selengkapnya tentang kemampuan, model, dan opsi konfigurasi tugas ini, lihat Ringkasan.
Contoh kode
Kode contoh MediaPipe Tasks adalah implementasi dasar aplikasi Pengenal Gestur untuk iOS. Contoh ini menggunakan kamera pada perangkat iOS fisik untuk secara terus mendeteksi gestur tangan, dan juga dapat menggunakan gambar dan video dari galeri perangkat untuk mendeteksi gestur secara statis.
Anda dapat menggunakan aplikasi sebagai titik awal untuk aplikasi iOS Anda sendiri, atau merujuk ke aplikasi tersebut saat memodifikasi aplikasi yang sudah ada. Kode contoh Pengenal Gestur dihosting di GitHub.
Mendownload kode
Petunjuk berikut menunjukkan cara membuat salinan lokal dari kode contoh menggunakan alat command line git.
Untuk mendownload kode contoh:
Clone repositori git menggunakan perintah berikut:
git clone https://github.com/google-ai-edge/mediapipe-samples
Secara opsional, konfigurasikan instance git 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 mengetahui petunjuknya, 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: Mengimplementasikan 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 Pengenalan Gestur. Guna mengetahui informasi umum tentang cara menyiapkan lingkungan pengembangan untuk menggunakan tugas MediaPipe, termasuk persyaratan versi platform, lihat Panduan penyiapan untuk iOS.
Dependensi
Pengenalan Gestur menggunakan library MediaPipeTasksVision
, yang harus diinstal
menggunakan CocoaPods. Library ini kompatibel dengan aplikasi Swift dan Objective-C, serta tidak memerlukan penyiapan khusus bahasa tambahan apa pun.
Untuk mengetahui petunjuk cara menginstal CocoaPods di macOS, lihat panduan penginstalan CocoaPods.
Untuk 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 untuk mengetahui informasi tambahan tentang
penyiapan Podfile
.
Model
Tugas Pengenal Gestur MediaPipe 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 Anda.
Gunakan properti BaseOptions.modelAssetPath
untuk menentukan jalur ke model di 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 mengetahui informasi selengkapnya tentang opsi
konfigurasi, lihat Ringkasan Konfigurasi.
Tugas Pengenalan 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 ingin tugas Anda diinisialisasi untuk memproses
file video atau streaming video live, gunakan GestureRecognizer(options:)
untuk menentukan
mode video atau livestream yang berjalan. Mode livestream juga memerlukan
opsi konfigurasi gestureRecognizerLiveStreamDelegate
tambahan, yang
memungkinkan Pengenal Gestur memberikan hasil pengenalan gestur ke delegasi
secara asinkron.
Pilih tab yang sesuai dengan mode lari Anda untuk melihat cara membuat tugas dan menjalankan inferensi.
Swift
Gambar
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)
Video
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)
Livestream
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
Gambar
@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];
Video
@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];
Livestream
@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:
Nama Opsi | Deskripsi | Rentang Nilai | Nilai Default | |
---|---|---|---|---|
runningMode |
Menetapkan mode berjalan untuk tugas. Ada tiga
mode: IMAGE: Mode untuk input gambar tunggal. VIDEO: Mode untuk frame video yang didekode. LIVE_STREAM: Mode untuk livestream data input, seperti dari kamera. Dalam mode ini, resultListener harus dipanggil untuk menyiapkan pemroses yang menerima hasil secara asinkron. Dalam mode ini, gestureRecognizerLiveStreamDelegate harus ditetapkan ke instance class yang mengimplementasikan GestureRecognizerLiveStreamDelegate untuk menerima hasil melakukan pengenalan gestur secara asinkron.
|
{RunningMode.image, RunningMode.video, RunningMode.liveStream } |
RunningMode.image |
|
num_hands |
Jumlah maksimum jarum dapat dideteksi oleh
GestureRecognizer .
|
Any integer > 0 |
1 |
|
min_hand_detection_confidence |
Skor keyakinan minimum untuk deteksi tangan agar dianggap berhasil dalam model deteksi telapak tangan. | 0.0 - 1.0 |
0.5 |
|
min_hand_presence_confidence |
Skor keyakinan minimum skor kehadiran tangan di model deteksi penanda tangan. Dalam mode Video dan mode Live stream Pengenal Gestur, jika kehadiran tangan dengan skor pasti dari model penanda tangan di bawah batas ini, model deteksi telapak tangan akan terpicu. Jika tidak, algoritma pelacakan tangan ringan akan digunakan untuk menentukan lokasi tangan untuk deteksi penanda berikutnya. | 0.0 - 1.0 |
0.5 |
|
min_tracking_confidence |
Skor keyakinan minimum agar pelacakan tangan dianggap berhasil. Ini adalah ambang batas IoU kotak pembatas antara tangan di frame saat ini dan frame terakhir. Dalam mode Video dan mode Streaming Pengenal Gestur, jika pelacakan gagal, Pengenal Gestur akan memicu deteksi tangan. Jika tidak, deteksi tangan akan dilewati. | 0.0 - 1.0 |
0.5 |
|
canned_gestures_classifier_options |
Opsi untuk mengonfigurasi perilaku pengklasifikasi gestur terekam. Gestur tersimpan ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"] |
|
|
|
custom_gestures_classifier_options |
Opsi untuk mengonfigurasi perilaku pengklasifikasi gestur kustom. |
|
|
|
result_listener |
Menetapkan pemroses hasil untuk menerima hasil klasifikasi secara asinkron saat pengenal gestur berada dalam mode live stream.
Hanya dapat digunakan saat mode lari disetel ke LIVE_STREAM |
ResultListener |
T/A | T/A |
Jika mode yang berjalan disetel untuk livestream, Pengenal Gestur memerlukan
opsi konfigurasi gestureRecognizerLiveStreamDelegate
tambahan, yang
memungkinkan Pengenalan Gestur memberikan hasil pengenalan gestur secara asinkron.
Delegasi harus mengimplementasikan metode
gestureRecognizer(_:didFinishRecognition:timestampInMilliseconds:error:)
, yang dipanggil oleh Pengenal Gestur setelah memproses hasil melakukan
pengenalan gestur di setiap frame.
Nama opsi | Deskripsi | Rentang Nilai | Nilai Default |
---|---|---|---|
gestureRecognizerLiveStreamDelegate |
Mengaktifkan Pengenalan Gestur untuk menerima hasil pengenalan gestur secara asinkron dalam mode livestream. Class yang
instance-nya ditetapkan ke properti ini harus mengimplementasikan
metode
gestureRecognizer(_:didFinishRecognition:timestampInMilliseconds:error:) . |
Tidak berlaku | Tidak ditetapkan |
Menyiapkan data
Anda harus 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 untuk inferensi. Untuk informasi
selengkapnya tentang MPImage
, lihat
MPImage API
Pilih format image iOS berdasarkan kasus penggunaan dan mode pengoperasian yang diperlukan aplikasi Anda.MPImage
menerima format image iOS UIImage
, CVPixelBuffer
, dan CMSampleBuffer
.
UIImage
Format UIImage
sangat cocok untuk mode lari berikut:
Gambar: gambar dari app bundle, galeri pengguna, atau sistem file yang diformat sebagai gambar
UIImage
dapat dikonversi menjadi objekMPImage
.Video: gunakan AVAssetImageGenerator untuk mengekstrak frame video ke format CGImage, lalu konversikan menjadi
UIImage
gambar.
Swift
// 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)
Objective-C
// 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 melakukan inisialisasi MPImage
dengan nilai
UIImage.Orientation
yang didukung. Pengenalan Gestur tidak mendukung orientasi yang dicerminkan seperti .upMirrored
,
.downMirrored
, .leftMirrored
, .rightMirrored
.
Untuk 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 lari berikut:
Gambar: aplikasi yang membuat gambar
CVPixelBuffer
setelah beberapa pemrosesan menggunakan frameworkCoreImage
iOS dapat dikirim ke Pengenal Gestur dalam mode berjalan gambar.Video: Frame video dapat dikonversi ke format
CVPixelBuffer
untuk diproses, lalu dikirim ke Pengenal Gestur dalam mode video.livestream: aplikasi yang menggunakan kamera iOS untuk menghasilkan frame dapat dikonversi ke dalam format
CVPixelBuffer
untuk diproses sebelum dikirim ke Pengenal Gestur dalam mode livestream.
Swift
// 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)
Objective-C
// 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 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 yang berjalan pada livestream. Frame live dari kamera iOS
dikirimkan secara asinkron dalam format CMSampleBuffer
oleh
AVCaptureVideoDataOutput iOS.
Swift
// 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)
Objective-C
// 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 berjalan 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 berjalan ini:
Swift
Gambar
let result = try gestureRecognizer.recognize(image: image)
Video
let result = try gestureRecognizer.recognize( videoFrame: image, timestampInMilliseconds: timestamp)
Livestream
try gestureRecognizer.recognizeAsync( image: image, timestampInMilliseconds: timestamp)
Objective-C
Gambar
MPPGestureRecognizerResult *result = [gestureRecognizer recognizeImage:mppImage error:nil];
Video
MPPGestureRecognizerResult *result = [gestureRecognizer recognizeVideoFrame:image timestampInMilliseconds:timestamp error:nil];
Livestream
BOOL success = [gestureRecognizer recognizeAsyncImage:image timestampInMilliseconds:timestamp error:nil];
Kode contoh ini memungkinkan pengguna beralih antar-mode pemrosesan yang mungkin tidak diperlukan untuk kasus penggunaan Anda.
Perhatikan hal berikut:
Saat berjalan dalam mode video atau mode livestream, Anda juga harus memberikan stempel waktu frame input ke tugas Pengenalan Gestur.
Saat berjalan dalam mode gambar atau video, tugas Pengenal Gestur 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 livestream, 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. Pengenalan Gestur memanggil metode ini secara asinkron pada antrean pengiriman serial khusus. Untuk menampilkan hasil pada antarmuka pengguna, kirimkan hasil ke antrean utama setelah memproses hasil. Jika fungsirecognizeAsync
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,
landmark tangan dalam koordinat dunia, handedness(tangan kiri/kanan), dan kategori gestur
tangan pada tangan yang terdeteksi.
Berikut ini contoh data output dari tugas ini:
GestureRecognizerResult
yang dihasilkan berisi empat komponen, dan setiap komponen adalah array, dengan setiap elemen berisi hasil yang terdeteksi dari satu tangan yang terdeteksi.
Kecenderungan penggunaan tangan
Tangan yang digunakan 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
, danz
. Koordinatx
dany
dinormalisasi ke [0.0, 1.0] berdasarkan lebar dan tinggi gambar. Koordinatz
mewakili kedalaman tempat terkenal, dengan kedalaman di pergelangan tangan sebagai asal. Semakin kecil nilainya, semakin dekat landmark ke kamera. Magnitudoz
menggunakan skala yang kurang lebih sama denganx
.Landmark Dunia
21 penanda tangan juga ditampilkan dalam koordinat dunia. Setiap penanda terdiri dari
x
,y
, danz
, 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: