ML Kit を使用すると、動画のフレーム間でオブジェクトを検出してトラックできます。
ML Kit に画像を渡すと、ML Kit は各画像について、最大 5 つの検出されたオブジェクトとその画像内での位置のリストを返します。動画ストリーム内のオブジェクトを検出する場合は、すべてのオブジェクトに ID を割り当てます。この ID を使用して、画像全体でオブジェクトをトラックできます。また、大まかなオブジェクト分類を有効にして、オブジェクトに幅広いカテゴリの説明をラベル付けすることもできます。
始める前に
- まだ Firebase を Android プロジェクトに追加していない場合は追加します。
- ML Kit Android ライブラリの依存関係をモジュール（アプリレベル）の Gradle ファイル（通常は
app/build.gradle）に追加します。apply plugin: 'com.android.application' apply plugin: 'com.google.gms.google-services' dependencies { // ... implementation 'com.google.firebase:firebase-ml-vision:24.0.3' implementation 'com.google.firebase:firebase-ml-vision-object-detection-model:19.0.6' }
1. オブジェクト検出を構成する
オブジェクトの検出とトラッキングを開始するには、まず FirebaseVisionObjectDetector インスタンスを作成し、必要に応じてデフォルトから変更する検出設定を指定します。
FirebaseVisionObjectDetectorOptionsオブジェクトを使用して、ユースケースにオブジェクト検出を構成します。次の設定を変更できます。オブジェクト検出の設定 検出モード STREAM_MODE（デフォルト）|SINGLE_IMAGE_MODESTREAM_MODE（デフォルト）では、オブジェクト検出は低レイテンシで実行されますが、最初の数回の検出の呼び出しで不完全な結果（未指定の境界ボックスやカテゴリラベルなど）が発生する可能性があります。また、STREAM_MODEでは、検出でオブジェクトにトラッキング ID が割り当てられます。これを使用して、フレームをまたいでオブジェクトをトラックできます。このモードは、オブジェクトをトラックする場合、または動画ストリームをリアルタイムで処理する場合のように低レイテンシが重要な場合に使用します。SINGLE_IMAGE_MODEでは、検出されたオブジェクトの境界ボックスと（分類を有効にしている場合）カテゴリラベルが利用可能になるまでオブジェクト検出を待機してから結果を返します。結果として、検出のレイテンシが潜在的に長くなります。また、SINGLE_IMAGE_MODEではトラッキング ID が割り当てられません。レイテンシが重要ではなく、部分的な結果を処理しない場合は、このモードを使用します。複数のオブジェクトを検出してトラックする false（デフォルト）|true最大 5 つのオブジェクトを検出してトラックするか、最も目立つオブジェクトのみをトラックするか（デフォルト）。
オブジェクトを分類する false（デフォルト）|true検出されたオブジェクトをおまかなカテゴリに分類するかどうか。有効にすると、オブジェクト検出でファッション グッズ、食品、家庭用品、場所、植物または不明のカテゴリにオブジェクトを分類します。
オブジェクトの検出とトラッキングの API は主に、次の 2 つのユースケース用に最適化されています。
- カメラのファインダー内で最も目立つオブジェクトをライブで検出してトラッキングする
- 静止画像からの複数のオブジェクトを検出する
これらのユースケースに API を構成するには以下を実行します。
Java
// Live detection and tracking FirebaseVisionObjectDetectorOptions options = new FirebaseVisionObjectDetectorOptions.Builder() .setDetectorMode(FirebaseVisionObjectDetectorOptions.STREAM_MODE) .enableClassification() // Optional .build(); // Multiple object detection in static images FirebaseVisionObjectDetectorOptions options = new FirebaseVisionObjectDetectorOptions.Builder() .setDetectorMode(FirebaseVisionObjectDetectorOptions.SINGLE_IMAGE_MODE) .enableMultipleObjects() .enableClassification() // Optional .build();Kotlin
// Live detection and tracking val options = FirebaseVisionObjectDetectorOptions.Builder() .setDetectorMode(FirebaseVisionObjectDetectorOptions.STREAM_MODE) .enableClassification() // Optional .build() // Multiple object detection in static images val options = FirebaseVisionObjectDetectorOptions.Builder() .setDetectorMode(FirebaseVisionObjectDetectorOptions.SINGLE_IMAGE_MODE) .enableMultipleObjects() .enableClassification() // Optional .build()FirebaseVisionObjectDetectorのインスタンスを取得します。Java
FirebaseVisionObjectDetector objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector(); // Or, to change the default settings: FirebaseVisionObjectDetector objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector(options);Kotlin
val objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector() // Or, to change the default settings: val objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector(options)
2. オブジェクト検出を実行する
オブジェクトを検出してトラックするには、FirebaseVisionObjectDetector インスタンスの processImage() メソッドに画像を渡します。
シーケンス内の動画または画像の各フレームに対して、次の操作を行います。
画像から
FirebaseVisionImageオブジェクトを作成します。-
FirebaseVisionImageオブジェクトをmedia.Imageオブジェクトから作成するには（デバイスのカメラから画像をキャプチャする場合など）、media.Imageオブジェクトと画像の回転をFirebaseVisionImage.fromMediaImage()に渡します。CameraX ライブラリを使用する場合は、
OnImageCapturedListenerクラスとImageAnalysis.Analyzerクラスによって回転値が計算されるので、FirebaseVisionImage.fromMediaImage()を呼び出す前に、その回転を ML Kit のROTATION_定数のいずれかに変換するだけで済みます。Java
private class YourAnalyzer implements ImageAnalysis.Analyzer { private int degreesToFirebaseRotation(int degrees) { switch (degrees) { case 0: return FirebaseVisionImageMetadata.ROTATION_0; case 90: return FirebaseVisionImageMetadata.ROTATION_90; case 180: return FirebaseVisionImageMetadata.ROTATION_180; case 270: return FirebaseVisionImageMetadata.ROTATION_270; default: throw new IllegalArgumentException( "Rotation must be 0, 90, 180, or 270."); } } @Override public void analyze(ImageProxy imageProxy, int degrees) { if (imageProxy == null || imageProxy.getImage() == null) { return; } Image mediaImage = imageProxy.getImage(); int rotation = degreesToFirebaseRotation(degrees); FirebaseVisionImage image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation); // Pass image to an ML Kit Vision API // ... } }
Kotlin
private class YourImageAnalyzer : ImageAnalysis.Analyzer { private fun degreesToFirebaseRotation(degrees: Int): Int = when(degrees) { 0 -> FirebaseVisionImageMetadata.ROTATION_0 90 -> FirebaseVisionImageMetadata.ROTATION_90 180 -> FirebaseVisionImageMetadata.ROTATION_180 270 -> FirebaseVisionImageMetadata.ROTATION_270 else -> throw Exception("Rotation must be 0, 90, 180, or 270.") } override fun analyze(imageProxy: ImageProxy?, degrees: Int) { val mediaImage = imageProxy?.image val imageRotation = degreesToFirebaseRotation(degrees) if (mediaImage != null) { val image = FirebaseVisionImage.fromMediaImage(mediaImage, imageRotation) // Pass image to an ML Kit Vision API // ... } } }
画像の回転を取得するカメラ ライブラリを使用しない場合は、デバイスの回転とデバイス内のカメラセンサーの向きから計算できます。
Java
private static final SparseIntArray ORIENTATIONS = new SparseIntArray(); static { ORIENTATIONS.append(Surface.ROTATION_0, 90); ORIENTATIONS.append(Surface.ROTATION_90, 0); ORIENTATIONS.append(Surface.ROTATION_180, 270); ORIENTATIONS.append(Surface.ROTATION_270, 180); } /** * 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, Context context) 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); // On most devices, the sensor orientation is 90 degrees, but for some // devices it is 270 degrees. For devices with a sensor orientation of // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees. CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE); int sensorOrientation = cameraManager .getCameraCharacteristics(cameraId) .get(CameraCharacteristics.SENSOR_ORIENTATION); rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360; // Return the corresponding FirebaseVisionImageMetadata rotation value. int result; switch (rotationCompensation) { case 0: result = FirebaseVisionImageMetadata.ROTATION_0; break; case 90: result = FirebaseVisionImageMetadata.ROTATION_90; break; case 180: result = FirebaseVisionImageMetadata.ROTATION_180; break; case 270: result = FirebaseVisionImageMetadata.ROTATION_270; break; default: result = FirebaseVisionImageMetadata.ROTATION_0; Log.e(TAG, "Bad rotation value: " + rotationCompensation); } return result; }
Kotlin
private val ORIENTATIONS = SparseIntArray() init { ORIENTATIONS.append(Surface.ROTATION_0, 90) ORIENTATIONS.append(Surface.ROTATION_90, 0) ORIENTATIONS.append(Surface.ROTATION_180, 270) ORIENTATIONS.append(Surface.ROTATION_270, 180) } /** * 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, context: Context): 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) // On most devices, the sensor orientation is 90 degrees, but for some // devices it is 270 degrees. For devices with a sensor orientation of // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees. val cameraManager = context.getSystemService(CAMERA_SERVICE) as CameraManager val sensorOrientation = cameraManager .getCameraCharacteristics(cameraId) .get(CameraCharacteristics.SENSOR_ORIENTATION)!! rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360 // Return the corresponding FirebaseVisionImageMetadata rotation value. val result: Int when (rotationCompensation) { 0 -> result = FirebaseVisionImageMetadata.ROTATION_0 90 -> result = FirebaseVisionImageMetadata.ROTATION_90 180 -> result = FirebaseVisionImageMetadata.ROTATION_180 270 -> result = FirebaseVisionImageMetadata.ROTATION_270 else -> { result = FirebaseVisionImageMetadata.ROTATION_0 Log.e(TAG, "Bad rotation value: $rotationCompensation") } } return result }
次に、
media.Imageオブジェクトと回転値をFirebaseVisionImage.fromMediaImage()に渡します。Java
FirebaseVisionImage image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
Kotlin
val image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation)
FirebaseVisionImageオブジェクトをファイルの URI から作成するには、アプリ コンテキストとファイルの URI をFirebaseVisionImage.fromFilePath()に渡します。これは、ACTION_GET_CONTENTインテントを使用して、ギャラリー アプリから画像を選択するようにユーザーに促すときに便利です。Java
FirebaseVisionImage image; try { image = FirebaseVisionImage.fromFilePath(context, uri); } catch (IOException e) { e.printStackTrace(); }
Kotlin
val image: FirebaseVisionImage try { image = FirebaseVisionImage.fromFilePath(context, uri) } catch (e: IOException) { e.printStackTrace() }
FirebaseVisionImageオブジェクトをByteBufferまたはバイト配列から作成するには、media.Image入力について上記のように、まず画像の回転を計算します。次に、画像の高さ、幅、カラー エンコード形式、回転を含む
FirebaseVisionImageMetadataオブジェクトを作成します。Java
FirebaseVisionImageMetadata metadata = new FirebaseVisionImageMetadata.Builder() .setWidth(480) // 480x360 is typically sufficient for .setHeight(360) // image recognition .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21) .setRotation(rotation) .build();
Kotlin
val metadata = FirebaseVisionImageMetadata.Builder() .setWidth(480) // 480x360 is typically sufficient for .setHeight(360) // image recognition .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21) .setRotation(rotation) .build()
メタデータ オブジェクトと、バッファまたは配列を使用して、
FirebaseVisionImageオブジェクトを作成します。Java
FirebaseVisionImage image = FirebaseVisionImage.fromByteBuffer(buffer, metadata); // Or: FirebaseVisionImage image = FirebaseVisionImage.fromByteArray(byteArray, metadata);
Kotlin
val image = FirebaseVisionImage.fromByteBuffer(buffer, metadata) // Or: val image = FirebaseVisionImage.fromByteArray(byteArray, metadata)
FirebaseVisionImageオブジェクトをBitmapオブジェクトから作成するコードは、以下のとおりです。Java
FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);
Kotlin
val image = FirebaseVisionImage.fromBitmap(bitmap)
Bitmapオブジェクトによって表される画像は、これ以上回転させる必要がないように、正しい向きになっている必要があります。
-
画像を
processImage()メソッドに渡します。Java
objectDetector.processImage(image) .addOnSuccessListener( new OnSuccessListener<List<FirebaseVisionObject>>() { @Override public void onSuccess(List<FirebaseVisionObject> detectedObjects) { // Task completed successfully // ... } }) .addOnFailureListener( new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { // Task failed with an exception // ... } });Kotlin
objectDetector.processImage(image) .addOnSuccessListener { detectedObjects -> // Task completed successfully // ... } .addOnFailureListener { e -> // Task failed with an exception // ... }processImage()の呼び出しが成功すると、FirebaseVisionObjectのリストが成功リスナーに渡されます。各
FirebaseVisionObjectには次のプロパティが含まれています。境界ボックス 画像内のオブジェクトの位置を示す Rect。トラッキング ID イメージ間でオブジェクトを識別する整数。SINGLE_IMAGE_MODE では、NULL です。 カテゴリ オブジェクトのおおまかなカテゴリ。オブジェクト検出で分類が有効になっていない場合、これは常に FirebaseVisionObject.CATEGORY_UNKNOWNです。信頼度 オブジェクト分類の信頼値。オブジェクト検出で分類が有効になっていない場合、またはオブジェクトが不明と分類されている場合、これは nullです。Java
// The list of detected objects contains one item if multiple object detection wasn't enabled. for (FirebaseVisionObject obj : detectedObjects) { Integer id = obj.getTrackingId(); Rect bounds = obj.getBoundingBox(); // If classification was enabled: int category = obj.getClassificationCategory(); Float confidence = obj.getClassificationConfidence(); }Kotlin
// The list of detected objects contains one item if multiple object detection wasn't enabled. for (obj in detectedObjects) { val id = obj.trackingId // A number that identifies the object across images val bounds = obj.boundingBox // The object's position in the image // If classification was enabled: val category = obj.classificationCategory val confidence = obj.classificationConfidence }
ユーザビリティとパフォーマンスの向上
最高のユーザー エクスペリエンスを提供するため、次のガイドラインに従ってアプリを作成してください。
- オブジェクトの検出に成功するかどうかは、オブジェクトの視覚的な複雑さによります。視覚的特徴の少ないオブジェクトは、検出対象の画像の大部分を占めていないと検出に成功しない可能性があります。検出するオブジェクトの種類に適した入力をキャプチャするためのガイダンスを用意する必要があります。
- 分類を使用するときに、サポート対象のカテゴリに該当しないオブジェクトを検出する場合は、未知のオブジェクトに対して特別な処理を実装してください。
また、[ML Kit Material Design ショーケース アプリ][showcase-link]{: .external } とマテリアル デザインの Patterns for machine learning-powered features のコレクションも確認してください。
リアルタイム アプリケーションでストリーミング モードを使用する場合は、最適なフレームレートを得るため、次のガイドラインに従ってください。
ストリーミング モードで複数のオブジェクト検出を使用しないでください。ほとんどのデバイスは十分なフレームレートを生成できません。
不要な場合は、分類を無効にします。
- 検出器の呼び出しのスロットル調整を行います。検出器の実行中に新しい動画フレームが使用可能になった場合は、そのフレームをドロップします。
- 検出器の出力を使用して入力画像の上にグラフィックスをオーバーレイする場合は、まず ML Kit から検出結果を取得し、画像とオーバーレイを 1 つのステップでレンダリングします。これにより、ディスプレイ サーフェスへのレンダリングは入力フレームごとに 1 回で済みます。
-
Camera2 API を使用する場合は、
ImageFormat.YUV_420_888形式で画像をキャプチャします。古い Camera API を使用する場合は、
ImageFormat.NV21形式で画像をキャプチャします。