تشخیص و ردیابی اشیا با ML Kit در Android

می‌توانید از ML Kit برای تشخیص و ردیابی اشیا در قاب‌های ویدیویی متوالی استفاده کنید.

وقتی تصویری را به ML Kit ارسال می‌کنید، حداکثر پنج شیء را در تصویر به‌همراه موقعیت هر شیء در تصویر تشخیص می‌دهد. هنگام شناسایی اشیاء در جاری‌سازی‌های ویدیویی، هر شیء شناسه یکتایی دارد که می‌توانید از آن برای ردیابی شیء از فریمی به فریم دیگر استفاده کنید. همچنین می‌توانید به‌صورت اختیاری طبقه‌بندی اشیای درشت را فعال کنید که اشیا را با شرح دسته‌های کلی برچسب‌گذاری می‌کند.

امتحان کنید

• با برنامه نمونه بازی کنید تا نمونه‌ای از استفاده از این API را ببینید.
• برای پیاده‌سازی سرتاسر این API، به برنامه ویترین Material Design مراجعه کنید.

قبل‌از شروع

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'
   
   }

۱. پیکربندی آشکارساز شیء

برای شناسایی و ردیابی اشیا، ابتدا نمونه‌ای از ObjectDetector ایجاد کنید و به‌صورت اختیاری هرگونه تنظیمات آشکارساز را که می‌خواهید از حالت پیش‌فرض تغییر دهید مشخص کنید.

1. تشخیص‌دهنده شیء را برای مورد استفاده‌تان با شیء ObjectDetectorOptions پیکربندی کنید. می‌توانید تنظیمات زیر را تغییر دهید:

   تنظیمات آشکارساز اشیا
   حالت تشخیص	‫STREAM_MODE (پیش‌فرض) | SINGLE_IMAGE_MODE در STREAM_MODE (پیش‌فرض)، آشکارساز شیء با تأخیر کم اجرا می‌شود، اما ممکن است در چند فراخوانی اول آشکارساز، نتایج ناقصی (مثل چارگوش‌های محدودکننده یا برچسب‌های دسته‌بندی نامشخص) تولید کند. همچنین در STREAM_MODE، آشکارساز شناسه‌های رهگیری را به اشیا اختصاص می‌دهد که می‌توانید از آن‌ها برای رهگیری اشیا در سراسر قاب‌ها استفاده کنید. از این حالت زمانی استفاده کنید که می‌خواهید اشیا را ردیابی کنید، یا زمانی که تأخیر کم مهم است، مثلاً هنگام پردازش جاری‌سازی‌های ویدیو به‌صورت هم‌زمان. در SINGLE_IMAGE_MODE، آشکارساز شیء نتیجه را پس‌از تعیین کادر محدودکننده شیء برمی‌گرداند. اگر دسته‌بندی را نیز فعال کنید، نتیجه را پس‌از دردسترس بودن چارگوش محدودکننده و برچسب دسته برمی‌گرداند. در نتیجه، تأخیر در تشخیص احتمالاً بیشتر است. همچنین، در SINGLE_IMAGE_MODE، شناسه‌های رهگیری اختصاص داده نمی‌شود. اگر تأخیر مهم نیست و نمی‌خواهید با نتایج جزئی سروکار داشته باشید، از این حالت استفاده کنید.
   شناسایی و ردیابی چند شیء	‫false (پیش‌فرض) | true اینکه حداکثر پنج شیء یا فقط برجسته‌ترین شیء (پیش‌فرض) شناسایی و ردیابی شود.
   طبقه‌بندی اشیاء	‫false (پیش‌فرض) | true اشیا تشخیص‌داده‌شده در دسته‌های کلی طبقه‌بندی شوند یا نه. وقتی فعال باشد، آشکارساز شیء اشیا را در دسته‌های زیر طبقه‌بندی می‌کند: کالاهای مد، غذا، کالاهای خانگی، مکان‌ها، و گیاهان.

   ‫API تشخیص و ردیابی شیء برای این دو مورد استفاده اصلی بهینه‌سازی شده است:

   • تشخیص و ردیابی زنده برجسته‌ترین شیء در منظره‌یاب دوربین.
   • تشخیص چند شیء از یک تصویر ثابت.

   برای پیکربندی میانای برنامه‌سازی کاربردی برای این موارد استفاده:

   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()

   جاوا

   // 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)

   جاوا

   ObjectDetector objectDetector = ObjectDetection.getClient(options);

۲. آماده کردن تصویر ورودی

تشخیص‌دهنده اشیا مستقیماً از Bitmap، NV21 ByteBuffer، یا YUV_420_888 media.Image اجرا می‌شود. ساختن InputImage از این منابع درصورتی‌که به یکی از آن‌ها دسترسی مستقیم داشته باشید توصیه می‌شود. اگر InputImage را از منابع دیگر بسازید، تبدیل را به‌صورت داخلی برایتان مدیریت می‌کنیم و ممکن است کارایی کمتری داشته باشد.

برای هر فریم ویدیو یا تصویر در یک توالی، موارد زیر را انجام دهید:

می‌توانید شیء InputImage را از منابع مختلف ایجاد کنید، هرکدام در زیر توضیح داده شده است.

استفاده از media.Image

برای ایجاد یک شیء InputImage از یک شیء media.Image، مثلاً وقتی تصویری را از دوربین دستگاه ضبط می‌کنید، شیء media.Image و چرخش تصویر را به InputImage.fromMediaImage() منتقل کنید.

اگر از کتابخانه CameraX استفاده می‌کنید، کلاس‌های OnImageCapturedListener و ImageAnalysis.Analyzer مقدار چرخش را برای شما محاسبه می‌کنند.

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
            // ...
        }
    }
}

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
          // ...
        }
    }
}

اگر از کتابخانه دوربینی استفاده نمی‌کنید که درجه چرخش تصویر را به شما ارائه دهد، می‌توانید آن را از درجه چرخش دستگاه و جهت حسگر دوربین در دستگاه محاسبه کنید:

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

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() منتقل کنید:

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

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

استفاده از نشانی وب فایل

برای ایجاد یک شیء InputImage از نشانی وب فایل، بافت برنامه و نشانی وب فایل را به InputImage.fromFilePath() ارسال کنید. این کار زمانی مفید است که از قصد ACTION_GET_CONTENT برای ترغیب کاربر به انتخاب تصویر از برنامه گالری‌اش استفاده می‌کنید.

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

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

استفاده از ByteBuffer یا ByteArray

برای ایجاد InputImage شیء از ByteBuffer یا ByteArray، ابتدا درجه چرخش تصویر را همان‌طور که قبلاً برای ورودی media.Image توضیح داده شد محاسبه کنید. سپس، شیء InputImage را با بافر یا آرایه، همراه با ارتفاع، عرض، قالب کدبندی رنگ، و درجه چرخش تصویر ایجاد کنید:

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

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، بیانیه زیر را اعلام کنید:

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

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

تصویر با یک شیء Bitmap به‌همراه درجه‌های چرخش نشان داده می‌شود.

۳. پردازش تصویر

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

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
                // ...
            }
        });

۴. دریافت اطلاعات درباره اشیای شناسایی‌شده

اگر تماس با process() موفقیت‌آمیز باشد، فهرستی از DetectedObject به شنونده موفقیت ارسال می‌شود.

هر DetectedObject شامل ویژگی‌های زیر است:

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
    }
}

// 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();
    }
}

تضمین تجربه کاربری عالی

برای ارائه بهترین تجربه کاربری، این دستورالعمل‌ها را در برنامه‌تان دنبال کنید:

• تشخیص موفقیت‌آمیز شیء به پیچیدگی بصری شیء بستگی دارد. برای شناسایی شدن، اشیایی که تعداد کمی ویژگی‌های بصری دارند ممکن است لازم باشد بخش بزرگ‌تری از تصویر را اشغال کنند. باید کاربران را درباره ضبط ورودی‌ای که با نوع اشیایی که می‌خواهید شناسایی کنید به‌خوبی کار می‌کند راهنمایی کنید.
• هنگام استفاده از طبقه‌بندی، اگر می‌خواهید اشیایی را که به‌طور واضح در دسته‌های پشتیبانی‌شده قرار نمی‌گیرند شناسایی کنید، مدیریت ویژه‌ای برای اشیای ناشناخته پیاده‌سازی کنید.

همچنین، برنامه ویترین «طراحی سه‌بعدی ML Kit» و مجموعه «طراحی سه‌بعدی» الگوهای ویژگی‌های مجهز به یادگیری ماشین را بررسی کنید.