手势识别任务指南

一只手做出点赞手势，被模型识别为点赞手势，置信度为 63%

借助 MediaPipe 手势识别器任务，您可以实时识别手势，并提供识别出的手势结果以及检测到的手的特征点。您可以使用此任务来识别用户的特定手势，并调用与这些手势对应的应用功能。

此任务使用机器学习 (ML) 模型处理图片数据，并接受静态数据或连续数据流。该任务会输出图片坐标中的手部地标、世界坐标中的手部地标、手的左右性以及多只手的手势类别。

试试吧！

开始使用

如需开始使用此任务，请按照适用于目标平台的以下任一实现指南操作。以下平台专用指南将引导您使用推荐的模型完成此任务的基本实现，并提供包含推荐配置选项的代码示例：

任务详情

本部分介绍了此任务的功能、输入、输出和配置选项。

功能

  • 输入图片处理 - 处理包括图片旋转、调整大小、归一化和颜色空间转换。
  • 得分阈值 - 根据预测得分过滤结果。
  • 标签许可名单和拒绝名单 - 指定模型识别的手势类别。
任务输入 任务输出
手势识别器接受以下任一数据类型的输入：
  • 静态图片
  • 解码后的视频帧
  • 实时视频画面
 手势识别器会输出以下结果：
  • 手势类别
  • 检测到的手的惯用手
  • 检测到的手的地标（以图片坐标表示）
  • 以世界坐标表示的检测到的手的特征点

配置选项

此任务具有以下配置选项：

选项名称 说明 值范围 默认值
running_mode 设置任务的运行模式。共有三种模式：

IMAGE：适用于单张图片输入的模式。

视频：视频的解码帧的模式。

LIVE_STREAM：输入数据（例如来自摄像头）的直播模式。在此模式下，必须调用 resultListener 以设置监听器以异步接收结果。 		{IMAGE, VIDEO, LIVE_STREAM} IMAGE
num_hands GestureRecognizer 可以检测的手数上限。 Any integer > 0 1
min_hand_detection_confidence 在手掌检测模型中，手检测被视为成功所需的最低置信度得分。 0.0 - 1.0 0.5
min_hand_presence_confidence 手部地标检测模型中手部存在得分的最小置信度得分。在手势识别器的视频模式和直播模式下，如果手部地标模型的手部存在置信度分数低于此阈值，则会触发手掌检测模型。否则，系统会使用轻量级手部跟踪算法来确定手部的位置，以便进行后续地标检测。 0.0 - 1.0 0.5
min_tracking_confidence 手部跟踪被视为成功所需的最低置信度得分。这是当前帧和上一帧中手部之间的边界框 IoU 阈值。在手势识别器的视频模式和流模式下，如果跟踪失败，手势识别器会触发手部检测。否则，系统会跳过手部检测。 0.0 - 1.0 0.5
canned_gestures_classifier_options 用于配置预设手势分类器行为的选项。预设手势为 ["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
    • 类别许可名单：空
    • 类别拒绝名单：为空
    custom_gestures_classifier_options 用于配置自定义手势分类器行为的选项。
  • 显示名称语言区域：用于通过 TFLite 模型元数据（如果有）指定的显示名称的语言区域。
  • 返回的结果数上限：返回的得分最高的分类结果的数量上限。如果小于 0，则会返回所有可用的结果。
  • 得分阈值：低于此得分阈值的结果会被拒绝。如果设置为 0，则返回所有可用的结果。
  • 类别许可名单：类别名称的许可名单。如果不为空，系统会滤除类别不在该集合中的分类结果。与拒绝名单相互排斥。
  • 类别拒绝名单：类别名称的拒绝名单。如果不为空，系统会滤除类别在此集合中的分类结果。与许可名单相互排斥。
    		•
    • 显示名称语言区域：any string
    • 结果数上限：any integer
    • 得分阈值：0.0-1.0
    • 类别许可名单：vector of strings
    • 类别拒绝名单：vector of strings
    • 显示名称语言区域："en"
    • 结果数上限：-1
    • 得分阈值：0
    • 类别许可名单：空
    • 类别拒绝名单：为空
    result_callback 设置结果监听器，以便在手势识别器处于实时流模式时异步接收分类结果。 仅当运行模式设置为 LIVE_STREAM 时才能使用 ResultListener 不适用 不适用

    模型

    手势识别器使用包含两个预打包模型软件包的模型软件包：手部地标模型软件包和手势分类模型软件包。地标模型检测手的存在和手部几何形状，而手势识别模型则根据手部几何形状识别手势。

    模型名称 输入形状 量化类型 模型卡片 版本
    HandGestureClassifier 192 x 192、224 x 224 float 16 信息 最新

    此任务还支持使用 Model Maker 修改模型软件包。如需详细了解如何使用 Model Maker 为此任务自定义模型，请参阅为手势识别器自定义模型页面。

    手部特征点模型软件包

    手部特征点模型软件包可检测检测到的手部区域内 21 个手指关节坐标的关键点定位。该模型是基于约 3 万张真实图片以及叠加在各种背景上的多种渲染合成手部模型进行训练的。请参阅下方 21 个地图注点的定义：

    特定手部地标点的代码

    手部地标模型软件包包含手掌检测模型和手部地标检测模型。手掌检测模型会在整个输入图片中定位手部区域，而手部特征点检测模型会在手掌检测模型定义的剪裁手部图片上查找特征点。

    由于手掌检测模型耗时更长，因此在视频模式或直播模式下，手势识别器会使用当前帧中检测到的手部地标定义的边界框来定位下一帧中的手部区域。这会减少手势识别器触发手掌检测模型的次数。只有当手部特征点模型无法再识别足够数量的手部存在时，或者手部跟踪失败时，系统才会调用手掌检测模型来重新定位手部。

    手势分类模型软件包

    手势分类模型软件包可以识别以下常见手势：

    0 - Unrecognized gesture, label: Unknown
1 - Closed fist, label: Closed_Fist
2 - Open palm, label: Open_Palm
3 - Pointing up, label: Pointing_Up
4 - Thumbs down, label: Thumb_Down
5 - Thumbs up, label: Thumb_Up
6 - Victory, label: Victory
7 - Love, label: ILoveYou

    如果模型检测到手部但未识别出手势，手势识别器会返回“None”结果。如果模型未检测到手，手势识别器会返回空值。

    手势分类模型软件包包含两个步骤的神经网络流水线，其中包含手势嵌入模型和手势分类模型。如需了解详情，请参阅手势分类模型卡片。

    手势嵌入模型会将图片特征编码为特征向量，分类模型则是采用特征向量作为输入的轻量级手势分类器。提供的手势分类模型软件包包含预先定义的手势分类器，用于检测上述 7 种常用手势。您可以训练自己的自定义手势分类器，以扩展模型软件包以识别更多手势。如需了解详情，请参阅下文中的自定义模型部分。

    如果预定义手势分类器和自定义手势分类器在其类别中识别出相同的手势，则带有这两种分类器的手势识别器会优先识别自定义手势。如果只有一个手势分类器识别出手势，手势识别器会直接输出识别出的手势。

    任务基准

    以下是基于上述预训练模型的整个流水线的任务基准。延迟时间结果是使用 CPU / GPU 在 Pixel 6 上的平均延迟时间。

    模型名称 CPU 延迟时间 GPU 延迟时间
    GestureRecognizer 16.76 毫秒 20.87 毫秒

    自定义模型

    如果您想改进或更改此任务中提供的模型的功能，可以使用模型制作工具修改现有模型。与 MediaPipe 搭配使用的自定义模型必须采用 .task 格式，即模型软件包文件。在构建自己的模型之前，您应考虑使用 Model Maker 修改此任务的提供的模型。

    如需详细了解如何为此任务自定义模型，请参阅为手势识别器自定义模型。