رصد العناصر وتتبّعها باستخدام أدوات تعلّم الآلة على Android

يمكنك استخدام أدوات تعلُّم الآلة لرصد العناصر في إطارات الفيديو المتتالية وتتبُّعها.

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

تستخدِم واجهة برمجة التطبيقات هذه مكتبة غير مجمّعة يجب تنزيلها قبل الاستخدام. اطّلِع على هذا الدليل للحصول على مزيد من المعلومات.

جرّبه الآن

• يمكنك استخدام نموذج التطبيق للاطّلاع على مثال على استخدام واجهة برمجة التطبيقات هذه.
• الاطلاع على واجهة عرض التصميم المتعدد الأبعاد app لمزيد من التنفيذ الشامل لواجهة برمجة التطبيقات هذه.

قبل البدء

تتطلّب واجهة برمجة التطبيقات هذه المستوى 21 من واجهة برمجة تطبيقات Android أو إصدارًا أحدث. تأكَّد من أنّ ملف الإصدار لتطبيقك يستخدم قيمة minSdkVersion‏ 21 أو أعلى.

1. في ملف build.gradle على مستوى المشروع، تأكَّد من تضمين مستودع Maven التابع لشركة Google في كل من buildscript أقسام allprojects
2. أضِف ملحقات مكتبات ML Kit على Android إلى ملف Gradle على مستوى التطبيق، ويكون عادةً app/build.gradle:

   dependencies {
     // ...
   
     implementation 'com.google.mlkit:object-detection:17.0.2'
   
   }
   

1. ضبط أداة رصد الكائنات

لرصد العناصر وتتبُّعها، عليك أولاً إنشاء مثيل لـ ObjectDetector اختياريًا، حدِّد أي إعدادات أداة رصد تريد تغييرها من الافتراضي.

1. اضبط أداة رصد الأجسام لحالة الاستخدام باستخدام كائن ObjectDetectorOptions. يمكنك تغيير ما يلي الإعدادات:

   إعدادات أداة رصد الأجسام
   وضع الكشف	STREAM_MODE (الخيار التلقائي) | SINGLE_IMAGE_MODE في STREAM_MODE (الإعداد التلقائي)، يعمل ميزة "كاشف الأجسام" بمعدّل استجابة منخفض، ولكن قد ينتج عنه نتائج غير مكتملة (مثل مربّعات حدود أو تصنيفات فئات غير محدّدة) في أوّل بضع عمليات تشغيل لميزة "كاشف الأجسام". أيضًا في STREAM_MODE، تخصص أداة الكشف أرقام تعريف تتبع للكائنات، والتي يمكنك استخدامها وتتبع الكائنات عبر الإطارات. استخدِم هذا الوضع عندما تريد تتبُّع الأجسام أو عندما يكون تقليل وقت الاستجابة مهمًا، مثل معالجة مجرى الفيديو في الوقت الفعلي. في SINGLE_IMAGE_MODE، يعرض "أداة رصد الأجسام" النتيجة بعد تحديد مربّع الحدود الخاص بالجسم. إذا فعّلت أيضًا التصنيف، ستظهر النتيجة بعد توفّر كل من مربّع حدود العنصر وعلامة الفئة. نتيجةً لذلك، قد يكون وقت استجابة رصد التهديدات أعلى. أيضًا، في SINGLE_IMAGE_MODE، لم يتم تعيين أرقام تعريف التتبع. استخدِم هذا الوضع إذا لم يكن وقت الاستجابة مهمًا ولم تكن تريد التعامل مع النتائج الجزئية.
   اكتشِف عناصر متعددة وتتبَّعها	false (الخيار التلقائي) | true ما إذا كان سيتم رصد وتتبع ما يصل إلى خمسة عناصر أو أكثرها فقط كائن بارز (الافتراضي).
   تصنيف الأجسام	false (الخيار التلقائي) | true تحديد ما إذا كان سيتم تصنيف العناصر المرصودة إلى فئات تقريبية أو لا. عند تفعيل هذه الميزة، تصنِّف أداة رصد الكائنات العناصر في الفئات التالية: سلع أزياء، طعام، سلع منزلية والأماكن والنباتات.

   تم تحسين واجهة برمجة التطبيقات لرصد الأجسام وتتبُّعها لاستخدامَين أساسيَّين:

   • الرصد المباشر للجسم الأكثر بروزًا في الكاميرا وتتبُّعه عدسة الكاميرا.
   • رصد عناصر متعددة من صورة ثابتة

   لضبط واجهة برمجة التطبيقات لحالات الاستخدام هذه:

   Kotlin

   // Live detection and tracking
   val options = ObjectDetectorOptions.Builder()
           .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
           .enableClassification()  // Optional
           .build()
   
   // Multiple object detection in static images
   val options = ObjectDetectorOptions.Builder()
           .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
           .enableMultipleObjects()
           .enableClassification()  // Optional
           .build()

   Java

   // Live detection and tracking
   ObjectDetectorOptions options =
           new ObjectDetectorOptions.Builder()
                   .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
                   .enableClassification()  // Optional
                   .build();
   
   // Multiple object detection in static images
   ObjectDetectorOptions options =
           new ObjectDetectorOptions.Builder()
                   .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
                   .enableMultipleObjects()
                   .enableClassification()  // Optional
                   .build();

2. الحصول على مثيل من ObjectDetector:

   Kotlin

   val objectDetector = ObjectDetection.getClient(options)

   Java

   ObjectDetector objectDetector = ObjectDetection.getClient(options);

2. تجهيز صورة الإدخال

لرصد الأجسام وتتبُّعها، عليك تمرير الصور إلى طريقة ObjectDetector process() الخاصة بالمثيل.

يتم تشغيل أداة رصد الكائنات مباشرةً من Bitmap أو NV21 ByteBuffer أو YUV_420_888 media.Image. ننصحك بإنشاء InputImage من هذه المصادر إذا كان بإمكانك الوصول مباشرةً إلى أحدها. إذا أنشأت InputImage من مصادر أخرى، سنتعامل مع عملية التحويل داخليًا نيابةً عنك وقد تكون أقل فعالية.

بالنسبة إلى كل إطار من لقطات الفيديو أو الصور في تسلسل، عليك اتّباع الخطوات التالية:

يمكنك إنشاء InputImage من مصادر مختلفة، في ما يلي شرح لكل منها.

استخدام media.Image

لإنشاء عنصر InputImage من عنصر media.Image، مثلاً عند التقاط صورة من كاميرا الجهاز، عليك تمرير عنصر media.Image ودرجة دوران الصورة إلى InputImage.fromMediaImage().

إذا كنت تستخدم CameraX وOnImageCapturedListener تحتسب صفوف ImageAnalysis.Analyzer قيمة عرض الإعلانات بالتناوب. لك.

Kotlin

private class YourImageAnalyzer : ImageAnalysis.Analyzer {

    override fun analyze(imageProxy: ImageProxy) {
        val mediaImage = imageProxy.image
        if (mediaImage != null) {
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

    @Override
    public void analyze(ImageProxy imageProxy) {
        Image mediaImage = imageProxy.getImage();
        if (mediaImage != null) {
          InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees());
          // Pass image to an ML Kit Vision API
          // ...
        }
    }
}

إذا كنت لا تستخدم مكتبة كاميرا تمنحك درجة دوران الصورة، يمكنك احتسابها من درجة دوران الجهاز واتجاه كاميرا الاستشعار في الجهاز:

Kotlin

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 0)
    ORIENTATIONS.append(Surface.ROTATION_90, 90)
    ORIENTATIONS.append(Surface.ROTATION_180, 180)
    ORIENTATIONS.append(Surface.ROTATION_270, 270)
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Throws(CameraAccessException::class)
private fun getRotationCompensation(cameraId: String, activity: Activity, isFrontFacing: Boolean): Int {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    val deviceRotation = activity.windowManager.defaultDisplay.rotation
    var rotationCompensation = ORIENTATIONS.get(deviceRotation)

    // Get the device's sensor orientation.
    val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360
    }
    return rotationCompensation
}
MLKitVisionImage.kt

Java

private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 0);
    ORIENTATIONS.append(Surface.ROTATION_90, 90);
    ORIENTATIONS.append(Surface.ROTATION_180, 180);
    ORIENTATIONS.append(Surface.ROTATION_270, 270);
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
private int getRotationCompensation(String cameraId, Activity activity, boolean isFrontFacing)
        throws CameraAccessException {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
    int rotationCompensation = ORIENTATIONS.get(deviceRotation);

    // Get the device's sensor orientation.
    CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360;
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360;
    }
    return rotationCompensation;
}

بعد ذلك، مرِّر الكائن media.Image قيمة درجة التدوير إلى InputImage.fromMediaImage():

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

استخدام معرف موارد منتظم (URI) لملف

لإنشاء InputImage من معرف موارد منتظم (URI) لملف، فمرر سياق التطبيق ومعرف الموارد المنتظم (URI) للملف إلى InputImage.fromFilePath() يكون ذلك مفيدًا عند استخدام نية ACTION_GET_CONTENT لطلب تحديد صورة من تطبيق معرض الصور.

Kotlin

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}
MLKitVisionImage.kt

Java

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

يتم استخدام ByteBuffer أو ByteArray

لإنشاء عنصر InputImage من ByteBuffer أو ByteArray، يجب أولاً احتساب درجة دوران الصورة كما هو موضّح سابقًا لإدخال media.Image. بعد ذلك، أنشئ عنصر InputImage باستخدام المخزن المؤقت أو الصفيف، بالإضافة إلى ارتفاع الصورة وعرضها وتنسيق ترميز الألوان ودرجة دورانها:

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java

استخدام Bitmap

لإنشاء InputImage من كائن Bitmap، قدِّم التعريف التالي:

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
MLKitVisionImage.java

يتم تمثيل الصورة بعنصر Bitmap مع درجات الدوران.

3- معالجة الصورة

نقْل الصورة إلى طريقة process():

Kotlin

objectDetector.process(image)
    .addOnSuccessListener { detectedObjects ->
        // Task completed successfully
        // ...
    }
    .addOnFailureListener { e ->
        // Task failed with an exception
        // ...
    }

Java

objectDetector.process(image)
    .addOnSuccessListener(
        new OnSuccessListener<List<DetectedObject>>() {
            @Override
            public void onSuccess(List<DetectedObject> detectedObjects) {
                // Task completed successfully
                // ...
            }
        })
    .addOnFailureListener(
        new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });

ملاحظة: إذا كنت تستخدم CameraX API، احرص على إغلاق ImageProxy عند الانتهاء من استخدامها، مثلاً، بإضافة OnCompleteListener إلى Task التي تم إرجاعها من process. يمكنك الاطّلاع على صف واحد (VisionProcessorBase) في نموذج تطبيق البدء السريع كمثال.

4. الحصول على معلومات عن العناصر المرصودة

إذا نجح الاتصال إلى process()، يتم إرسال قائمة تضم DetectedObject إلى المستمع الناجح.

ملاحظة: في وضع البث، قد يحتاج نظام رصد الأجسام إلى معالجة 30 لقطة أو أكثر، استنادًا إلى أداء الجهاز، قبل رصد أول جسم.

تحتوي كل DetectedObject على السمات التالية:

مربّع الحدود	Rect يشير إلى موضع الجسم في الصورة.
الرقم التعريفي للتتبع	عدد صحيح يحدِّد الجسم في جميع الصور خالية SINGLE_IMAGE_MODE.
التصنيفات	وصف التصنيف الوصف النصي للتصنيف. سيكون أحد ثوابت السلسلة المعرفة في PredefinedCategory. فهرس التصنيف فهرس التسمية بين كافة التسميات التي تدعمها العلامة المصنِّف. سيكون أحد ثوابت الأعداد الصحيحة المحددة في PredefinedCategory. ثقة التصنيف قيمة الثقة لتصنيف العنصر.

Kotlin

for (detectedObject in detectedObjects) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
        val text = label.text
        if (PredefinedCategory.FOOD == text) {
            ...
        }
        val index = label.index
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        val confidence = label.confidence
    }
}

Java

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (DetectedObject detectedObject : detectedObjects) {
    Rect boundingBox = detectedObject.getBoundingBox();
    Integer trackingId = detectedObject.getTrackingId();
    for (Label label : detectedObject.getLabels()) {
        String text = label.getText();
        if (PredefinedCategory.FOOD.equals(text)) {
            ...
        }
        int index = label.getIndex();
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        float confidence = label.getConfidence();
    }
}

ضمان تجربة رائعة للمستخدم

للحصول على أفضل تجربة للمستخدم، يُرجى اتّباع الإرشادات التالية في تطبيقك:

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

يمكنك أيضًا الاطّلاع على تطبيق عرض Material Design في حزمة ML Kit ومجموعة نماذج Material Design لتصميم الميزات المستندة إلى تعلُّم الآلة.

تحسين الأداء

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

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

• أوقِف التصنيف إذا لم تكن بحاجة إليه.

• إذا كنت تستخدم Camera أو camera2 واجهة برمجة التطبيقات، تقييد المكالمات الواردة إلى أداة الكشف. إذا توفّر إطار فيديو جديد أثناء تشغيل أداة الكشف، يمكنك إسقاط الإطار. يمكنك الاطّلاع على صف واحد (VisionProcessorBase) في نموذج تطبيق Quickstart كمثال.
• إذا كنت تستخدِم واجهة برمجة التطبيقات CameraX، تأكَّد من ضبط استراتيجية الضغط الخلفي على قيمتها التلقائية ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. ويضمن ذلك عرض صورة واحدة فقط للتحليل في كل مرة. إذا كانت المزيد من الصور يتم إنتاجها عندما يكون المحلل مشغولاً، فسيتم إسقاطها تلقائيًا ولن يتم وضعها في قائمة الانتظار التسليم. بعد إغلاق الصورة التي يتم تحليلها من خلال استدعاء ‎(ImageProxy.close())‎، سيتم إرسال أحدث صورة تالية.
• إذا كنت تستخدِم ناتج أداة الكشف لوضع الرسومات فوق صورة الإدخال، يمكنك أولاً الحصول على النتيجة من ML Kit، ثم عرض الصورة والعنصر المتراكب في خطوة واحدة. ويتم عرض هذا المحتوى على سطح العرض مرّة واحدة فقط لكل إطار إدخال. يمكنك الاطّلاع على CameraSourcePreview و GraphicOverlay صفًا في نموذج تطبيق Quickstart كمثال.
• إذا كنت تستخدم واجهة برمجة التطبيقات Camera2 API، يمكنك التقاط الصور بتنسيق ImageFormat.YUV_420_888. إذا كنت تستخدم الإصدار القديم من Camera API، يمكنك التقاط الصور بتنسيق ImageFormat.NV21.