简介面向计算机相关专业学生与机器学习初学者这是一套基于MediaPipe实现手势数字识别的完整项目资源包含Python源码和详细项目说明覆盖从手部关键点提取、特征处理到数字分类的完整流程适合用于课程设计、毕业设计或大作业实战。压缩包共2014个文件其中1991个npy数据文件集中存放训练与测试所需的特征样本另有3个py源文件负责核心代码5个xml配置文件用于参数或管线配置1个md说明文档详解实现思路与运行方式整体仅11.64MB数据与代码组织清晰、便于对照学习。读者可以通过阅读md快速理解MediaPipe手部关键点提取、数据组织与分类模型训练的衔接关系再直接运行py源码观察实际识别效果。目前已有318人学习下载对于希望在真实项目中熟悉手势识别流程、积累机器学习实战经验的学习者具有较高借鉴价值。1. 为什么这个手势数字识别项目选 mediapipe关键点比轮廓检测省一半的事如果你第一次做手势数字识别很容易照着老教程走一遍轮廓检测加凸包分析背景一杂、光线一变、手稍微偏个角度就全线翻车。基于 mediapipe 实现手势数字识别本质上是把问题从“图像检测”换成了“关键点分类”——mediapipe 直接给出手部 21 个关键点坐标你不需要自己写分割、不需要算手指数量只需要把这些关键点整理成特征交给机器学习模型分出 0-9。对正在做课程项目、想练 cv 加机器学习完整流程、或者想快速做出交互原型的开发者来说这是当前投入产出比最高的一条路。这篇文章按我实际做过的手势数字识别方案把环境搭建、数据采集、模型训练、实时推理和踩坑记录一整套写给你。2. 搭建环境与最小管线用 mediapipe 提取手势 21 关键点的详细步骤2.1 安装 mediapipe 与 opencv先确认 python 版本再动手常见做法是先创建一个干净的 python 环境再装依赖。用手势数字识别项目最常用的一套组合是 mediapipe 加 opencv-python训练部分加 scikit-learn数据运算加 numpy。安装命令如下python -m pip install mediapipe opencv-python numpy scikit-learn这里有两个细节。第一要用python -m pip而不是直接pip install因为很多人的电脑里同时存在 python2 和 python3 的 pip直接敲 pip 可能装进了错误的环境。第二mediapipe 对 python 版本有要求建议使用 3.8 到 3.11 之间的版本不要一上来就装最新的 python 3.13否则很可能会遇到没有对应轮子、编译失败或者 import 报错。装完之后验证一下环境是否干净。打开终端执行python -c import mediapipe; print(mediapipe.__version__)能打印出版本号就说明安装成功。如果报错多半是 protobuf 或 numpy 版本冲突。我遇到这种情况一般会执行python -m pip install --upgrade mediapipe numpy重新拉一遍依赖少数情况需要卸载重装 mediapipe。这些是安装阶段最常见的坑没必要死磕重装一次通常能解决。2.2 第一段识别代码从摄像头取帧打印 hand landmark 坐标环境就绪后先写一段最小代码跑通摄像头取流和关键点提取确认 mediapipe 在你的机器上能正常工作再往下做数据集和模型。import cv2 import mediapipe as mp mp_hands mp.solutions.hands mp_draw mp.solutions.drawing_utils cap cv2.VideoCapture(0) with mp_hands.Hands( static_image_modeFalse, max_num_hands1, min_detection_confidence0.5, min_tracking_confidence0.5) as hands: while cap.isOpened(): ret, frame cap.read() if not ret: break # 自拍镜像让画面和真实动作方向一致方便调试 frame cv2.flip(frame, 1) # mediapipe 的 process 接口吃 RGBOpenCV 读出来是 BGR rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) result hands.process(rgb) if result.multi_hand_landmarks: for hand_landmarks in result.multi_hand_landmarks: mp_draw.draw_landmarks( frame, hand_landmarks, mp_hands.HAND_CONNECTIONS) lm hand_landmarks.landmark # 打印手腕点坐标验证数据通路 print(lm[0].x, lm[0].y, lm[0].z) cv2.imshow(hand, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()这段代码的逻辑分三步OpenCV 读帧、mediapipe 提关键点、OpenCV 画出来。其中cv2.flip(frame, 1)是做水平镜像摄像头正对着自己时画面左右是反的镜像后手往右挥画面里也往右调试直觉好很多。cv2.cvtColor这一步很容易漏mediapipe 的训练数据是 RGB直接喂 BGR 帧虽然不会报错但坐标会不准。参数方面static_image_modeFalse表示使用视频流模式mediapipe 会在帧间做跟踪速度比逐帧检测快很多适合实时场景。min_detection_confidence控制检测器的最低置信度取值 0.5 是保守起点调低到 0.4 更容易检测到手但误检也变多调高到 0.7 更准确但手出画面再回来时会短暂丢失。min_tracking_confidence控制跟踪置信度低于阈值会触发重新检测一般保持默认 0.5 就好。2.3 为什么是 21 点不是图像关键点特征对数字识别意味着什么mediapipe 的手部关键点模型输出 21 个点编号固定含义固定。下面是数字识别最常用到的几个关键点编号位置在数字识别中的作用0手腕归一化基准点所有坐标以它为原点4食指尖判断 1、9、8 的关键8中指尖判断 2、3、4 的关键12无名指尖配合 8 判断三指、四指16小指尖判断 6 的关键20食指根部与 4 的距离反映食指弯曲程度数字识别不关心图像本身长什么样关心的是“哪几个指尖伸出来了”“手指弯了多少”。这些信息可以从关键点之间的相对距离和角度算出来。这就是为什么说关键点方案比轮廓检测省事轮廓方案要做背景分割、找轮廓、算凸包、定位指尖谷底每一步都可能因为光线或者背景翻车而 mediapipe 把这一整套封装成黑匣子你拿到的直接是稳定坐标。有一点需要提醒mediapipe 输出的 x、y 是相对图像宽高的 0 到 1 归一化坐标不是像素坐标。这意味着手在画面左上角和右下角原始坐标完全不同训练出来的模型会把“位置”也学进去。这个问题留到下一章数据预处理部分专门解决现在先记住原始坐标不能直接拿来训练。3. 自建手势数字数据集采集、标注与归一化的一站式脚本3.1 数字手势约定先把 0-9 的定义写清楚再采数据很多人做手势识别最隐蔽的坑是数据还没采手上动作已经不一致了。比如数字 0有人用握拳有人用 OK 手势数字 7有人用拇指食指中指捏合有人用食指中指无名指并拢。训练时采集和推理时动作不同模型精度直接崩掉。所以第一个步骤不是写代码是定一套明确的数字手势约定。我一般用下面这套数字手势定义说明0拇指与食指成环其余三指自然伸开比握拳更好识别和 5 区分度高1食指伸直其余手指握拳指尖朝上不要弯曲2食指和中指伸直成 V常见剪刀手3食指、中指、无名指伸直小指和拇指自然弯曲4食指、中指、无名指、小指伸直拇指内扣或外展均可5五指全部张开手指间适当分开6拇指和小指伸直其余弯曲常见打电话手势7拇指、食指、中指三指捏合指尖聚拢成一撮8拇指和食指张开成枪形其余三指弯曲9食指弯曲成钩状其余握拳或者用拇指食指成环但拇指在上注意这套约定不是标准答案关键是“训练和推理用同一套动作”。你自己定义一套完全没问题但要把约定表写进项目说明里不然过两周自己都忘了当时怎么比的。3.2 采集脚本按数字键采集并保存 CSV约定确定后写采集脚本。思路很简单摄像头实时跑 mediapipe检测到手就把 21 个点的 x、y 坐标共 42 个数值写进 CSV最后一列是标签。你按下键盘数字键 1 到 9、0程序就把当前帧的关键点存成对应类别的样本。import csv import cv2 import mediapipe as mp LABELS {0: 0, 1: 1, 2: 2, 3: 3, 4: 4, 5: 5, 6: 6, 7: 7, 8: 8, 9: 9} save_path gesture_data.csv f open(save_path, w, newline) writer csv.writer(f) mp_hands mp.solutions.hands cap cv2.VideoCapture(0) num_per_class 200 # 每类至少采 200 个样本 with mp_hands.Hands( static_image_modeTrue, max_num_hands1, min_detection_confidence0.6) as hands: collected {k: 0 for k in LABELS} while cap.isOpened(): ret, frame cap.read() if not ret: break frame cv2.flip(frame, 1) rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) result hands.process(rgb) if result.multi_hand_landmarks: lm result.multi_hand_landmarks[0].landmark pts [] for p in lm: pts.extend([p.x, p.y]) cv2.putText(frame, counts: str(collected), (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2) key cv2.waitKey(1) 0xFF label_char chr(key) if key 256 else if label_char in LABELS: label LABELS[label_char] writer.writerow(pts [label]) collected[label_char] 1 print(flabel {label}: {collected[label_char]}/{num_per_class}) else: key cv2.waitKey(1) 0xFF if key ord(q): break cv2.imshow(collect, frame) if all(v num_per_class for v in collected.values()): print(done) break cap.release() cv2.destroyAllWindows()这里几个参数值得说清楚。static_image_modeTrue表示每一帧都走完整检测不用跟踪模式采集阶段不需要速度反而需要每次检测稳定独立。min_detection_confidence0.6比上一章的 0.5 稍高宁可漏掉几帧也不要存进去一堆低置信度脏样本。num_per_class200是我建议的最少样本量低于 100 模型很容易过拟合高于 500 边际收益明显下降。采集时的动作习惯直接影响数据质量。手要放在画面中央偏下一点不要超出边缘每次按键采样时手不要快速移动静止一拍同一个数字换几种角度来几组比如手掌稍微内偏、外偏。这样模型泛化能力会好很多。3.3 位移与尺度归一化让模型不再依赖手在画面的位置CSV 里的原始坐标不能直接训练原因前文已经提到了坐标是相对图像宽高的 0 到 1 值手在画面不同位置、离摄像头远近不同都会让同一手势的坐标分布完全不同。这时就要做归一化是机器学习中的数据处理最典型的一步。import numpy as np def normalize_landmarks(lm): # 输入 lm: shape (21, 2)已经取出的 21 点 x,y 坐标 lm np.array(lm, dtypenp.float32) wrist lm[0] # 手腕点作为原点 diff lm - wrist # 所有点相对手腕的偏移 scale np.linalg.norm(lm[9] - wrist) # 中指根部到手腕的距离 return diff / scale这套归一化分两步。第一步把所有坐标减去手腕点坐标消除位置影响——手在画面左上角和右下角归一化后坐标相同。第二步除以中指根部到手腕的距离消除尺度影响——手离摄像头近时整体坐标偏大离得远时偏小除以这个距离后两种情况下指尖相对位置可比。选第 9 点中指根部做尺度基准是因为它到手腕的距离在大多数手势中变化不大而且不像指尖那样容易弯曲变形。训练和推理必须使用同一套归一化逻辑。我见过太多人训练时做了归一化推理时忘了结果模型精度从 95% 掉到 50% 还找不到原因。建议把归一化写成一个独立函数采集、训练、推理三个环节都调用同一个函数从源头杜绝这件事。4. 训练与实时推理随机森林与 MLP 的取舍跑通 0-9 识别4.1 模型选型为什么先选随机森林而不是深度学习到这一步你已经有了一个形状为 (N, 42) 的特征矩阵和对应的标签接下来要选机器学习模型。标准的机器学习应用流程是特征提取、数据预处理、模型训练、评估、推理。这个项目的特征维度只有 42 维类别只有 10 个样本量通常在几千的量级用深度学习属于杀鸡用牛刀。模型数据量要求训练速度实时推理调参难度随机森林几百样本即可快极快几乎不用调MLPClassifier千样本起步快极快需要调网络层数和迭代次数CNN/LSTM上万样本慢有压力高实际项目里我最常用随机森林起步因为它对特征维度和样本量的要求很低训练快、背书少、调参空间小出结果非常快。如果你想要稍微连续一点的分类边界用 scikit-learn 的 MLPClassifier 也完全可以两者在这个任务上的准确率差距一般不超过 2 个百分点。真正拉开精度差距的不是模型选择而是数据质量和归一化是否做对。4.2 训练脚本与参数从 CSV 到可保存的模型文件训练脚本把三件事串起来读取 CSV、归一化、交叉验证并保存模型。import csv import numpy as np from sklearn.ensemble import RandomForestClassifier from sklearn.model_selection import cross_val_score import joblib def load_csv(path): rows [] with open(path, r) as f: reader csv.reader(f) for r in reader: rows.append([float(v) for v in r]) data np.array(rows) X data[:, :42].reshape(-1, 21, 2) # 42 列还原成 21 个二维点 y data[:, 42].astype(int) # 最后一列是标签 wrist X[:, 0, :] X_rel X - wrist[:, None, :] # 平移归一化 scale np.linalg.norm(X_rel[:, 9, :], axis1) X_norm X_rel / scale[:, None, None] # 尺度归一化 return X_norm.reshape(-1, 42), y X, y load_csv(gesture_data.csv) print(样本分布:, np.bincount(y)) clf RandomForestClassifier( n_estimators300, min_samples_leaf1, random_state42, n_jobs-1) print(5折交叉验证准确率:, cross_val_score(clf, X, y, cv5).mean()) clf.fit(X, y) joblib.dump(clf, gesture_rf.pkl)几个参数的调法要说明。n_estimators300是随机森林里的树数量300 棵足够收敛加到 1000 准确率提升很有限但模型文件体积会变大许多。min_samples_leaf1是叶子节点最少样本数默认 1 在数据量大时会过拟合如果你发现训练准确率很高而交叉验证准确率掉很多把这个值调到 2 或 4 会有改善。n_jobs-1让所有 CPU 核并行训练小数据集上差距不明显但样本上万时能省下大量时间。交叉验证用的是简单 5 折但有个隐患采集数据时每类样本是连续按出来的时序上高度相关同一手势的连续帧可能同时落在训练集和验证集里导致交叉验证分数虚高。想更可靠一点可以在采集脚本里做成每类轮换采样或者用StratifiedKFold(shuffleTrue)先把数据打乱再划分。4.3 实时推理 demo把模型接回摄像头输出数字训练完会得到一个gesture_rf.pkl文件推理代码就是把采集脚本中的“保存坐标”替换成“预测并显示”。import cv2 import mediapipe as mp import joblib import numpy as np clf joblib.load(gesture_rf.pkl) mp_hands mp.solutions.hands mp_draw mp.solutions.drawing_utils cap cv2.VideoCapture(0) with mp_hands.Hands( static_image_modeFalse, max_num_hands1, min_detection_confidence0.5, min_tracking_confidence0.5) as hands: while True: ret, frame cap.read() if not ret: break frame cv2.flip(frame, 1) rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) result hands.process(rgb) if result.multi_hand_landmarks: lm result.multi_hand_landmarks[0].landmark pts np.array([[p.x, p.y] for p in lm]) pts pts - pts[0] # 平移 pts pts / np.linalg.norm(pts[9]) # 尺度 pred clf.predict(pts.reshape(1, -1))[0] cv2.putText(frame, fnum: {pred}, (20, 60), cv2.FONT_HERSHEY_SIMPLEX, 2, (0, 255, 0), 3) mp_draw.draw_landmarks( frame, result.multi_hand_landmarks[0], mp_hands.HAND_CONNECTIONS) cv2.imshow(recognition, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()推理部分的归一化和训练脚本保持完全一致减去手腕点、除以第 9 点到手腕的距离。这里再次强调训练和推理不一致是这类项目里最隐蔽的翻车点。如果你发现模型在自己摄像头下准确率奇低优先检查推理代码里的归一化步骤是不是和训练时一模一样。5. 避坑清单手势数字识别项目中最常见的五个翻车现场5.1 数字 0 和 5、6 和 7 总混淆约定不一致比模型不行更常见现象自己测试其他数字都对只有 0 经常识别成 56 和 7 互相串。原因如果约定里 0 是握拳那么握拳姿态下指尖弯曲mediapipe 检测到的关键点实际落在手掌表面和五指张开的 5 相比只有手指间距的差别特征边界很薄。解决方法是把 0 的约定改成拇指和食指成环的 OK 手势环形的关键点分布和 5 的张开状态差异非常大识别稳定性立刻上一个台阶。6 和 7 混淆通常是因为动作幅度太小拇指小指伸出不够明确采集时把动作做夸张比如 6 的小指和拇指尽力向外张开不要含在掌心里。5.2 实时推理卡顿、掉帧瓶颈在摄像头读取和绘制现象摄像头画面明显发卡识别延迟接近半秒。原因很多人以为是模型太慢其实是 mediapipe 检测、OpenCV 读取和画面绘制全挤在同一帧的主线程里cv2.waitKey(1)又限制了帧循环速度。解决思路是降分辨率加隔帧处理把摄像头分辨率调到 640×480每两帧取一帧做识别中间帧直接画上一次的检测结果。另一个有效手段是把static_image_mode保持在 False让 mediapipe 在帧间走跟踪而不是重新检测能省掉大量计算量。模型本身在 CPU 上单次推理不到 1 毫秒根本不构成瓶颈。5.3 换个人、换个背景就不准采集数据太“干净”了现象自己一个人测准确率 95% 以上换同事测直接掉到 60%。原因采集是在固定光线、固定背景、固定手型下完成的模型学到的不仅是手型还包括了肤色、光照、手大小的分布。解决的办法是采集阶段就引入多样性至少找三个人各采一部分分别在白天和晚上采两轮每个人的手型都不一样模型被迫去学真正区分数字的特征。还有一个常见增强手段是手部翻转但注意不能直接对关键点做水平翻转——左右手交换后关键点的对应关系也变了不加映射的翻转只会让模型学到错误信息。5.4 mediapipe 首次运行要下载模型离线环境直接报错现象第一次运行时一切正常第二次在没网环境运行程序卡在hands.process然后报错退出。原因mediapipe 的 Hands 接口在第一次实例化时会从官方仓库下载手部关键点模型文件下载成功后缓存到本地目录。离线环境下模型文件不存在就会直接失败。解决方法是联网状态下先跑通一次程序把模型缓存到本地部署到离线机器时把这部分缓存文件一起带上。另外mediapipe 2.x 换了新的 tasks API初始化写法完全不一样如果你拿到的压缩包里的代码是旧版写法而安装的 mediapipe 是新版运行会直接报错找不到solutions.hands这时候去查对应版本的官方样例照着改初始化部分即可。5.5 多只手同时出现或手出画面边缘关键点能拿到但输出乱跳现象一只手正常识别另一只手从画面边缘伸进来时识别结果在两个数字之间疯狂横跳。原因max_num_hands1参数只是限制了最多检测一只手的模型输出上限但多只手同时出现时 mediapipe 会返回置信度最高的那只置信度可能在两只手之间反复横跳导致每帧取到的关键点来源不一致。解决方法是固定只用画面中心区域的手检测到多只手时选离画面中心最近的那只进行识别另一只直接忽略。手出画面边缘时关键点会被截断坐标不可信这种情况直接丢弃这一帧宁可不识别也不要输出错误结果。6. 进阶多帧投票与关键点平滑把实时识别精度再稳定一档单帧识别做到 90% 很容易要做到 98% 以上就得在时序上下功夫。先看两个小技巧。from collections import deque, Counter import numpy as np class EMAFilter: 指数移动平均平滑关键点坐标抑制逐帧抖动 def __init__(self, alpha0.7): self.alpha alpha self.old None def __call__(self, pts): if self.old is None: self.old pts else: self.old self.alpha * pts (1 - self.alpha) * self.old return self.old class VoteFilter: 近 N 帧多数投票输出稳定类别 def __init__(self, window5): self.buf deque(maxlenwindow) def __call__(self, cls): self.buf.append(cls) return Counter(self.buf).most_common(1)[0][0]EMA 平滑的作用对象是关键点坐标。把上一帧的关键点坐标和当前帧按比例混合alpha0.7表示当前帧占 70%历史占 30%。alpha 太大会让手部动作显得迟钝太小起不到平滑效果0.6 到 0.9 之间是安全区。平滑后的坐标再进分类器预测结果就不容易因为一两帧的关键点抖动而跳变。投票过滤器作用于类别输出连续 5 帧中出现次数最多的数字作为最终结果窗口越大越稳定但延迟越高实时场景建议用 3 到 5 帧。验证方法上我不建议对着摄像头反复挥手自己觉得准但量化不了。更好的做法是录一段 30 秒的视频每帧标注真实数字然后离线跑推理脚本计算逐帧准确率和混淆矩阵这样才能定位到底是哪两个数字在互相打架。做完这两步平滑再动手去优化数据分布效果通常比换模型更明显。我做这个项目最大的教训是花了大量时间调模型参数结果发现是采集时 0 的约定前后不一致脏数据占到三成任何调参都救不回来。希望你上手时先把数字手势约定写死在项目说明里再开始采集能省掉后面一整轮的返工。希望帮到你。本文还有配套的精品资源点击获取