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

此页面由 Cloud Translation API 翻译。

适用于 Android 的手势识别指南

借助 MediaPipe 手势识别器任务，您可以实时识别手势，并提供识别出的手势结果和检测到的手的特征点。这些说明介绍了如何在 Android 应用中使用手势识别器。这些说明中介绍的代码示例可在 GitHub 上找到。

您可以查看网页演示，了解此任务的实际运作方式。如需详细了解此任务的功能、模型和配置选项，请参阅概览。

代码示例

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

您可以将该应用用作您自己的 Android 应用的起点，也可以在修改现有应用时参考该应用。手势识别器示例代码托管在 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/gesture_recognizer/android
```

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

关键组件

以下文件包含此手势识别示例应用的重要代码：

GestureRecognizerHelper.kt - 初始化手势识别器，并处理模型和委托选择。
MainActivity.kt - 实现应用，包括调用 GestureRecognizerHelper 和 GestureRecognizerResultsAdapter。
GestureRecognizerResultsAdapter.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

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

baseOptionBuilder.setModelAssetPath(MP_RECOGNIZER_TASK)

创建任务

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

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

Image

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

val optionsBuilder =
    GestureRecognizer.GestureRecognizerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()
gestureRecognizer =
    GestureRecognizer.createFromOptions(context, options)

视频

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

val optionsBuilder =
    GestureRecognizer.GestureRecognizerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()
gestureRecognizer =
    GestureRecognizer.createFromOptions(context, options)

直播

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

val optionsBuilder =
    GestureRecognizer.GestureRecognizerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.LIVE_STREAM)

val options = optionsBuilder.build()
gestureRecognizer =
    GestureRecognizer.createFromOptions(context, options)

手势识别器示例代码实现允许用户在处理模式之间切换。这种方法会使任务创建代码变得更复杂，可能不适合您的用例。您可以在 GestureRecognizerHelper.kt 文件的 setupGestureRecognizer() 函数中看到此代码。

配置选项

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

选项名称	说明	值范围	默认值
`runningMode`	设置任务的运行模式。共有三种模式： IMAGE：适用于单张图片输入的模式。视频：视频的解码帧的模式。 LIVE_STREAM：输入数据（例如来自摄像头）的直播模式。在此模式下，必须调用 resultListener 以设置监听器以异步接收结果。	{`IMAGE, VIDEO, LIVE_STREAM`}	`IMAGE`
`numHands`	`GestureRecognizer` 可以检测的手数上限。	`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`
`cannedGesturesClassifierOptions`	用于配置预设手势分类器行为的选项。预设手势为 `["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"]` 显示名称语言区域：用于通过 TFLite 模型元数据（如果有）指定的显示名称的语言区域。返回的结果数上限：返回的得分最高的分类结果的数量上限。如果小于 0，则会返回所有可用的结果。得分阈值：低于此得分阈值的结果会被拒绝。如果设置为 0，则返回所有可用的结果。类别许可名单：类别名称的许可名单。如果不为空，系统会滤除类别不在该集合中的分类结果。与拒绝名单相互排斥。类别拒绝名单：类别名称的拒绝名单。如果不为空，系统会滤除类别在此集合中的分类结果。与许可名单相互排斥。	显示名称语言区域：`any string` 结果数上限：`any integer` 得分阈值：`0.0-1.0` 类别许可名单：`vector of strings` 类别拒绝名单：`vector of strings`	显示名称语言区域：`"en"` 结果数上限：`-1` 得分阈值：`0` 类别许可名单：空类别拒绝名单：为空
`customGesturesClassifierOptions`	用于配置自定义手势分类器行为的选项。显示名称语言区域：用于通过 TFLite 模型元数据（如果有）指定的显示名称的语言区域。返回的结果数上限：返回的得分最高的分类结果的数量上限。如果小于 0，则会返回所有可用的结果。得分阈值：低于此得分阈值的结果会被拒绝。如果设置为 0，则返回所有可用的结果。类别许可名单：类别名称的许可名单。如果不为空，系统会滤除类别不在该集合中的分类结果。与拒绝名单相互排斥。类别拒绝名单：类别名称的拒绝名单。如果不为空，系统会滤除类别在此集合中的分类结果。与许可名单相互排斥。	显示名称语言区域：`any string` 结果数上限：`any integer` 得分阈值：`0.0-1.0` 类别许可名单：`vector of strings` 类别拒绝名单：`vector of strings`	显示名称语言区域：`"en"` 结果数上限：`-1` 得分阈值：`0` 类别许可名单：空类别拒绝名单：为空
`resultListener`	设置结果监听器，以便在手势识别器处于实时流模式时异步接收分类结果。仅当运行模式设置为 `LIVE_STREAM` 时才能使用	`ResultListener`	不适用	不适用
`errorListener`	设置可选的错误监听器。	`ErrorListener`	不适用	不适用

准备数据

手势识别器适用于图片、视频文件和直播视频。该任务会处理数据输入预处理，包括调整大小、旋转和值归一化。

以下代码演示了如何将数据交接给其他进程进行处理。这些示例详细介绍了如何处理来自图片、视频文件和直播视频流的数据。

Image

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

在手势识别器示例代码中，数据准备是在 GestureRecognizerHelper.kt 文件中处理的。

运行任务

手势识别器使用 recognize、recognizeForVideo 和 recognizeAsync 函数触发推理。对于手势识别，这涉及预处理输入数据、检测图片中的手、检测手部地标，以及根据地标识别手势。

以下代码演示了如何使用任务模型执行处理。这些示例详细介绍了如何处理来自图片、视频文件和直播视频流的数据。

Image

val result = gestureRecognizer?.recognize(mpImage)

视频

val timestampMs = i * inferenceIntervalMs

gestureRecognizer?.recognizeForVideo(mpImage, timestampMs)
    ?.let { recognizerResult ->
        resultList.add(recognizerResult)
    }

直播

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

gestureRecognizer?.recognizeAsync(mpImage, frameTime)

请注意以下几点：

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

在手势识别器示例代码中，recognize、recognizeForVideo 和 recognizeAsync 函数在 GestureRecognizerHelper.kt 文件中定义。

处理和显示结果

手势识别器会为每次运行的识别生成一个手势检测结果对象。结果对象包含图片坐标中的手部特征点、世界坐标中的手部特征点、手的左右手性以及检测到的手的手势类别。

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

生成的 GestureRecognizerResult 包含四个组件，每个组件都是一个数组，其中每个元素都包含单个检测到的手的检测结果。

惯用手

惯用手表示检测到的手是左手还是右手。
手势

检测到的手的已识别手势类别。
地标

手部地标共有 21 个，每个地标由 x、y 和 z 坐标组成。x 和 y 坐标分别按图片宽度和高度归一化为 [0.0, 1.0]。z 坐标表示地标深度，其中手腕处的深度为原点。值越小，地标离相机越近。z 的大小与 x 大致相同。
世界地标

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

GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  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)

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

一只手做出竖起大拇指的动作，手部的骨骼结构已映射

在手势识别器示例代码中，GestureRecognizerResultsAdapter.kt 文件中的 GestureRecognizerResultsAdapter 类会处理结果。