このページは Cloud Translation API によって翻訳されました。

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

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

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

試してみる

サンプルアプリを試して、この API の使用例をご覧ください。
この API のエンドツーエンドの実装については、マテリアルデザインショーケースアプリをご覧ください。

始める前に

この API には Android API レベル 19 以降が必要です。アプリのビルドファイルで minSdkVersion 値 19 以上が使用されていることを確認します。

プロジェクトレベルの build.gradle ファイルで、buildscript セクションと allprojects セクションの両方に Google の Maven リポジトリを含めます。
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'
}
```
Google Play 開発者サービスでモデルを使用する場合は、アプリが Play ストアからインストールされたら、モデルをデバイスに自動ダウンロードするようにアプリを構成できます。これを行うには、アプリの AndroidManifest.xml ファイルに次の宣言を追加します。
```
<application ...>
      ...
      <meta-data
          android:name="com.google.mlkit.vision.DEPENDENCIES"
          android:value="barcode" >
      
</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()BarcodeScanningActivity.kt

Java

BarcodeScannerOptions options =
        new BarcodeScannerOptions.Builder()
        .setBarcodeFormats(
                Barcode.FORMAT_QR_CODE,
                Barcode.FORMAT_AZTEC)
        .build();BarcodeScanningActivity.java

次の形式がサポートされています。

コード 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）
Aztec（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
}MLKitVisionImage.kt

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)MLKitVisionImage.kt

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()
}MLKitVisionImage.kt

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
)MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

Java

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

`Bitmap` の使用

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

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)MLKitVisionImage.kt

Java

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

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

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

Kotlin

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

Java

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

4. 画像を処理する

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

Kotlin

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

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
                // ...
            }
        });BarcodeScanningActivity.java

注: CameraX API を使用している場合は、必ず ImageProxy の使用が終了したら、process メソッドから返された Task に OnCompleteListener を追加するなどして必ず閉じてください。例については、クイックスタートサンプルアプリの VisionProcessorBase クラスをご覧ください。

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
        }
    }
}BarcodeScanningActivity.kt

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;
    }
}BarcodeScanningActivity.java

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

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

カメラのネイティブ解像度で入力をキャプチャしないでください。一部のデバイスでは、ネイティブ解像度で入力をキャプチャすると、非常に大きな（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 形式で画像をキャプチャします。

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

試してみる

始める前に

入力画像に関するガイドライン

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

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

2. Prepare the input image

Using a media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

ファイル URI の使用

Kotlin

Java

ByteBuffer または ByteArray の使用

Kotlin

Java

Bitmap の使用

Kotlin

Java

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

Kotlin

Java

4. 画像を処理する

Kotlin

Java

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

Kotlin

Java

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

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

Using a `media.Image`

`ByteBuffer` または `ByteArray` の使用

`Bitmap` の使用