شناسایی و ردیابی اشیاء با ML Kit در اندروید

می‌توانید از کیت ML برای شناسایی و ردیابی اشیا در فریم‌های ویدیو استفاده کنید.

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

قبل از اینکه شروع کنی

1. اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه Android خود اضافه کنید .
2. وابستگی های کتابخانه های اندروید ML Kit را به فایل 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 ایجاد کنید و به صورت اختیاری تنظیمات آشکارساز را که می خواهید از حالت پیش فرض تغییر دهید، مشخص کنید.

1. آشکارساز شی را برای مورد استفاده خود با یک شی FirebaseVisionObjectDetectorOptions پیکربندی کنید. می توانید تنظیمات زیر را تغییر دهید:

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

   API تشخیص و ردیابی شی برای این دو مورد اصلی بهینه شده است:

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

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

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

2. یک نمونه از 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. آشکارساز شی را اجرا کنید

برای شناسایی و ردیابی اشیا، تصاویر را به متد processImage() نمونه FirebaseVisionObjectDetector ارسال کنید.

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

1. یک شی FirebaseVisionImage از تصویر خود ایجاد کنید.

   • برای ایجاد یک شی FirebaseVisionImage از یک شی media.Image ، مانند هنگام گرفتن تصویر از دوربین دستگاه، شی media.Image Image و چرخش تصویر را به FirebaseVisionImage.fromMediaImage() منتقل کنید.

     اگر از کتابخانه CameraX ، کلاس‌های OnImageCapturedListener و ImageAnalysis.Analyzer استفاده می‌کنید، مقدار چرخش را برای شما محاسبه می‌کنند، بنابراین فقط باید قبل از فراخوانی FirebaseVisionImage.fromMediaImage() چرخش را به یکی از ثابت‌های ROTATION_ ML Kit تبدیل کنید:

     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 باید عمودی باشد، بدون نیاز به چرخش اضافی.

2. تصویر را به متد 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
               // ...
           }
   

3. اگر فراخوانی 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
   }
   

بهبود قابلیت استفاده و عملکرد

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

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

همچنین، [ML Kit Material Design showcase app][showcase-link]{: .external } و الگوهای طراحی مواد برای مجموعه ویژگی های مبتنی بر یادگیری ماشین را بررسی کنید.

هنگام استفاده از حالت پخش در یک برنامه بلادرنگ، این دستورالعمل ها را برای دستیابی به بهترین نرخ فریم دنبال کنید:

• از تشخیص چند شی در حالت پخش استفاده نکنید، زیرا اکثر دستگاه‌ها قادر به تولید نرخ فریم مناسب نیستند.

• اگر به آن نیاز ندارید، طبقه بندی را غیرفعال کنید.

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

• اگر از Camera2 API استفاده می کنید، تصاویر را با فرمت ImageFormat.YUV_420_888 بگیرید.

  اگر از دوربین قدیمی‌تر API استفاده می‌کنید، تصاویر را با فرمت ImageFormat.NV21 بگیرید.