手势识别任务指南

一只手做出点赞动作，模型识别出这是点赞手势，置信度为 63%

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

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

试一试！

开始使用

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

任务详情

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

功能

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

配置选项

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

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

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

VIDEO：用于视频的解码帧的模式。

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 毫秒

    自定义模型

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

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