دليل رصد المعالم لنظام التشغيل iOS

تتيح لك مهمة "وضع المَعلمات" رصد معالم أجسام البشر في صورة أو فيديو. يمكنك استخدام هذه المهمة لتحديد مواضع الجسم الرئيسية وتحليل الوضع و تصنيف الحركات. تستخدِم هذه المهمة نماذج تعلُّم الآلة التي تعمل مع الصور أو الفيديوهات الفردية. تُخرج المهمة معالم وضع الجسم في إحداثيات الصورة وفي إحداثيات العالم الثلاثية الأبعاد.

توضّح لك هذه التعليمات كيفية استخدام ميزة "وضع علامات على العناصر في الصورة" مع تطبيقات iOS. يتوفّر نموذج الرمز المبرمَج الموصوف في هذه التعليمات على 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/pose_landmarker/ios/
   

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

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

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

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

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

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

التبعيات

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

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

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

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

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

الطراز

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

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

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

إنشاء المهمة

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

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

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

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

Swift

import MediaPipeTasksVision

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

let options = PoseLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.minPoseDetectionConfidence = minPoseDetectionConfidence
options.minPosePresenceConfidence = minPosePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numPoses = numPoses

let poseLandmarker = try PoseLandmarker(options: options)
    

import MediaPipeTasksVision

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

let options = PoseLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.minPoseDetectionConfidence = minPoseDetectionConfidence
options.minPosePresenceConfidence = minPosePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numPoses = numPoses

let poseLandmarker = try PoseLandmarker(options: options)
    

import MediaPipeTasksVision

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

  func poseLandmarker(
    _ poseLandmarker: PoseLandmarker,
    didFinishDetection result: PoseLandmarkerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the pose landmarker result or errors here.

  }
}

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

let options = PoseLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.minPoseDetectionConfidence = minPoseDetectionConfidence
options.minPosePresenceConfidence = minPosePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numPoses = numPoses

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

let poseLandmarker = try PoseLandmarker(options: options)
    

Objective-C

@import MediaPipeTasksVision;

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

MPPPoseLandmarkerOptions *options = [[MPPPoseLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.minPoseDetectionConfidence = minPoseDetectionConfidence;
options.minPosePresenceConfidence = minPosePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numPoses = numPoses;

MPPPoseLandmarker *poseLandmarker =
  [[MPPPoseLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

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

MPPPoseLandmarkerOptions *options = [[MPPPoseLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.minPoseDetectionConfidence = minPoseDetectionConfidence;
options.minPosePresenceConfidence = minPosePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numPoses = numPoses;

MPPPoseLandmarker *poseLandmarker =
  [[MPPPoseLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPPoseLandmarkerLiveStreamDelegate` protocol
// and implements the method that the pose landmarker calls once it finishes
// performing pose landmarks= detection in each input frame.

@interface APPPoseLandmarkerResultProcessor : NSObject 

@end

@implementation APPPoseLandmarkerResultProcessor

-   (void)poseLandmarker:(MPPPoseLandmarker *)poseLandmarker
    didFinishDetectionWithResult:(MPPPoseLandmarkerResult *)poseLandmarkerResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the pose landmarker result or errors here.

}

@end

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

MPPPoseLandmarkerOptions *options = [[MPPPoseLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.minPoseDetectionConfidence = minPoseDetectionConfidence;
options.minPosePresenceConfidence = minPosePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numPoses = numPoses;

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

MPPPoseLandmarker *poseLandmarker =
  [[MPPPoseLandmarker alloc] initWithOptions:options error:nil];
    

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

خيارات الضبط

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

إعداد البث المباشر

عند ضبط وضع التشغيل على "البث المباشر"، يتطلب "مُحدِّد معالم الوضع" استخدام خيار الإعداد poseLandmarkerLiveStreamDelegate الإضافي، والذي يتيح لـ "مُحدِّد معالم الوضع" تقديم نتائج رصد معالم الوضع بشكل غير متزامن. يجب أن ينفِّذ المفوَّض الأسلوب poseLandmarker(_:didFinishDetection: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 لمعالجتها قبل إرسالها إلى Pose 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.

تنفيذ المهمة

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

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

تعرض عيّنات الرموز البرمجية التالية أمثلة بسيطة على كيفية تشغيل أداة وضع علامات على العناصر في الوضعين التاليين:

Swift

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

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

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

Objective-C

MPPPoseLandmarkerResult *result =
  [poseLandmarker detectImage:image error:nil];
    

MPPPoseLandmarkerResult *result =
  [poseLandmarker detectVideoFrame:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

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

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

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

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

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

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

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

عند تنفيذ الاستنتاج، تُعرِض مهمة "وضع علامات على معالِم الوضع" PoseLandmarkerResult الذي يحتوي على إحداثيات كلّ معلم من معالِم الوضع.

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

PoseLandmarkerResult:
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : 0.129959
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
      visibility   : 0.999909
      presence     : 0.999958
    ... (33 landmarks per pose)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
      visibility   : 0.999976
      presence     : 0.999998
    ... (33 world landmarks per pose)
  SegmentationMasks:
    ... (pictured below)

يحتوي الإخراج على كلّ من الإحداثيات العادية (Landmarks) وإحداثيات العالم (WorldLandmarks) لكلّ معلم.

يحتوي الإخراج على الإحداثيات التالية (Landmarks) التي تم تسويتها:

• ‫x وy: إحداثيات المَعلمة التي تم تسويتها بين 0.0 و1.0 حسب عرض الصورة (x) وارتفاعها (y).

• z: عمق المَعلم، مع تحديد عمق منتصف الوركين كنقطة المنشأ وكلما كانت القيمة أصغر، كان المَعلم أقرب إلى الكاميرا. يستخدم حجم z المقياس نفسه تقريبًا المستخدَم في x.

• visibility: احتمال ظهور المَعلمة في الصورة

يحتوي الإخراج على إحداثيات العالم التالية (WorldLandmarks):

• ‫x وy وz: إحداثيات ثلاثية الأبعاد في العالم الواقعي بالمتر، مع تحديد نقطة وسط الوركين كمصدر.

• visibility: احتمال ظهور المَعلمة في الصورة

تعرض الصورة التالية عرضًا مرئيًا لمعدّل تكرار المهمة:

يمثّل قناع التقسيم الاختياري احتمالية أن تنتمي كل بكسل إلى شخص تم رصده. الصورة التالية هي قناع تقسيم لمخرجات المهمة:

يوضّح مثال الرمز البرمجي لميزة "مُحدِّد معالم الوضع" كيفية عرض نتائج ميزة "مُحدِّد معالم الوضع".