简介：面向 FPGA 与图像处理开发者的原创手势识别工程包，首次发布，提供基于 Verilog 的完整源代码与配套说明文档，覆盖静态手势、动态手势、轨迹跟踪三类典型识别模式，适合学习数字逻辑设计与实时视觉算法的学生、研究者及工程师。压缩包共 523 个文件，约 22.12MB，以 v 源码、bin/bit 配置文件、ucf/ncf 约束文件、xise 工程文件及 pdf 文档为主体，并保留大量仿真、综合、布局布线过程文件，便于直接查看工程结构、恢复完整设计流程。已有 4223 人学习下载。说明文档对系统架构、Verilog 关键模块、FPGA 配置与调试流程做了细致展开，同时给出扩展手势库和优化识别率的建议；结合代码可完整走通图像采集、预处理、特征提取、匹配决策的实现链路，对上手 FPGA 视觉项目很有参考价值，对后续接入人工智能与物联网应用也有帮助。 最近终于把手头这个手势识别项目整理干净了，源码加说明文档一并发出来。项目从零手写，没有套用任何现成模板，核心基于 Python 和 OpenCV 实现，配合 MediaPipe 做手部关键点检测，可以实时识别数字 1 到 5，以及握拳、掌心、OK 等几个常用指令。实测在普通笔记本摄像头上能稳定跑到 25 帧以上，代码注释详细，文档齐全，拿过去就能跑、能改、能二次开发。这篇博文就把整个项目的设计思路、核心原理、源码结构和实操过程掰开揉碎讲一遍。
适合正在学计算机视觉、入门深度学习模型落地，或者想做人机交互小项目的朋友参考。哪怕你之前没接触过 MediaPipe，跟着走一遍也能搞清楚“摄像头里的手”是怎么被机器“看懂”的。
1. 项目概述与整体设计思路
1.1 为什么选择摄像头手势识别这个方向
传统的人机交互基本靠鼠标、键盘、触摸屏，但很多场景下“隔空操作”明显更自然——比如讲 PPT 的时候不想走回电脑前，做饭时戴着一次性手套不方便碰屏幕，或者只是单纯想摆脱物理设备的束缚。手势识别就是解决这类问题的关键技术之一，也是计算机视觉里一个典型的“入门容易、做好难”的方向。
我最初想做这个项目，主要目的是验证一条完整的视觉识别链路：摄像头采集图像、把图像里的手“找”出来、再把手势语义转化成控制指令。这个链路打通之后，无论是控制鼠标、切歌、翻页，还是做智能家居的人体感应，都只是在系统输出端接不同的执行器而已，底层的识别逻辑完全可以复用。
另一个原因是“可用性”。网上关于手势识别的代码很多，但大部分要么只贴了一段原理演示，要么依赖一堆训练好的第三方模型，没有说明文档、没有可运行的工程结构，下载来根本跑不通。所以这次特意把工程结构、注释、说明书一并整理好，以后自己回看也省事，别人拿到也不至于一脸懵。
1.2 技术选型：OpenCV + MediaPipe 还是纯 OpenCV
做手势识别，视觉方案上通常有几条路：传统 OpenCV 手法（肤色检测、轮廓提取、凸包缺陷分析）、深度学习方案（YOLO 检测手部区域再加分类网络）、轻量级关键点方案（MediaPipe Hands 或者手部姿态估计模型）。
我一开始在“纯 OpenCV”和“OpenCV + MediaPipe”之间纠结了很久，后来给了自己一张对比表：
| 方案 | 识别精度 | 实时性能 | 开发成本 | 依赖复杂度 | 可解释性 |
|---|---|---|---|---|---|
| 纯 OpenCV 肤色+轮廓 | 低，受光照和背景影响极大 | 高 | 低，但调参到崩溃 | 低 | 高，逻辑完全可控 |
| OpenCV + MediaPipe | 高，关键点定位稳定 | 高，CPU 下也能实时 | 中，需要读文档 | 中，多一个 pip 包 | 中，关键点可视化清晰 |
| 自定义训练手势分类网络 | 取决于数据量和训练 | 需要 GPU 加速 | 高，要准备数据集 | 高 | 低，黑盒 |
纯 OpenCV 方案最大的问题在于鲁棒性。肤色检测在黄种人、白种人、黑种人身上的 HSV 范围不一样，环境光稍微一变就容易把脸或背景里的暖色物体误判成手；轮廓特征又处理不了手指并拢、遮挡、复杂背景的情况。调参调到怀疑人生，最后还是决定放弃。
MediaPipe Hands 是 Google 开源的轻量级手部关键点检测方案，模型能在 CPU 上跑，输出手部 21 个关键点的坐标。关键是它做过大量数据增强，对不同肤色、光照、复杂背景的适应能力远强于传统肤色算法。所以最终确定方案：OpenCV 负责图像采集、画面绘制、交互处理，MediaPipe 只负责把手部关键点“抠”出来，手势的语义判断由自己写的算法完成，整体可控、可解释、可读性强。
2. 核心细节解析与源码实现要点
2.1 手部关键点检测原理：21 个关键点是怎么回事
MediaPipe Hands 输出的 21 个关键点，可以理解成在手掌和手指上“打”了 21 个坐标。每个点都有固定的编号，比如 0 号点是手腕根部，4 号点是拇指指尖，8 号点是食指指尖，12 号点是中指指尖，16 号点是无名指指尖，20 号点是小拇指指尖。
如果只把这 21 个点画在画面上，你会发现它们完美勾勒出整只手的骨架。这背后的原理是：模型通过深度卷积网络，从图像中直接回归出每个关键点的坐标，相当于先“看懂”了手的大致位置和姿态，再精确到关节级别。
做手势分类时，并不需要所有关键点都参与计算。核心参考点其实就两类：一类是五根手指的指尖点，用来判断手指伸没伸直；另一类是相邻关节的坐标，用来做角度计算。比如判断食指是否伸直，可以比较食指指尖（8 号点）和食指中间关节（7 号点）之间的相对位置，再加上食指根部（6 号点）的连线角度，综合判断比单独看距离可靠得多。
2.2 手势分类算法设计：从关键点到手势意图
拿到 21 个关键点坐标之后，最核心的问题是：怎么判断当前手势是数字 2 还是数字 3？我采用的算法思路是“手指伸直数量 + 方向约束”，没有额外训练分类模型，直接把几何规则写到代码里。
判断一根手指是否伸直，最直观的方法是看“指尖到手腕的距离”和“该手指根部到手腕的距离”的比值。如果指尖离手腕比根部远很多，说明手指是伸开的；如果两者差不多，说明手指是弯曲的。但这个方法对大拇指不太友好，因为大拇指的活动方向和其它四指不一样，所以我单独用角度来判断：计算拇指指尖、食指根部、手腕三点之间的夹角，再根据夹角判断拇指是张开还是贴在手掌上。
具体识别规则举例：
- 数字 1：仅食指伸直，其余四指弯曲
- 数字 2：食指和中指伸直，其余弯曲
- 数字 3：食指、中指、无名指伸直，其余弯曲
- 数字 4：除拇指外四指伸直
- 数字 5：五指全部伸直
- 握拳：五指全部弯曲
- 掌心：五指全部伸直且掌面正对摄像头，这个还可以结合掌心点的深度信息辅助判断
这段识别逻辑看起来简单，但在实际调的时候发现，每个人手指比例不一样，固定的距离阈值会导致有的人握拳被判成数字 1。所以我把所有阈值都改成了对 21 个关键点坐标的归一化计算——先把坐标全部转换到手部包围框的相对位置，再算比值和角度，这样不同手掌大小的人都能通用。
2.3 平滑处理与帧率优化：让识别结果不“抽搐”
单帧识别最大的问题是抖动。摄像头每帧图像都会有轻微噪声，模型定位关键点也可能出现一两个像素的漂移，反映到手势判断上就是“明明没动，识别结果在 1 和 2 之间疯狂跳变”。
解决抖动最直接的手段是做时间维度的平滑，类似信号处理里的低通滤波。我实现了一个简单的指数滑动平均：当前识别结果是current，上一帧的稳定结果是last，那么新输出的结果result = alpha * current + (1 - alpha) * last。alpha 在 0 到 1 之间，取值越大越灵敏，取值越小越稳定。
但这里有个小陷阱：alpha 不能设得太低，否则手势真变了结果却很迟钝，产生很明显的“跟手延迟”。我测试下来 alpha 在 0.6 到 0.8 之间比较平衡。另外，对于离散的手势类型（比如“数字 2”和“数字 3”），不能直接做数值平均，需要改为“连续 N 帧结果一致才刷新显示”的策略。我用了 3 帧确认制，相当于给识别结果加了一个去抖窗口，既避免了单帧误判，又不会太多地引入延迟。
帧率优化方面，最有效的手段是降低输入分辨率。摄像头原始画面可能是 640x480，如果直接丢给 MediaPipe 处理，在低端 CPU 上会比较吃力。我先把画面缩放一档，识别完关键点后再把坐标映射回原始分辨率用于显示。对用户来说几乎感觉不到画质变化，但 FPS 能明显提升。
3. 说明文档的编写与项目发布结构
3.1 说明文档要写什么：从环境到 FAQ
很多开源项目源码质量不错，但 README 写得太随意，拿到手根本不知道怎么从零跑起来。这次写说明文档的时候，我坚持一个原则：假设读者完全不了解这个项目，但懂基本的 Python 操作，顺着文档一步一步走，能在 20 分钟内把项目跑起来。
文档结构我分成了五块：项目简介、环境依赖、快速开始、自定义配置、常见问题。项目简介里不写废话，直接说清楚“这个项目是什么、能识别哪些手势”；环境依赖精确到 Python 版本和几个核心库的版本号；快速开始部分给出逐条命令，并在最后附上运行截图；自定义配置部分把代码里常用的几个参数（识别置信度、平滑帧数、摄像头编号）都抽出来讲解；常见问题部分提前写清楚新手最容易踩的三个坑：摄像头打不开、检测不到手、运行报错。
写说明文档最大的心得是：命令要能直接复制粘贴，参数修改要写清楚改动后有什么效果。比如“把 min_detection_confidence 从 0.5 改成 0.7，识别会更谨慎，误检变少但有时会漏检”，这种描述对于一个第一次接触 MediaPipe 的读者非常有价值。
3.2 项目目录结构与运行流程
这次项目的工程结构不算复杂，但为了方便后续扩展，我特意把“摄像头处理”和“手势识别逻辑”分开了。核心目录如下：
gesture-recognition/ ├── main.py # 程序入口，负责摄像头、主循环、展示 ├── gesture_recognition.py # 手势识别核心模块，封装了关键点解析和分类 ├── config.py # 配置文件，集中管理所有可调参数 ├── requirements.txt # 依赖清单 ├── README.md # 说明文档 └── assets/ └── demo.gif # 演示动图main.py 里只做四件事：初始化摄像头、初始化识别模块、循环读取和处理帧、退出时释放资源。gesture_recognition.py 里有两个核心类：HandDetector 负责调用 MediaPipe 获取关键点坐标，GestureRecognizer 负责把关键点坐标解析成具体手势。config.py 把所有魔法数字全部集中起来，方便根据不同摄像头或使用场景调参。
整体运行流程是：读摄像头帧 → 转换颜色空间（OpenCV 是 BGR，MediaPipe 需要 RGB）→ 送入检测模型 → 拿回 21 个关键点 → 传入手势分类器 → 将结果画在原始帧上 → 显示到窗口。整个链路中，颜色空间转换是最容易忽略但最容易出错的环节，少了这一步，关键点检测效果会变得非常差，基本等同于不可用。
3.3 “绝对原创、可用”是怎么做到的
标题里写了“绝对原创、可用”，这不是随便说说。为了达到这两个标准，我做了三件事：第一，手势分类算法完全自己实现，没有调用任何别人封装好的识别函数；第二，代码不依赖付费库、不依赖在线服务，模型文件在安装 MediaPipe 时同步下载，第一次运行后就能离线使用；第三，在发布前把代码放到两台配置完全不同的电脑上分别跑了一遍，一台是 Win10 + 核显笔记本，一台是 Win11 + 独显台式机，都跑通了才放出来。
这个“可用”不是指在自己的环境里能跑，而是要经得起换环境折腾。所以我在 README 里明确写了测试环境：Python 3.8 到 3.11、OpenCV 4.x、MediaPipe 0.10 以上。如果读者用的版本不一样，大概率也能跑，但遇到兼容性问题时，先检查这三个依赖版本是最快的排查路径。
4. 实操过程与核心环节实现
4.1 环境准备与依赖安装
先说明一下我用的开发环境：Windows 10、Python 3.9。这三个核心库是必须的：
| 库名 | 版本 | 作用 |
|---|---|---|
| opencv-python | 4.8+ | 图像采集、图像处理、画面绘制 |
| mediapipe | 0.10+ | 手部关键点检测模型 |
| numpy | 1.24+ | 坐标计算与数值处理 |
安装命令很简单，用 pip 一把梭：
pip install opencv-python mediapipe numpy如果你使用的是 conda 环境，建议先创建独立环境再安装，避免污染基础环境：
conda create -n gesture python=3.9 conda activate gesture pip install opencv-python mediapipe numpy这里有一个容易被坑的点：MediaPipe 在某些 Python 版本下可能没有预编译的 wheel 包，建议优先使用 Python 3.8 或 3.9，这两个版本兼容性最好。如果碰到安装报错，往下看第 5 节的排查表。
4.2 核心代码模块解析
先看 main.py 里的主循环部分，代码不算复杂，但每一步都有明确目的：
import cv2 from gesture_recognition import HandDetector, GestureRecognizer from config import Config cap = cv2.VideoCapture(Config.CAMERA_ID) detector = HandDetector(min_detection_confidence=Config.MIN_DETECT_CONF) recognizer = GestureRecognizer() while True: success, frame = cap.read() if not success: break # 转成 RGB，因为 MediaPipe 模型是基于 RGB 训练的 rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) landmarks = detector.get_landmarks(rgb_frame) if landmarks: gesture = recognizer.recognize(landmarks) detector.draw_landmarks(frame) cv2.putText(frame, f"Gesture: {gesture}", (10, 50), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2) else: cv2.putText(frame, "No hand detected", (10, 50), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 0, 255), 2) cv2.imshow("Gesture Recognition", frame) if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()HandDetector 类的核心是调用 MediaPipe 的hands.process()方法拿到multi_hand_landmarks，然后提取第一只手的 21 个关键点坐标：
class HandDetector: def __init__(self, min_detection_confidence=0.5): self.mp_hands = mp.solutions.hands self.hands = self.mp_hands.Hands( static_image_mode=False, max_num_hands=1, min_detection_confidence=min_detection_confidence, min_tracking_confidence=0.5 ) def get_landmarks(self, rgb_frame): result = self.hands.process(rgb_frame) if not result.multi_hand_landmarks: return None hand = result.multi_hand_landmarks[0] h, w, _ = rgb_frame.shape return [(int(lm.x * w), int(lm.y * h)) for lm in hand.landmark]这里把关键点的坐标从归一化空间映射回像素坐标空间，方便后续直接做几何计算和画面绘制。GestureRecognizer 里的识别算法基于手指伸直状态，核心逻辑是分别判断五根手指的弯曲和伸直，然后组合成手势。代码里最好把每一根手指的判断逻辑拆成独立函数，方便调试时单独验证哪根指头误判了。
4.3 参数调节建议：让识别更听话
config.py 集中了所有可调参数，是我在实际调试中反复调整后总结出来的经验值：
class Config: CAMERA_ID = 0 # 摄像头编号，多个摄像头时切换 MIN_DETECT_CONF = 0.5 # 最小检测置信度，0.5-0.8 之间 MIN_TRACK_CONF = 0.5 # 最小跟踪置信度 SMOOTH_FRAMES = 3 # 手势确认帧数，越大越稳定 SHOW_LANDMARKS = True # 是否显示关键点连线min_detection_confidence 是最影响手感的参数。设低了，手在半遮挡或快速移动时也能被检测到，但容易出现误检；设高了，误检变少，但手偶尔离摄像头远一点就会丢失。我建议先用默认值 0.5 跑通流程，看自己的摄像头表现再微调，不要一上来就追求“完美参数”。
SMOOTH_FRAMES 是去抖窗口大小。用 2 帧确认时，误判还是会有；用 5 帧确认时，明显感觉响应变慢。3 帧是我测试下来实时性和稳定性最均衡的档位。另外，如果使用环境背景比较杂乱，建议降低输入图像分辨率，同时裁剪出画面中心区域给检测模型，这样可以显著减少背景干扰。
5. 常见问题与排查技巧实录
5.1 常见问题速查表
开发过程中踩了不少坑，我把最常遇到的几类问题整理成了表格，按“现象 → 原因 → 解法”的结构来排查：
| 故障现象 | 可能原因 | 解决办法 |
|---|---|---|
| 摄像头打不开，程序直接崩 | 摄像头编号不对或被占用 | 把 CAMERA_ID 改成 1 或 2；关闭其他占用摄像头的软件 |
| 一直提示 No hand detected | 手离得太远、光照太暗、手部运动过快 | 保持手在画面中央，距离 30-70cm；改善光照；降低分辨率 |
| 识别结果在几个手势间跳变 | 单帧误判、没有去抖 | 增大 SMOOTH_FRAMES；调整置信度阈值 |
| 运行卡顿，画面掉帧严重 | 输入分辨率太高、电脑性能不足 | 在读取摄像头后先 resize 再送检测模型 |
| 手势总是判断错误 | 摄像头安装角度倾斜、手掌方向不对 | 让手掌正面朝向摄像头，手指自然张开 |
最容易被忽略的是光照问题。逆光环境下手部轮廓几乎全黑，再好的模型也很难识别。建议把灯光打在手上而不是背后，或者在头上加一个小光源。另一个容易忽略的点是，MediaPipe 的手部检测对“朝向”有要求，手背对着摄像头时关键点定位会不稳定，尽量保持手掌心朝向摄像头。
5.2 独家避坑经验
第一，不要用 32 位 Python。很多视觉库对 32 位环境的支持不完整，装 OpenCV 和 MediaPipe 容易踩坑，建议直接用 64 位 Python。
第二，MediaPipe 依赖的 protobuf 版本可能和 TensorFlow 等其他库冲突。如果你电脑上同时装了 TensorFlow 和 MediaPipe，安装顺序不同可能导致运行时崩溃。解决办法是统一装 MediaPipe 推荐的 protobuf 版本，或者用虚拟环境隔离项目。
第三，摄像头分辨率不要盲目追求高。我试过用 1080p 分辨率跑，CPU 直接拉满，识别帧率掉到 10 FPS 以下；改成 480p 之后，帧率翻倍，识别精度几乎没有变化。因为手部关键点检测在中等分辨率下已经足够精确，没必要为像素浪费算力。
第四，在大窗口上显示识别结果时，不要用太高倍数的缩放。cv2.imshow 默认不支持鼠标缩放，窗口太大会超出屏幕边界，甚至导致 OpenCV 无法正常显示。可以在显示前把画面缩放到固定宽度（比如 960px），观感会好很多。
6. 扩展设想与二次开发建议
6.1 手势控制鼠标与音量
如果想让手势识别“有用”而不是“好玩”，可以把手势映射成系统级的控制指令。控制鼠标光标的核心是让手部关键点坐标变化与鼠标位移对应：取食指指尖坐标，映射到屏幕坐标，然后用 pyautogui 库移动鼠标；用拇指和食指指尖距离控制点击——距离小于某个阈值就触发点击事件。
控制系统音量可以借助 pycaw 库。先把音量分成 0 到 100 档，再把手掌垂直位置映射到音量档位，手抬高一点音量增大，放低一点音量减小。实测下来，这种交互很有科幻感，但要注意加一个“激活条件”，比如只有检测到数字 5 才开始控制音量，避免平时挥手就误调音量。
6.2 手势控制 PPT 翻页与视频播放
这个场景最适合做演示。默认规则可以设计为：识别到“掌心”表示进入控制模式；识别到“数字 2”表示下一页；识别到“数字 1”表示上一页。如果配合 pynput 库模拟键盘按键，直接监听手势识别结果，然后发送 PageDown 或 PageUp 按键事件，演示时就不用跑回电脑前按键了。
视频播放器控制也类似，用“数字 3”表示播放/暂停，“数字 4”表示快进，“握拳”表示退出。核心思路还是把识别结果映射成键盘快捷键，不需要和具体播放器深度绑定。如果你愿意，还可以进一步做动态手势识别——比如记录手指尖连续几帧的运动轨迹，根据轨迹方向判断“向左滑动”“向右滑动”“双击”等更复杂的手势，但这一块对算法和算力的要求会更高。
我个人做完这套手势识别之后，最大的感受是“说明文档比代码本身更费心思”。代码的逻辑是固定的，写完基本不会跑；但文档要揣摩别人拿到手之后会卡在哪些地方，尤其是环境安装和参数调试这两个环节，值得花时间写得细一点。另外，别小看 3 帧确认这种小技巧，它看起来没什么技术含量，却能让识别体验从“玩具级”提升到“接近可用”。希望这份源码和文档能帮你少踩一些坑。
本文还有配套的精品资源，点击获取
