ML Kit を使用すると、画像内のエンティティを認識してラベル付けできます。この API は、さまざまなカスタム画像分類モデルをサポートしています。モデルの互換性要件、事前トレーニング済みモデルの場所、独自のモデルをトレーニングする方法については、ML Kit のカスタムモデルをご覧ください。
画像ラベル付けをカスタムモデルと統合するには、パイプラインをアプリの一部としてバンドルする方法と、Google Play 開発者サービスに依存するバンドルされていないパイプラインを使用する方法の 2 つがあります。バンドルされていないパイプラインを選択すると、アプリのサイズが小さくなります。詳しくは、以下の表をご覧ください。
バンドル | バンドルなし | |
---|---|---|
ライブラリ名 | com.google.mlkit:image-labeling-custom | com.google.android.gms:play-services-mlkit-image-labeling-custom |
実装 | パイプラインはビルド時に静的にアプリにリンクされます。 | パイプラインは Google Play 開発者サービスを介して動的にダウンロードされます。 |
アプリのサイズ | 約 3.8 MB のサイズ増大。 | 約 200 KB のサイズ増加。 |
初期化時間 | パイプラインは直ちに利用可能 | パイプラインのダウンロードが完了するまで待たなければならない場合があります。 |
API ライフサイクル ステージ | 一般提供(GA) | Beta |
カスタムモデルを統合するには、モデルをアプリのアセット フォルダに入れてモデルをバンドルする方法と、Firebase から動的にダウンロードする方法が 2 つあります。次の表は、これら 2 つのオプションを比較したものです。
バンドルモデル | ホストされているモデル |
---|---|
モデルがアプリの APK の一部であるため、サイズが大きくなります。 | モデルは APK に含まれていません。Firebase Machine Learning にアップロードすることでホストされます。 |
このモデルは、Android デバイスがオフラインのときでもすぐに利用できます。 | モデルがオンデマンドでダウンロードされる |
Firebase プロジェクトは不要 | Firebase プロジェクトが必要 |
モデルを更新するにはアプリを再公開する必要があります | アプリを再公開することなくモデルの更新を push できる |
組み込みの A/B テストなし | Firebase Remote Config による簡単な A/B テスト |
試してみる
- バンドルされたモデルの使用例については、Vision クイックスタート アプリをご覧ください。ホストされるモデルの使用例については、automl クイックスタート アプリをご覧ください。
始める前に
プロジェクト レベルの
build.gradle
ファイルのbuildscript
セクションとallprojects
セクションの両方に Google の Maven リポジトリを組み込みます。ML Kit Android ライブラリの依存関係をモジュールのアプリレベルの Gradle ファイル(通常は
app/build.gradle
)に追加します。ニーズに応じて、次のいずれかの依存関係を選択します。パイプラインをアプリにバンドルするには:
dependencies { // ... // Use this dependency to bundle the pipeline with your app implementation 'com.google.mlkit:image-labeling-custom:17.0.1' }
Google Play 開発者サービスでパイプラインを使用するには:
dependencies { // ... // Use this dependency to use the dynamically downloaded pipeline in Google Play Services implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta4' }
Google Play 開発者サービスでパイプラインを使用する場合は、アプリが Play ストアからインストールされたら、パイプラインをデバイスに自動的にダウンロードするようにアプリを構成できます。そのためには、アプリの
AndroidManifest.xml
ファイルに次の宣言を追加します。<application ...> ... <meta-data android:name="com.google.mlkit.vision.DEPENDENCIES" android:value="custom_ica" /> <!-- To use multiple downloads: android:value="custom_ica,download2,download3" --> </application>
また、パイプラインの可用性を明示的に確認したり、Google Play 開発者サービスの ModuleInstallClient API を介してダウンロードをリクエストしたりすることもできます。
インストール時のパイプライン ダウンロードを有効にしない場合や、明示的なダウンロードをリクエストしない場合、ラベラーを初めて実行するときにパイプラインがダウンロードされます。ダウンロードが完了する前にリクエストを送信しても、結果は生成されません。
Firebase からモデルを動的にダウンロードする場合は、
linkFirebase
依存関係を追加します。Firebase からモデルを動的にダウンロードするには、
linkFirebase
の依存関係を追加します。dependencies { // ... // Image labeling feature with model downloaded from Firebase implementation 'com.google.mlkit:image-labeling-custom:17.0.1' // Or use the dynamically downloaded pipeline in Google Play Services // implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta4' implementation 'com.google.mlkit:linkfirebase:17.0.0' }
モデルをダウンロードするには、Firebase を Android プロジェクトに追加します(まだ行っていない場合)。これは、モデルをバンドルする際には必要ありません。
1. モデルを読み込む
ローカルモデル ソースの構成
モデルをアプリにバンドルするには:
モデルファイル(拡張子は通常
.tflite
または.lite
)をアプリのassets/
フォルダにコピーします。(場合によっては、最初にapp/
フォルダを右クリックし、次に [新規] > [フォルダ] > [Assets フォルダ] をクリックします)。次に、アプリのビルド時に Gradle がモデルファイルを圧縮しないように、アプリの
build.gradle
ファイルに以下を追加します。android { // ... aaptOptions { noCompress "tflite" // or noCompress "lite" } }
モデルファイルはアプリ パッケージに含められ、ML Kit から生のアセットとして使用できます。
モデルファイルのパスを指定して、
LocalModel
オブジェクトを作成します。Kotlin
val localModel = LocalModel.Builder() .setAssetFilePath("model.tflite") // or .setAbsoluteFilePath(absolute file path to model file) // or .setUri(URI to model file) .build()
Java
LocalModel localModel = new LocalModel.Builder() .setAssetFilePath("model.tflite") // or .setAbsoluteFilePath(absolute file path to model file) // or .setUri(URI to model file) .build();
Firebase がホストするモデルソースを構成する
リモートでホストされるモデルを使用するには、FirebaseModelSource
までに RemoteModel
オブジェクトを作成します。その際に、モデルを公開したときに割り当てた名前を指定します。
Kotlin
// Specify the name you assigned in the Firebase console. val remoteModel = CustomRemoteModel .Builder(FirebaseModelSource.Builder("your_model_name").build()) .build()
Java
// Specify the name you assigned in the Firebase console. CustomRemoteModel remoteModel = new CustomRemoteModel .Builder(new FirebaseModelSource.Builder("your_model_name").build()) .build();
次に、ダウンロードを許可する条件を指定してモデルのダウンロード タスクを開始します。モデルがデバイスにない場合、または新しいバージョンのモデルが使用可能な場合、このタスクは Firebase から非同期でモデルをダウンロードします。
Kotlin
val downloadConditions = DownloadConditions.Builder() .requireWifi() .build() RemoteModelManager.getInstance().download(remoteModel, downloadConditions) .addOnSuccessListener { // Success. }
Java
DownloadConditions downloadConditions = new DownloadConditions.Builder() .requireWifi() .build(); RemoteModelManager.getInstance().download(remoteModel, downloadConditions) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(@NonNull Task task) { // Success. } });
多くのアプリは、初期化コードでモデルのダウンロード タスクを開始しますが、モデルを使用する前に開始することもできます。
画像ラベラーを構成する
モデルソースを構成したら、そのソースのいずれか 1 つから ImageLabeler
オブジェクトを作成します。
使用できるオプションを以下に示します。
オプション | |
---|---|
confidenceThreshold
|
検出されたラベルの最小信頼スコア。設定しなかった場合、モデルのメタデータで指定された分類器のしきい値が使用されます。モデルにメタデータが含まれていない場合、またはメタデータが分類器のしきい値を指定していない場合は、デフォルトのしきい値である 0.0 が使用されます。 |
maxResultCount
|
返されるラベルの最大数。設定しない場合は、デフォルト値の 10 が使用されます。 |
ローカル バンドルモデルのみがある場合は LocalModel
オブジェクトからラベラーを作成するだけです。
Kotlin
val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel) .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build() val labeler = ImageLabeling.getClient(customImageLabelerOptions)
Java
CustomImageLabelerOptions customImageLabelerOptions = new CustomImageLabelerOptions.Builder(localModel) .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build(); ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);
リモートでホストされるモデルがある場合は、実行する前にモデルがダウンロードされていることを確認する必要があります。モデルのダウンロード タスクのステータスは、モデル マネージャーの isModelDownloaded()
メソッドを使用して確認できます。
ラベラーを実行する前に確認する必要があるだけですが、リモートホストモデルとローカル バンドルモデルの両方がある場合は、画像ラベラーをインスタンス化するときにこのチェックを行うのが適切な場合があります。リモートモデルをダウンロードしている場合はそのモデルを作成し、それ以外の場合はローカルモデルからラベラーを作成します。
Kotlin
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener { isDownloaded -> val optionsBuilder = if (isDownloaded) { CustomImageLabelerOptions.Builder(remoteModel) } else { CustomImageLabelerOptions.Builder(localModel) } val options = optionsBuilder .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build() val labeler = ImageLabeling.getClient(options) }
Java
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(Boolean isDownloaded) { CustomImageLabelerOptions.Builder optionsBuilder; if (isDownloaded) { optionsBuilder = new CustomImageLabelerOptions.Builder(remoteModel); } else { optionsBuilder = new CustomImageLabelerOptions.Builder(localModel); } CustomImageLabelerOptions options = optionsBuilder .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build(); ImageLabeler labeler = ImageLabeling.getClient(options); } });
リモートでホストされるモデルのみがある場合は、モデルがダウンロード済みであることを確認するまで、モデルに関連する機能を無効にする必要があります(UI の一部をグレー表示または非表示にするなど)。確認はモデル マネージャーの download()
メソッドにリスナーを接続して行います。
Kotlin
RemoteModelManager.getInstance().download(remoteModel, conditions) .addOnSuccessListener { // Download complete. Depending on your app, you could enable the ML // feature, or switch from the local model to the remote model, etc. }
Java
RemoteModelManager.getInstance().download(remoteModel, conditions) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(Void v) { // Download complete. Depending on your app, you could enable // the ML feature, or switch from the local model to the remote // model, etc. } });
2. 入力画像を準備する
次に、ラベルを付ける画像ごとに、画像からInputImage
オブジェクトを作成します。Bitmap
を使用するか、camera2 API(YUV_420_888 media.Image
)を使用すると、画像ラベラーの処理が速くなります。可能であれば、このフォーマットの使用をおすすめします。
さまざまなソースから InputImage
オブジェクトを作成できます。以下では、この各オブジェクトについて説明します。
media.Image
の使用
media.Image
オブジェクトから InputImage
オブジェクト(デバイスのカメラから画像をキャプチャする場合など)を作成するには、media.Image
オブジェクトと画像の回転を InputImage.fromMediaImage()
に渡します。
CameraX ライブラリを使用する場合は、OnImageCapturedListener
クラスと ImageAnalysis.Analyzer
クラスによって回転値が計算されます。
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.画像ラベラーを実行する
画像内のオブジェクトにラベルを付けるには、image
オブジェクトを ImageLabeler
の process()
メソッドに渡します。
Kotlin
labeler.process(image) .addOnSuccessListener { labels -> // Task completed successfully // ... } .addOnFailureListener { e -> // Task failed with an exception // ... }
Java
labeler.process(image) .addOnSuccessListener(new OnSuccessListener<List<ImageLabel>>() { @Override public void onSuccess(List<ImageLabel> labels) { // Task completed successfully // ... } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { // Task failed with an exception // ... } });
4. ラベル付きエンティティに関する情報を取得する
画像のラベル付けオペレーションが成功すると、ImageLabel
オブジェクトのリストが成功リスナーに渡されます。各 ImageLabel
オブジェクトは画像内でラベル付けされたものを表します。各ラベルのテキストの説明(TensorFlow Lite モデルファイルのメタデータで使用できる場合)、信頼スコア、インデックスを取得できます。例:
Kotlin
for (label in labels) { val text = label.text val confidence = label.confidence val index = label.index }
Java
for (ImageLabel label : labels) { String text = label.getText(); float confidence = label.getConfidence(); int index = label.getIndex(); }
リアルタイムのパフォーマンスを改善するためのヒント
リアルタイムのアプリケーションでラベルイメージを使用する場合は、適切なフレームレートを得るために次のガイドラインに従ってください。
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
形式で画像をキャプチャします。