ML Kit を使用すると、バーコードを認識してデコードできます。
特徴 | バンドルなし | バンドル |
---|---|---|
実装 | モデルは Google Play 開発者サービスを介して動的にダウンロードされます。 | モデルはビルド時にアプリに静的にリンクされます。 |
アプリのサイズ | サイズを約 200 KB 拡大。 | サイズが約 2.4 MB 増加します。 |
初期化時間 | 最初に使用する前に、モデルのダウンロードを待たなければならない場合があります。 | モデルはすぐに使用できます。 |
試してみる
- サンプルアプリを試して、この API の使用例を確認します。
- この API のエンドツーエンドの実装については、マテリアル デザイン ショーケース アプリをご覧ください。
始める前に
プロジェクト レベルの
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 開発者サービスでモデルを使用することを選択した場合、アプリが 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 anInputImage
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
形式で画像をキャプチャします。
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2024-02-28 UTC。