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

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

توضّح لك هذه التعليمات كيفية استخدام ميزة "وضع علامات على العناصر في الصورة" مع تطبيقات iOS. تتوفر عينة التعليمات البرمجية في هذه التعليمات على GitHub.

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

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

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

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

تنزيل الرمز

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

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

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

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

2. اختياريًا، يمكنك ضبط مثيل git لاستخدام عملية دفع متفرقة، بحيث لا يكون لديك سوى ملفات تطبيق Pose Lookerer الذي تريده:

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

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

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

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

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

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

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

التبعيات

يستخدم Pose Recorder مكتبة 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 قبل تمريره إلى Pose Marker. يتيح 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 المسموح بها. لا تتيح ميزة Pose Insightser استخدام الاتجاهات المعكوسة، مثل .upMirrored و.downMirrored و.leftMirrored و.rightMirrored.

لمزيد من المعلومات حول UIImage، يمكنك الرجوع إلى وثائق مطوّري برامج UIImage من Apple.

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];
    

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

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

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

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

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

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

عند إجراء الاستنتاج، تعرض مهمة Pose Metricser 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: احتمالية ظهور المَعلم ضمن الصورة.

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

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

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