详细了解我们在 I/O 大会上发布的 Google AI Edge

此页面由 Cloud Translation API 翻译。

适用于 Android 的手部特征检测指南

MediaPipe 手部地标任务可让您检测图片中手部的特征点。以下说明介绍了如何在 Android 应用中使用手形地标。GitHub 上提供了这些说明中描述的代码示例。

如需详细了解此任务的功能、模型和配置选项，请参阅概览。

代码示例

MediaPipe Tasks 示例代码是 Android 版手标记应用的简单实现。该示例使用实体 Android 设备上的相机连续检测手部特征点，还可以使用设备图库中的图片和视频来静态检测手部特征点。

您可以使用该应用作为基础来开发自己的 Android 应用，也可以在修改现有应用时参考该应用。Hand Markerer 示例代码托管在 GitHub 上。

下载代码

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

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

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

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

（可选）将您的 Git 实例配置为使用稀疏签出，这样您就只有 Hand Markerer 示例应用的文件：
```
cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/hand_landmarker/android
```

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

关键组件

以下文件包含此手部位置检测示例应用的关键代码：

HandLandmarkerHelper.kt - 初始化手部特征点检测器并处理模型和委托选择。
MainActivity.kt - 实现应用，包括调用 HandLandmarkerHelper。

初始设置

本部分介绍了专门针对使用手动地标设置开发环境和代码项目的关键步骤。如需了解如何为使用 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

在 ModelAssetPath 参数中指定模型的路径。在示例代码中，模型在 HandLandmarkerHelper.kt 文件中定义：

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

创建任务

MediaPipe 手点地标任务使用 createFromOptions() 函数来设置该任务。createFromOptions() 函数接受配置选项的值。如需详细了解配置选项，请参阅配置选项。

手点地标支持 3 种输入数据类型：静态图片、视频文件和直播。您需要在创建任务时指定与输入数据类型对应的运行模式。选择与输入数据类型对应的标签页，了解如何创建任务并运行推断。

映像

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

视频

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

直播

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

手动标记器示例代码实现可让用户在处理模式之间切换。这种方法会使任务创建代码更加复杂，可能不适合您的用例。您可以在 HandLandmarkerHelper.kt 文件的 setupHandLandmarker() 函数中查看此代码。

配置选项

此任务具有以下 Android 应用的配置选项：

选项名称	说明	值范围	默认值
`runningMode`	设置任务的运行模式。有三种模式： IMAGE：单张图片输入的模式。 VIDEO：视频的已解码帧的模式。 LIVE_STREAM：输入数据（例如来自摄像头）的直播的模式。在此模式下，必须调用 resultListener 来设置监听器，以异步接收结果。	{`IMAGE, VIDEO, LIVE_STREAM`}	`IMAGE`
`numHands`	手部特征点检测器检测到的手部数量上限。	`Any integer > 0`	`1`
`minHandDetectionConfidence`	要在手掌检测模型中被视为成功的手部检测的最低置信度分数。	`0.0 - 1.0`	`0.5`
`minHandPresenceConfidence`	手部特征点检测模型中手存在状态分数的最低置信度分数。在视频模式和直播模式下，如果手部特征点模型的手部存在置信度分数低于此阈值，则手部特征点会触发手掌检测模型。否则，轻量级手部跟踪算法会确定手的位置，以便进行后续地标检测。	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	手部跟踪被视为成功所需的最低置信度分数。这是当前帧和最后一帧中手之间的边界框 IoU 阈值。在“手部特征点”的“视频”模式和“流式”模式下，如果跟踪失败，“手部特征点”会触发手部检测。否则，它会跳过手部检测。	`0.0 - 1.0`	`0.5`
`resultListener`	设置结果监听器，以在手形地标处于直播模式时异步接收检测结果。仅在跑步模式设为“`LIVE_STREAM`”时适用	N/A	N/A
`errorListener`	设置可选的错误监听器。	N/A	N/A

准备数据

Hand Markerer 可处理图片、视频文件和直播视频。该任务会处理数据输入预处理，包括大小调整、旋转和值归一化。

以下代码演示了如何移交数据进行处理。这些示例详细介绍了如何处理图片、视频文件和直播视频流中的数据。

映像

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

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(image).build()

视频

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

val argb8888Frame =
    if (frame.config == Bitmap.Config.ARGB_8888) frame
    else frame.copy(Bitmap.Config.ARGB_8888, false)

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(argb8888Frame).build()

直播

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

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(rotatedBitmap).build()

在 Handlander 示例代码中，数据准备是在 HandLandmarkerHelper.kt 文件中处理的。

运行任务

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

以下代码示例展示了如何在这些不同的数据模式下运行手动标记工具的简单示例：

映像

val result = handLandmarker?.detect(mpImage)

视频

val timestampMs = i * inferenceIntervalMs

handLandmarker?.detectForVideo(mpImage, timestampMs)
    ?.let { detectionResult ->
        resultList.add(detectionResult)
    }

直播

val mpImage = BitmapImageBuilder(rotatedBitmap).build()
val frameTime = SystemClock.uptimeMillis()

handLandmarker?.detectAsync(mpImage, frameTime)

请注意以下几点：

在视频模式或直播模式下运行时，您还必须向 Hand Markerer 任务提供输入帧的时间戳。
在图片模式或视频模式下运行时，手动标记任务将阻塞当前线程，直到处理完输入图片或帧。为避免阻塞界面，请在后台线程中执行处理。
在直播模式下运行时，Hander Markerer 任务不会阻塞当前线程，而是立即返回。每当处理完输入帧时，它都会使用检测结果调用其结果监听器。如果在手部特征点任务正忙于处理另一帧时调用检测函数，该任务将忽略新的输入帧。

在 Handand Markerer 示例代码中，detect、detectForVideo 和 detectAsync 函数在 HandLandmarkerHelper.kt 文件中定义。

处理和显示结果

手部特征点每次检测运行都会生成一个手部特征点结果对象。结果对象包含图片坐标中的手部地标、世界坐标中的手部地标，以及检测到的手的惯用手（左/右）。

下面显示了此任务的输出数据示例：

HandLandmarkerResult 输出包含三个组成部分。每个组成部分都是一个数组，其中每个元素都包含检测到的一只手的以下结果：

用手习惯

用手表示检测到的手是左手还是右手。
地标

共有 21 个手部位置标记，每个位置标记由 x、y 和 z 坐标组成。x 和 y 坐标分别根据图片宽度和高度标准化为 [0.0, 1.0]。z 坐标表示地标深度，以手腕处的深度为原点。值越小，地标越靠近相机。z 的大小大小与 x 的大小大致相同。
世界地标

21 只手部位标也以世界坐标表示。每个地标由 x、y 和 z 组成，表示现实世界的 3D 坐标（以米为单位），原点位于手的几何中心。

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : -3.41E-7
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
    ... (21 landmarks for a hand)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
    ... (21 world landmarks for a hand)

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

Hand Markerer 示例代码演示了如何显示任务返回的结果。如需了解详情，请参阅 OverlayView 类。