دليل "التعرّف على مَعلَمات الوجه" لنظام التشغيل iOS

تتيح لك مهمة "وضع علامات على الوجه" في MediaPipe رصد معالم الوجه والشدائد الوجهية في الصور والفيديوهات. يمكنك استخدام هذه المهمة لتحديد تعابير الوجه البشرية وتطبيق فلاتر وتأثيرات الوجه وإنشاء صور رمزية افتراضية. تستخدِم هذه ال tâche نماذج تعلُّم الآلة التي يمكنها العمل مع صور أو فيديوهات مفردة أو بث مستمر للصور. تُخرج المهمة معالم الوجه الثلاثية الأبعاد، ونتائج أشكال المزج (المعاملات التي تمثّل تعابير الوجه) لاستنتاج السطوح التفصيلية للوجه في الوقت الفعلي، ومصفوفات التحويل لتنفيذ عمليات التحويل المطلوبة لعرض التأثيرات.

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

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

مثال رمز مهام MediaPipe هو تطبيق أساسي لتحديد معالم الوجه لنظام التشغيل 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/face_landmarker/ios
   

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

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

تحتوي الملفات التالية على الرمز البرمجي المهم لمثال تطبيق "مُحدِّد معالم الوجه":

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

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

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

التبعيات

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

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

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

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

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

الطراز

تتطلب مهمة MediaPipe Face Designerer حزمة نموذج مدرّبة ومتوافقة مع هذه المهمة. لمزيد من المعلومات حول النماذج المتعلّمة المتوفّرة لميزة "تحديد معالم الوجه"، اطّلِع على قسم نماذج ضمن النظرة العامة على المهمة.

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

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

إنشاء المهمة

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

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

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

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

Swift

import MediaPipeTasksVision

let modelPath = Bundle.main.path(
  forResource: "face_landmarker",
  ofType: "task")

let options = FaceLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.minFaceDetectionConfidence = minFaceDetectionConfidence
options.minFacePresenceConfidence = minFacePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numFaces = numFaces

let faceLandmarker = try FaceLandmarker(options: options)
    

import MediaPipeTasksVision

let modelPath = Bundle.main.path(
  forResource: "face_landmarker",
  ofType: "task")

let options = FaceLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.minFaceDetectionConfidence = minFaceDetectionConfidence
options.minFacePresenceConfidence = minFacePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numFaces = numFaces

let faceLandmarker = try FaceLandmarker(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `FaceLandmarkerLiveStreamDelegate` protocol and
// implements the method that the face landmarker calls once it finishes
// performing face landmark detection in each input frame.
class FaceLandmarkerResultProcessor: NSObject, FaceLandmarkerLiveStreamDelegate {

  func faceLandmarker(
    _ faceLandmarker: FaceLandmarker,
    didFinishDetection result: FaceLandmarkerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the face landmarker result or errors here.

  }
}

let modelPath = Bundle.main.path(
  forResource: "face_landmarker",
  ofType: "task")

let options = FaceLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.minFaceDetectionConfidence = minFaceDetectionConfidence
options.minFacePresenceConfidence = minFacePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numFaces = numFaces

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

let faceLandmarker = try FaceLandmarker(options: options)
    

Objective-C

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"face_landmarker"
                                                      ofType:@"task"];

MPPFaceLandmarkerOptions *options = [[MPPFaceLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.minFaceDetectionConfidence = minFaceDetectionConfidence;
options.minFacePresenceConfidence = minFacePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numFaces = numFaces;

MPPFaceLandmarker *faceLandmarker =
  [[MPPFaceLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"face_landmarker"
                                                      ofType:@"task"];

MPPFaceLandmarkerOptions *options = [[MPPFaceLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.minFaceDetectionConfidence = minFaceDetectionConfidence;
options.minFacePresenceConfidence = minFacePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numFaces = numFaces;

MPPFaceLandmarker *faceLandmarker =
  [[MPPFaceLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPFaceLandmarkerLiveStreamDelegate` protocol
// and implements the method that the face landmarker calls once it finishes
// performing face landmark detection in each input frame.
@interface APPFaceLandmarkerResultProcessor : NSObject 

@end

@implementation APPFaceLandmarkerResultProcessor

-   (void)faceLandmarker:(MPPFaceLandmarker *)faceLandmarker
    didFinishDetectionWithResult:(MPPFaceLandmarkerResult *)faceLandmarkerResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the face landmarker result or errors here.

}

@end

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"face_landmarker"
                                                      ofType:@"task"];

MPPFaceLandmarkerOptions *options = [[MPPFaceLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.minFaceDetectionConfidence = minFaceDetectionConfidence;
options.minFacePresenceConfidence = minFacePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numFaces = numFaces;

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

MPPFaceLandmarker *faceLandmarker =
  [[MPPFaceLandmarker alloc] initWithOptions:options error:nil];
    

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

خيارات الضبط

تتضمّن هذه المهمة خيارات الضبط التالية لتطبيقات iOS:

عند ضبط وضع التشغيل على LIVE_STREAM، يتطلب "أداة وضع علامات على الوجه" استخدام خيار الضبط faceLandmarkerLiveStreamDelegate الإضافي، والذي يتيح لأداة وضع علامات على الوجه تقديم نتائج رصد معالم الوجه بدون التزامن. يجب أن ينفِّذ المفوَّض الأسلوب faceLandmarker(_:didFinishDetection:timestampInMilliseconds:error:)، الذي يستدعيه Face Landmarker بعد معالجة نتائج تنفيذ رصد معالم الوجه في كل إطار.

إعداد البيانات

يجب تحويل الصورة أو الإطار الذي تم إدخاله إلى عنصر 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 لمعالجتها قبل إرسالها إلى Face Landmarker في وضع البث المباشر.

// 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 .

تنفيذ المهمة

لتشغيل Face Landmarker، استخدِم طريقة detect() الخاصة بالوضع المخصّص للعمل:

• صورة ثابتة: detect(image:)
• الفيديو: detect(videoFrame:timestampInMilliseconds:)
• بث مباشر: detectAsync(image:timestampInMilliseconds:)

تعرض نماذج التعليمات البرمجية التالية أمثلة أساسية حول كيفية تشغيل "أداة التعرّف على الوجه" في أوضاع التشغيل المختلفة هذه:

Swift

let result = try faceLandmarker.detect(image: image)
    

let result = try faceLandmarker.detect(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try faceLandmarker.detectAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

MPPFaceLandmarkerResult *result =
  [faceLandmarker detectImage:image error:nil];
    

MPPFaceLandmarkerResult *result =
  [faceLandmarker detectVideoFrame:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

BOOL success =
  [faceLandmarker detectAsyncImage:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

يعرض مثال رمز "مُحدِّد معالم الوجه" عمليات تنفيذ كلٍّ من هذه الأوضاع بمزيد من التفصيل detect(image:) وdetect(videoFrame:timestampInMilliseconds:) وdetectAsync(image:timestampInMilliseconds:). يسمح رمز المثال للمستخدم بالتبديل بين أوضاع المعالجة التي قد لا تكون مطلوبة في حالة الاستخدام.

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

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

• عند التشغيل في وضع الصورة أو الفيديو، تحظر مهمة "مُحدِّد معالم الوجه" السلسلة الجارية إلى أن تنتهي من معالجة الصورة أو الإطار المُدخل. لتجنُّب حظر سلسلة المحادثات الحالية، نفِّذ المعالجة في سلسلة محادثات خلفية باستخدام إطارَي عمل iOS Dispatch أو NSOperation. إذا تم إنشاء تطبيقك باستخدام Swift، يمكنك أيضًا استخدام Swift Concurrency لتشغيل مؤشر التسلسل في الخلفية.

• عند التشغيل في وضع البث المباشر، تُعرض مهمة "مُحدِّد معالم الوجه" على الفور ولا تحظر سلسلة المحادثات الحالية. ويُستخدَم الأسلوب faceLandmarker(_:didFinishDetection:timestampInMilliseconds:error:) مع نتيجة رصد معالم الوجه بعد معالجة كل لقطة إدخال. يستدعي Face Landmarker هذه الطريقة بشكل غير متزامن في قائمة انتظار إرسال تسلسلي مخصّصة. لعرض النتائج على واجهة المستخدم، أرسِل النتائج إلى "القائمة الرئيسية" بعد معالجة النتائج.

معالجة النتائج وعرضها

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

في ما يلي مثال على بيانات الإخراج من هذه المهمة:

FaceLandmarkerResult:
  face_landmarks:
    NormalizedLandmark #0:
      x: 0.5971359014511108
      y: 0.485361784696579
      z: -0.038440968841314316
    NormalizedLandmark #1:
      x: 0.3302789330482483
      y: 0.29289937019348145
      z: -0.09489090740680695
    ... (478 landmarks for each face)
  face_blendshapes:
    browDownLeft: 0.8296722769737244
    browDownRight: 0.8096957206726074
    browInnerUp: 0.00035583582939580083
    browOuterUpLeft: 0.00035752105759456754
    ... (52 blendshapes for each face)
  facial_transformation_matrixes:
    [9.99158978e-01, -1.23036895e-02, 3.91213447e-02, -3.70770246e-01]
    [1.66496094e-02,  9.93480563e-01, -1.12779640e-01, 2.27719707e+01]
    ...

تُظهر الصورة التالية تصورًا لنتج المهمة:

يوضّح مثال رمز Face Landmarker كيفية عرض النتائج التي تعرضها الخطوة، اطّلِع على FaceOverlay.swift للحصول على مزيد من التفاصيل.