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

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

يتوفّر نموذج الرمز البرمجي الموضّح في هذه التعليمات على 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/face_landmarker/ios
   

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

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

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

• ‫FaceLandmarkerService.swift: تُستخدَم هذه الوظيفة لإعداد ميزة "وضع علامات على الوجه" ومعالجة اختيار النموذج وتنفيذ عملية الاستنتاج على بيانات الإدخال.
• ‫CameraViewController.swift: ينفِّذ واجهة المستخدم لوضع إدخال خلاصة الكاميرا المباشرة ويعرض visually النتائج.
• ‫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 Landmarker حِزمة نموذج مدرَّب متوافقة مع هذه المهمة. لمزيد من المعلومات حول النماذج المتعلّمة المتوفّرة لميزة "تحديد معالم الوجه"، اطّلِع على قسم نماذج ضمن النظرة العامة على المهمة.

اختَر نموذجًا ونزِّله وأضِفه إلى دليل مشروعك باستخدام 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];
    

يعرض مثال رمز Face Landmarker عمليات تنفيذ كلٍّ من هذه الأوضاع بمزيد من التفصيل 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 للحصول على مزيد من التفاصيل.