סריקת ברקודים באמצעות ערכת ML ב-Android

אתם יכולים להשתמש ב-ML Kit כדי לזהות ולפענח קודי מ barras.

לפני שמתחילים

  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 מורכבים מפסים ומרווחים ברוחב של יחידה אחת, שתיים, שלוש או ארבע. לכן, רצוי שתמונה של קוד EAN-13 תכלול פסים מרווחים ברוחב של לפחות 2, 4, 6 ו-8 פיקסלים. מכיוון שקוד הברקוד EAN-13 הוא ברוחב של 95 יחידות בסך הכול, רוחב הקוד צריך להיות לפחות 190 פיקסלים.

    בפורמטים צפופים יותר, כמו PDF417, צריך מידות פיקסלים גדולות יותר כדי ש-ML Kit יוכל לקרוא אותם בצורה מהימנה. לדוגמה, קוד PDF417 יכול לכלול עד 34 "מילים" ברוחב 17 יחידות בשורה אחת, שרוחב הרצוי שלה הוא לפחות 1,156 פיקסלים.

  • אם התמונה לא ממוקדת, יכול להיות שהסריקה תהיה פחות מדויקת. אם התוצאות לא מתקבלות, נסו לבקש מהמשתמש לצלם מחדש את התמונה.

  • באפליקציות רגילות, מומלץ לספק תמונה ברזולוציה גבוהה יותר (כמו 1280x720 או 1920x1080), כדי שאפשר יהיה לזהות את הקודים המוטבעים ממרחק גדול יותר מהמצלמה.

    עם זאת, באפליקציות שבהן זמן האחזור קריטי, אפשר לשפר את הביצועים על ידי צילום תמונות ברזולוציה נמוכה יותר, אבל תוך דרישת שהברקוד יהווה את רוב התמונה. מומלץ לקרוא גם את המאמר טיפים לשיפור הביצועים בזמן אמת.

1. הגדרת הגלאי של ברקודים

אם אתם יודעים אילו פורמטים של קודי מ barras אתם צפויים לקרוא, תוכלו לשפר את המהירות של גלאי קודי המ barras על ידי הגדרה שלו לזיהוי הפורמטים האלה בלבד.

לדוגמה, כדי לזהות רק קודי Aztec וקודי QR, יוצרים אובייקט FirebaseVisionBarcodeDetectorOptions כמו בדוגמה הבאה:

Java 

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

Kotlin 

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

הפורמטים הבאים נתמכים:

  • Code 128‏ (FORMAT_CODE_128)
  • Code 39‏ (FORMAT_CODE_39)
  • קוד 93 (FORMAT_CODE_93)
  • Codabar‏ (FORMAT_CODABAR)
  • EAN-13‏ (FORMAT_EAN_13)
  • EAN-8‏ (FORMAT_EAN_8)
  • ITF‏ (FORMAT_ITF)
  • UPC-A‏ (FORMAT_UPC_A)
  • UPC-E‏ (FORMAT_UPC_E)
  • קוד QR (FORMAT_QR_CODE)
  • PDF417‏ (FORMAT_PDF417)
  • Aztec (FORMAT_AZTEC)
  • Data Matrix‏ (FORMAT_DATA_MATRIX)

2. הרצת הגלאי לזיהוי ברקודים

כדי לזהות קודי מ barras בתמונה, יוצרים אובייקט 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

      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

      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

      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

      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

      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

      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

      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 

    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 

    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 

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 מגה-פיקסלים), וכתוצאה מכך זמן האחזור (latency) נמוך מאוד ללא שיפור ברמת הדיוק. במקום זאת, צריך לבקש מהמצלמה רק את הגודל שנחוץ לזיהוי ברקוד: בדרך כלל לא יותר מ-2 מגה-פיקסלים.

    אם מהירות הסריקה חשובה לכם, תוכלו להקטין עוד יותר את רזולוציית הצילום. עם זאת, חשוב לזכור את הדרישות המינימליות לגבי גודל הברקוד שמפורטות למעלה.

  • צמצום מספר הקריאות למזהה. אם מסגרת וידאו חדשה זמינה בזמן שהגלאי פועל, צריך להסיר את המסגרת.
  • אם אתם משתמשים בפלט של הגלאי כדי להוסיף שכבת-על של גרפיקה לתמונה הקלט, קודם צריך לקבל את התוצאה מ-ML Kit, ואז לבצע עיבוד (רנדור) של התמונה ולהוסיף את שכבת-העל בשלב אחד. כך תוכלו לבצע עיבוד (render) למשטח התצוגה רק פעם אחת לכל מסגרת קלט.

  • אם אתם משתמשים ב-Camera2 API, כדאי לצלם תמונות בפורמט ImageFormat.YUV_420_888.

    אם משתמשים ב-Camera API הקודם, צריך לצלם תמונות בפורמט ImageFormat.NV21.