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

ML Kit を使用して画像にラベルを付ける（Android）

ML Kit を使用すると、画像内で認識されたオブジェクトにラベルを付けることができます。ML Kit に付属のデフォルトモデルは、400 を超えるラベルをサポートしています。

機能	バンドル解除	バンドル
実装	モデルは Google Play 開発者サービス経由で動的にダウンロードされます。	モデルはビルド時に静的にリンクされます。
アプリのサイズ	サイズが約 200 KB 増加します。	サイズが約 5.7 MB 増加します。
初期化時間	初めて使用する前にモデルのダウンロードを待つ必要がある場合があります。	モデルはすぐに利用可能

試してみる

サンプルアプリを試して、この API の使用例を確認してください。

始める前に

この API には Android API レベル 21 以降が必要です。アプリのビルドファイルで minSdkVersion の値が 21 以上であることを確認します。

プロジェクトレベルの 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:image-labeling:17.0.9'
}

Google Play 開発者サービスでモデルを使用する場合:

dependencies {
  // ...
  // Use this dependency to use the dynamically downloaded model in Google Play Services
  implementation 'com.google.android.gms:play-services-mlkit-image-labeling:16.0.8'
}

Google Play 開発者サービスでモデルを使用する場合は、アプリが Google Play ストアからインストールされたら、モデルをデバイスに自動的にダウンロードするようにアプリを構成できます。この構成を行うには、アプリの AndroidManifest.xml ファイルに次の宣言を追加します。
```
<application ...>
      ...
      <meta-data
          android:name="com.google.mlkit.vision.DEPENDENCIES"
          android:value="ica" >
      
</application>
```
Google Play 開発者サービスの ModuleInstallClient API を使用して、モデルの可用性を明示的に確認し、ダウンロードをリクエストすることもできます。

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

これで、画像にラベルを付ける準備が整いました。

1. 入力画像を準備する

画像から 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 の使用

ファイルの URI から InputImage オブジェクトを作成するには、アプリコンテキストとファイルの 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 オブジェクトと回転角度で表されます。

2. 画像ラベラーを構成して実行する

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

まず、ImageLabeler のインスタンスを取得します。

デバイス上の画像ラベラーを使用する場合は、次の宣言を行います。

Kotlin

// To use default options:
val labeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS)

// Or, to set the minimum confidence required:
// val options = ImageLabelerOptions.Builder()
//     .setConfidenceThreshold(0.7f)
//     .build()
// val labeler = ImageLabeling.getClient(options)
ImageLabelingActivity.kt

Java

// To use default options:
ImageLabeler labeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS);

// Or, to set the minimum confidence required:
// ImageLabelerOptions options =
//     new ImageLabelerOptions.Builder()
//         .setConfidenceThreshold(0.7f)
//         .build();
// ImageLabeler labeler = ImageLabeling.getClient(options);
ImageLabelingActivity.java

次に、画像を 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 を閉じてください。たとえば、process メソッドから返された Task に OnCompleteListener を追加します。例については、クイックスタートサンプルアプリの VisionProcessorBase クラスをご覧ください。

3. ラベル付きオブジェクトに関する情報を取得する

画像のラベル付けオペレーションが成功すると、ImageLabel オブジェクトのリストが成功リスナーに渡されます。各 ImageLabel オブジェクトは画像内でラベル付けされたものを表します。ベースモデルは 400 を超えるラベルをサポートしています。各ラベルのテキストの説明、モデルでサポートされているすべてのラベルのインデックス、マッチの信頼スコアを取得できます。次に例を示します。

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

ML Kit を使用して画像にラベルを付ける（Android）

試してみる

始める前に

1. 入力画像を準備する

media.Image の使用

Kotlin

Java

Kotlin

Java

Kotlin

Java

ファイル URI の使用

Kotlin

Java

ByteBuffer または ByteArray の使用

Kotlin

Java

Bitmap の使用

Kotlin

Java

2. 画像ラベラーを構成して実行する

Kotlin

Java

Kotlin

Java

3. ラベル付きオブジェクトに関する情報を取得する

Kotlin

Java

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

`media.Image` の使用

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

`Bitmap` の使用