Panduan deteksi penanda tangan untuk iOS

Tugas MediaPipe Hand Landmarker memungkinkan Anda mendeteksi penanda tangan dalam gambar. Petunjuk ini menunjukkan cara menggunakan Penanda Tangan Tangan dengan aplikasi iOS. Contoh kode yang dijelaskan dalam petunjuk ini tersedia di GitHub.

Untuk mengetahui informasi selengkapnya tentang kemampuan, model, dan opsi konfigurasi tugas ini, lihat Ringkasan.

Contoh kode

Kode contoh MediaPipe Tasks adalah implementasi dasar aplikasi Hand Landmarker untuk iOS. Contoh ini menggunakan kamera pada perangkat iOS fisik untuk mendeteksi bangunan terkenal tangan dalam streaming video nonstop. Aplikasi ini juga dapat mendeteksi penanda tangan dalam gambar dan video dari galeri perangkat.

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 Hand Landmarker dihosting di GitHub.

Mendownload kode

Petunjuk berikut menunjukkan cara membuat salinan lokal dari kode contoh 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 untuk menggunakan checkout sparse, sehingga Anda hanya memiliki file untuk aplikasi contoh Hand Landmarker:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/hand_landmarker/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 Hand Landmarker:

• HandLandmarkerService.swift: Melakukan inisialisasi Hand Landmarker, 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 membuat kode project untuk menggunakan Penanda Tangan Tangan. Guna mengetahui informasi umum tentang cara menyiapkan lingkungan pengembangan untuk menggunakan tugas MediaPipe, termasuk persyaratan versi platform, lihat Panduan penyiapan untuk iOS.

Dependensi

Hand 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 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 'MyHandLandmarkerApp' 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 MediaPipe Hand Landmarker memerlukan model terlatih yang kompatibel dengan tugas ini. Untuk mengetahui informasi selengkapnya tentang model terlatih yang tersedia untuk Penanda Tangan Tangan, 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 Hand Landmarker dengan memanggil salah satu penginisialisasinya. Penginisialisasi HandLandmarker(options:) menerima nilai untuk opsi konfigurasi.

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

Tugas Hand Landmarker mendukung 3 jenis data input: gambar diam, file video, dan streaming video live. Secara default, HandLandmarker(modelPath:) melakukan inisialisasi tugas untuk gambar diam. Jika ingin tugas diinisialisasi untuk memproses file video atau streaming video live, gunakan HandLandmarker(options:) untuk menentukan mode yang berjalan untuk video atau livestream. Mode livestream juga memerlukan opsi konfigurasi handLandmarkerLiveStreamDelegate tambahan, yang memungkinkan Penanda Tangan memberikan hasil penanda tangan kepada delegasi secara asinkron.

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

Swift

import MediaPipeTasksVision

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

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

let handLandmarker = try HandLandmarker(options: options)
    

import MediaPipeTasksVision

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

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

let handLandmarker = try HandLandmarker(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `HandLandmarkerLiveStreamDelegate` protocol and
// implements the method that the hand landmarker calls once it finishes
// performing landmarks detection in each input frame.
class HandLandmarkerResultProcessor: NSObject, HandLandmarkerLiveStreamDelegate {

  func handLandmarker(
    _ handLandmarker: HandLandmarker,
    didFinishDetection result: HandLandmarkerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the hand landmarker result or errors here.

  }
}

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

let options = HandLandmarkerOptions()
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 `handLandmarkerLiveStreamDelegate`
// property.
let processor = HandLandmarkerResultProcessor()
options.handLandmarkerLiveStreamDelegate = processor

let handLandmarker = try HandLandmarker(options: options)
    

Objective-C

@import MediaPipeTasksVision;

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

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

MPPHandLandmarker *handLandmarker =
  [[MPPHandLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

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

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

MPPHandLandmarker *handLandmarker =
  [[MPPHandLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

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

@interface APPHandLandmarkerResultProcessor : NSObject 

@end

@implementation APPHandLandmarkerResultProcessor

-   (void)handLandmarker:(MPPHandLandmarker *)handLandmarker
    didFinishDetectionWithResult:(MPPHandLandmarkerResult *)handLandmarkerResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the hand landmarker result or errors here.

}

@end

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

MPPHandLandmarkerOptions *options = [[MPPHandLandmarkerOptions 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 `handLandmarkerLiveStreamDelegate`
// property.
APPHandLandmarkerResultProcessor *processor =
  [APPHandLandmarkerResultProcessor new];
options.handLandmarkerLiveStreamDelegate = processor;

MPPHandLandmarker *handLandmarker =
  [[MPPHandLandmarker alloc] initWithOptions:options error:nil];
    

Opsi konfigurasi

Tugas ini memiliki opsi konfigurasi berikut untuk aplikasi iOS:

Saat mode lari disetel ke livestream, Penanda Tangan memerlukan opsi konfigurasi handLandmarkerLiveStreamDelegate tambahan, yang memungkinkan Penanda Tangan Tangan memberikan hasil deteksi tempat terkenal tangan secara asinkron. Delegasi harus mengimplementasikan metode handLandmarker(_:didFinishDetection:timestampInMilliseconds:error:), yang dipanggil oleh Penanda Tangan Tangan setelah memproses hasil deteksi penanda tangan untuk setiap frame.

Menyiapkan data

Anda harus mengonversi gambar atau frame input ke objek MPImage sebelum meneruskannya ke Penanda Tangan Tangan. 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 objek MPImage.

• Video: gunakan AVAssetImageGenerator untuk mengekstrak frame video ke format CGImage, lalu konversikan menjadi UIImage gambar.

// 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 melakukan inisialisasi MPImage dengan nilai UIImage.Orientation yang didukung. Penanda Tangan 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 framework CoreImage iOS dapat dikirim ke Penanda Tangan dalam mode gambar berjalan.

• Video: frame video dapat dikonversi ke format CVPixelBuffer untuk diproses, lalu dikirim ke Penanda Tangan dalam mode video.

• livestream: aplikasi yang menggunakan kamera iOS untuk menghasilkan frame dapat dikonversi ke dalam format CVPixelBuffer untuk diproses sebelum dikirim ke Penanda Tangan 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 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.

// 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 Penanda Tangan Tangan, gunakan metode detect() khusus untuk mode lari yang ditetapkan:

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

Swift

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

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

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

Objective-C

MPPHandLandmarkerResult *result =
  [handLandmarker detectInImage:image error:nil];
    

MPPHandLandmarkerResult *result =
  [handLandmarker detectInVideoFrame:image
             timestampInMilliseconds:timestamp
                               error:nil];
    

BOOL success =
  [handLandmarker detectAsyncInImage:image
             timestampInMilliseconds:timestamp
                               error:nil];
    

Contoh kode Penanda Tangan Tangan menunjukkan implementasi setiap mode ini secara lebih mendetail. Kode contoh ini memungkinkan pengguna beralih antarmode 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 Penanda Tangan Tangan.

• Saat berjalan dalam mode gambar atau video, tugas Penanda Tangan Tangan 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 Penanda Tangan Tangan akan segera ditampilkan dan tidak memblokir thread saat ini. Metode ini memanggil metode handLandmarker(_:didFinishDetection:timestampInMilliseconds:error:) dengan hasil penanda tangan setelah memproses setiap frame input. Penanda Tangan 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 fungsi detectAsync dipanggil saat tugas Penanda Tangan Tangan sibuk memproses frame lain, Penanda Tangan Tangan akan mengabaikan frame input baru.

Menangani dan menampilkan hasil

Setelah menjalankan inferensi, tugas Hand Landmarker menampilkan HandLandmarkerResult yang berisi penanda tangan dalam koordinat gambar, penanda tangan di koordinat dunia, dan gestur tangan(tangan kiri/kanan) dari tangan yang terdeteksi.

Berikut ini contoh data output dari tugas ini:

Output HandLandmarkerResult berisi tiga komponen. Setiap komponen adalah array, dengan setiap elemen berisi hasil berikut untuk satu tangan yang terdeteksi:

• Kecenderungan penggunaan tangan

  Tangan yang digunakan menunjukkan apakah tangan yang terdeteksi adalah tangan kiri atau kanan.

• 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 tempat terkenal, dengan kedalaman di pergelangan tangan sebagai asal. Semakin kecil nilainya, semakin dekat landmark ke kamera. Magnitudo z menggunakan skala yang kurang lebih sama dengan x.

• Landmark Dunia

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

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  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: