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();
次の形式がサポートされています。
- Code 128(
FORMAT_CODE_128
) - Code 39(
FORMAT_CODE_39
) - Code 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
) - Data Matrix(
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 の使用
ファイル URI から InputImage
オブジェクトを作成するには、アプリ コンテキストとファイル 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-07-12 UTC。