Panduan penyematan gambar untuk iOS

Tugas MediaPipe Image Embedder memungkinkan Anda mengonversi data gambar menjadi representasi numerik untuk menyelesaikan tugas pemrosesan gambar terkait ML, seperti membandingkan kemiripan dua gambar.

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 Image Embedder untuk iOS. Contoh ini menggunakan kamera di perangkat iOS fisik untuk menyisipkan gambar secara terus-menerus, dan juga dapat menjalankan penyempan pada file gambar 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 Image Embedder 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 Anda untuk menggunakan checkout jarang, sehingga Anda hanya memiliki file untuk aplikasi contoh Image Embedder:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/image_embedder/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 Image Embedder:

• ImageEmbedderService.swift: Menginisialisasi Image Embedder, 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 gambar diam dan memvisualisasikan hasilnya.

Penyiapan

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

Dependensi

Image Embedder 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 'MyImageEmbedderApp' 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 Image Embedder memerlukan model terlatih yang kompatibel dengan tugas ini. Untuk informasi selengkapnya tentang model terlatih yang tersedia untuk Image Embedder, lihat bagian Model.

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

Gunakan properti BaseOptions.modelAssetPath untuk menentukan jalur ke model dalam app bundle Anda.

Membuat tugas

Anda dapat membuat tugas Penyematan Gambar dengan memanggil salah satu penginisialisasinya. Penginisialisasi ImageEmbedder(options:) menerima nilai untuk opsi konfigurasi.

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

Tugas Penyematan Gambar mendukung 3 jenis data input: gambar diam, file video, dan streaming video live. Secara default, ImageEmbedder(modelPath:) melakukan inisialisasi tugas untuk gambar diam. Jika Anda ingin tugas diinisialisasi untuk memproses file video atau streaming video live, gunakan ImageEmbedder(options:) untuk menentukan mode video atau live stream yang berjalan. Mode livestream juga memerlukan opsi konfigurasi imageEmbedderLiveStreamDelegate tambahan, yang memungkinkan Image Embedder memberikan hasil penyematan gambar 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: "model",
  ofType: "tflite")

let options = ImageEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.quantize = true
options.l2Normalize = true

let imageEmbedder = try ImageEmbedder(options: options)
    

import MediaPipeTasksVision

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

let options = ImageEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.quantize = true
options.l2Normalize = true

let imageEmbedder = try ImageEmbedder(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `ImageEmbedderLiveStreamDelegate` protocol and
// implements the method that the image embedder calls once it finishes
// embedding each input frame.
class ImageEmbedderResultProcessor: NSObject, ImageEmbedderLiveStreamDelegate {

  func imageEmbedder(
    _ imageEmbedder: ImageEmbedder,
    didFinishEmbedding result: ImageEmbedderResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the image embedder result or errors here.

  }
}

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

let options = ImageEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.quantize = true
options.l2Normalize = true

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

let imageEmbedder = try ImageEmbedder(options: options)
    

Objective-C

@import MediaPipeTasksVision;

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

MPPImageEmbedderOptions *options = [[MPPImageEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.quantize = YES;
options.l2Normalize = YES;

MPPImageEmbedder *imageEmbedder =
  [[MPPImageEmbedder alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

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

MPPImageEmbedderOptions *options = [[MPPImageEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.quantize = YES;
options.l2Normalize = YES;

MPPImageEmbedder *imageEmbedder =
  [[MPPImageEmbedder alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPImageEmbedderLiveStreamDelegate` protocol
// and implements the method that the image embedder calls once it finishes
// embedding each input frame.
@interface APPImageEmbedderResultProcessor : NSObject 

@end

@implementation APPImageEmbedderResultProcessor

-   (void)imageEmbedder:(MPPImageEmbedder *)imageEmbedder
    didFinishEmbeddingWithResult:(MPPImageEmbedderResult *)imageEmbedderResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the image embedder result or errors here.

}

@end

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

MPPImageEmbedderOptions *options = [[MPPImageEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.quantize = YES;
options.l2Normalize = YES;

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

MPPImageEmbedder *imageEmbedder =
  [[MPPImageEmbedder alloc] initWithOptions:options error:nil];
    

Opsi konfigurasi

Tugas ini memiliki opsi konfigurasi berikut untuk aplikasi iOS:

Jika mode berjalan disetel ke livestream, Image Embedder memerlukan opsi konfigurasi imageEmbedderLiveStreamDelegate tambahan, yang memungkinkan Image Embedder memberikan hasil penyematan gambar secara asinkron. Delegasi harus menerapkan metode imageEmbedder(_:didFinishEmbedding:timestampInMilliseconds:error:), yang dipanggil Image Embedder setelah memproses hasil penyematan setiap bingkai gambar input.

Menyiapkan data

Anda perlu mengonversi gambar atau frame input menjadi objek MPImage sebelum meneruskannya ke Penyematan Gambar. 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 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. Penyematan Gambar 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 membuat 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 Image Embedder dalam mode gambar yang berjalan.

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

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

• Gambar diam: embed(image:)
• Video: embed(videoFrame:timestampInMilliseconds:)
• Livestream: embedAsync(image:timestampInMilliseconds:)

Contoh kode berikut menunjukkan contoh dasar cara menjalankan Image Embedder dalam berbagai mode lari ini:

Swift

let result = try imageEmbedder.embed(image: image)
    

let result = try imageEmbedder.embed(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try imageEmbedder.embedAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

MPPImageEmbedderResult *result =
  [imageEmbedder embedImage:image error:nil];
    

MPPImageEmbedderResult *result =
  [imageEmbedder embedVideoFrame:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

BOOL success =
  [imageEmbedder embedAsyncImage:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

Contoh kode Penyematan Gambar menunjukkan implementasi setiap mode ini secara lebih mendetail embed(image:), embed(videoFrame:timestampInMilliseconds:), dan embedAsync(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 livestream, Anda juga harus memberikan stempel waktu frame input ke tugas Image Embedder.

• Saat berjalan dalam mode gambar atau video, tugas Penyematan Gambar 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. Jika aplikasi dibuat menggunakan Swift, Anda juga dapat menggunakan Swift Concurrency untuk eksekusi thread latar belakang.

• Saat berjalan dalam mode live stream, tugas Image Embedder akan segera ditampilkan dan tidak memblokir thread saat ini. Fungsi ini memanggil metode imageEmbedder(_:didFinishEmbedding:timestampInMilliseconds:error:) dengan hasilnya, setelah menyematkan setiap frame input. Penyematan Gambar 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 embedAsync dipanggil saat tugas Image Embedder sibuk memproses frame lain, Image Embedder akan mengabaikan frame input baru.

Menangani dan menampilkan hasil

Setelah menjalankan inferensi, Image Embedder menampilkan objek ImageEmbedderResult yang berisi daftar penyematan (floating point atau kuantisasi skalar) untuk gambar input.

Berikut ini contoh data output dari tugas ini:

ImageEmbedderResult:
  Embedding #0 (sole embedding head):
    float_embedding: {0.0, 0.0, ..., 0.0, 1.0, 0.0, 0.0, 2.0}
    head_index: 0

Hasil ini diperoleh dengan menyematkan gambar berikut:

Anda dapat membandingkan kemiripan dua penyematan menggunakan fungsi ImageEmbedder.cosineSimilarity.

let similarity = try ImageEmbedder.cosineSimilarity(
  embedding1: result.embeddingResult.embeddings[0],
  embedding2: otherResult.embeddingResult.embeddings[0])
    

NSNumber *similarity = [MPPImageEmbedder
      cosineSimilarityBetweenEmbedding1:result.embeddingResult.embeddings[0]
                          andEmbedding2:otherResult.embeddingResult.embeddings[0]
                                  error:nil];