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

ML Kit を使用すると、画像内のエンティティを認識してラベル付けできます。この API は、さまざまなカスタム画像分類モデルをサポートしています。モデルの互換性要件、事前トレーニング済みモデルの場所、独自のモデルのトレーニング方法については、ML Kit によるカスタムモデルをご覧ください。

画像のラベル付けをカスタムモデルと統合する方法は 2 つあります。パイプラインをアプリの一部としてバンドルする方法と、Google Play 開発者サービスに依存するバンドルされていないパイプラインを使用する方法です。バンドルされていないパイプラインを選択すると、アプリのサイズが小さくなります。詳しくは、以下の表をご覧ください。

バンドルバンドルなし
ライブラリ名com.google.mlkit:image-labeling-customcom.google.android.gms:play-services-mlkit-image-labeling-custom
実装パイプラインは、ビルド時にアプリに静的にリンクされます。パイプラインは Google Play 開発者サービスを介して動的にダウンロードされます。
アプリのサイズサイズが約 3.8 MB 増加。約 200 KB のサイズ増加。
初期化時間パイプラインはすぐに利用可能。最初に使用する前に、パイプラインがダウンロードされるのを待たなければならない場合があります。
API ライフサイクル ステージ一般提供(GA)ベータ版

カスタムモデルを統合するには、アプリのアセット フォルダに入れてモデルをバンドルする方法と、Firebase から動的にダウンロードする方法の 2 つがあります。次の表は、これら 2 つのオプションを比較したものです。

バンドルモデル ホストされているモデル
このモデルはアプリの APK の一部であるため、サイズが大きくなります。 モデルは APK の一部ではありません。これは、Firebase Machine Learning にアップロードすることでホストされます。
Android デバイスがオフラインの場合でも、モデルをすぐに利用できます モデルがオンデマンドでダウンロードされる
Firebase プロジェクトは不要 Firebase プロジェクトが必要
モデルを更新するにはアプリを再公開する必要があります アプリを再公開することなくモデルの更新を push できる
組み込みの A/B テストなし Firebase Remote Config による簡単な A/B テスト

試してみる

始める前に

  1. プロジェクト レベルの build.gradle ファイルの buildscript セクションと allprojects セクションの両方に Google の Maven リポジトリを含めます。

  2. 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.2'
    }
    

    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-beta5'
    }
    
  3. 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 を使用して、パイプラインの可用性を明示的に確認して、ダウンロードをリクエストすることもできます。

    インストール時のパイプラインのダウンロードを有効にしない場合、または明示的なダウンロードをリクエストしない場合は、ラベラーの初回実行時にパイプラインがダウンロードされます。ダウンロードが完了する前に行ったリクエストでは結果は生成されません。

  4. Firebase からモデルを動的にダウンロードする場合は、linkFirebase 依存関係を追加します。

    Firebase からモデルを動的にダウンロードするには、linkFirebase 依存関係を追加します。

    dependencies {
      // ...
      // Image labeling feature with model downloaded from Firebase
      implementation 'com.google.mlkit:image-labeling-custom:17.0.2'
      // Or use the dynamically downloaded pipeline in Google Play Services
      // implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta5'
      implementation 'com.google.mlkit:linkfirebase:17.0.0'
    }
    
  5. モデルをダウンロードする場合は、Firebase を Android プロジェクトに追加します(まだ行っていない場合)。これは、モデルをバンドルする場合には必要ありません。

1. モデルを読み込む

ローカル モデルソースを構成する

モデルをアプリにバンドルするには:

  1. モデルファイル(拡張子は通常 .tflite または .lite)をアプリの assets/ フォルダにコピーします。(先にフォルダを作成する必要がある場合があります。それには、app/ フォルダを右クリックし、次に [新規] > [フォルダ] > [Assets フォルダ] をクリックします)。

  2. 次に、アプリのビルド時に Gradle がモデルファイルを圧縮しないように、アプリの build.gradle ファイルに次の行を追加します。

    android {
        // ...
        aaptOptions {
            noCompress "tflite"
            // or noCompress "lite"
        }
    }
    

    モデルファイルはアプリ パッケージに含められ、ML Kit から生のアセットとして使用できます。

  3. モデルファイルへのパスを指定して 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 によってホストされるモデルソースを構成する

リモートでホストされるモデルを使用するには、公開時にモデルに割り当てた名前を指定して、FirebaseModelSourceRemoteModel オブジェクトを作成します。

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 の使用

InputImage オブジェクトを media.Image オブジェクトから作成するには(デバイスのカメラから画像をキャプチャする場合など)、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 オブジェクトを ImageLabelerprocess() メソッドに渡します。

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 つのイメージのみが配信されることが保証されます。Analyzer がビジー状態のときにそれ以上の画像が生成されると、自動的に破棄され、配信のキューに登録されません。ImageProxy.close() を呼び出して分析対象の画像を閉じると、次の最新の画像が配信されます。
  • 画像ラベラーの出力を使用して入力画像にグラフィックをオーバーレイする場合は、まず ML Kit から結果を取得し、画像とオーバーレイを 1 つのステップでレンダリングします。これにより、ディスプレイ サーフェスに入力フレームごとに 1 回だけレンダリングされます。例については、クイックスタート サンプルアプリの CameraSourcePreview クラスと GraphicOverlay クラスをご覧ください。
  • Camera2 API を使用する場合は、ImageFormat.YUV_420_888 形式で画像をキャプチャします。古い Camera API を使用する場合は、ImageFormat.NV21 形式で画像をキャプチャしてください。