全新推出：LiteRT：Google 专为设备端 AI 打造的高性能运行时，以前称为 TensorFlow Lite。

此页面由 Cloud Translation API 翻译。

适用于 Android 的对象检测指南

借助对象检测器任务，您可以检测多类对象的存在情况和位置。例如，对象检测器可以定位图片中的狗。以下说明介绍了如何在 Android 上使用对象检测器任务。这些说明中介绍的代码示例可在 GitHub 上找到。您可以查看此Web 演示，了解此任务的实际运作方式。如需详细了解此任务的功能、模型和配置选项，请参阅概览。

代码示例

MediaPipe Tasks 示例代码是对 Android 对象检测器应用的简单实现。该示例使用实体 Android 设备上的摄像头持续检测对象，还可以使用设备图库中的图片和视频静态检测对象。

您可以将该应用用作您自己的 Android 应用的起点，也可以在修改现有应用时参考该应用。Object Detector 示例代码托管在 GitHub 上。

下载代码

以下说明介绍了如何使用 git 命令行工具创建示例代码的本地副本。

如需下载示例代码，请执行以下操作：

使用以下命令克隆 Git 代码库：

git clone https://github.com/google-ai-edge/mediapipe-samples

（可选）将您的 Git 实例配置为使用稀疏检出，以便您只保留对象检测器示例应用的文件：
```
cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/object_detection/android
```

创建示例代码的本地版本后，您可以将项目导入 Android Studio 并运行应用。如需了解相关说明，请参阅 Android 设置指南。

关键组件

以下文件包含物体检测器示例应用的重要代码：

ObjectDetectorHelper.kt - 初始化对象检测器并处理模型和代理选择
MainActivity.kt - 实现应用并组装界面组件
OverlayView.kt - 处理和显示结果

设置

本部分介绍了设置开发环境和编写代码项目以使用对象检测器的关键步骤。如需了解如何设置开发环境以使用 MediaPipe 任务（包括平台版本要求）的一般信息，请参阅 Android 设置指南。

依赖项

对象检测器使用 com.google.mediapipe:tasks-vision 库。将此依赖项添加到 Android 应用开发项目的 build.gradle 文件中。使用以下代码导入所需的依赖项：

dependencies {
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

型号

MediaPipe 对象检测器任务需要与此任务兼容的训练模型。如需详细了解适用于对象检测器的已训练模型，请参阅任务概览的“模型”部分。

选择并下载模型，然后将其存储在项目目录中：

<dev-project-root>/src/main/assets

使用 BaseOptions.Builder.setModelAssetPath() 方法指定模型使用的路径。如需查看代码示例，请参阅下一部分。

创建任务

您可以使用 createFromOptions 函数创建任务。createFromOptions 函数接受配置选项，包括运行模式、显示名称语言区域、结果数量上限、置信度阈值、类别许可名单和禁止名单。如果未指定配置选项，系统将使用默认值。如需详细了解配置选项，请参阅配置概览。

对象检测器任务支持 3 种输入数据类型：静态图片、视频文件和实时视频流。创建任务时，您需要指定与输入数据类型对应的运行模式。选择与输入数据类型对应的标签页，了解如何创建任务和运行推理。

Image

ObjectDetectorOptions options =
  ObjectDetectorOptions.builder()
    .setBaseOptions(BaseOptions.builder().setModelAssetPath(‘model.tflite’).build())
    .setRunningMode(RunningMode.IMAGE)
    .setMaxResults(5)
    .build();
objectDetector = ObjectDetector.createFromOptions(context, options);

视频

ObjectDetectorOptions options =
  ObjectDetectorOptions.builder()
    .setBaseOptions(BaseOptions.builder().setModelAssetPath(‘model.tflite’).build())
    .setRunningMode(RunningMode.VIDEO)
    .setMaxResults(5)
    .build();
objectDetector = ObjectDetector.createFromOptions(context, options);

直播

ObjectDetectorOptions options =
  ObjectDetectorOptions.builder()
    .setBaseOptions(BaseOptions.builder().setModelAssetPath(‘model.tflite’).build())
    .setRunningMode(RunningMode.LIVE_STREAM)
    .setMaxResults(5)
    .setResultListener((result, inputImage) -> {
      // Process the detection result here.
    })
    .setErrorListener((result, inputImage) -> {
      // Process the classification errors here.
    })
   .build();
objectDetector = ObjectDetector.createFromOptions(context, options);

借助对象检测器示例代码实现，用户可以在处理模式之间切换。这种方法会使任务创建代码变得更复杂，可能不适合您的用例。您可以在 ObjectDetectorHelper 类的 setupObjectDetector() 函数中看到此代码。

配置选项

此任务针对 Android 应用提供了以下配置选项：

选项名称	说明	值范围	默认值
`runningMode`	设置任务的运行模式。共有三种模式： IMAGE：适用于单张图片输入的模式。视频：视频的解码帧的模式。 LIVE_STREAM：输入数据（例如来自摄像头）的直播模式。在此模式下，必须调用 resultListener 以设置监听器以异步接收结果。	{`IMAGE, VIDEO, LIVE_STREAM`}	`IMAGE`
`displayNamesLocales`	设置要为任务模型的元数据（如果有）中提供的显示名称使用的标签语言。默认值为 `en`（英语）。您可以使用 TensorFlow Lite Metadata Writer API 向自定义模型的元数据添加本地化标签	语言区域代码	en
`maxResults`	设置可选的要返回的得分最高的检测结果的数量上限。	任何正数	-1（返回所有结果）
`scoreThreshold`	设置预测得分阈值，该阈值会替换模型元数据中提供的阈值（如果有）。低于此值的结果将被拒绝。	任何浮点数	未设置
`categoryAllowlist`	设置允许的类别名称的可选列表。如果不为空，则系统会滤除类别名称不在该集合中的检测结果。系统会忽略重复或未知的类别名称。此选项与 `categoryDenylist` 互斥，同时使用这两个选项会导致错误。	任何字符串	未设置
`categoryDenylist`	设置不允许的类别名称的可选列表。如果不为空，系统会滤除类别名称在此集合中的检测结果。系统会忽略重复或未知的类别名称。此选项与 `categoryAllowlist` 互斥，同时使用这两个选项会导致错误。	任何字符串	未设置
`resultListener`	设置结果监听器，以便在对象检测器处于实时流模式时异步接收检测结果。只有在将 runningMode 设置为 LIVE_STREAM 时，才能使用此选项。	不适用	未设置

准备数据

您需要先将输入图片或帧转换为 com.google.mediapipe.framework.image.MPImage 对象，然后才能将其传递给对象检测器。

以下示例说明了如何为每种可用数据类型准备数据以供处理：

Image

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load an image on the user’s device as a Bitmap object using BitmapFactory.

// Convert an Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(bitmap).build();

视频

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load a video file on the user's device using MediaMetadataRetriever

// From the video’s metadata, load the METADATA_KEY_DURATION and
// METADATA_KEY_VIDEO_FRAME_COUNT values. Use these values
// to calculate the timestamp of each frame later.

// Loop through the video and load each frame as a Bitmap object.

// Convert the Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(frame).build();

直播

import com.google.mediapipe.framework.image.MediaImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Create a CameraX’s ImageAnalysis to continuously receive frames
// from the device’s camera. Configure it to output frames in RGBA_8888
// format to match with what is required by the model.

// For each Android’s ImageProxy object received from the ImageAnalysis,
// extract the encapsulated Android’s Image object and convert it to
// a MediaPipe’s Image object.
android.media.Image mediaImage = imageProxy.getImage()
MPImage mpImage = new MediaImageBuilder(mediaImage).build();

在对象检测器示例代码中，数据准备工作在 detectImage()、detectVideoFile() 和 detectLivestreamFrame() 函数内的 ObjectDetectorHelper 类中处理。

运行任务

根据您要处理的数据类型，使用特定于该数据类型的 ObjectDetector.detect...() 方法。detect() 适用于单个图片，detectForVideo() 适用于视频文件中的帧，detectAsync() 适用于视频流。对视频流执行检测时，请务必在单独的线程中运行检测，以免阻塞界面线程。

以下代码示例展示了如何在这些不同的数据模式下运行对象检测器的简单示例：

Image

ObjectDetectorResult detectionResult = objectDetector.detect(image);

视频

// Calculate the timestamp in milliseconds of the current frame.
long frame_timestamp_ms = 1000 * video_duration * frame_index / frame_count;

// Run inference on the frame.
ObjectDetectorResult detectionResult =
    objectDetector.detectForVideo(image, frameTimestampMs);

直播

// Run inference on the frame. The detection results will be available
// via the `resultListener` provided in the `ObjectDetectorOptions` when
// the object detector was created.
objectDetector.detectAsync(image, frameTimestampMs);

对象检测器代码示例详细介绍了 detect()、detectVideoFile() 和 detectAsync() 这三种模式的实现。示例代码允许用户在处理模式之间切换，但您的用例可能不需要这样做。

请注意以下几点：

在视频模式或实时视频流模式下运行时，您还必须向物体检测器任务提供输入帧的时间戳。
在图片或视频模式下运行时，对象检测器任务会阻塞当前线程，直到其处理完输入图片或帧。为避免阻塞当前线程，请在后台线程中执行处理。
在直播模式下运行时，对象检测器任务不会阻塞当前线程，而是会立即返回。每当它处理完输入帧后，都会调用其结果监听器并传递检测结果。如果在对象检测器任务忙于处理其他帧时调用 detect 函数，系统会忽略新的输入帧。

处理和显示结果

运行推理后，对象检测器任务会返回一个 ObjectDetectorResult 对象，该对象描述了它在输入图片中发现的对象。

以下是此任务的输出数据示例：

ObjectDetectorResult:
 Detection #0:
  Box: (x: 355, y: 133, w: 190, h: 206)
  Categories:
   index       : 17
   score       : 0.73828
   class name  : dog
 Detection #1:
  Box: (x: 103, y: 15, w: 138, h: 369)
  Categories:
   index       : 17
   score       : 0.73047
   class name  : dog

下图显示了任务输出的可视化结果：

两个用边界框突出显示的狗

对象检测器示例代码演示了如何显示从任务返回的检测结果，如需了解详情，请参阅 OverlayView 类。