借助 MediaPipe 手势识别器任务,你可以实时识别手势; 提供识别出的手势结果以及 检测到手部设备。以下说明介绍了如何使用手势识别程序 。
要了解此任务的实际运行情况,请查看 演示。 如需详细了解功能、模型和配置选项 部分,请参阅概览。
代码示例
手势识别程序的示例代码提供了该手势的完整实现, 供您参考。此代码可帮助您测试此任务, 开始打造自己的手势识别应用。您可以查看、运行 修改手势识别器示例代码 只需使用网络浏览器即可。
设置
本部分介绍设置开发环境的关键步骤 特别是使用手势识别器有关 设置 Web 和 JavaScript 开发环境 平台版本要求,请参阅 网页版设置指南。
JavaScript 软件包
手势识别器代码可通过 MediaPipe @mediapipe/tasks-vision
获取
NPM 软件包。您可以
按照平台中的说明查找并下载这些库
设置指南。
您可以通过 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"] |
|
|
custom_gestures_classifier_options |
用于配置自定义手势分类器行为的选项。 |
|
|
准备数据
手势识别程序可以识别图片中采用 托管浏览器该任务还会处理数据输入预处理,包括 调整大小、旋转和值归一化。要识别视频中的手势,您需要 可以使用该 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 个手形标志,每个标志由
x
、y
和z
坐标组成。通过x
和y
坐标按图片宽度和 高度。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)
下图直观显示了任务输出:
有关创建手势识别器任务的更完整实现,请参阅 代码示例。