Panduan deteksi objek untuk iOS

Tugas Detektor Objek memungkinkan Anda mendeteksi keadaan dan lokasi beberapa objek objek tertentu. Misalnya, Detektor Objek dapat menemukan dalam jaringan gambar. Petunjuk ini menunjukkan cara menggunakan tugas Detektor Objek di iOS. Tujuan contoh kode yang dijelaskan dalam petunjuk ini tersedia di GitHub.

Anda dapat melihat cara kerja tugas ini dengan membuka Web demo. Sebagai informasi lebih lanjut tentang kemampuan, model, dan opsi konfigurasi dari untuk tugas ini, lihat Ringkasan.

Contoh kode

Kode contoh Tugas MediaPipe adalah implementasi dasar dari suatu Objek Aplikasi pendeteksi untuk iOS. Contoh ini menggunakan kamera pada perangkat iOS fisik untuk terus mendeteksi objek, serta dapat menggunakan gambar dan video dari perangkat galeri untuk mendeteksi objek secara statis.

Anda dapat menggunakan aplikasi ini sebagai titik awal untuk aplikasi iOS Anda sendiri, atau merujuk ke sana saat memodifikasi aplikasi yang ada. Kode contoh Detektor Objek dihosting di GitHub.

Mendownload kode

Petunjuk berikut menunjukkan cara membuat salinan lokal dari 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 sparse, sehingga Anda memiliki hanya file untuk aplikasi contoh Object Detector:

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

Setelah membuat versi lokal dari kode contoh, Anda dapat menginstal Library tugas MediaPipe, buka project menggunakan Xcode dan jalankan aplikasi. Sebagai lihat Panduan Penyiapan untuk iOS.

Komponen utama

File berikut berisi kode penting untuk contoh Detektor Objek aplikasi:

Penyiapan

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

Dependensi

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

Untuk petunjuk menginstal CocoaPods di macOS, lihat CocoaPods panduan pemasangan kami. Untuk mendapatkan petunjuk cara membuat Podfile dengan pod yang diperlukan untuk aplikasi, lihat Menggunakan CocoaPods.

Tambahkan pod MediaPipeTasksVision di Podfile menggunakan kode berikut:

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

Jika aplikasi Anda menyertakan target pengujian unit, lihat Panduan Penyiapan untuk iOS untuk informasi tambahan terkait penyiapan Podfile Anda.

Model

Tugas Detektor Objek MediaPipe memerlukan model terlatih yang kompatibel dengan tugas ini. Untuk informasi lebih lanjut tentang model terlatih yang tersedia Detektor Objek, lihat ringkasan tugas Models bagian.

Pilih dan download model, lalu tambahkan ke direktori project Anda menggunakan Xcode. Untuk instruksi tentang cara menambahkan file ke proyek Xcode Anda, lihat Mengelola dan folder di Xcode Anda project Anda.

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

Membuat tugas

Anda bisa membuat tugas Object Detector dengan memanggil salah satu penginisialisasinya. Tujuan Penginisialisasi ObjectDetector(options:) menetapkan nilai untuk opsi konfigurasi termasuk mode berjalan, lokal nama tampilan, jumlah hasil maksimal, tingkat keyakinan nilai minimum, daftar kategori yang diizinkan, dan daftar tolak.

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

Tugas Detektor Objek mendukung 3 jenis data input: gambar diam, file video dan streaming video live. Secara default, ObjectDetector(modelPath:) menginisialisasi untuk gambar diam. Jika Anda ingin tugas Anda diinisialisasi untuk memproses video file atau streaming video live, gunakan ObjectDetector(options:) untuk menentukan video atau livestream berjalan. Mode livestream juga memerlukan opsi konfigurasi objectDetectorLiveStreamDelegate, yang memungkinkan Pendeteksi Objek untuk mengirimkan hasil deteksi kepada 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: "model",
                                      ofType: "tflite")

let options = ObjectDetectorOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.maxResults = 5

let objectDetector = try ObjectDetector(options: options)
    

Video

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "model",
                                      ofType: "tflite")

let options = ObjectDetectorOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.maxResults = 5

let objectDetector = try ObjectDetector(options: options)
    

livestream

import MediaPipeTasksVision

// Class that conforms to the `ObjectDetectorLiveStreamDelegate` protocol and
// implements the method that the object detector calls once it
// finishes performing detection on each input frame.
class ObjectDetectorResultProcessor: NSObject, ObjectDetectorLiveStreamDelegate {

  func objectDetector(
    _ objectDetector: ObjectDetector,
    didFinishDetection objectDetectionResult: ObjectDetectorResult?,
    timestampInMilliseconds: Int,
    error: Error?) {
    // Process the detection result or errors here.
  }
}

let modelPath = Bundle.main.path(forResource: "model",
                                      ofType: "tflite")

let options = ObjectDetectorOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.maxResults = 5

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

let objectDetector = try ObjectDetector(options: options)
    

Objective-C

Gambar

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPObjectDetectorOptions *options = [[MPPObjectDetectorOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.maxResults = 5;

MPPObjectDetector *objectDetector =
      [[MPPObjectDetector alloc] initWithOptions:options error:nil];
    

Video

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPObjectDetectorOptions *options = [[MPPObjectDetectorOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.maxResults = 5;

MPPObjectDetector *objectDetector =
      [[MPPObjectDetector alloc] initWithOptions:options error:nil];
    

livestream

@import MediaPipeTasksVision;

// Class that conforms to the `ObjectDetectorLiveStreamDelegate` protocol and
// implements the method that the object detector calls once it
// finishes performing detection on each input frame.

@interface APPObjectDetectorResultProcessor : NSObject 

@end

@implementation MPPObjectDetectorResultProcessor

-   (void)objectDetector:(MPPObjectDetector *)objectDetector
    didFinishDetectionWithResult:(MPPObjectDetectorResult *)ObjectDetectorResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the detection result or errors here.

}

@end

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPObjectDetectorOptions *options = [[MPPObjectDetectorOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.maxResults = 5;

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

MPPObjectDetector *objectDetector =
      [[MPPObjectDetector 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 moda:

IMAGE: Mode untuk input gambar tunggal.

VIDEO: Mode untuk frame video yang didekode.

LIVE_STREAM: Mode untuk live stream input besar, seperti dari kamera. Dalam mode ini, resultListener harus dipanggil untuk menyiapkan pemroses yang akan menerima hasil secara asinkron.
{RunningMode.image, RunningMode.video, RunningMode.liveStream} RunningMode.image
displayNamesLocales Menyetel bahasa label yang akan digunakan untuk nama tampilan yang diberikan di metadata model tugas, jika tersedia. Defaultnya adalah en untuk Bahasa Inggris. Anda dapat menambahkan label yang dilokalkan ke metadata model kustom menggunakan TensorFlow Lite Metadata Writer API Kode lokal id
maxResults Menetapkan jumlah maksimum opsional untuk hasil deteksi dengan skor tertinggi ke kembali. Semua angka positif -1 (semua hasil ditampilkan)
scoreThreshold Menetapkan ambang batas skor prediksi yang menggantikan skor yang diberikan dalam metadata model (jika ada). Hasil di bawah nilai ini ditolak. Float mana pun Tidak ditetapkan
categoryAllowlist Menetapkan daftar opsional untuk nama kategori yang diizinkan. Jika tidak kosong, hasil deteksi yang nama kategorinya tidak ada dalam kumpulan ini akan disaring. Nama kategori duplikat atau yang tidak diketahui akan diabaikan. Opsi ini sama-sama bersifat eksklusif dengan categoryDenylist dan menggunakan keduanya akan menghasilkan {i>error<i}. String apa pun Tidak ditetapkan
categoryDenylist Menetapkan daftar opsional nama kategori yang tidak diizinkan. Jika hasil deteksi yang tidak kosong, yang nama kategorinya dalam rangkaian ini akan difilter posisi-posisi ini. Nama kategori duplikat atau yang tidak diketahui akan diabaikan. Opsi ini sama-sama eksklusif dengan categoryAllowlist dan menggunakan keduanya akan menyebabkan error. String apa pun Tidak ditetapkan

Konfigurasi livestream

Jika mode berjalan disetel ke livestream, Detektor Objek memerlukan opsi konfigurasi objectDetectorLiveStreamDelegate tambahan, yang memungkinkan detektor menyampaikan hasil deteksi secara asinkron. Delegasi mengimplementasikan objectDetector(_objectDetector:didFinishDetection:timestampInMilliseconds:error:) , yang dipanggil Detektor Objek setelah memproses hasil deteksi untuk setiap {i>frame<i}.

Nama opsi Deskripsi Rentang Nilai Nilai Default
objectDetectorLiveStreamDelegate Mengaktifkan Detektor Objek untuk menerima hasil deteksi secara asinkron dalam mode livestream. Kelas yang instance-nya disetel ke properti ini harus menerapkan objectDetector(_:didFinishDetection:timestampInMilliseconds:error:) . Tidak berlaku Tidak ditetapkan

Menyiapkan data

Anda harus mengonversi gambar atau bingkai input menjadi objek MPImage sebelum meneruskannya ke Detektor Objek. MPImage mendukung berbagai jenis image iOS format, dan dapat menggunakannya dalam mode berjalan apa pun untuk inferensi. Untuk selengkapnya informasi tentang MPImage, lihat MPImage API

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

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: menggunakan AVAssetImageGenerator untuk mengekstrak frame video ke CGImage baru, lalu konversikan menjadi gambar UIImage.

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 UIImage.Orientation.Up orientasi. Anda dapat menginisialisasi MPImage dengan metode UIImage.Orientation masing-masing. Detektor Objek tidak mendukung orientasi yang dicerminkan seperti .upMirrored, .downMirrored, .leftMirrored, .rightMirrored.

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

CVPixelBuffer

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

Format CVPixelBuffer sangat cocok untuk mode berjalan berikut:

  • Gambar: aplikasi yang membuat gambar CVPixelBuffer setelah beberapa pemrosesan menggunakan framework CoreImage iOS dapat dikirim ke Detektor Objek di mode image running.

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

  • livestream: aplikasi yang menggunakan kamera iOS untuk membuat frame dapat dikonversi ke dalam format CVPixelBuffer untuk diproses sebelum dikirim ke Pendeteksi Objek 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 CVPixelBuffer Apple Pengembang Dokumentasi.

CMSampleBuffer

Format CMSampleBuffer menyimpan sampel media dari jenis media yang seragam, dan sangat cocok untuk mode livestream yang sedang berjalan. {i>Live frame<i} dari kamera iOS dikirim secara asinkron dalam format CMSampleBuffer oleh iOS AVCaptureVideoDataOutput.

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 informasi selengkapnya tentang CMSampleBuffer, lihat CMSampleBuffer Apple Pengembang Dokumentasi.

Menjalankan tugas

Untuk menjalankan Detektor Objek, gunakan metode detect() khusus untuk objek yang mode lari:

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

Contoh kode berikut menunjukkan contoh dasar cara menjalankan Detektor Objek di mode lari yang berbeda:

Swift

Gambar

let objectDetector.detect(image:image)
    

Video

let objectDetector.detect(videoFrame:image)
    

livestream

let objectDetector.detectAsync(image:image)
    

Objective-C

Gambar

MPPObjectDetectorResult *result = [objectDetector detectInImage:image error:nil];
    

Video

MPPObjectDetectorResult *result = [objectDetector detectInVideoFrame:image          timestampInMilliseconds:timestamp error:nil];
    

livestream

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

Contoh kode Detektor Objek menunjukkan implementasi dari setiap mode ini dengan lebih detail detect(image:), detect(videoFrame:), dan detectAsync(image:). Kode contoh memungkinkan pengguna untuk beralih antara yang mungkin tidak diperlukan untuk kasus penggunaan Anda.

Perhatikan hal berikut:

  • Saat berjalan dalam mode video atau mode livestream, Anda juga harus menyediakan stempel waktu {i>frame<i} input ke tugas Object Detector.

  • Saat dijalankan dalam mode gambar atau video, tugas Detektor Objek akan memblokir thread saat ini hingga selesai memproses gambar atau bingkai input. Kepada menghindari pemblokiran thread saat ini, jalankan pemrosesan di latar belakang thread menggunakan iOS Dispatch atau NSOperation framework.

  • Saat berjalan dalam mode livestream, tugas Detektor Objek segera ditampilkan dan tidak memblokir thread saat ini. Fungsi ini memanggil objectDetector(_objectDetector:didFinishDetection:timestampInMilliseconds:error:) dengan hasil deteksi setelah memproses setiap bingkai input. Tujuan Detektor Objek memanggil metode ini secara asinkron pada rangkaian khusus antrean pengiriman. Untuk menampilkan hasil di antarmuka pengguna, kirim hasil ke antrean utama setelah memproses hasilnya. Jika detectAsync dipanggil saat tugas Detektor Objek sedang sibuk memproses {i>frame<i}, Detektor Objek mengabaikan {i>frame<i} input baru.

Menangani dan menampilkan hasil

Setelah menjalankan inferensi, tugas Detektor Objek akan menampilkan ObjectDetectorResult yang mendeskripsikan objek yang ditemukannya di gambar input.

Berikut ini contoh data output dari tugas ini:

ObjectDetectorResult:
 Detection #0:
  Box: (x: 355, y: 133, w: 190, h: 206)
  Categories:
   index       : 17
   score       : 0.73828
   class name  : dog
 Detection #1:
  Box: (x: 103, y: 15, w: 138, h: 369)
  Categories:
   index       : 17
   score       : 0.73047
   class name  : dog

Gambar berikut menunjukkan visualisasi output tugas:

Kode contoh Detektor Objek menunjukkan cara menampilkan hasil deteksi ditampilkan dari tugas, lihat contoh kode untuk detailnya.