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

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

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

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

يمكنك استخدام التطبيق كنقطة بداية لتطبيق Android الخاص بك، أو الرجوع إليه عند تعديل تطبيق حالي. يتم استضافة مثال رمز "كاشف الأجسام" على 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/object_detection/android
   

بعد إنشاء نسخة محلية من رمز المثال، يمكنك استيراد المشروع إلى "استوديو Android" وتشغيل التطبيق. للحصول على التعليمات، اطّلِع على دليل الإعداد لنظام التشغيل Android.

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

تحتوي الملفات التالية على الرمز البرمجي المهم لتطبيق مثال "كاشف الأجسام":

• ‫ObjectDetectorHelper.kt: تُستخدَم لإعداد أداة رصد الأجسام ومعالجة النموذج وتحديد المفوَّض
• ‫MainActivity.kt: ينفِّذ التطبيق ويجمع مكوّنات واجهة المستخدم
• ‫OverlayView.kt: تعالج هذه الفئة النتائج وتعرضها.

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

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

التبعيات

تستخدِم ميزة "كاشف الأجسام" مكتبة com.google.mediapipe:tasks-vision. أضِف هذا الاعتماد إلى ملف build.gradle في مشروع تطوير تطبيق Android. استورِد العناصر التابعة المطلوبة باستخدام الرمز التالي:

dependencies {
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

الطراز

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

اختَر النموذج ونزِّله، ثم احفظه في دليل مشروعك:

<dev-project-root>/src/main/assets

استخدِم الطريقة BaseOptions.Builder.setModelAssetPath() لتحديد المسار الذي يستخدمه النموذج. للاطّلاع على مثال على الرمز، يُرجى الاطّلاع على القسم التالي.

إنشاء المهمة

يمكنك استخدام الدالة createFromOptions لإنشاء المهمة. تقبل الدالة createFromOptions خيارات الضبط، بما في ذلك وضع التشغيل ولغة الأسماء المعروضة والحد الأقصى لعدد النتائج وعتبة الثقة وقائمة السماح بالкатегориات وقائمة الرفض. في حال عدم تحديد خيار ضبط، سيتم استخدام القيمة التلقائية. لمزيد من المعلومات حول خيارات الضبط، يُرجى الاطّلاع على نظرة عامة على الضبط.

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

ObjectDetectorOptions options =
  ObjectDetectorOptions.builder()
    .setBaseOptions(BaseOptions.builder().setModelAssetPath(‘model.tflite’).build())
    .setRunningMode(RunningMode.IMAGE)
    .setMaxResults(5)
    .build();
objectDetector = ObjectDetector.createFromOptions(context, options);
    

ObjectDetectorOptions options =
  ObjectDetectorOptions.builder()
    .setBaseOptions(BaseOptions.builder().setModelAssetPath(‘model.tflite’).build())
    .setRunningMode(RunningMode.VIDEO)
    .setMaxResults(5)
    .build();
objectDetector = ObjectDetector.createFromOptions(context, options);
    

ObjectDetectorOptions options =
  ObjectDetectorOptions.builder()
    .setBaseOptions(BaseOptions.builder().setModelAssetPath(‘model.tflite’).build())
    .setRunningMode(RunningMode.LIVE_STREAM)
    .setMaxResults(5)
    .setResultListener((result, inputImage) -> {
      // Process the detection result here.
    })
    .setErrorListener((result, inputImage) -> {
      // Process the classification errors here.
    })
   .build();
objectDetector = ObjectDetector.createFromOptions(context, options);
    

يتيح مثال تنفيذ رمز "كاشف الأجسام" للمستخدم التبديل بين أوضاع المعالجة. تؤدي هذه الطريقة إلى جعل رمز إنشاء المهام أكثر تعقيدًا، وقد لا يكون مناسبًا لحالة الاستخدام. يمكنك الاطّلاع على هذا الرمز في دالة setupObjectDetector() للفئة ObjectDetectorHelper.

خيارات الضبط

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

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

عليك تحويل الصورة أو الإطار المُدخلَين إلى عنصر com.google.mediapipe.framework.image.MPImage قبل تمريره إلى أداة رصد الأجسام.

توضِّح الأمثلة التالية كيفية إعداد البيانات للمعالجة لكل نوع من أنواع البيانات المتاحة:

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load an image on the user’s device as a Bitmap object using BitmapFactory.

// Convert an Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(bitmap).build();
    

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load a video file on the user's device using MediaMetadataRetriever

// From the video’s metadata, load the METADATA_KEY_DURATION and
// METADATA_KEY_VIDEO_FRAME_COUNT values. Use these values
// to calculate the timestamp of each frame later.

// Loop through the video and load each frame as a Bitmap object.

// Convert the Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(frame).build();
    

import com.google.mediapipe.framework.image.MediaImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Create a CameraX’s ImageAnalysis to continuously receive frames
// from the device’s camera. Configure it to output frames in RGBA_8888
// format to match with what is required by the model.

// For each Android’s ImageProxy object received from the ImageAnalysis,
// extract the encapsulated Android’s Image object and convert it to
// a MediaPipe’s Image object.
android.media.Image mediaImage = imageProxy.getImage()
MPImage mpImage = new MediaImageBuilder(mediaImage).build();
    

في مثال رمز "كاشف الأجسام"، يتم التعامل مع إعداد البيانات في فئة ObjectDetectorHelper ضمن وظائف detectImage() وdetectVideoFile() وdetectLivestreamFrame().

تنفيذ المهمة

استنادًا إلى نوع البيانات التي تعمل معها، استخدِم طريقة ObjectDetector.detect...() الخاصة بهذا النوع من البيانات. استخدِم ‎ detect() للصور الفردية و‎ detectForVideo() للإطارات في ملفات الفيديو و‎ detectAsync() لأحداث بث الفيديو. عند إجراء عمليات رصد في مجرى فيديو، تأكَّد من تشغيل عمليات الرصد في سلسلة محادثات منفصلة لتجنُّب حظر سلسلة محادثات واجهة المستخدم.

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

ObjectDetectorResult detectionResult = objectDetector.detect(image);
    

// Calculate the timestamp in milliseconds of the current frame.
long frame_timestamp_ms = 1000 * video_duration * frame_index / frame_count;

// Run inference on the frame.
ObjectDetectorResult detectionResult =
    objectDetector.detectForVideo(image, frameTimestampMs);
    

// Run inference on the frame. The detection results will be available
// via the `resultListener` provided in the `ObjectDetectorOptions` when
// the object detector was created.
objectDetector.detectAsync(image, frameTimestampMs);
    

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

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

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

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

عند تنفيذ الاستدلال، تعرض مهمة "كاشف الأجسام" ObjectDetectorResult يصف الأجسام التي عثر عليها في الصورة المُدخلة.

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

ObjectDetectorResult:
 Detection #0:
  Box: (x: 355, y: 133, w: 190, h: 206)
  Categories:
   index       : 17
   score       : 0.73828
   class name  : dog
 Detection #1:
  Box: (x: 103, y: 15, w: 138, h: 369)
  Categories:
   index       : 17
   score       : 0.73047
   class name  : dog

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

يوضّح مثال رمز "أداة رصد الأجسام" كيفية عرض نتائج الرصد المعروضة من المهمة، اطّلِع على فئة OverlayView لمزيد من التفاصيل.