دليل التعرّف على الإيماءات لنظام التشغيل iOS

تتيح لك مهمة MediaPipe Gesture Recognizer (معرّف إيماءات MediaPipe) التعرّف على إيماءات اليد في الوقت الفعلي، وprovides the recognized hand gesture results and hand landmarks of the detected hands (توفّر نتائج إيماءات اليد التي تم التعرّف عليها ومواقع اليد المميّزة لليدين التي تم رصدها). توضِّح لك هذه التعليمات كيفية استخدام معرّف الإيماءات مع تطبيقات iOS.

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

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

مثال التعليمات البرمجية لـ 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/gesture_recognizer/ios/
   

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

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

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

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

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

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

التبعيات

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

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

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

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

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

الطراز

تتطلّب مهمة MediaPipe Gesture Recognizer (أداة التعرّف على الإيماءات من MediaPipe) استخدام نموذج مدرَّب متوافق مع هذه المهمة. لمزيد من المعلومات عن النماذج المدربة المتاحة لميزة "التعرّف على الإيماءات"، اطّلِع على قسم نماذج ضمن النظرة العامة على المهمة.

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

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

إنشاء المهمة

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

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

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

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

Swift

import MediaPipeTasksVision

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

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let gestureRecognizer = try GestureRecognizer(options: options)
    

import MediaPipeTasksVision

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

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let gestureRecognizer = try GestureRecognizer(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `GestureRecognizerLiveStreamDelegate` protocol and
// implements the method that the gesture recognizer calls once it finishes
// performing recognizing hand gestures in each input frame.
class GestureRecognizerResultProcessor: NSObject, GestureRecognizerLiveStreamDelegate {

  func gestureRecognizer(
    _ gestureRecognizer: GestureRecognizer,
    didFinishRecognition result: GestureRecognizerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the gesture recognizer result or errors here.

  }
}

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

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

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

let gestureRecognizer = try GestureRecognizer(options: options)
    

Objective-C

@import MediaPipeTasksVision;

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

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

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

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPGestureRecognizerLiveStreamDelegate` protocol
// and implements the method that the gesture recognizer calls once it finishes
// performing gesture recognition on each input frame.

@interface APPGestureRecognizerResultProcessor : NSObject 

@end

@implementation APPGestureRecognizerResultProcessor

-   (void)gestureRecognizer:(MPPGestureRecognizer *)gestureRecognizer
    didFinishRecognitionWithResult:(MPPGestureRecognizerResult *)gestureRecognizerResult
           timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                             error:(NSError *)error {

    // Process the gesture recognizer result or errors here.

}

@end

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

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

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

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

خيارات الضبط

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

عند ضبط وضع التشغيل على "البث المباشر"، يتطلب "معرّف الإيماءات" استخدام خيار الضبط gestureRecognizerLiveStreamDelegate الإضافي، والذي بدوره يمكّن "معرّف الإيماءات" من تقديم نتائج التعرّف على الإيماءات بشكل غير متزامن. يجب أن ينفذ المفوَّض الطريقة gestureRecognizer(_:didFinishRecognition: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.

تنفيذ المهمة

لتشغيل معرّف الإيماءات، استخدِم طريقة recognize() الخاصة بالوضع الذي تم تحديده:

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

تعرض عيّنات الرموز البرمجية التالية أمثلة أساسية على كيفية تشغيل "معرّف الإيماءات" في أوضاع التشغيل المختلفة التالية:

Swift

let result = try gestureRecognizer.recognize(image: image)
    

let result = try gestureRecognizer.recognize(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try gestureRecognizer.recognizeAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

  MPPGestureRecognizerResult *result =
    [gestureRecognizer recognizeImage:mppImage
                                error:nil];
    

MPPGestureRecognizerResult *result =
  [gestureRecognizer recognizeVideoFrame:image
                 timestampInMilliseconds:timestamp
                                   error:nil];
    

BOOL success =
  [gestureRecognizer recognizeAsyncImage:image
                 timestampInMilliseconds:timestamp
                                   error:nil];
    

يسمح مثال الرمز المبرمَج للمستخدم بالتبديل بين أوضاع المعالجة التي قد لا تكون مطلوبة في حالة الاستخدام.

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

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

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

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

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

عند تنفيذ الاستنتاج، تُرجع مهمة "التعرّف على الإيماءات" GestureRecognizerResult يحتوي على معالِم اليد في إحداثيات الصورة، ومعالم اليد في إحداثيات العالم، واتجاه اليد(اليد اليسرى/اليمنى)، وفئات إيماءات اليد لليدين التي تم رصدها.

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

يحتوي GestureRecognizerResult الناتج على أربعة مكوّنات، وكل مكوّن هو صفيف، حيث يحتوي كل عنصر على النتيجة التي تم رصدها ليد واحدة تم رصدها.

• استخدام إحدى اليدين

  يشير مقياس اليد المفضّلة إلى ما إذا كانت الأيدي التي تم رصدها هي اليد اليمنى أو اليسرى.

• الإيماءات

  فئات الإيماءات التي تم التعرّف عليها لليدين التي تم رصدها

• معالم

  هناك 21 معلمًا يخصّ اليد، ويتكون كلّ منها من إحداثيات x وy وz. يتم توحيد إحداثيات x وy لتكون [0.0, 1.0] حسب عرض الصورة وارتفاعها على التوالي. يمثّل الإحداثي z عمق المَعلم، مع كون العميق عند الرسغ هو الأصل. وكلما كانت القيمة أصغر، كان المَعلم أقرب إلى الكاميرا. يستخدم حجم z المقياس نفسه تقريبًا الذي يستخدمه x.

• معالم عالمية

  يتم أيضًا عرض 21 معلمًا يدويًا بالإحداثيات العالمية. يتألّف كل معلم من x وy وz، وهي تمثل إحداثيات ثلاثية الأبعاد في العالم الحقيقي بال مترات مع منشأ في المركز الهندسي لليد.

GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : -3.41E-7
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
    ... (21 landmarks for a hand)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
    ... (21 world landmarks for a hand)

تعرض الصور التالية عرضًا مرئيًا لمخرجات المهمة: