تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

قبل البدء

إذا لم تكن قد فعلت ذلك بالفعل، إضافة Firebase إلى مشروع Android

إضافة الموارد التابعة لمكتبات ML Kit على Android إلى الوحدة (على مستوى التطبيق) ملف Gradle (عادةً app/build.gradle):

apply plugin: 'com.android.application'
apply plugin: 'com.google.gms.google-services'

dependencies {
  // ...

  implementation 'com.google.firebase:firebase-ml-vision:24.0.3'
  implementation 'com.google.firebase:firebase-ml-vision-object-detection-model:19.0.6'
}

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

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

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

إعدادات ميزة "رصد الأجسام"

وضع الكشف

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

STREAM_MODE (الخيار التلقائي) | SINGLE_IMAGE_MODE

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

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

اكتشِف عناصر متعددة وتتبَّعها

false (الخيار التلقائي) | true

ما إذا كان سيتم رصد وتتبع ما يصل إلى خمسة عناصر أو أكثرها فقط كائن بارز (الافتراضي).

تصنيف العناصر

false (الخيار التلقائي) | true

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

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

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

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

Java

// Live detection and tracking
FirebaseVisionObjectDetectorOptions options =
        new FirebaseVisionObjectDetectorOptions.Builder()
                .setDetectorMode(FirebaseVisionObjectDetectorOptions.STREAM_MODE)
                .enableClassification()  // Optional
                .build();

// Multiple object detection in static images
FirebaseVisionObjectDetectorOptions options =
        new FirebaseVisionObjectDetectorOptions.Builder()
                .setDetectorMode(FirebaseVisionObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableMultipleObjects()
                .enableClassification()  // Optional
                .build();

Kotlin+KTX

// Live detection and tracking
val options = FirebaseVisionObjectDetectorOptions.Builder()
        .setDetectorMode(FirebaseVisionObjectDetectorOptions.STREAM_MODE)
        .enableClassification()  // Optional
        .build()

// Multiple object detection in static images
val options = FirebaseVisionObjectDetectorOptions.Builder()
        .setDetectorMode(FirebaseVisionObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableMultipleObjects()
        .enableClassification()  // Optional
        .build()

الحصول على نسخة افتراضية من FirebaseVisionObjectDetector:

Java

FirebaseVisionObjectDetector objectDetector =
        FirebaseVision.getInstance().getOnDeviceObjectDetector();

// Or, to change the default settings:
FirebaseVisionObjectDetector objectDetector =
        FirebaseVision.getInstance().getOnDeviceObjectDetector(options);

Kotlin+KTX

val objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector()

// Or, to change the default settings:
val objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector(options)

2- تشغيل أداة رصد الكائنات

لرصد العناصر وتتبُّعها، أرسِل الصور إلى FirebaseVisionObjectDetector. للمثيل processImage().

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

أنشِئ عنصر FirebaseVisionImage من صورتك.

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

إذا كنت تستخدم CameraX وOnImageCapturedListener تحتسب صفوف ImageAnalysis.Analyzer قيمة عرض الإعلانات بالتناوب. لك، لذا ما عليك سوى تحويل الدوران إلى إحدى أدوات تعلّم الآلة ROTATION_ ثابت قبل إجراء الطلب FirebaseVisionImage.fromMediaImage():

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

    private int degreesToFirebaseRotation(int degrees) {
        switch (degrees) {
            case 0:
                return FirebaseVisionImageMetadata.ROTATION_0;
            case 90:
                return FirebaseVisionImageMetadata.ROTATION_90;
            case 180:
                return FirebaseVisionImageMetadata.ROTATION_180;
            case 270:
                return FirebaseVisionImageMetadata.ROTATION_270;
            default:
                throw new IllegalArgumentException(
                        "Rotation must be 0, 90, 180, or 270.");
        }
    }

    @Override
    public void analyze(ImageProxy imageProxy, int degrees) {
        if (imageProxy == null || imageProxy.getImage() == null) {
            return;
        }
        Image mediaImage = imageProxy.getImage();
        int rotation = degreesToFirebaseRotation(degrees);
        FirebaseVisionImage image =
                FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
        // Pass image to an ML Kit Vision API
        // ...
    }
}

Kotlin+KTX

private class YourImageAnalyzer : ImageAnalysis.Analyzer {
    private fun degreesToFirebaseRotation(degrees: Int): Int = when(degrees) {
        0 -> FirebaseVisionImageMetadata.ROTATION_0
        90 -> FirebaseVisionImageMetadata.ROTATION_90
        180 -> FirebaseVisionImageMetadata.ROTATION_180
        270 -> FirebaseVisionImageMetadata.ROTATION_270
        else -> throw Exception("Rotation must be 0, 90, 180, or 270.")
    }

    override fun analyze(imageProxy: ImageProxy?, degrees: Int) {
        val mediaImage = imageProxy?.image
        val imageRotation = degreesToFirebaseRotation(degrees)
        if (mediaImage != null) {
            val image = FirebaseVisionImage.fromMediaImage(mediaImage, imageRotation)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

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

Java

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

/**
 * 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, Context context)
        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);

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360;

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    int result;
    switch (rotationCompensation) {
        case 0:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            break;
        case 90:
            result = FirebaseVisionImageMetadata.ROTATION_90;
            break;
        case 180:
            result = FirebaseVisionImageMetadata.ROTATION_180;
            break;
        case 270:
            result = FirebaseVisionImageMetadata.ROTATION_270;
            break;
        default:
            result = FirebaseVisionImageMetadata.ROTATION_0;
            Log.e(TAG, "Bad rotation value: " + rotationCompensation);
    }
    return result;
}VisionImage.java

Kotlin+KTX

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 90)
    ORIENTATIONS.append(Surface.ROTATION_90, 0)
    ORIENTATIONS.append(Surface.ROTATION_180, 270)
    ORIENTATIONS.append(Surface.ROTATION_270, 180)
}
/**
 * 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, context: Context): 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)

    // On most devices, the sensor orientation is 90 degrees, but for some
    // devices it is 270 degrees. For devices with a sensor orientation of
    // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
    val cameraManager = context.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!
    rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360

    // Return the corresponding FirebaseVisionImageMetadata rotation value.
    val result: Int
    when (rotationCompensation) {
        0 -> result = FirebaseVisionImageMetadata.ROTATION_0
        90 -> result = FirebaseVisionImageMetadata.ROTATION_90
        180 -> result = FirebaseVisionImageMetadata.ROTATION_180
        270 -> result = FirebaseVisionImageMetadata.ROTATION_270
        else -> {
            result = FirebaseVisionImageMetadata.ROTATION_0
            Log.e(TAG, "Bad rotation value: $rotationCompensation")
        }
    }
    return result
}VisionImage.kt

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

Java

FirebaseVisionImage image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation);VisionImage.java

Kotlin+KTX

val image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation)VisionImage.kt

لإنشاء كائن FirebaseVisionImage من معرّف موارد منتظم (URI) لملف، مرِّر سياق التطبيق ومعرّف الموارد المنتظم (URI) للملف FirebaseVisionImage.fromFilePath() يكون ذلك مفيدًا عندما يجب استخدام هدف ACTION_GET_CONTENT لتطلب من المستخدم الاختيار. صورة من تطبيق المعرض الخاص به.
Java
```
FirebaseVisionImage image;
try {
    image = FirebaseVisionImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}VisionImage.java
```
Kotlin+KTX
```
val image: FirebaseVisionImage
try {
    image = FirebaseVisionImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}VisionImage.kt
```

لإنشاء عنصر FirebaseVisionImage من ByteBuffer أو صفيف بايت، احسب الصورة أولاً تدوير كما هو موضح أعلاه لإدخال media.Image.

بعد ذلك، يمكنك إنشاء كائن FirebaseVisionImageMetadata. يتضمن ارتفاع الصورة وعرضها وتنسيق ترميز الألوان لها وتدوير:

Java

FirebaseVisionImageMetadata metadata = new FirebaseVisionImageMetadata.Builder()
        .setWidth(480)   // 480x360 is typically sufficient for
        .setHeight(360)  // image recognition
        .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
        .setRotation(rotation)
        .build();VisionImage.java

Kotlin+KTX

val metadata = FirebaseVisionImageMetadata.Builder()
        .setWidth(480) // 480x360 is typically sufficient for
        .setHeight(360) // image recognition
        .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
        .setRotation(rotation)
        .build()VisionImage.kt

استخدم المخزن المؤقت أو الصفيفة وكائن البيانات الوصفية لإنشاء كائن FirebaseVisionImage:

Java

FirebaseVisionImage image = FirebaseVisionImage.fromByteBuffer(buffer, metadata);
// Or: FirebaseVisionImage image = FirebaseVisionImage.fromByteArray(byteArray, metadata);VisionImage.java

Kotlin+KTX

val image = FirebaseVisionImage.fromByteBuffer(buffer, metadata)
// Or: val image = FirebaseVisionImage.fromByteArray(byteArray, metadata)VisionImage.kt

لإنشاء عنصر FirebaseVisionImage من كائن Bitmap:
Java
```
FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);VisionImage.java
```
Kotlin+KTX
```
val image = FirebaseVisionImage.fromBitmap(bitmap)VisionImage.kt
```
يجب أن تكون الصورة التي يمثّلها الكائن Bitmap مستقيمًا، دون الحاجة إلى دوران إضافي.

تمرير الصورة إلى طريقة processImage():

Java

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

Kotlin+KTX

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

إذا نجح الاتصال إلى processImage()، ستظهر قائمة من FirebaseVisionObject. يتم تمريره إلى المستمع الناجح.

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

مربّع ربط العناصر	علامة `Rect` تشير إلى موضع العنصر في .
الرقم التعريفي للتتبع	عدد صحيح يعرّف العنصر عبر الصور. خالية SINGLE_IMAGE_mode.
الفئة	الفئة التقريبية للعنصر. وإذا لم تتعرّف أداة رصد الكائنات على تمكين التصنيف، يكون هذا `FirebaseVisionObject.CATEGORY_UNKNOWN`
الثقة	قيمة الثقة لتصنيف العنصر. إذا كان الكائن أنّ التصنيف لم يكُن تصنيفًا في أداة الرصد، أو أنّ العنصر مصنفة على أنها غير معروفة، فهذا يعني `null`

Java

// The list of detected objects contains one item if multiple object detection wasn't enabled.
for (FirebaseVisionObject obj : detectedObjects) {
    Integer id = obj.getTrackingId();
    Rect bounds = obj.getBoundingBox();

    // If classification was enabled:
    int category = obj.getClassificationCategory();
    Float confidence = obj.getClassificationConfidence();
}

Kotlin+KTX

// The list of detected objects contains one item if multiple object detection wasn't enabled.
for (obj in detectedObjects) {
    val id = obj.trackingId       // A number that identifies the object across images
    val bounds = obj.boundingBox  // The object's position in the image

    // If classification was enabled:
    val category = obj.classificationCategory
    val confidence = obj.classificationConfidence
}

تحسين سهولة الاستخدام والأداء

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

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

يمكنك أيضًا الاطّلاع على [تطبيق عرض التصميم المتعدد الأبعاد لمجموعة أدوات تعلّم الآلة][showcase-link]{: .external } و التصميم المتعدد الأبعاد مجموعة أنماط الميزات المستنِدة إلى تعلُّم الآلة:

عند استخدام وضع البث في تطبيق في الوقت الفعلي، اتّبِع الإرشادات التالية وتحقيق أفضل معدلات عرض الإطارات:

يجب عدم استخدام ميزة رصد الكائنات المتعددة في وضع البث، إذ لا تسمح معظم الأجهزة بذلك قادرًا على إنتاج معدلات إطارات مناسبة.
يمكنك إيقاف التصنيف إذا لم تكن بحاجة إليه.
التحكُّم في المكالمات الواردة إلى أداة الرصد. إذا أصبح إطار فيديو جديد المتاح أثناء تشغيل أداة الكشف، أفلِت الإطار.
إذا كنت تستخدم ناتج أداة الكشف لتراكب الرسومات على الصورة المدخلة، والحصول أولاً على النتيجة من ML Kit، ثم عرض الصورة وتراكبها في خطوة واحدة. ومن خلال القيام بذلك، يمكنك العرض على سطح الشاشة مرة واحدة فقط لكل إطار إدخال
في حال استخدام واجهة برمجة التطبيقات Camera2 API، يمكنك التقاط الصور في تنسيق ImageFormat.YUV_420_888

إذا كنت تستخدم واجهة برمجة التطبيقات للكاميرا القديمة، يمكنك التقاط الصور في تنسيق ImageFormat.NV21