您可以使用机器学习套件来跨视频帧检测和跟踪对象。
当您向机器学习套件传递图片后，机器学习套件会以列表形式为每个图片返回最多五个检测到的对象及其在图片中的位置。检测视频流中的对象时，每个对象都有一个 ID，您可以使用此 ID 来跨图片跟踪对象。您还可以选择启用对象粗分类，该功能会使用粗略的类别描述来给对象加标签。
准备工作
- 将 Firebase 添加到您的 Android 项目（如果尚未添加）。
- 将 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_MODE在
STREAM_MODE（默认）下，对象检测器以低延迟高速运行，但在前几次调用检测器时可能会产生不完整的结果（例如未指定的边界框或类别标签）。此外，在STREAM_MODE下，检测器会为对象分配跟踪 ID，您可以使用该 ID 来跨帧跟踪对象。如果您想要跟踪对象，或者对延迟有要求（例如在实时处理视频流时），请使用此模式。在
SINGLE_IMAGE_MODE下，直到获得所检测到的对象的边界框和类别标签（如果启用了分类），对象检测器才会返回结果。因此，此模式下的检测延迟可能较高。 此外，在SINGLE_IMAGE_MODE下，不会分配跟踪 ID。如果不计较延迟高低，且不想处理不完整的结果，请使用此模式。检测和跟踪多个对象 false（默认）|true是检测和跟踪最多五个对象，还是仅检测和跟踪最突出的对象（默认）。
对对象进行分类 false（默认）|true是否对检测到的对象进行粗分类。启用后，对象检测器会将对象分为以下类别：时尚商品、食品、家居用品、地点、植物和未知类别。
对象检测和跟踪 API 针对以下两个核心使用场景进行了优化：
- 实时检测和跟踪相机取景器中最突出的对象
- 检测静态图片中的多个对象
如需为这些使用场景配置 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+KTX
// 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+KTX
val objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector() // Or, to change the default settings: val objectDetector = FirebaseVision.getInstance().getOnDeviceObjectDetector(options)
2. 运行对象检测器
如需检测和跟踪对象，请将图片传递给 FirebaseVisionObjectDetector 实例的 processImage() 方法。
对于一个序列中的每个视频或图片帧，请执行以下操作：
基于图片创建
FirebaseVisionImage对象。-
如需基于
media.Image对象创建FirebaseVisionImage对象（例如从设备的相机捕获图片时），请将media.Image对象和图片的旋转角度传递给FirebaseVisionImage.fromMediaImage()。如果您使用 CameraX 库，
OnImageCapturedListener和ImageAnalysis.Analyzer类会为您计算旋转角度值，因此您只需在调用FirebaseVisionImage.fromMediaImage()之前将旋转角度转换为机器学习套件的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+KTX
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+KTX
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+KTX
val image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation)
- 如需基于文件 URI 创建
FirebaseVisionImage对象，请将应用上下文和文件 URI 传递给FirebaseVisionImage.fromFilePath()。如果您使用ACTION_GET_CONTENTIntent 提示用户从图库应用中选择图片，这一操作会非常有用。Java
FirebaseVisionImage image; try { image = FirebaseVisionImage.fromFilePath(context, uri); } catch (IOException e) { e.printStackTrace(); }Kotlin+KTX
val image: FirebaseVisionImage try { image = FirebaseVisionImage.fromFilePath(context, uri) } catch (e: IOException) { e.printStackTrace() } - 如需基于
ByteBuffer或字节数组创建FirebaseVisionImage对象，请先按上述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+KTX
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+KTX
val image = FirebaseVisionImage.fromByteBuffer(buffer, metadata) // Or: val image = FirebaseVisionImage.fromByteArray(byteArray, metadata)
- 如需基于
Bitmap对象创建FirebaseVisionImage对象，请运行以下代码：以Java
FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);
Kotlin+KTX
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+KTX
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+KTX
// 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 }
提升易用性和性能
如需获得最佳用户体验，请在您的应用中遵循以下准则：
- 对象检测成功与否取决于对象的视觉复杂性。具有较少视觉特征的对象可能需要占据待检测图片的较大部分区域。您应为用户提供有关捕获输入的指导，该输入应适用于您要检测的对象类型。
- 使用分类时，如果您要检测不完全归于受支持类别的对象，请对未知对象执行特殊处理。
另请参阅 [机器学习套件 Material Design 展示应用][showcase-link]{: .external } 和适用于机器学习所支持功能集的 Material Design 模式。
在实时应用中使用流式传输模式时，请遵循以下准则以实现最佳帧速率：
请勿在流式传输模式下使用多个对象检测，因为大多数设备无法产生足够高的帧速率。
如果您不需要，请停用分类。
- 限制检测器的调用次数。如果在检测器运行时有新的视频帧可用，请丢弃该帧。
- 如果要将检测器的输出作为图形叠加在输入图片上，请先从机器学习套件获取结果，然后在一个步骤中完成图片的呈现和叠加。采用这一方法，每个输入帧只需在显示表面呈现一次。
-
如果您使用 Camera2 API，请以
ImageFormat.YUV_420_888格式捕获图片。如果您使用旧版 Camera API，请以
ImageFormat.NV21格式捕获图片。