دليل تضمين الصور لأجهزة iOS

تتيح لك مهمة "إدراج الصور" من MediaPipe تحويل بيانات الصور إلى تمثيل عددي لإنجاز مهام معالجة الصور ذات الصلة بالذكاء الاصطناعي، مثل مقارنة التشابه بين صورتَين.

يتوفّر نموذج الرمز البرمجي الموضّح في هذه التعليمات على GitHub. يمكنك الاطّلاع على هذه المهمة أثناء تنفيذها من خلال مشاهدة هذا العرض التمهيدي لتطبيق الويب. لمزيد من المعلومات عن الإمكانات والنماذج وخيارات الضبط لهذه المهمة، اطّلِع على نظرة عامة.

مثال على الرمز البرمجي

مثال التعليمات البرمجية لـ MediaPipe Tasks هو تنفيذ أساسي لتطبيق "إدراج الصور" لنظام التشغيل iOS. يستخدم المثال الكاميرا على جهاز iOS مادي لدمج الصور باستمرار، ويمكنه أيضًا تشغيل أداة الدمج على ملفات الصور من معرض الجهاز.

يمكنك استخدام التطبيق كنقطة بداية لتطبيقك الخاص على نظام التشغيل iOS، أو الرجوع إليه عند تعديل تطبيق حالي. يتم استضافة رمز مثال أداة "إدراج الصور" على GitHub.

تنزيل الرمز

توضِّح لك التعليمات التالية كيفية إنشاء نسخة محلية من مثال الرمز البرمجي باستخدام أداة سطر الأوامر git.

لتنزيل نموذج الرمز البرمجي:

1. استنسِخ مستودع git باستخدام الأمر التالي:

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

2. يمكنك اختياريًا ضبط مثيل git لاستخدام ميزة "الفحص الخفيف"، بحيث تتوفّر لديك فقط ملفات مثال تطبيق "أداة تضمين الصور":

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

بعد إنشاء نسخة محلية من رمز المثال، يمكنك تثبيت مكتبة مهام MediaPipe وفتح المشروع باستخدام Xcode وتشغيل التطبيق. للاطّلاع على التعليمات، يمكنك الاطّلاع على دليل الإعداد لنظام التشغيل iOS.

المكونات الرئيسية

تحتوي الملفات التالية على الرمز البرمجي المهم لمثال تطبيق "أداة تضمين الصور":

• ‫ImageEmbedderService.swift: تُستخدَم هذه الوظيفة لإعداد أداة "إدراج الصور" ومعالجة اختيار النموذج وتنفيذ استنتاج البيانات التي يتم إدخالها.
• ‫CameraViewController.swift: ينفِّذ واجهة المستخدم لوضع إدخال خلاصة الكاميرا المباشرة ويعرض visually النتائج.
• ‫MediaLibraryViewController.swift: ينفِّذ واجهة المستخدم لوضع إدخال الصور الثابتة ويعرض النتائج بشكل مرئي.

ضبط إعدادات الجهاز

يوضّح هذا القسم الخطوات الرئيسية لإعداد بيئة التطوير و مشاريع الرموز البرمجية لاستخدام أداة "إدراج الصور". للحصول على معلومات عامة عن إعداد بيئة التطوير لاستخدام مهام MediaPipe، بما في ذلك متطلبات إصدار النظام الأساسي، يُرجى الاطّلاع على دليل الإعداد لنظام iOS.

التبعيات

يستخدم "أداة تضمين الصور" مكتبة MediaPipeTasksVision التي يجب تثبيتها باستخدام CocoaPods. تتوافق المكتبة مع تطبيقات Swift وObjective-C ولا تتطلّب أي إعدادات إضافية خاصة باللغة.

للحصول على تعليمات لتثبيت CocoaPods على نظام التشغيل macOS، يُرجى الرجوع إلى دليل تثبيت CocoaPods. للحصول على تعليمات حول كيفية إنشاء Podfile باستخدام الحِزم اللازمة لتطبيقك، يُرجى الاطّلاع على مقالة استخدام CocoaPods.

أضِف مجموعة MediaPipeTasksVision في Podfile باستخدام الرمز التالي:

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

إذا كان تطبيقك يتضمّن أهداف اختبار الوحدات، يمكنك الرجوع إلى دليل الإعداد لنظام التشغيل iOS للحصول على معلومات إضافية عن إعداد Podfile.

الطراز

تتطلّب مهمة "إدراج الصور" في MediaPipe نموذجًا مدرَّبًا متوافقًا مع هذه المهمة. لمزيد من المعلومات عن النماذج المدربة المتاحة لميزة "إدراج الصور"، اطّلِع على قسم "النماذج".

اختَر نموذجًا ونزِّله وأضِفه إلى دليل مشروعك باستخدام Xcode. للحصول على تعليمات حول كيفية إضافة ملفات إلى مشروع Xcode، يُرجى الاطّلاع على مقالة إدارة الملفات والمجلدات في مشروع Xcode.

استخدِم السمة BaseOptions.modelAssetPath لتحديد مسار الوصول إلى النموذج في حِزمة تطبيقك.

إنشاء المهمة

يمكنك إنشاء مهمة "مُضمِّن الصور" من خلال استدعاء أحد مُنشئِيها. يقبل مُنشئ ImageEmbedder(options:) قيمًا لخيارات الضبط.

إذا لم تكن بحاجة إلى أداة "إدراج صور" تم إعدادها باستخدام خيارات إعداد مخصّصة، يمكنك استخدام أداة إعداد ImageEmbedder(modelPath:) لإنشاء أداة "إدراج صور" باستخدام الخيارات التلقائية. لمزيد من المعلومات عن خيارات الإعداد، يُرجى الاطّلاع على نظرة عامة على الإعداد.

تتيح مهمة "إدراج الصور" 3 أنواع من بيانات الإدخال: الصور الثابتة وملفات الفيديو وأحداث البث المباشر للفيديوهات. بشكلٍ تلقائي، يبدأ ImageEmbedder(modelPath:) مهمة للصور الثابتة. إذا كنت تريد بدء مهمتك لمعالجة ملفات الفيديوهات أو أحداث البث المباشر للفيديوهات، استخدِم ImageEmbedder(options:) لتحديد وضع تشغيل الفيديوهات أو البث المباشر. يتطلّب وضع البث المباشر أيضًا خيار الإعداد imageEmbedderLiveStreamDelegate الإضافي، الذي يتيح لتطبيق Image Embedder إرسال نتائج تضمين الصور إلى المفوَّض بشكل غير متزامن.

اختَر علامة التبويب المناسبة لوضع التشغيل لمعرفة كيفية إنشاء المهمة وتنفيذ الاستنتاج.

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 استنادًا إلى حالة الاستخدام ووضع التشغيل الذي يتطلبه تطبيقك.يقبلMPImage تنسيقات صور iOS UIImage وCVPixelBuffer و CMSampleBuffer.

UIImage

تنسيق UIImage مناسب تمامًا لأوضاع التشغيل التالية:

• الصور: يمكن تحويل الصور من حِزمة تطبيق أو معرض مستخدم أو نظام ملفات بتنسيق 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، يُرجى الرجوع إلى مستندات "مطوّرو تطبيقات Apple" المتعلقين بـ CVPixelBuffer.

CMSampleBuffer

يخزّن تنسيق CMSampleBuffer عيّنات وسائط من نوع وسائط موحّد، وهو مناسب لوضع تشغيل البث المباشر. يتم إرسال اللقطات المباشرة من كاميرات iOS بشكل غير متزامن بتنسيق CMSampleBuffer من خلال 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];
    

لمزيد من المعلومات حول CMSampleBuffer، يُرجى الرجوع إلى مستندات مطوّري CMSampleBuffer Apple.

تنفيذ المهمة

لتشغيل أداة "إدراج الصور"، استخدِم طريقة 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:). يسمح مثال الرمز المبرمَج للمستخدم بالتبديل بين أوضاع المعالجة التي قد لا تكون مطلوبة في حالة الاستخدام.

يُرجى ملاحظة ما يلي:

• عند التشغيل في وضع الفيديو أو وضع البث المباشر، يجب أيضًا تقديم الطابع الزمني لإطار الإدخال إلى مهمة "أداة تضمين الصور".

• عند التشغيل في وضع الصورة أو الفيديو، تحظر مهمة "مُضمِّن الصور" المحادثة الحالية إلى أن تنتهي من معالجة الصورة أو الإطار المُدخل. لتجنُّب حظر سلسلة المحادثات الحالية، نفِّذ المعالجة في سلسلة محادثات في الخلفية باستخدام إطارَي عمل iOS Dispatch أو NSOperation. إذا تم إنشاء تطبيقك باستخدام 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

تم الحصول على هذه النتيجة من خلال تضمين الصورة التالية:

يمكنك مقارنة تشابه عنصرَي إدراج باستخدام الدالة 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];