网页版手势识别指南

借助 MediaPipe 手势识别器任务,你可以实时识别手势; 提供识别出的手势结果以及 检测到手部设备。以下说明介绍了如何使用手势识别程序 。

要了解此任务的实际运行情况,请查看 演示。 如需详细了解功能、模型和配置选项 部分,请参阅概览

代码示例

手势识别程序的示例代码提供了该手势的完整实现, 供您参考。此代码可帮助您测试此任务, 开始打造自己的手势识别应用。您可以查看、运行 修改手势识别器示例代码 只需使用网络浏览器即可。

设置

本部分介绍设置开发环境的关键步骤 特别是使用手势识别器有关 设置 Web 和 JavaScript 开发环境 平台版本要求,请参阅 网页版设置指南

JavaScript 软件包

手势识别器代码可通过 MediaPipe @mediapipe/tasks-vision 获取 NPM 软件包。您可以 按照平台中的说明查找并下载这些库 设置指南

<ph type="x-smartling-placeholder">

您可以通过 NPM 安装所需的软件包 创建 Deployment

npm install @mediapipe/tasks-vision

如果您想通过内容分发网络 (CDN) 导入任务代码 服务,请在 HTML 文件的 <head> 标记中添加以下代码:

<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
    crossorigin="anonymous"></script>
</head>

型号

MediaPipe 手势识别器任务需要一个与此任务兼容的经过训练的模型 任务。如需详细了解适用于手势识别程序且经过训练的模型,请参阅 任务概览的“模型”部分

选择并下载模型,然后将其存储在项目目录中:

<dev-project-root>/app/shared/models/

创建任务

使用某个手势识别器 createFrom...() 函数执行以下操作: 为运行推理准备任务。使用 createFromModelPath() 函数。 如果模型已加载到内存中,您可以使用 createFromModelBuffer() 方法结合使用。

以下代码示例演示了如何使用 createFromOptions() 函数来 设置任务。借助 createFromOptions 函数,您可以自定义 具有配置选项的手势识别器。如需详细了解配置 选项,请参阅配置选项

以下代码演示了如何使用自定义的 选项:

// Create task for image file processing:
const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm "
);
const gestureRecognizer = await GestureRecognizer.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: "https://storage.googleapis.com/mediapipe-tasks/gesture_recognizer/gesture_recognizer.task"
  },
  numHands: 2
});

配置选项

此任务具有以下适用于 Web 应用的配置选项:

选项名称 说明 值范围 默认值
runningMode 设置任务的运行模式。有两个 模式:

IMAGE:单图输入的模式。

视频:已解码的帧的模式。 视频或对输入数据(例如来自摄像头的直播数据)进行直播。
{IMAGE, VIDEO} 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
    • 类别许可名单:空
    • 类别拒绝名单:空

    准备数据

    手势识别程序可以识别图片中采用 托管浏览器该任务还会处理数据输入预处理,包括 调整大小、旋转和值归一化。要识别视频中的手势,您需要 可以使用该 API 根据事件视频的时间戳,一次快速处理一帧。 帧,以确定手势在视频中出现的时间。

    运行任务

    手势识别程序使用 recognize()(在运行模式 'image' 下)和 要触发的 recognizeForVideo()(采用运行模式 'video')方法 推理。任务处理数据,尝试识别手部信息 并报告结果。

    以下代码演示了如何使用任务模型执行处理:

    映像

    const image = document.getElementById("image") as HTMLImageElement;
    const gestureRecognitionResult = gestureRecognizer.recognize(image);

    视频

    await gestureRecognizer.setOptions({ runningMode: "video" });
    
    let lastVideoTime = -1;
    function renderLoop(): void {
      const video = document.getElementById("video");
    
      if (video.currentTime !== lastVideoTime) {
        const gestureRecognitionResult = gestureRecognizer.recognizeForVideo(video);
        processResult(gestureRecognitionResult);
        lastVideoTime = video.currentTime;
      }
    
      requestAnimationFrame(() => {
        renderLoop();
      });
    }

    运行对手势识别器 recognize()recognizeForVideo() 方法的调用 同时阻塞界面线程。如果你熟悉以下手势: 从设备相机拍摄视频帧时,每次识别都会屏蔽主视频 线程。为防止这种情况发生,您可以实施 Web Worker 另一个线程上的 recognize()recognizeForVideo() 方法。

    有关运行手势识别器任务的更完整实现,请参阅 代码示例

    处理和显示结果

    手势识别程序会针对每个人 识别运行。结果对象包含图片坐标形式的手部特征点, 用世界坐标表示的手形地标、惯用手(左手/右手)和手用手势 所检测到的手的手势类别。

    以下示例展示了此任务的输出数据:

    生成的 GestureRecognizerResult 包含四个组成部分,每个组成部分都是一个数组,其中每个元素都包含所检测到的一只手的检测结果。

    • 惯用手

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

    • 手势

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

    • 地标

      这里有 21 个手形标志,每个标志由 xyz 坐标组成。通过 xy 坐标按图片宽度和 高度。z 坐标表示地标深度, 手腕的深度就是起点。值越小, 最接近的是镜头。z的震级使用的刻度与 x

    • 世界地标

      21 个手形地标也以世界坐标表示。每个地标 由 xyz 组成,表示现实世界中的 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)
    

    下图直观显示了任务输出:

    有关创建手势识别器任务的更完整实现,请参阅 代码示例