通过 MediaPipe 手部地标器任务,您可以检测图片中手部的特征点。 以下说明介绍了如何在 Python 中使用手部特征点。通过 您可在 GitHub
如需详细了解功能、模型和配置选项 部分,请参阅概览。
代码示例
手部特征器的示例代码提供了此特征 供您参考。此代码可帮助您测试此任务, 开始构建自己的手部特征点检测器。您可以查看、运行 修改 手势特征器示例代码 只需使用网络浏览器即可。
设置
本部分介绍了设置开发环境和 代码项目。有关 设置开发环境以使用 MediaPipe 任务,包括 平台版本要求,请参阅 Python 设置指南。
<ph type="x-smartling-placeholder">软件包
MediaPipe Hand Markerer 任务需要 mediapipe PyPI 软件包。 您可以使用以下命令安装并导入这些依赖项:
$ python -m pip install mediapipe
导入
导入以下类以使用手部特征点任务函数:
import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision
型号
MediaPipe 手部地标器任务需要一个与此训练兼容的模型, 任务。如需详细了解适用于手部特征器的训练后模型,请参阅 任务概览的“模型”部分。
选择并下载模型,然后将其存储在本地目录中:
model_path = '/absolute/path/to/gesture_recognizer.task'
使用 BaseOptions
对象 model_asset_path
参数指定路径
要使用的模型。如需查看代码示例,请参阅下一部分。
创建任务
MediaPipe 手部地标器任务使用 create_from_options
函数
设置任务。create_from_options
函数接受值
处理配置选项如需详细了解配置
选项,请参阅配置选项。
以下代码演示了如何构建和配置此任务。
这些示例还展示了图片任务构建的不同变体, 视频文件和直播服务
映像
import mediapipe as mp BaseOptions = mp.tasks.BaseOptions HandLandmarker = mp.tasks.vision.HandLandmarker HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions VisionRunningMode = mp.tasks.vision.RunningMode # Create a hand landmarker instance with the image mode: options = HandLandmarkerOptions( base_options=BaseOptions(model_asset_path='/path/to/model.task'), running_mode=VisionRunningMode.IMAGE) with HandLandmarker.create_from_options(options) as landmarker: # The landmarker is initialized. Use it here. # ...
视频
import mediapipe as mp BaseOptions = mp.tasks.BaseOptions HandLandmarker = mp.tasks.vision.HandLandmarker HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions VisionRunningMode = mp.tasks.vision.RunningMode # Create a hand landmarker instance with the video mode: options = HandLandmarkerOptions( base_options=BaseOptions(model_asset_path='/path/to/model.task'), running_mode=VisionRunningMode.VIDEO) with HandLandmarker.create_from_options(options) as landmarker: # The landmarker is initialized. Use it here. # ...
直播
import mediapipe as mp BaseOptions = mp.tasks.BaseOptions HandLandmarker = mp.tasks.vision.HandLandmarker HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions HandLandmarkerResult = mp.tasks.vision.HandLandmarkerResult VisionRunningMode = mp.tasks.vision.RunningMode # Create a hand landmarker instance with the live stream mode: def print_result(result: HandLandmarkerResult, output_image: mp.Image, timestamp_ms: int): print('hand landmarker result: {}'.format(result)) options = HandLandmarkerOptions( base_options=BaseOptions(model_asset_path='/path/to/model.task'), running_mode=VisionRunningMode.LIVE_STREAM, result_callback=print_result) with HandLandmarker.create_from_options(options) as landmarker: # The landmarker is initialized. Use it here. # ...
有关创建与图片搭配使用的手部地标器的完整示例,请参阅 代码示例。
配置选项
此任务具有以下适用于 Python 应用的配置选项:
选项名称 | 说明 | 值范围 | 默认值 |
---|---|---|---|
running_mode |
设置任务的运行模式。有三个
模式: IMAGE:单图输入的模式。 VIDEO:视频已解码帧的模式。 LIVE_STREAM:输入流媒体直播模式 例如来自相机的数据。在此模式下,resultListener 必须为 调用以设置监听器以接收结果 异步执行。 |
{IMAGE, VIDEO, LIVE_STREAM } |
IMAGE |
num_hands |
手部地标检测器检测到的手的数量上限。 | 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 |
result_callback |
设置结果监听器以接收检测结果
异步执行。
仅在跑步模式设为“LIVE_STREAM ”时适用 |
不适用 | 不适用 |
准备数据
将输入准备为图片文件或 Numpy 数组,
然后将其转换为 mediapipe.Image
对象。如果输入是视频文件
或使用摄像头进行直播时,您可以使用外部媒体库,例如
OpenCV:以 Numpy 形式加载输入帧
数组。
映像
import mediapipe as mp # Load the input image from an image file. mp_image = mp.Image.create_from_file('/path/to/image') # Load the input image from a numpy array. mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)
视频
import mediapipe as mp # Use OpenCV’s VideoCapture to load the input video. # Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS # You’ll need it to calculate the timestamp for each frame. # Loop through each frame in the video using VideoCapture#read() # Convert the frame received from OpenCV to a MediaPipe’s Image object. mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
直播
import mediapipe as mp # Use OpenCV’s VideoCapture to start capturing from the webcam. # Create a loop to read the latest frame from the camera using VideoCapture#read() # Convert the frame received from OpenCV to a MediaPipe’s Image object. mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
运行任务
手部特征点使用检测、detect_for_video 和 detect_async 函数来触发推理。对于手部特征点检测,这涉及 预处理输入数据、检测图片中的手和检测手 地标。
以下代码演示了如何使用任务模型执行处理。
映像
# Perform hand landmarks detection on the provided single image. # The hand landmarker must be created with the image mode. hand_landmarker_result = landmarker.detect(mp_image)
视频
# Perform hand landmarks detection on the provided single image. # The hand landmarker must be created with the video mode. hand_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)
直播
# Send live image data to perform hand landmarks detection. # The results are accessible via the `result_callback` provided in # the `HandLandmarkerOptions` object. # The hand landmarker must be created with the live stream mode. landmarker.detect_async(mp_image, frame_timestamp_ms)
请注意以下几点:
- 在视频模式或直播模式下投放广告时,您还必须 为手部地标器任务提供输入帧的时间戳。
- 在图片或视频模型中运行时,手部特征点任务将 阻塞当前线程,直到它处理完输入图像,或者 帧。
- 在直播模式下运行时,手部特征点任务不会阻止 当前线程,但会立即返回。它将调用其结果 监听器,从而在每次完成处理后返回检测结果 输入帧。如果在调用手部特征器时调用了检测函数, 任务正忙于处理另一个帧,则该任务将忽略新的输入帧。
有关对图片运行手部特征点标记器的完整示例,请参阅 代码示例。
处理和显示结果
手部地标器会针对每次检测生成手部地标器结果对象 运行。结果对象包含以图片坐标表示的手部地标 世界坐标上的地标和所检测到的惯用手(左/右) 的双手。
以下示例展示了此任务的输出数据:
HandLandmarkerResult
输出包含三个组成部分。每个组成部分都是一个数组,其中每个元素都包含所检测到的单个手的以下结果:
惯用手
惯用手表示检测到的手是左手还是右手。
地标
这里有 21 个手形标志,每个标志由
x
、y
和z
坐标组成。通过x
和y
坐标按图片宽度和 高度。z
坐标表示地标深度, 手腕的深度就是起点。值越小, 最接近的是镜头。z
的震级使用的刻度与x
。世界地标
21 个手形地标也以世界坐标表示。每个地标 由
x
、y
和z
组成,表示现实世界中的 3D 坐标 以指针的几何中心为起点
HandLandmarkerResult:
Handedness:
Categories #0:
index : 0
score : 0.98396
categoryName : Left
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)
下图直观显示了任务输出:
手部特征器示例代码演示了如何显示 结果,请参阅 代码示例 了解详情。