ML Kit を使用してオブジェクトを検出して追跡する(Android)

ML Kit を使用すると、連続する動画フレーム内のオブジェクトを検出してトラッキングできます。

ML Kit に画像を渡すと、画像内の最大 5 つのオブジェクトと、画像内の各オブジェクトの位置が検出されます。動画ストリーム内のオブジェクトを検出する場合は、各オブジェクトに固有の ID を割り当てます。この ID を使用して、フレーム間でオブジェクトをトラックできます。また、大まかなオブジェクト分類を有効にして、オブジェクトに幅広いカテゴリの説明をラベル付けすることもできます。

試してみる

始める前に

  1. プロジェクト レベルの build.gradle ファイルにおいて、buildscript セクションと allprojects セクションの両方に Google の Maven リポジトリを組み込みます。
  2. ML Kit Android ライブラリの依存関係をモジュールのアプリレベルの Gradle ファイル(通常は app/build.gradle)に追加します。
    dependencies {
      // ...
    
      implementation 'com.google.mlkit:object-detection:17.0.2'
    
    }

1. オブジェクト検出を構成する

オブジェクトを検出してトラッキングするには、まず ObjectDetector のインスタンスを作成し、必要に応じてデフォルトから変更する検出設定を指定します。

  1. ObjectDetectorOptions オブジェクトを使用して、ユースケースにオブジェクト検出を構成します。次の設定を変更できます。

    オブジェクト検出の設定
    検出モード STREAM_MODE(デフォルト)| SINGLE_IMAGE_MODE

    STREAM_MODE(デフォルト)では、オブジェクト検出は低レイテンシで実行されますが、最初の数回の検出の呼び出しで不完全な結果(未指定の境界ボックスやカテゴリラベルなど)が発生する可能性があります。また、STREAM_MODE では、検出でオブジェクトにトラッキング ID が割り当てられます。これを使用して、フレームをまたいでオブジェクトをトラックできます。このモードは、オブジェクトをトラックする場合、または動画ストリームをリアルタイムで処理する場合のように低レイテンシが重要な場合に使用します。

    SINGLE_IMAGE_MODE では、オブジェクトの境界ボックスが決定された後にオブジェクト検出が結果を返します。分類も有効にすると、境界ボックスとカテゴリラベルの両方が利用可能になった後に結果が返されます。結果として、検出のレイテンシが潜在的に長くなります。また、SINGLE_IMAGE_MODE ではトラッキング ID が割り当てられません。レイテンシが重要ではなく、部分的な結果を処理しない場合は、このモードを使用します。

    複数のオブジェクトを検出してトラックする false(デフォルト)| true

    最大 5 つのオブジェクトを検出してトラックするか、最も目立つオブジェクトのみをトラックするか(デフォルト)。

    オブジェクトを分類する false(デフォルト)| true

    検出されたオブジェクトをおまかなカテゴリに分類するかどうか。有効にすると、オブジェクト検出でファッション グッズ、食品、家庭用品、場所、植物のカテゴリにオブジェクトを分類します。

    オブジェクトの検出とトラッキングの API は主に、次の 2 つのユースケース用に最適化されています。

    • カメラのファインダー内で最も目立つオブジェクトをライブで検出してトラッキングする。
    • 静止画像からの複数のオブジェクトの検出。

    これらのユースケースに API を構成するには以下を実行します。

    Kotlin

    // Live detection and tracking
    val options = ObjectDetectorOptions.Builder()
            .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
            .enableClassification()  // Optional
            .build()
    
    // Multiple object detection in static images
    val options = ObjectDetectorOptions.Builder()
            .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
            .enableMultipleObjects()
            .enableClassification()  // Optional
            .build()

    Java

    // Live detection and tracking
    ObjectDetectorOptions options =
            new ObjectDetectorOptions.Builder()
                    .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
                    .enableClassification()  // Optional
                    .build();
    
    // Multiple object detection in static images
    ObjectDetectorOptions options =
            new ObjectDetectorOptions.Builder()
                    .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
                    .enableMultipleObjects()
                    .enableClassification()  // Optional
                    .build();
  2. ObjectDetector のインスタンスを取得します。

    Kotlin

    val objectDetector = ObjectDetection.getClient(options)

    Java

    ObjectDetector objectDetector = ObjectDetection.getClient(options);

2. 入力画像を準備する

オブジェクトを検出してトラックするには、ObjectDetector インスタンスの process() メソッドに画像を渡します。

オブジェクト検出は、Bitmap、NV21 ByteBuffer、または YUV_420_888 media.Image から直接実行されます。これらのソースのいずれかに直接アクセスできる場合は、これらのソースから InputImage を作成することをおすすめします。他のソースから InputImage を構築すると、Google が内部でコンバージョンを処理するため、効率が低下する可能性があります。

シーケンス内の動画または画像の各フレームに対して、次の操作を行います。

さまざまなソースから 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 の使用

ファイルの 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. 画像を処理する

画像を process() メソッドに渡します。

Kotlin

objectDetector.process(image)
    .addOnSuccessListener { detectedObjects ->
        // Task completed successfully
        // ...
    }
    .addOnFailureListener { e ->
        // Task failed with an exception
        // ...
    }

Java

objectDetector.process(image)
    .addOnSuccessListener(
        new OnSuccessListener<List<DetectedObject>>() {
            @Override
            public void onSuccess(List<DetectedObject> detectedObjects) {
                // Task completed successfully
                // ...
            }
        })
    .addOnFailureListener(
        new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });

4. 検出されたオブジェクトに関する情報を取得する

process() の呼び出しが成功すると、DetectedObject のリストが成功リスナーに渡されます。

DetectedObject には次のプロパティが含まれています。

境界ボックス 画像内のオブジェクトの位置を示す Rect
トラッキング ID イメージ間でオブジェクトを識別する整数。SINGLE_IMAGE_MODE では、NULL です。
ラベル
ラベルの説明 ラベルのテキストによる説明。これは、PredefinedCategory で定義されている String 定数のいずれかになります。
ラベル インデックス 分類システムでサポートされているすべてのラベルの中でのラベルのインデックス。これは、PredefinedCategory で定義されている整数定数のいずれかになります。
ラベルの信頼度 オブジェクト分類の信頼値。

Kotlin

for (detectedObject in detectedObjects) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
        val text = label.text
        if (PredefinedCategory.FOOD == text) {
            ...
        }
        val index = label.index
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        val confidence = label.confidence
    }
}

Java

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (DetectedObject detectedObject : detectedObjects) {
    Rect boundingBox = detectedObject.getBoundingBox();
    Integer trackingId = detectedObject.getTrackingId();
    for (Label label : detectedObject.getLabels()) {
        String text = label.getText();
        if (PredefinedCategory.FOOD.equals(text)) {
            ...
        }
        int index = label.getIndex();
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        float confidence = label.getConfidence();
    }
}

優れたユーザー エクスペリエンスを確保する

最高のユーザー エクスペリエンスを提供するため、次のガイドラインに従ってアプリを作成してください。

  • オブジェクトの検出に成功するかどうかは、オブジェクトの視覚的な複雑さによります。視覚的特徴の少ないオブジェクトは、検出対象の画像の大部分を占めていないと検出に成功しない可能性があります。検出するオブジェクトの種類に適した入力をキャプチャするためのガイダンスを用意する必要があります。
  • 分類を使用するときに、サポート対象のカテゴリに該当しないオブジェクトを検出する場合は、未知のオブジェクトに対して特別な処理を実装してください。

また、ML Kit Material Design ショーケース アプリと Material Design の Patterns for machine learning-powered features のコレクションも確認してください。

パフォーマンスの向上

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

  • リアルタイム アプリケーションでストリーミング モードを使用する場合は、複数のオブジェクト検出を使用しないでください。ほとんどのデバイスは十分なフレームレートを生成できません。

  • 不要な場合は、分類を無効にします。

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