适用于 Android 的手势识别指南

借助 MediaPipe 手势识别程序任务，您可以实时识别手势，并提供检测到的手势的已识别手势结果和手势标记。以下说明介绍了如何在 Android 应用中使用手势识别程序。GitHub 上提供了这些说明中描述的代码示例。

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

代码示例

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

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

下载代码

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

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

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

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

2. （可选）将您的 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 种输入数据类型：静态图片、视频文件和实时视频串流。您需要在创建任务时指定与输入数据类型对应的运行模式。选择与输入数据类型对应的标签页，了解如何创建任务并运行推断。

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 应用的配置选项：

准备数据

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

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

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 函数来触发推断。对于手势识别，这涉及预处理输入数据、检测图片中的手、检测手特征点，以及识别地标中的手势。

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

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 类会处理结果。