ML Kit を使用してバーコードをスキャンする(Android)

ML Kit を使用すると、バーコードを認識してデコードできます。

特徴バンドルなしバンドル
実装モデルは Google Play 開発者サービスを介して動的にダウンロードされます。モデルはビルド時にアプリに静的にリンクされます。
アプリのサイズサイズを約 200 KB 拡大。サイズが約 2.4 MB 増加します。
初期化時間最初に使用する前に、モデルのダウンロードを待たなければならない場合があります。モデルはすぐに使用できます。

試してみる

始める前に

  1. プロジェクト レベルの build.gradle ファイルの buildscript セクションと allprojects セクションの両方に Google の Maven リポジトリを組み込みます。

  2. ML Kit Android ライブラリの依存関係をモジュールのアプリレベルの Gradle ファイル(通常は app/build.gradle)に追加します。必要に応じて、次のいずれかの依存関係を選択します。

    モデルをアプリにバンドルする場合:

    dependencies {
      // ...
      // Use this dependency to bundle the model with your app
      implementation 'com.google.mlkit:barcode-scanning:17.2.0'
    }
    

    Google Play 開発者サービスでモデルを使用する場合:

    dependencies {
      // ...
      // Use this dependency to use the dynamically downloaded model in Google Play Services
      implementation 'com.google.android.gms:play-services-mlkit-barcode-scanning:18.3.0'
    }
    
  3. Google Play 開発者サービスでモデルを使用することを選択した場合、アプリが Google Play ストアからインストールされた後でモデルが自動的にデバイスにダウンロードされるようアプリを構成できます。そのためには、アプリの AndroidManifest.xml ファイルに次の宣言を追加します。

    <application ...>
          ...
          <meta-data
              android:name="com.google.mlkit.vision.DEPENDENCIES"
              android:value="barcode" >
          <!-- To use multiple models: android:value="barcode,model2,model3" -->
    </application>
    

    また、Google Play 開発者サービスの ModuleInstallClient API を使用して、モデルの可用性を明示的に確認してダウンロードをリクエストすることもできます。

    インストール時のモデルのダウンロードを有効にしない場合、または明示的なダウンロードをリクエストしない場合は、スキャナの初回実行時にモデルがダウンロードされます。ダウンロードが完了する前に行ったリクエストでは結果は生成されません。

入力画像のガイドライン

  • ML Kit でバーコードを正確に読み取るには、入力画像に十分なピクセルデータで表されるバーコードが含まれている必要があります。

    多くのバーコードは可変サイズのペイロードをサポートしているため、具体的なピクセルデータの要件は、バーコードの種類とエンコードされるデータの量の両方によって異なります。一般に、バーコードの意味のある最小単位は幅 2 ピクセル以上、2 次元コードの場合は高さ 2 ピクセル以上にする必要があります。

    たとえば、EAN-13 バーコードは幅が 1、2、3、または 4 単位のバーとスペースで構成されているため、EAN-13 バーコード画像には少なくとも 2、4、6、8 ピクセル幅のバーとスペースを含めることが理想的です。EAN-13 バーコードの幅は合計 95 単位であるため、バーコードの幅は少なくとも 190 ピクセルである必要があります。

    PDF417 などの高密度形式では、ML Kit で確実に読み取るためには、より大きなピクセルサイズが必要です。たとえば、PDF417 コードでは、1 行に最大 34 の 17 単位幅のワードを含めることができます。理想的には、幅は 1,156 ピクセル以上にする必要があります。

  • 画像のフォーカスが弱いと、スキャンの精度に影響することがあります。アプリで許容できる結果が得られない場合は、画像をキャプチャし直すようユーザーに依頼します。

  • 一般的なアプリでは、1280x720 や 1920x1080 などの高解像度の画像を提供することをおすすめします。これにより、カメラから離れたところからバーコードをスキャンできます。

    ただし、レイテンシが重要なアプリケーションでは、低い解像度で画像をキャプチャし、バーコードが入力画像の大部分を占めるようにすることで、パフォーマンスを改善できます。リアルタイムのパフォーマンスを改善するためのヒントもご覧ください。

1. バーコード スキャナを設定する

読み取るバーコード形式がわかっている場合は、その形式のみを検出するようにバーコード検出器を構成することで、バーコード検出器の速度を向上させることができます。

たとえば、Aztec コードと QR コードのみを検出するには、次の例のように BarcodeScannerOptions オブジェクトをビルドします。

Kotlin

val options = BarcodeScannerOptions.Builder()
        .setBarcodeFormats(
                Barcode.FORMAT_QR_CODE,
                Barcode.FORMAT_AZTEC)
        .build()

Java

BarcodeScannerOptions options =
        new BarcodeScannerOptions.Builder()
        .setBarcodeFormats(
                Barcode.FORMAT_QR_CODE,
                Barcode.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
  • QR コード(FORMAT_QR_CODE
  • PDF417(FORMAT_PDF417
  • アステカ語(FORMAT_AZTEC
  • データ マトリックス(FORMAT_DATA_MATRIX

バンドルモデル 17.1.0 とバンドルされていないモデル 18.2.0 以降では、enableAllPotentialBarcodes() を呼び出して、デコードできない可能性があるバーコードをすべて返すこともできます。これを使用して詳細な検出を容易に行うことができます。たとえば、カメラをズームインして、返された境界ボックス内のバーコードの鮮明な画像を取得できます。

Kotlin

val options = BarcodeScannerOptions.Builder()
        .setBarcodeFormats(...)
        .enableAllPotentialBarcodes() // Optional
        .build()

Java

BarcodeScannerOptions options =
        new BarcodeScannerOptions.Builder()
        .setBarcodeFormats(...)
        .enableAllPotentialBarcodes() // Optional
        .build();

Further on, starting from bundled library 17.2.0 and unbundled library 18.3.0, a new feature called auto-zoom has been introduced to further enhance the barcode scanning experience. With this feature enabled, the app is notified when all barcodes within the view are too distant for decoding. As a result, the app can effortlessly adjust the camera's zoom ratio to the recommended setting provided by the library, ensuring optimal focus and readability. This feature will significantly enhance the accuracy and success rate of barcode scanning, making it easier for apps to capture information precisely.

To enable auto-zooming and customize the experience, you can utilize the setZoomSuggestionOptions() method along with your own ZoomCallback handler and desired maximum zoom ratio, as demonstrated in the code below.

Kotlin

val options = BarcodeScannerOptions.Builder()
        .setBarcodeFormats(...)
        .setZoomSuggestionOptions(
            new ZoomSuggestionOptions.Builder(zoomCallback)
                .setMaxSupportedZoomRatio(maxSupportedZoomRatio)
                .build()) // Optional
        .build()

Java

BarcodeScannerOptions options =
        new BarcodeScannerOptions.Builder()
        .setBarcodeFormats(...)
        .setZoomSuggestionOptions(
            new ZoomSuggestionOptions.Builder(zoomCallback)
                .setMaxSupportedZoomRatio(maxSupportedZoomRatio)
                .build()) // Optional
        .build();

zoomCallback is required to be provided to handle whenever the library suggests a zoom should be performed and this callback will always be called on the main thread.

The following code snippet shows an example of defining a simple callback.

Kotlin

fun setZoom(ZoomRatio: Float): Boolean {
    if (camera.isClosed()) return false
    camera.getCameraControl().setZoomRatio(zoomRatio)
    return true
}

Java

boolean setZoom(float zoomRatio) {
    if (camera.isClosed()) {
        return false;
    }
    camera.getCameraControl().setZoomRatio(zoomRatio);
    return true;
}

maxSupportedZoomRatio is related to the camera hardware, and different camera libraries have different ways to fetch it (see the javadoc of the setter method). In case this is not provided, an unbounded zoom ratio might be produced by the library which might not be supported. Refer to the setMaxSupportedZoomRatio() method introduction to see how to get the max supported zoom ratio with different Camera libraries.

When auto-zooming is enabled and no barcodes are successfully decoded within the view, BarcodeScanner triggers your zoomCallback with the requested zoomRatio. If the callback correctly adjusts the camera to this zoomRatio, it is highly probable that the most centered potential barcode will be decoded and returned.

A barcode may remain undecodable even after a successful zoom-in. In such cases, BarcodeScanner may either invoke the callback for another round of zoom-in until the maxSupportedZoomRatio is reached, or provide an empty list (or a list containing potential barcodes that were not decoded, if enableAllPotentialBarcodes() was called) to the OnSuccessListener (which will be defined in step 4. Process the image).

2. Prepare the input image

To recognize barcodes in an image, create an InputImage object from either a Bitmap, media.Image, ByteBuffer, byte array, or a file on the device. Then, pass the InputImage object to the BarcodeScanner's process method.

You can create an InputImage object from different sources, each is explained below.

Using a media.Image

To create an InputImage object from a media.Image object, such as when you capture an image from a device's camera, pass the media.Image object and the image's rotation to InputImage.fromMediaImage().

If you use the CameraX library, the OnImageCapturedListener and ImageAnalysis.Analyzer classes calculate the rotation value for you.

Kotlin

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

Java

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

画像の回転角度を取得するカメラ ライブラリを使用しない場合は、デバイスの回転角度とデバイス内のカメラセンサーの向きから計算できます。

Kotlin

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
}

Java

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() に渡します。

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)

Java

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

ファイル URI の使用

InputImage オブジェクトをファイルの URI から作成するには、アプリ コンテキストとファイルの URI を InputImage.fromFilePath() に渡します。これは、ACTION_GET_CONTENT インテントを使用して、ギャラリー アプリから画像を選択するようにユーザーに促すときに便利です。

Kotlin

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

Java

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

ByteBuffer または ByteArray の使用

ByteBuffer または ByteArray から InputImage オブジェクトを作成するには、media.Image 入力について前述したように、まず画像の回転角度を計算します。次に、画像の高さ、幅、カラー エンコード形式、回転角度とともに、バッファまたは配列を含む InputImage オブジェクトを作成します。

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);

Bitmap の使用

Bitmap オブジェクトから InputImage オブジェクトを作成するには、次の宣言を行います。

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)

Java

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

画像は Bitmap オブジェクトと回転角度で表されます。

3.BarcodeScanner のインスタンスを取得する

Kotlin

val scanner = BarcodeScanning.getClient()
// Or, to specify the formats to recognize:
// val scanner = BarcodeScanning.getClient(options)

Java

BarcodeScanner scanner = BarcodeScanning.getClient();
// Or, to specify the formats to recognize:
// BarcodeScanner scanner = BarcodeScanning.getClient(options);

4. 画像を処理する

画像を process メソッドに渡します。

Kotlin

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

Java

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

5. バーコードから情報を取得する

バーコード認識オペレーションが成功すると、Barcode オブジェクトのリストが成功リスナーに渡されます。各 Barcode オブジェクトは、画像内で検出されたバーコードを表します。バーコードごとに、入力画像の境界座標と、バーコードによってエンコードされた元データを取得できます。また、バーコード スキャナがバーコードでエンコードされたデータの種類を判別できた場合は、解析済みのデータを含むオブジェクトを取得できます。

次に例を示します。

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) {
        Barcode.TYPE_WIFI -> {
            val ssid = barcode.wifi!!.ssid
            val password = barcode.wifi!!.password
            val type = barcode.wifi!!.encryptionType
        }
        Barcode.TYPE_URL -> {
            val title = barcode.url!!.title
            val url = barcode.url!!.url
        }
    }
}

Java

for (Barcode 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 Barcode.TYPE_WIFI:
            String ssid = barcode.getWifi().getSsid();
            String password = barcode.getWifi().getPassword();
            int type = barcode.getWifi().getEncryptionType();
            break;
        case Barcode.TYPE_URL:
            String title = barcode.getUrl().getTitle();
            String url = barcode.getUrl().getUrl();
            break;
    }
}

リアルタイムのパフォーマンスを改善するためのヒント

リアルタイム アプリケーションでバーコードをスキャンする場合は、最適なフレームレートを得るために次のガイドラインに従ってください。

  • カメラのネイティブ解像度で入力をキャプチャしないでください。一部のデバイスでは、ネイティブ解像度で入力をキャプチャすると、非常に大きな画像(10 メガピクセル以上)が生成されるため、レイテンシが非常に低く、精度にメリットはありません。代わりに、バーコード検出に必要なサイズ(通常は 2 メガピクセル以下)のみをカメラにリクエストしてください。

    スキャン速度が重要な場合は、画像キャプチャの解像度をさらに下げることができます。ただし、上記のバーコードの最小サイズ要件に注意してください。

    一連のストリーミング動画フレームからバーコードを認識しようとすると、認識機能がフレームごとに異なる結果を生成することがあります。適切な結果を返すと確信するには、同じ値が連続して得られるまで待つ必要があります。

    ITF と CODE-39 ではチェックサム ディジットはサポートされていません。

  • Camera API または camera2 API を使用する場合は、検出機能の呼び出しをスロットリングします。検出機能の実行中に新しい動画フレームが使用可能になった場合は、そのフレームをドロップします。例については、クイックスタート サンプルアプリの VisionProcessorBase クラスをご覧ください。
  • CameraX API を使用する場合は、バックプレッシャー戦略がデフォルト値の ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST に設定されていることを確認してください。これにより、分析のために一度に 1 つのイメージのみが配信されることが保証されます。アナライザがビジー状態のときにさらに多くの画像が生成された場合、それらの画像は自動的に破棄され、配信のキューには追加されません。ImageProxy.close() を呼び出して分析対象のイメージを閉じると、次の最新のイメージが配信されます。
  • 検出機能の出力を使用して入力画像にグラフィックスをオーバーレイする場合は、まず ML Kit から結果を取得してから、画像とオーバーレイを 1 つのステップでレンダリングします。これにより、ディスプレイ サーフェスに入力フレームごとに 1 回だけレンダリングされます。例については、クイックスタート サンプルアプリの CameraSourcePreview クラスと GraphicOverlay クラスをご覧ください。
  • Camera2 API を使用する場合は、ImageFormat.YUV_420_888 形式で画像をキャプチャします。古い Camera API を使用する場合は、ImageFormat.NV21 形式で画像をキャプチャします。