借助 MediaPipe 手势识别程序任务,您可以实时识别手势,并提供检测到的手势的已识别手势结果和手势标记。以下说明介绍了如何在 Android 应用中使用手势识别程序。GitHub 上提供了这些说明中描述的代码示例。
您可以查看 Web 演示,了解此任务的实际效果。如需详细了解此任务的功能、模型和配置选项,请参阅概览。
代码示例
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 种输入数据类型:静态图片、视频文件和实时视频串流。您需要在创建任务时指定与输入数据类型对应的运行模式。选择与输入数据类型对应的标签页,了解如何创建任务并运行推断。
映像
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:单张图片输入的模式。 VIDEO:视频的已解码帧的模式。 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"] |
|
|
|
customGesturesClassifierOptions |
用于配置自定义手势分类器行为的选项。 |
|
|
|
resultListener |
设置结果监听器,以在手势识别器处于直播模式时异步接收分类结果。
只能在跑步模式设为“LIVE_STREAM ”时使用 |
ResultListener |
N/A | N/A |
errorListener |
设置可选的错误监听器。 | ErrorListener |
N/A | N/A |
准备数据
手势识别程序可处理图片、视频文件和直播视频。该任务会处理数据输入预处理,包括大小调整、旋转和值归一化。
以下代码演示了如何移交数据进行处理。这些示例详细介绍了如何处理图片、视频文件和直播视频流中的数据。
映像
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
类会处理结果。