คำแนะนำในการฝังรูปภาพสำหรับ iOS

งานโปรแกรมฝังรูปภาพ MediaPipe ช่วยให้คุณแปลงข้อมูลรูปภาพเป็นการแสดงผลตัวเลขเพื่อทำงานการประมวลผลรูปภาพที่เกี่ยวข้องกับ ML ให้เสร็จสมบูรณ์ เช่น การเปรียบเทียบความคล้ายคลึงของรูปภาพ 2 รูป

ตัวอย่างโค้ดที่อธิบายในวิธีการเหล่านี้มีอยู่ใน GitHub คุณสามารถดูการทํางานของงานนี้ได้โดยดูการสาธิตบนเว็บนี้ ดูข้อมูลเพิ่มเติมเกี่ยวกับความสามารถ รูปแบบ และตัวเลือกการกําหนดค่าของงานนี้ได้ที่ภาพรวม

ตัวอย่างโค้ด

โค้ดตัวอย่างของ MediaPipe Tasks คือการใช้งานพื้นฐานของแอปฝังรูปภาพสำหรับ iOS ตัวอย่างนี้ใช้กล้องในอุปกรณ์ iOS จริงเพื่อฝังรูปภาพอย่างต่อเนื่อง และยังสามารถเรียกใช้โปรแกรมฝังในไฟล์รูปภาพจากแกลเลอรีของอุปกรณ์ได้ด้วย

คุณสามารถใช้แอปเป็นจุดเริ่มต้นสำหรับแอป iOS ของคุณเอง หรือใช้อ้างอิงเมื่อแก้ไขแอปที่มีอยู่ โค้ดตัวอย่างเครื่องมือฝังรูปภาพจะโฮสต์อยู่ใน GitHub

ดาวน์โหลดรหัส

วิธีการต่อไปนี้แสดงวิธีสร้างสำเนาโค้ดตัวอย่างในเครื่องโดยใช้เครื่องมือบรรทัดคำสั่ง git

วิธีดาวน์โหลดโค้ดตัวอย่าง

1. โคลนที่เก็บ Git โดยใช้คําสั่งต่อไปนี้

   git clone https://github.com/google-ai-edge/mediapipe-samples
   

2. คุณสามารถเลือกกำหนดค่าอินสแตนซ์ git ให้ใช้การชำระเงินแบบกระจัดกระจายเพื่อให้มีเพียงไฟล์สำหรับแอปตัวอย่างเครื่องมือฝังรูปภาพเท่านั้น

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

หลังจากสร้างโค้ดตัวอย่างเวอร์ชันในเครื่องแล้ว คุณสามารถติดตั้งไลบรารีงาน MediaPipe, เปิดโปรเจ็กต์โดยใช้ Xcode และเรียกใช้แอปได้ ดูวิธีการได้ที่คู่มือการตั้งค่าสำหรับ iOS

คอมโพเนนต์หลัก

ไฟล์ต่อไปนี้มีโค้ดสําคัญสําหรับตัวอย่างแอปพลิเคชันโปรแกรมฝังรูปภาพ

• ImageEmbedderService.swift: เริ่มต้นเครื่องมือฝังรูปภาพ จัดการการเลือกโมเดล และเรียกใช้การอนุมานเกี่ยวกับข้อมูลอินพุต
• CameraViewController.swift: ใช้ UI สําหรับโหมดอินพุตฟีดกล้องสดและแสดงผลลัพธ์เป็นภาพ
• MediaLibraryViewController.swift: ใช้ UI สำหรับโหมดการป้อนรูปภาพนิ่งและแสดงผลลัพธ์เป็นภาพ

ตั้งค่า

ส่วนนี้จะอธิบายขั้นตอนสำคัญในการตั้งค่าสภาพแวดล้อมการพัฒนาและโปรเจ็กต์โค้ดเพื่อใช้เครื่องมือฝังรูปภาพ ดูข้อมูลทั่วไปเกี่ยวกับการตั้งค่าสภาพแวดล้อมการพัฒนาเพื่อใช้งาน MediaPipe รวมถึงข้อกำหนดเวอร์ชันแพลตฟอร์มได้ที่คู่มือการตั้งค่าสำหรับ iOS

การอ้างอิง

เครื่องมือฝังรูปภาพใช้ไลบรารี MediaPipeTasksVision ซึ่งต้องติดตั้งโดยใช้ CocoaPods ไลบรารีนี้ใช้ได้กับทั้งแอป Swift และ Objective-C และไม่จำเป็นต้องมีการตั้งค่าเพิ่มเติมสำหรับภาษาใดภาษาหนึ่ง

โปรดดูวิธีติดตั้ง CocoaPods ใน macOS ที่คู่มือการติดตั้ง CocoaPods ดูวิธีการสร้าง Podfile ที่มีพ็อดที่จำเป็นสำหรับแอปได้ที่การใช้ CocoaPods

เพิ่มพ็อด MediaPipeTasksVision ใน Podfile โดยใช้โค้ดต่อไปนี้

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

หากแอปมีเป้าหมายการทดสอบ 1 หน่วย โปรดดูข้อมูลการตั้งค่า Podfile เพิ่มเติมในคู่มือการตั้งค่าสำหรับ iOS

รุ่น

งานเครื่องมือฝังรูปภาพ MediaPipe ต้องใช้โมเดลที่ผ่านการฝึกและใช้งานได้กับงานนี้ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับโมเดลที่ผ่านการฝึกที่ใช้ได้สำหรับเครื่องมือฝังรูปภาพ โปรดดูส่วนโมเดล

เลือกและดาวน์โหลดโมเดล แล้วเพิ่มลงในไดเรกทอรีโปรเจ็กต์โดยใช้ Xcode ดูวิธีการเพิ่มไฟล์ลงในโปรเจ็กต์ Xcode ได้ที่การจัดการไฟล์และโฟลเดอร์ในโปรเจ็กต์ Xcode

ใช้พร็อพเพอร์ตี้ BaseOptions.modelAssetPath เพื่อระบุเส้นทางไปยังโมเดลใน App Bundle ของคุณ

สร้างงาน

คุณสร้างงานโปรแกรมฝังรูปภาพได้โดยเรียกตัวเริ่มต้นรายการใดรายการหนึ่ง ตัวเริ่มต้น ImageEmbedder(options:) จะยอมรับค่าสําหรับตัวเลือกการกําหนดค่า

หากไม่ต้องการให้เครื่องมือฝังรูปภาพเริ่มต้นทำงานด้วยตัวเลือกการกำหนดค่าที่กำหนดเอง ให้ใช้เครื่องมือเริ่มต้น ImageEmbedder(modelPath:) เพื่อสร้างเครื่องมือฝังรูปภาพโดยใช้ตัวเลือกเริ่มต้น ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวเลือกการกำหนดค่าได้ที่ภาพรวมการกําหนดค่า

งานเครื่องมือฝังรูปภาพรองรับอินพุต 3 ประเภท ได้แก่ ภาพนิ่ง ไฟล์วิดีโอ และสตรีมวิดีโอสด โดยค่าเริ่มต้น ImageEmbedder(modelPath:) จะเริ่มต้นงานสำหรับภาพนิ่ง หากต้องการให้เริ่มต้นงานเพื่อประมวลผลไฟล์วิดีโอหรือสตรีมวิดีโอสด ให้ใช้ ImageEmbedder(options:) เพื่อระบุโหมดการทำงานของวิดีโอหรือสตรีมแบบสด โหมดสตรีมแบบสดยังต้องใช้ตัวเลือกการกำหนดค่าimageEmbedderLiveStreamDelegateเพิ่มเติม ซึ่งช่วยให้โปรแกรมฝังรูปภาพส่งผลลัพธ์การฝังรูปภาพไปยังผู้รับมอบสิทธิ์แบบไม่พร้อมกันได้

เลือกแท็บที่สอดคล้องกับโหมดการทํางานเพื่อดูวิธีสร้างงานและเรียกใช้การอนุมาน

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];
    

ตัวเลือกการกำหนดค่า

งานนี้มีตัวเลือกการกำหนดค่าต่อไปนี้สำหรับแอป iOS

เมื่อตั้งค่าโหมดการทํางานเป็น "สตรีมแบบสด" ตัวฝังรูปภาพจะต้องมีตัวเลือกการกําหนดค่า imageEmbedderLiveStreamDelegate เพิ่มเติม ซึ่งจะช่วยให้ตัวฝังรูปภาพแสดงผลลัพธ์การฝังรูปภาพแบบไม่พร้อมกันได้ ตัวแทนต้องใช้งานเมธอด imageEmbedder(_:didFinishEmbedding:timestampInMilliseconds:error:) ซึ่งโปรแกรมฝังรูปภาพจะเรียกใช้หลังจากประมวลผลผลลัพธ์ของการฝังเฟรมรูปภาพอินพุตแต่ละเฟรม

เตรียมข้อมูล

คุณต้องแปลงรูปภาพหรือเฟรมอินพุตเป็นวัตถุ MPImage ก่อนที่จะส่งต่อไปยังเครื่องมือฝังรูปภาพ MPImage รองรับรูปแบบรูปภาพ iOS ประเภทต่างๆ และใช้รูปภาพเหล่านั้นในโหมดการทํางานใดก็ได้สําหรับการอนุมาน ดูข้อมูลเพิ่มเติมเกี่ยวกับ MPImage ได้ที่ MPImage API

เลือกรูปแบบรูปภาพ iOS ตาม Use Case และโหมดการทํางานของแอปพลิเคชันMPImageยอมรับรูปแบบรูปภาพ iOS UIImage, CVPixelBuffer และ CMSampleBuffer

UIImage

รูปแบบ UIImage เหมาะสําหรับโหมดการทํางานต่อไปนี้

• รูปภาพ: รูปภาพจาก App Bundle, แกลเลอรีของผู้ใช้ หรือระบบไฟล์ที่จัดรูปแบบเป็นรูปภาพ UIImage สามารถแปลงเป็นออบเจ็กต์ MPImage ได้

• วิดีโอ: ใช้ AVAssetImageGenerator เพื่อดึงข้อมูลเฟรมวิดีโอเป็นรูปแบบ CGImage แล้วแปลงเป็นรูปภาพ 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];
    

ตัวอย่างนี้จะเริ่มต้น MPImage ด้วยการวางแนวเริ่มต้น UIImage.Orientation.Up คุณสามารถเริ่มต้น MPImage ด้วยค่า UIImage.Orientation ที่รองรับค่าใดก็ได้ เครื่องมือฝังรูปภาพไม่รองรับการวางแนวแบบมิเรอร์ เช่น .upMirrored, .downMirrored, .leftMirrored, .rightMirrored

ดูข้อมูลเพิ่มเติมเกี่ยวกับ UIImage ได้ที่เอกสารสำหรับนักพัฒนาซอฟต์แวร์ Apple ด้าน UIImage

CVPixelBuffer

รูปแบบ CVPixelBuffer เหมาะสําหรับแอปพลิเคชันที่สร้างเฟรมและใช้เฟรมเวิร์ก CoreImage ของ iOS ในการประมวลผล

รูปแบบ CVPixelBuffer เหมาะสําหรับโหมดการทํางานต่อไปนี้

• รูปภาพ: แอปที่สร้างรูปภาพ CVPixelBuffer หลังจากการประมวลผลบางอย่างโดยใช้เฟรมเวิร์ก CoreImage ของ iOS สามารถส่งไปยังเครื่องมือฝังรูปภาพในโหมดการเรียกใช้รูปภาพ

• วิดีโอ: เฟรมวิดีโอแปลงเป็นรูปแบบ CVPixelBuffer เพื่อประมวลผลได้ แล้วส่งไปยังเครื่องมือฝังรูปภาพในโหมดวิดีโอ

• สตรีมแบบสด: แอปที่ใช้กล้อง iOS เพื่อสร้างเฟรมอาจได้รับการแปลงเป็นรูปแบบ CVPixelBuffer เพื่อประมวลผลก่อนที่จะส่งไปยังโปรแกรมฝังรูปภาพในโหมดสตรีมแบบสด

// 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];
    

ดูข้อมูลเพิ่มเติมเกี่ยวกับ CVPixelBuffer ได้ที่เอกสารประกอบสำหรับนักพัฒนาแอป CVPixelBuffer ของ Apple

CMSampleBuffer

รูปแบบ CMSampleBuffer จะจัดเก็บตัวอย่างสื่อของประเภทสื่อแบบเดียวกัน และเหมาะอย่างยิ่งสำหรับโหมดการทํางานของสตรีมแบบสด เฟรมสดจากกล้อง iOS จะส่งแบบไม่พร้อมกันในรูปแบบ CMSampleBuffer โดย iOSAVCaptureVideoDataOutput

// 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];
    

ดูข้อมูลเพิ่มเติมเกี่ยวกับ CMSampleBuffer ได้ที่เอกสารประกอบสำหรับนักพัฒนาแอปของ Apple เกี่ยวกับ CMSampleBuffer

เรียกใช้งาน

หากต้องการเรียกใช้เครื่องมือฝังรูปภาพ ให้ใช้เมธอด embed() สำหรับโหมดการทำงานที่กำหนดไว้โดยเฉพาะ ดังนี้

• ภาพนิ่ง: embed(image:)
• วิดีโอ: embed(videoFrame:timestampInMilliseconds:)
• สตรีมสด: embedAsync(image:timestampInMilliseconds:)

ตัวอย่างโค้ดต่อไปนี้แสดงตัวอย่างพื้นฐานของวิธีเรียกใช้เครื่องมือฝังรูปภาพในโหมดการทํางานต่างๆ ต่อไปนี้

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];
    

ตัวอย่างโค้ดของเครื่องมือฝังรูปภาพแสดงการใช้งานโหมดแต่ละโหมดเหล่านี้โดยละเอียด embed(image:), embed(videoFrame:timestampInMilliseconds:) และ embedAsync(image:timestampInMilliseconds:) โค้ดตัวอย่างช่วยให้ผู้ใช้สลับโหมดการประมวลผลซึ่งอาจไม่จำเป็นสำหรับกรณีการใช้งานของคุณ

โปรดทราบดังต่อไปนี้

• เมื่อทำงานในโหมดวิดีโอหรือโหมดสตรีมแบบสด คุณต้องระบุการประทับเวลาของเฟรมอินพุตให้กับงานโปรแกรมฝังรูปภาพด้วย

• เมื่อทำงานในโหมดรูปภาพหรือวิดีโอ งานโปรแกรมฝังรูปภาพจะบล็อกเธรดปัจจุบันจนกว่าจะประมวลผลรูปภาพหรือเฟรมอินพุตเสร็จ หากต้องการหลีกเลี่ยงการบล็อกเธรดปัจจุบัน ให้ดำเนินการประมวลผลในเธรดเบื้องหลังโดยใช้เฟรมเวิร์ก Dispatch หรือ NSOperation ของ iOS หากแอปสร้างขึ้นโดยใช้ Swift คุณจะใช้ Swift Concurrency สำหรับการเรียกใช้เธรดเบื้องหลังได้ด้วย

• เมื่อทำงานในโหมดสตรีมแบบสด งานโปรแกรมฝังรูปภาพจะแสดงผลทันทีและไม่บล็อกเธรดปัจจุบัน โดยจะเรียกใช้วิธี imageEmbedder(_:didFinishEmbedding:timestampInMilliseconds:error:) ด้วยผลลัพธ์หลังจากฝังเฟรมอินพุตแต่ละเฟรม ตัวฝังรูปภาพจะเรียกใช้เมธอดนี้แบบไม่พร้อมกันในคิวการจัดเตรียมแบบอนุกรมเฉพาะ สําหรับการแสดงผลลัพธ์ในอินเทอร์เฟซผู้ใช้ ให้ส่งผลลัพธ์ไปยังคิวหลักหลังจากประมวลผลผลลัพธ์แล้ว หากมีการเรียกใช้ฟังก์ชัน embedAsync เมื่องานของเครื่องมือฝังรูปภาพกำลังประมวลผลเฟรมอื่นอยู่ เครื่องมือฝังรูปภาพจะไม่สนใจเฟรมอินพุตใหม่

จัดการและแสดงผลลัพธ์

เมื่อทำการอนุมาน โปรแกรมฝังรูปภาพจะแสดงผลImageEmbedderResult ออบเจ็กต์ที่มีรายการการฝัง (ทศนิยมหรือเชิงปริมาณ) สำหรับรูปภาพอินพุต

ต่อไปนี้คือตัวอย่างข้อมูลเอาต์พุตจากงานนี้

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

ผลลัพธ์นี้ได้มาจากการฝังรูปภาพต่อไปนี้

คุณสามารถเปรียบเทียบความคล้ายคลึงของข้อมูลเชิงลึก 2 รายการได้โดยใช้ฟังก์ชัน 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];