Panduan segmentasi gambar untuk iOS

Tugas Image Segmenter memungkinkan Anda membagi gambar menjadi beberapa area berdasarkan kategori yang telah ditentukan, dan menerapkan efek visual seperti pemburaman latar belakang. Petunjuk ini menunjukkan cara menggunakan Image Segmenter dengan aplikasi iOS.

Contoh kode yang dijelaskan dalam petunjuk ini tersedia di GitHub.

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

Contoh kode Tugas MediaPipe berisi implementasi sederhana aplikasi Image Segmenter untuk iOS.

Contoh ini menerapkan pengelompok gambar yang menghasilkan mask kategori. Fitur ini menggunakan kamera di perangkat iOS fisik untuk melakukan segmentasi gambar pada feed kamera live, atau pada gambar dan video 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 Segmenter 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 Segmenter:

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

Setelah membuat versi lokal kode contoh, Anda dapat menginstal library tugas MediaPipe, buka project menggunakan Xcode, lalu jalankan aplikasi. Untuk mengetahui petunjuknya, lihat Panduan Penyiapan untuk iOS.

Komponen utama

File berikut berisi kode penting untuk aplikasi contoh Image Segmenter:

• ImageSegmenterService.swift: Melakukan inisialisasi Image Segmenter, 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 Image Segmenter. Untuk informasi umum tentang cara menyiapkan lingkungan pengembangan untuk menggunakan tugas MediaPipe, termasuk persyaratan versi platform, lihat Panduan penyiapan untuk iOS.

Dependensi

Image Segmenter 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 mendapatkan petunjuk cara membuat Podfile dengan pod yang diperlukan untuk aplikasi Anda, lihat Menggunakan CocoaPods.

Tambahkan pod MediaPipeTasksVision di Podfile menggunakan kode berikut:

target 'MyImageSegmenterApp' 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 Segmenter memerlukan model terlatih yang kompatibel dengan tugas ini. Untuk mengetahui informasi selengkapnya tentang model terlatih yang tersedia untuk Image Segmenter, lihat ringkasan tugas di bagian Model.

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 Image Segmenter dengan memanggil salah satu penginisialisasinya. Penginisialisasi ImageSegmenter(options:) menerima nilai untuk opsi konfigurasi.

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

Tugas Image Segmenter mendukung 3 jenis data input: gambar diam, file video, dan streaming video live. Secara default, ImageSegmenter(modelPath:) menginisialisasi tugas untuk gambar diam. Jika Anda ingin tugas diinisialisasi untuk memproses file video atau streaming video live, gunakan ImageSegmenter(options:) untuk menentukan mode video atau live stream yang berjalan. Mode livestream juga memerlukan opsi konfigurasi imageSegmenterLiveStreamDelegate tambahan, yang memungkinkan Image Segmenter mengirimkan hasil segmentasi gambar kepada 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 = ImageSegmenterOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.shouldOutputCategoryMask = true
options.shouldOutputConfidenceMasks = false

let imageSegmenter = try ImageSegmenter(options: options)
    

import MediaPipeTasksVision

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

let options = ImageSegmenterOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.shouldOutputCategoryMask = true
options.shouldOutputConfidenceMasks = false

let imageSegmenter = try ImageSegmenter(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `imageSegmenterLiveStreamDelegate` protocol and
// implements the method that the image segmenter calls once it finishes
// performing segmentation of each input frame.
class ImageSegmenterResultProcessor: NSObject, ImageSegmenterLiveStreamDelegate {

  func imageSegmenter(
    _ imageSegmenter: ImageSegmenter,
    didFinishSegmentation result: ImageSegmenterResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the image segmentation result or errors here.

  }
}

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

let options = ImageSegmenterOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.shouldOutputCategoryMask = true
options.shouldOutputConfidenceMasks = false

// Set `imageSegmenterLiveStreamDelegate` to the object of the class that
// confirms to the `ImageSegmenterLiveStreamDelegate` protocol.
let processor = ImageSegmenterResultProcessor()
options.imageSegmenterLiveStreamDelegate = processor

let imageSegmenter = try ImageSegmenter(options: options)
    

Objective-C

@import MediaPipeTasksVision;

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

MPPImageSegmenterOptions *options = [[MPPImageSegmenterOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.shouldOutputCategoryMask = YES;
options.shouldOutputConfidenceMasks = NO;

MPPImageSegmenter *imageSegmenter =
  [[MPPImageSegmenter alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

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

MPPImageSegmenterOptions *options = [[MPPImageSegmenterOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.shouldOutputCategoryMask = YES;
options.shouldOutputConfidenceMasks = NO;

MPPImageSegmenter *imageSegmenter =
  [[MPPImageSegmenter alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPImageSegmenterLiveStreamDelegate` protocol
// and implements the method that the image segmenter calls once it finishes
// performing segmentation of each input frame.

@interface APPImageSegmenterResultProcessor : NSObject 

@end

@implementation APPImageSegmenterResultProcessor

-   (void)imageSegmenter:(MPPImageSegmenter *)imageSegmenter
    didFinishSegmentationWithResult:(MPPImageSegmenterResult *)imageSegmenterResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the image segmentation result or errors here.

}

@end

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

MPPImageSegmenterOptions *options = [[MPPImageSegmenterOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.shouldOutputCategoryMask = YES;
options.shouldOutputConfidenceMasks = NO;

// Set `imageSegmenterLiveStreamDelegate` to the object of the class that
// confirms to the `MPPImageSegmenterLiveStreamDelegate` protocol.
APPImageSegmenterResultProcessor *processor =
  [APPImageSegmenterResultProcessor new];
options.imageSegmenterLiveStreamDelegate = processor;

MPPImageSegmenter *imageSegmenter =
  [[MPPImageSegmenter alloc] initWithOptions:options error:nil];
    

Penerapan kode contoh Segmenter Gambar memungkinkan pengguna beralih antar-mode pemrosesan. Pendekatan ini membuat kode pembuatan tugas menjadi lebih rumit dan mungkin tidak sesuai untuk kasus penggunaan Anda.

Opsi konfigurasi

Tugas ini memiliki opsi konfigurasi berikut untuk aplikasi iOS:

Jika mode berjalan disetel ke LIVE_STREAM, Image Segmenter memerlukan opsi konfigurasi imageSegmenterLiveStreamDelegate tambahan, yang memungkinkan Image Segmenter mengirimkan hasil segmentasi gambar secara asinkron. Delegasi harus mengimplementasikan metode imageSegmenter(_:didFinishSegmentation:timestampInMilliseconds:error:), yang dipanggil Image Segmenter setelah memproses hasil dari melakukan segmentasi pada setiap frame.

Menyiapkan data

Anda perlu mengonversi gambar atau frame input menjadi objek MPImage sebelum meneruskannya ke Image Segmenter. MPImage mendukung berbagai jenis format gambar iOS, dan dapat menggunakannya dalam mode berjalan apa pun untuk inferensi. Untuk informasi selengkapnya tentang MPImage, lihat MPImage API.

Pilih format image iOS berdasarkan kasus penggunaan dan mode yang diperlukan aplikasi Anda.MPImage menerima format image 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. Image Segmenter 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 operasi berikut:

• Gambar: aplikasi yang membuat gambar CVPixelBuffer setelah beberapa pemrosesan menggunakan framework CoreImage iOS dapat dikirim ke Segmentasi Gambar dalam mode gambar yang berjalan.

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

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

• Gambar diam: segment(image:)
• Video: segment(videoFrame:timestampInMilliseconds:)
• Livestream: segmentAsync(image:timestampInMilliseconds:)

Contoh kode berikut menunjukkan contoh sederhana cara menjalankan Image Segmenter dalam berbagai mode operasi ini:

Swift

let result = try imageSegmenter.segment(image: image)
    

let result = try imageSegmenter.segment(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try imageSegmenter.segmentAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

MPPImageSegmenterResult *result =
  [imageSegmenter segmentImage:image error:nil];
    

MPPImageSegmenterResult *result =
  [imageSegmenter segmentVideoFrame:image
            timestampInMilliseconds:timestamp
                              error:nil];
    

BOOL success =
  [imageSegmenter segmentAsyncImage:image
            timestampInMilliseconds:timestamp
                              error:nil];
    

Contoh kode Image Segmenter menunjukkan implementasi setiap mode ini secara lebih mendetail segment(image:), segment(videoFrame:timestampInMilliseconds:), dan segmentAsync(image:timestampInMilliseconds:).

Perhatikan hal berikut:

• Saat berjalan dalam mode video atau mode live stream, Anda juga harus memberikan stempel waktu frame input ke tugas Image Segmenter.

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

Menangani dan menampilkan hasil

Setelah menjalankan inferensi, tugas Image Segmenter akan menampilkan objek ImageSegmenterResult yang berisi hasil tugas segmentasi. Konten output bergantung pada jenis output yang Anda tetapkan saat mengonfigurasi tugas.

Gambar berikut menunjukkan visualisasi output tugas untuk mask nilai kategori. Rentang mask kategori adalah [0, 255] dan setiap nilai piksel mewakili indeks kategori pemenang dari output model. Indeks kategori pemenang memiliki skor tertinggi di antara kategori yang dapat dikenali model.

Output mask kategori dan gambar asli. Gambar sumber dari set data Pascal VOC 2012.

Kode contoh Image Segmenter menunjukkan cara menampilkan hasil Image Segmenter. Lihat contoh kode untuk mengetahui detailnya.