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

此页面由 Cloud Translation API 翻译。

适用于 Android 的对象检测指南

通过对象检测器任务，您可以检测多个对象是否存在对象的类别。例如，物体检测器可以定位图片。以下说明介绍了如何在 Android。您可在 GitHub 查看此任务的实际运行情况：网页演示。如需详细了解功能、模型和配置选项部分，请参阅概览。

代码示例

MediaPipe Tasks 示例代码是对象检测器的简单实现 Android 版应用。该示例使用 Android 实体设备上的相机持续检测物体，也可以使用来自物体的图片和视频，设备图库来静态检测对象。

您可以用该应用作为基础来开发自己的 Android 应用，也可以指代该应用对现有应用进行了修改。对象检测器示例代码托管在 GitHub

下载代码

以下说明介绍了如何创建示例的本地副本使用 git 命令行工具运行 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 - 处理和显示结果

设置

本部分介绍了设置开发环境和代码项目使用 Object Detector。有关设置开发环境以使用 MediaPipe 任务，包括平台版本要求，请参阅 Android 版设置指南。

依赖项

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

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

型号

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

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

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

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

创建任务

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

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

映像

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：单图输入的模式。 VIDEO：视频已解码帧的模式。 LIVE_STREAM：输入流媒体直播模式例如来自相机的数据。在此模式下，resultListener 必须为调用以设置监听器以接收结果异步执行。	{`IMAGE, VIDEO, LIVE_STREAM`}	`IMAGE`
`displayNamesLocales`	设置要用于任务模型的元数据（如果有）。默认值为 `en`，英语。您可以向自定义模型的元数据中添加本地化标签使用 TensorFlow Lite Metadata Writer API	语言区域代码	en
`maxResults`	将可选的最高评分检测结果数上限设置为 return。	任何正数	-1（返回所有结果）
`scoreThreshold`	设置预测分数阈值，以替换模型元数据（如果有）。低于此值的结果将被拒绝。	任意浮点数	未设置
`categoryAllowlist`	设置允许的类别名称的可选列表。如果不为空，类别名称未在此集合内的检测结果已滤除。重复或未知的类别名称会被忽略。此选项与 `categoryDenylist` 互斥，使用都会导致错误。	任何字符串	未设置
`categoryDenylist`	设置不允许使用的类别名称的可选列表。如果非空，则类别名称在此集中的检测结果将被滤除。重复或未知的类别名称会被忽略。这个选项 `categoryAllowlist` 不包含，同时使用这两个元素会导致错误。	任何字符串	未设置
`resultListener`	设置结果监听器以接收检测结果当对象检测器在直播中时异步执行模式。只有在将 runningMode 设置为 LIVE_STREAM 时，才能使用此选项。	不适用	未设置

准备数据

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

以下示例解释并展示了如何准备数据以进行处理每个可用数据类型：

映像

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();

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

运行任务

根据您处理的数据类型，使用 ObjectDetector.detect...() 方法。使用 detect()，适用于单个图片； detectForVideo()（针对视频文件中的帧）和 detectAsync() 适用于视频流。当您在 Google Analytics 4 上则务必在单独的线程中运行检测，阻塞用户界面线程

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

映像

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()。示例代码允许用户在处理模式之间切换您的用例可能并不需要这样做

请注意以下几点：

在视频模式或直播模式下投放广告时，您还必须为对象检测器任务提供输入帧的时间戳。
在图片模式或视频模式下运行时，对象检测器任务将阻塞当前线程，直到它处理完输入图像，或者帧。为避免阻塞当前线程，请在后台线程。
在直播模式下运行时，对象检测器任务不会阻塞当前线程，但会立即返回。它将调用其结果并在每次处理完一个监听器后将带有检测结果的监听器输入帧。如果在执行对象检测器任务时调用了检测函数，系统正忙于处理另一帧，系统会忽略新的输入帧。

处理和显示结果

运行推理时，“对象检测器”任务会返回一个 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 类以了解更多详情。