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

Android でカスタムモデルを使用して画像にラベルを付ける

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" />
    
</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 から生のアセットとして使用できます。

注: Android Gradle プラグインのバージョン 4.1 以降、デフォルトで .tflite が noCompress リストに追加され、上記の必要はなくなりました。
モデルファイルのパスを指定して、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();
```
注: Android 11（API レベル 30）を対象とするアプリでは、Android 11 のストレージアップデートにより、外部ストレージからファイルにアクセスできなくなりました。
注: Firebase の AutoML Vision Edge（Google Cloud 以外）でトレーニングしたモデルがある場合、上記は機能しない可能性があります。手順については、移行ガイドをご覧ください。

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
}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.画像ラベラーを実行する

画像内のオブジェクトにラベルを付けるには、image オブジェクトを ImageLabeler の process() メソッドに渡します。

Kotlin

labeler.process(image)
        .addOnSuccessListener { labels ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }ImageLabelingActivity.kt

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

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

4. ラベル付きエンティティに関する情報を取得する

画像のラベル付けオペレーションが成功すると、ImageLabel オブジェクトのリストが成功リスナーに渡されます。各 ImageLabel オブジェクトは画像内でラベル付けされたものを表します。各ラベルのテキストの説明（TensorFlow Lite モデルファイルのメタデータで使用できる場合）、信頼スコア、インデックスを取得できます。例:

Kotlin

for (label in labels) {
    val text = label.text
    val confidence = label.confidence
    val index = label.index
}ImageLabelingActivity.kt

Java

for (ImageLabel label : labels) {
    String text = label.getText();
    float confidence = label.getConfidence();
    int index = label.getIndex();
}ImageLabelingActivity.java

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

リアルタイムのアプリケーションでラベルイメージを使用する場合は、適切なフレームレートを得るために次のガイドラインに従ってください。

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 形式で画像をキャプチャします。

Android でカスタムモデルを使用して画像にラベルを付ける

試してみる

始める前に

1. モデルを読み込む

ローカルモデル ソースの構成

Kotlin

Java

Firebase がホストするモデルソースを構成する

Kotlin

Java

Kotlin

Java

画像ラベラーを構成する

Kotlin

Java

Kotlin

Java

Kotlin

Java

2. 入力画像を準備する

media.Image の使用

Kotlin

Java

Kotlin

Java

Kotlin

Java

ファイル URI の使用

Kotlin

Java

ByteBuffer または ByteArray の使用

Kotlin

Java

Bitmap の使用

Kotlin

Java

3.画像ラベラーを実行する

Kotlin

Java

4. ラベル付きエンティティに関する情報を取得する

Kotlin

Java

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

ローカルモデルソースの構成

`media.Image` の使用

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

`Bitmap` の使用