了解 2023 年 Google I/O 大会上介绍的 Firebase 亮点。了解详情

在 Android 上使用機器學習套件掃描條碼

您可以使用 ML Kit 來識別和解碼條形碼。

在你開始之前

  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 和8 像素寬。因為 EAN-13 條碼總共有 95 個單位寬，所以條碼應至少有 190 像素寬。

    更密集的格式（例如 PDF417）需要更大的像素尺寸，機器學習套件才能可靠地讀取它們。例如，PDF417 代碼在單行中最多可以包含 34 個 17 單位寬的“單詞”，理想情況下至少為 1156 像素寬。

  • 圖像聚焦不佳會影響掃描精度。如果您沒有得到可接受的結果，請嘗試要求用戶重新捕獲圖像。

  • 對於典型應用，建議提供更高分辨率的圖像（例如 1280x720 或 1920x1080），這樣可以在距離攝像頭更遠的地方檢測到條碼。

    但是，在延遲至關重要的應用程序中，您可以通過以較低分辨率捕獲圖像來提高性能，但要求條形碼構成輸入圖像的大部分。另請參閱提高實時性能的技巧。

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 )
  • 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 )
  • 二維碼（ FORMAT_QR_CODE ）
  • PDF417 ( FORMAT_PDF417 )
  • 阿茲特克 ( FORMAT_AZTEC )
  • 數據矩陣 ( FORMAT_DATA_MATRIX )

2.運行條碼檢測器

要識別圖像中的條形碼，請從Bitmap 、 media.Image 、 ByteBuffer 、字節數組或設備上的文件創建一個FirebaseVisionImage對象。然後，將FirebaseVisionImage對像傳遞給FirebaseVisionBarcodeDetector的detectInImage方法。

  1. 從您的圖像創建一個FirebaseVisionImage對象。

    • 要從media.Image對象創建FirebaseVisionImage對象，例如從設備的攝像頭捕獲圖像時，請將media.Image對象和圖像的旋轉傳遞給FirebaseVisionImage.fromMediaImage() 。

      如果您使用CameraX庫， OnImageCapturedListener和ImageAnalysis.Analyzer類會為您計算旋轉值，因此您只需在調用FirebaseVisionImage.fromMediaImage()之前將旋轉轉換為 ML Kit 的ROTATION_常量之一：

      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
    • 要從文件 URI 創建FirebaseVisionImage對象，請將應用上下文和文件 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
    • 要從ByteBuffer或字節數組創建FirebaseVisionImage對象，請首先按照上面針對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
    • 要從Bitmap對象創建FirebaseVisionImage對象：

      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格式捕獲圖像。

    如果您使用較舊的 Camera API，請以ImageFormat.NV21格式捕獲圖像。