مسح الباركود باستخدام ML Kit على نظام Android

تصف هذه الصفحة إصدارًا قديمًا من Barcode Scanning API، والذي كان جزءًا من ML Kit for Firebase. تم نقل تطوير واجهة برمجة التطبيقات هذه إلى حزمة ML Kit SDK المستقلة، والتي يمكنك استخدامها مع Firebase أو بدونه. يتعلم أكثر .

راجع Scan Barcodes with ML Kit on Android للحصول على أحدث الوثائق.

يمكنك استخدام ML Kit للتعرف على الرموز الشريطية وفك تشفيرها.

يقدم الإصدار 24.0.0 من firebase-ml-vision نموذجًا جديدًا لمسح الباركود، والذي يأتي مع تحسينات كبيرة في كل من زمن الوصول والدقة مقارنة بالنموذج الأقدم. بالإضافة إلى ذلك، باستخدام أحدث واجهة برمجة التطبيقات (API)، يمكنك الآن الوصول إلى وحدات البايت الأولية لبيانات الرمز الشريطي غير المشفرة بـ UTF-8.

تأكد من إضافة وحدة firebase-ml-vision-barcode-model الجديدة إلى تبعيات مشروعك لاستخدام النموذج الجديد.

قبل ان تبدأ

1. إذا لم تكن قد قمت بذلك بالفعل، فأضف Firebase إلى مشروع Android الخاص بك .
2. أضف تبعيات مكتبات 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-barcode-model:16.0.1'
   }
   

إرشادات إدخال الصورة

• لكي تتمكن ML Kit من قراءة الرموز الشريطية بدقة، يجب أن تحتوي الصور المدخلة على رموز شريطية يتم تمثيلها ببيانات بكسل كافية.

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

  على سبيل المثال، تتكون الرموز الشريطية EAN-13 من أشرطة ومسافات يبلغ عرضها 1 أو 2 أو 3 أو 4 وحدات، لذلك تحتوي صورة الرمز الشريطي EAN-13 بشكل مثالي على أشرطة ومسافات يبلغ عرضها 2 و4 و6 و6 على الأقل. 8 بكسل واسعة. نظرًا لأن عرض الرمز الشريطي EAN-13 يبلغ إجماليًا 95 وحدة، فيجب أن يكون عرض الرمز الشريطي 190 بكسل على الأقل.

  تحتاج التنسيقات الأكثر كثافة، مثل PDF417، إلى أبعاد بكسل أكبر حتى تتمكن ML Kit من قراءتها بشكل موثوق. على سبيل المثال، يمكن أن يحتوي كود PDF417 على ما يصل إلى 34 "كلمة" بعرض 17 وحدة في صف واحد، والتي من المفترض أن يبلغ عرضها 1156 بكسل على الأقل.

• قد يؤدي التركيز الضعيف للصورة إلى الإضرار بدقة المسح الضوئي. إذا لم تحصل على نتائج مقبولة، فحاول مطالبة المستخدم باستعادة الصورة.

• بالنسبة للتطبيقات النموذجية، يوصى بتوفير صورة بدقة أعلى (مثل 1280 × 720 أو 1920 × 1080)، مما يجعل الرموز الشريطية قابلة للاكتشاف من مسافة أكبر بعيدًا عن الكاميرا.

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

1. قم بتكوين كاشف الباركود

إذا كنت تعرف تنسيقات الباركود التي تتوقع قراءتها، فيمكنك تحسين سرعة كاشف الباركود عن طريق تكوينه لاكتشاف تلك التنسيقات فقط.

على سبيل المثال، لاكتشاف رمز Aztec ورموز QR فقط، قم بإنشاء كائن FirebaseVisionBarcodeDetectorOptions كما في المثال التالي:

Java

FirebaseVisionBarcodeDetectorOptions options =
        new FirebaseVisionBarcodeDetectorOptions.Builder()
        .setBarcodeFormats(
                FirebaseVisionBarcode.FORMAT_QR_CODE,
                FirebaseVisionBarcode.FORMAT_AZTEC)
        .build();

Kotlin+KTX

val options = FirebaseVisionBarcodeDetectorOptions.Builder()
        .setBarcodeFormats(
                FirebaseVisionBarcode.FORMAT_QR_CODE,
                FirebaseVisionBarcode.FORMAT_AZTEC)
        .build()

يتم دعم التنسيقات التالية:

• كود 128 ( FORMAT_CODE_128 )
• الكود 39 ( FORMAT_CODE_39 )
• الكود 93 ( FORMAT_CODE_93 )
• كودابار ( FORMAT_CODABAR )
• EAN-13 ( FORMAT_EAN_13 )
• EAN-8 ( FORMAT_EAN_8 )
• إي تي إف ( FORMAT_ITF )
• UPC-A ( FORMAT_UPC_A )
• UPC-E ( FORMAT_UPC_E )
• رمز الاستجابة السريعة ( FORMAT_QR_CODE )
• PDF417 ( FORMAT_PDF417 )
• الأزتيك ( FORMAT_AZTEC )
• مصفوفة البيانات ( FORMAT_DATA_MATRIX )

ملاحظة: لكي يتم التعرف على رمز مصفوفة البيانات، يجب أن يتقاطع الرمز مع النقطة المركزية لصورة الإدخال. وبالتالي، يمكن التعرف على كود مصفوفة بيانات واحد فقط في الصورة.

2. قم بتشغيل كاشف الباركود

للتعرف على الرموز الشريطية في صورة ما، قم بإنشاء كائن FirebaseVisionImage إما من Bitmap أو media.Image أو ByteBuffer أو مصفوفة بايت أو ملف على الجهاز. بعد ذلك، قم بتمرير كائن FirebaseVisionImage إلى طريقة detectInImage الخاصة بـ FirebaseVisionBarcodeDetector .

1. قم بإنشاء كائن FirebaseVisionImage من صورتك.

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

     إذا كنت تستخدم مكتبة CameraX ، فإن فئتي OnImageCapturedListener و ImageAnalysis.Analyzer تحسب قيمة التدوير لك، لذلك تحتاج فقط إلى تحويل التدوير إلى أحد ثوابت ROTATION_ الخاصة بـ ML Kit قبل استدعاء 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 في وضع مستقيم، دون الحاجة إلى تدوير إضافي.

2. احصل على مثيل لـ FirebaseVisionBarcodeDetector :

   Java

   FirebaseVisionBarcodeDetector detector = FirebaseVision.getInstance()
           .getVisionBarcodeDetector();
   // Or, to specify the formats to recognize:
   // FirebaseVisionBarcodeDetector detector = FirebaseVision.getInstance()
   //        .getVisionBarcodeDetector(options);

   Kotlin+KTX

   val detector = FirebaseVision.getInstance()
           .visionBarcodeDetector
   // Or, to specify the formats to recognize:
   // val detector = FirebaseVision.getInstance()
   //        .getVisionBarcodeDetector(options)

3. وأخيرًا، قم بتمرير الصورة إلى طريقة detectInImage :

   Java

   Task<List<FirebaseVisionBarcode>> result = detector.detectInImage(image)
           .addOnSuccessListener(new OnSuccessListener<List<FirebaseVisionBarcode>>() {
               @Override
               public void onSuccess(List<FirebaseVisionBarcode> barcodes) {
                   // Task completed successfully
                   // ...
               }
           })
           .addOnFailureListener(new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                   // Task failed with an exception
                   // ...
               }
                   });

   Kotlin+KTX

   val result = detector.detectInImage(image)
           .addOnSuccessListener { barcodes ->
               // Task completed successfully
               // ...
           }
           .addOnFailureListener {
               // Task failed with an exception
               // ...
           }

3. الحصول على المعلومات من الباركود

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

على سبيل المثال:

Java

for (FirebaseVisionBarcode barcode: barcodes) {
    Rect bounds = barcode.getBoundingBox();
    Point[] corners = barcode.getCornerPoints();

    String rawValue = barcode.getRawValue();

    int valueType = barcode.getValueType();
    // See API reference for complete list of supported types
    switch (valueType) {
        case FirebaseVisionBarcode.TYPE_WIFI:
            String ssid = barcode.getWifi().getSsid();
            String password = barcode.getWifi().getPassword();
            int type = barcode.getWifi().getEncryptionType();
            break;
        case FirebaseVisionBarcode.TYPE_URL:
            String title = barcode.getUrl().getTitle();
            String url = barcode.getUrl().getUrl();
            break;
    }
}

Kotlin+KTX

for (barcode in barcodes) {
    val bounds = barcode.boundingBox
    val corners = barcode.cornerPoints

    val rawValue = barcode.rawValue

    val valueType = barcode.valueType
    // See API reference for complete list of supported types
    when (valueType) {
        FirebaseVisionBarcode.TYPE_WIFI -> {
            val ssid = barcode.wifi!!.ssid
            val password = barcode.wifi!!.password
            val type = barcode.wifi!!.encryptionType
        }
        FirebaseVisionBarcode.TYPE_URL -> {
            val title = barcode.url!!.title
            val url = barcode.url!!.url
        }
    }
}

نصائح لتحسين الأداء في الوقت الحقيقي

إذا كنت تريد مسح الرموز الشريطية ضوئيًا في تطبيق في الوقت الفعلي، فاتبع هذه الإرشادات لتحقيق أفضل معدلات الإطارات:

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

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

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

• إذا كنت تستخدم Camera2 API، فالتقط الصور بتنسيق ImageFormat.YUV_420_888 .

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