视觉 · 手势识别

1. 模块概述

主要功能：基于 YOLOv5 的手势检测与分类，识别图像中的手势类别（如拳头、张开手掌、竖拇指等），输出手势区域的边界框、置信度与手势类别。
规格或特性：
- 支持模型：YOLOv5 Gesture
- 输入尺寸：[1, 3, 640, 640]
- 量化类型：int8
- 输出：手势边界框 + 置信度 + 手势类别
- 推理后端：ONNX Runtime + SpaceMITExecutionProvider
- 接口形态：C++（vision_service.h）、Python（spacemit_vision wheel：VisionServiceNative）
相关目录结构：

examples/yolov5_gesture/
├── config/yolov5_gesture.yaml   # 配置文件
├── cpp/yolov5_gesture.cpp       # C++ 示例
├── python/yolov5_gesture.py     # Python 示例
└── scripts/                     # 模型下载脚本
src/deploy/yolov5_gesture/       # 部署实现（C++ / Python）
assets/labels/gesture.txt        # 手势类别标签

2. 环境准备

前置条件

SDK 源码获取和基础编译环境配置统一参考 2.3-构建编译。完成 SDK 初始化后，回到本文继续执行"构建编译"。

后续命令默认在 spacemit_robot SDK 根目录执行。

构建编译

系统缺少依赖时先安装：

sudo apt install python3-spacemit-ort opencv-spacemit libeigen3-dev spacemit-onnxruntime libyaml-cpp-dev

在 SDK 根目录加载构建环境后编译视觉组件：

source build/envsetup.sh
cd components/model_zoo/vision
mm

SDK 集成构建会把 yolov5_gesture 等示例程序安装到 output/staging/bin，加载 build/envsetup.sh 后可直接运行。

运行 Python 示例前，需先安装 spacemit_vision wheel：

cd components/model_zoo/vision
python3 -m pip install -U pybind11 build setuptools wheel
cmake -S . -B build && cmake --build build -j
python3 -m pip install --force-reinstall src/python/dist/*.whl
python3 -c "from spacemit_vision import VisionServiceNative; print('ok')"

模型权重默认存放路径为 ~/.cache/models/vision/yolov5/。须先手动执行下载脚本；缺失时程序会直接报错（Model file not found）。

3. 示例使用（从 0 跑通）

3.1 手势识别（Python）

前置：见 §2。

步骤 1：下载模型

cd components/model_zoo/vision
bash examples/yolov5_gesture/scripts/download_models.sh

预期现象：模型文件下载至 ~/.cache/models/vision/yolov5/yolov5_gesture.q.onnx。

步骤 2：下载测试素材

bash scripts/download_assets.sh

步骤 3：运行推理

python3 examples/yolov5_gesture/python/yolov5_gesture.py --config examples/yolov5_gesture/config/yolov5_gesture.yaml

3.2 手势识别（C++）

前置：见 §2，C++ 编译完成。

步骤 1：下载模型（同 §3.1 步骤 1）

步骤 2：运行推理

yolov5_gesture examples/yolov5_gesture/config/yolov5_gesture.yaml

3.3 运行结果示例

终端输出示例：

Detected 2 gesture(s):
  ok (class 0) score=0.900 box=[809.209,762.571,923.803,915.754]
  no_gesture (class 5) score=0.815 box=[401.791,1386.415,469.781,1524.662]
Result saved to: result_gesture.jpg

可视化结果：

YOLOv5 手势识别结果示例

图中展示了检测到的手势边界框、类别标签和置信度分数。

4. 应用开发

本章面向应用开发者，说明如何在自己的 C++ 或 Python 应用中集成手势识别组件。完整接口定义以 include/vision_service.h 和 src/python/spacemit_vision/vision_service_native.py 为准；本节介绍常用公开接口和典型调用方式。

4.1 接口说明

手势识别组件的核心入口是 VisionService（C++）和 VisionServiceNative（Python，spacemit_vision wheel）。应用侧通过这些接口加载 YOLOv5 手势识别模型，并发起图像或视频流的手势检测请求。

4.1.1 常用数据结构

类型	说明
vision::Detection	手势识别结果（位于 `namespace vision`），包含手势区域边界框 `bbox`（x1, y1, x2, y2）、置信度 `score`、手势类别 ID `label`。可用 `vision::get_bbox(result)`、`vision::get_label(result)`、`vision::get_score(result)` 读取共用字段。
VisionServiceResponse	推理响应，`results` 字段为 variant 列表 `vision::ResultList`（手势识别时元素为 `vision::Detection`）；另含 `ok`、`error_message`。

4.1.2 服务初始化

C++ 接口

接口	说明	参数	返回值
VisionService::Create	从 YAML 配置文件创建手势识别服务实例	config_path：YAML 配置文件路径	VisionService 智能指针
VisionService::LastCreateError	获取最近一次创建失败的错误信息	无	错误描述字符串

Python 接口

接口	说明	参数	返回值
VisionServiceNative.create	从 YAML 配置文件创建手势识别服务	config_path：YAML 路径；model_path_override：可选覆盖模型路径	VisionServiceNative 实例
VisionServiceNative.last_create_error	获取最近一次创建失败的错误信息	无	错误描述字符串

4.1.3 手势识别

C++ 接口

接口	说明	参数	返回值
Infer	对单张图像进行手势识别	image_path：图像文件路径；response：输出响应（VisionServiceResponse*）	VisionServiceStatus（VISION_SERVICE_OK 表示成功）
Infer	对 cv::Mat 图像进行手势识别	image：OpenCV Mat 对象；response：输出响应（VisionServiceResponse*）	VisionServiceStatus（VISION_SERVICE_OK 表示成功）
Draw	在图像上绘制识别结果（边界框、手势标签、置信度）	image：输入图像；response：识别响应；out_image：输出图像	VisionServiceStatus
LastError	获取最近一次推理的错误信息	无	错误描述字符串

Python 接口

接口	说明	参数	返回值
infer_image	对图像进行手势识别	image_or_path：BGR numpy 数组或图像路径；conf/iou：可选阈值	(VisionServiceStatus, results 列表)
draw	绘制最近一次推理结果	image：BGR numpy 数组	(VisionServiceStatus, 绘制后图像)
supports_draw	当前模型是否支持 C++ 侧绘制	无	bool
last_error	获取最近一次推理错误	无	错误描述字符串

4.1.4 性能监控

C++ 接口

接口	说明	参数	返回值
SetTimingOptions	启用/禁用性能计时	options：VisionServiceTimingOptions（enabled 控制启用）	void
GetLastTiming	获取最近一次推理的各阶段耗时	无	VisionServiceTiming 结构体（preprocess_ms、model_infer_ms、postprocess_ms、infer_ms 等）

4.2 典型调用流程

4.2.1 C++ 单图手势识别

#include "vision_service.h"
#include <opencv2/opencv.hpp>
#include <iostream>

int main() {
    // 1. 创建服务
    auto service = VisionService::Create("examples/yolov5_gesture/config/yolov5_gesture.yaml");
    if (!service) {
        std::cerr << "Failed to create service: " 
                  << VisionService::LastCreateError() << std::endl;
        return -1;
    }

    // 2. 启用性能计时（可选）
    VisionServiceTimingOptions timing_opts;
    timing_opts.enabled = true;
    service->SetTimingOptions(timing_opts);

    // 3. 执行推理
    VisionServiceResponse response;
    VisionServiceStatus ret = service->Infer("test.jpg", &response);
    if (ret != VISION_SERVICE_OK) {
        std::cerr << "Inference failed: " << service->LastError() << std::endl;
        return -1;
    }

    // 4. 处理结果
    std::cout << "Detected " << response.results.size() << " gesture(s):" << std::endl;
    for (const auto& r : response.results) {
        const vision::BoundingBox box = vision::get_bbox(r);
        std::cout << "  Gesture class " << vision::get_label(r)
                  << ", Score: " << vision::get_score(r)
                  << ", Box: [" << box.x1 << "," << box.y1 << ","
                  << box.x2 << "," << box.y2 << "]" << std::endl;
    }

    // 5. 绘制结果
    cv::Mat image = cv::imread("test.jpg");
    cv::Mat output;
    service->Draw(image, response, &output);
    cv::imwrite("result.jpg", output);

    // 6. 查看性能指标（可选）
    auto timing = service->GetLastTiming();
    std::cout << "Preprocess: " << timing.preprocess_ms << " ms" << std::endl;
    std::cout << "Inference: " << timing.model_infer_ms << " ms" << std::endl;
    std::cout << "Postprocess: " << timing.postprocess_ms << " ms" << std::endl;

    return 0;
}

4.2.2 C++ 视频流手势识别

#include "vision_service.h"
#include <opencv2/opencv.hpp>

int main() {
    auto service = VisionService::Create("examples/yolov5_gesture/config/yolov5_gesture.yaml");
    cv::VideoCapture cap(0);  // 打开摄像头
    cv::Mat frame, output;

    while (cap.read(frame)) {
        VisionServiceResponse response;
        service->Infer(frame, &response);
        service->Draw(frame, response, &output);
        
        cv::imshow("Gesture Recognition", output);
        if (cv::waitKey(1) == 'q') break;
    }

    return 0;
}

4.2.3 Python 单图手势识别

import cv2
from spacemit_vision import VisionServiceNative, VisionServiceStatus

svc = VisionServiceNative.create("examples/yolov5_gesture/config/yolov5_gesture.yaml")
image = cv2.imread("test.jpg")

status, results = svc.infer_image(image)
if status != VisionServiceStatus.OK:
    raise RuntimeError(svc.last_error())

for r in results:
    print(f"Class {r.label}, Score: {r.score:.4f}")

if svc.supports_draw():
    st, output = svc.draw(image)
    if st == VisionServiceStatus.OK:
        cv2.imwrite("result.jpg", output)

4.2.4 Python 视频流手势识别

import cv2
from spacemit_vision import VisionServiceNative, VisionServiceStatus

svc = VisionServiceNative.create("examples/yolov5_gesture/config/yolov5_gesture.yaml")
cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break
    status, _ = svc.infer_image(frame)
    if status != VisionServiceStatus.OK:
        break
    output = frame
    if svc.supports_draw():
        st, output = svc.draw(frame)
    cv2.imshow("Gesture", output)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

4.3 配置说明

YAML 配置文件是模型加载和推理参数的核心，以下是完整配置项说明：

# 模型文件路径（YOLOv5 手势识别模型）
model_path: ~/.cache/models/vision/yolov5/yolov5_gesture.q.onnx

# 测试图像路径（用于示例程序）
test_image: ~/.cache/assets/image/007_gesture.jpg

# 类别标签文件路径（手势类别）
label_file_path: assets/labels/gesture.txt

# 模型输入尺寸 [height, width]
image_size: [640, 640]

# 部署类名（C++ 模型工厂注册名，Python 通过 yaml 路径间接使用）
class: deploy.yolov5_gesture.YOLOv5GestureDetector

# 推理参数
default_params:
  # 置信度阈值（0.0-1.0），手势识别使用较高阈值
  conf_threshold: 0.8
  
  # IOU 阈值（0.0-1.0），用于 NMS 非极大值抑制
  iou_threshold: 0.5
  
  # 推理线程数（示例默认 8；K3 平台 intra-op 最大建议 8，可按场景调低）
  num_threads: 8
  
  # 推理后端（优先使用 SpaceMITExecutionProvider）
  providers:
    - SpaceMITExecutionProvider
    - CPUExecutionProvider  # 备用后端

参数调优建议：

conf_threshold：手势识别默认使用较高阈值 0.8 以减少误检，如检测不到手势可适当降低至 0.5-0.6。
iou_threshold：默认 0.5 适用于大多数场景。
num_threads：示例 yaml 默认为 8，K3 平台 intra-op 线程数最大建议 8。若 CPU 竞争或延迟不稳定，可尝试降至 4 观察效果，不建议超过 8。
providers：优先使用 SpaceMITExecutionProvider 以获得最佳性能。

4.4 性能监控

通过启用性能计时，可以分析推理各阶段的耗时，用于性能优化和瓶颈定位。

C++ 示例：

VisionServiceTimingOptions timing_opts;
timing_opts.enabled = true;
service->SetTimingOptions(timing_opts);

VisionServiceResponse response;
service->Infer("test.jpg", &response);

auto timing = service->GetLastTiming();
std::cout << "Preprocess: " << timing.preprocess_ms << " ms" << std::endl;
std::cout << "Inference: " << timing.model_infer_ms << " ms" << std::endl;
std::cout << "Postprocess: " << timing.postprocess_ms << " ms" << std::endl;
std::cout << "Total: " << (timing.preprocess_ms + timing.model_infer_ms + timing.postprocess_ms) << " ms" << std::endl;

性能优化建议：

预处理耗时高：检查图像尺寸是否过大，考虑降低输入分辨率。
推理耗时高：确认使用 SpaceMITExecutionProvider，检查线程数设置。
后处理耗时高：适当提高 conf_threshold 可减少处理对象数量。

参考 demo 路径：examples/yolov5_gesture/

5. 调试指南

启用计时：通过 SetTimingOptions 查看各阶段耗时
检测不到手势：默认 conf_threshold 为 0.8，较高，可适当降低
确认标签文件 assets/labels/gesture.txt 存在且内容正确

6. 常见问题

现象	可能原因	处理
`Model file not found`	模型未下载	执行 `bash examples/yolov5_gesture/scripts/download_models.sh`
`No module named 'spacemit_vision'`	wheel 未安装	按 §2 编译并 `pip install src/python/dist/*.whl`
检测结果为空	`conf_threshold` 过高	降低 `conf_threshold`（如 0.5）
手势类别错误	标签文件不匹配	确认 `label_file_path` 指向 `assets/labels/gesture.txt`

附录：性能与测试数据

手势模型 yolov5_gesture.q.onnx 在 README 中未单独列出；同架构 YOLOv5 检测模型在 README.md 附录「不包含前后处理」中的 K3 数据如下（纯 ONNX 推理，不含前后处理）：

具体模型	输入大小	数据类型	帧率 (4核)	帧率 (8核)
yolov5n	[1,3,640,640]	int8	69.1	104.4
yolov5s	[1,3,640,640]	int8	41.3	62.8

复现方法（手势专用模型）：

onnxruntime_perf_test ~/.cache/models/vision/yolov5/yolov5_gesture.q.onnx -e spacemit -r 20 -x 1 -S 1 -s -I -c 1 -i "SPACEMIT_EP_INTRA_THREAD_NUM|4"

1. 模块概述​

2. 环境准备​

前置条件​

构建编译​

3. 示例使用（从 0 跑通）​

3.1 手势识别（Python）​

3.2 手势识别（C++）​

3.3 运行结果示例​

4. 应用开发​

4.1 接口说明​

4.1.1 常用数据结构​

4.1.2 服务初始化​

4.1.3 手势识别​

4.1.4 性能监控​

4.2 典型调用流程​

4.2.1 C++ 单图手势识别​

4.2.2 C++ 视频流手势识别​

4.2.3 Python 单图手势识别​

4.2.4 Python 视频流手势识别​

4.3 配置说明​

4.4 性能监控​

5. 调试指南​

6. 常见问题​

附录：性能与测试数据​

1. 模块概述

2. 环境准备

前置条件

构建编译

3. 示例使用（从 0 跑通）

3.1 手势识别（Python）

3.2 手势识别（C++）

3.3 运行结果示例

4. 应用开发

4.1 接口说明

4.1.1 常用数据结构

4.1.2 服务初始化

4.1.3 手势识别

4.1.4 性能监控

4.2 典型调用流程

4.2.1 C++ 单图手势识别

4.2.2 C++ 视频流手势识别

4.2.3 Python 单图手势识别

4.2.4 Python 视频流手势识别

4.3 配置说明

4.4 性能监控

5. 调试指南

6. 常见问题

附录：性能与测试数据