简介面向计算机视觉入门与课程设计实践的CNN手势识别小项目围绕OpenCV图像处理与卷积神经网络分类展开解决用手势实时操控飞机大战小游戏的问题。压缩包共14个文件以9个png图像素材/运行截图、4个Python脚本和1份README说明为主整体约8.68MB结构紧凑便于快速浏览项目素材与代码组织。已有196人学习适合Python基础尚可、希望把CNN从理论落到交互式小游戏中的学习者参考。代码覆盖摄像头/图像采集、背景去除、轮廓提取与手势分类等环节并把识别结果映射为游戏控制指令README可用于了解运行环境与模块关系png文件则辅助对照预处理效果和识别流程。读者可借此理解OpenCV读图、灰度处理、轮廓分析到CNN推理的完整链路也能改造成手势控制或课程演示项目。1. 摄像头当摇杆一个用 CNN 手势识别控飞机大战小游戏的 Python 项目上周有个读者发来一段录屏人坐在电脑前手在摄像头前左右一晃屏幕里的飞机就跟着平移握一下拳头子弹连发。他问的不是「这炫不炫」而是「这套 Python CNN OpenCV 的手势识别控飞机大战小游戏我拿下来能不能在自己机器上跑通能不能改成别的玩法」。这个问题问得很实在——市面上讲卷积神经网络做手势识别的资料一抓一大把但真正把一个能玩的小游戏从摄像头采集、模型训练、推理循环到游戏对接完整串起来的工程不多。这个项目就属于后者。它的定位很明确用一个轻量级 CNN 把摄像头画面里的手部姿态分成几类再把分类结果翻译成飞机大战的操作指令。适合两类人一是刚学完 PyTorch 基础、想找一个能看见反馈的落地项目练手的二是想把计算机视觉模块塞进已有 2D 游戏、做一个体感 Demo 的。整条链路不长但每一环都有坑尤其是训练和推理的预处理对齐问题翻车的概率比想象中高。2. 整体链路拆解从一帧摄像头画面到一次飞机位移的四层结构2.1 四层职责划分采集、识别、映射、渲染我把这套东西拆成四层来看比直接翻代码清楚得多。采集层负责跟摄像头打交道用 OpenCV 的VideoCapture拿 BGR 帧做水平镜像、感兴趣区域ROI裁剪、尺寸归一化。识别层是 CNN 的地盘输入一张 64×64 的单通道图输出各手势类别的概率。映射层是最容易被忽略但决定手感的一层它把「这一帧识别成什么」翻译成「游戏里该执行什么动作」还要处理识别抖动、连续帧一致性、以及手势消失后的释放逻辑。渲染层就是 Pygame 的飞机大战本体负责精灵移动、子弹生成、碰撞检测、帧率维持。这四层如果全塞在一个while True里跑起来会很难受。摄像头读帧是阻塞的CNN 推理在 CPU 上大概 10~30msPygame 的clock.tick(60)要求你每帧不能超过 16ms。三者节奏完全不一致串行执行最直接的后果就是游戏卡成幻灯片。所以工程上的标准做法是把采集和推理放进一个独立线程主线程只负责游戏循环两边通过一个线程安全的共享变量交换「当前手势」。这里有个取舍用全局变量加锁也行但我一般更习惯用一个单元素的queue.Queue(maxsize1)。原因很简单——识别线程比游戏线程慢的时候队列会堆积旧帧导致画面里的手势和你手上的动作对不上延迟越来越大。maxsize1配合put_nowait失败就丢弃天然做到了「只保留最新结果」这个设计在后面第 5 章还会再提一次。数据流大致是这样摄像头 BGR 帧 → 镜像翻转 ROI 裁剪 → 灰度化 高斯模糊 尺寸缩放 64×64 → CNN 前向推理 → 类别索引 置信度 → 时序平滑连续 N 帧一致才生效 → 当前动作枚举LEFT / RIGHT / FIRE / IDLE → Pygame 事件或直接改玩家坐标2.2 目录结构与依赖清单一个能跑起来的最小工程目录我建议按下面组织。别小看这个结构第一次写的时候我把采集脚本、训练脚本、推理脚本全堆在根目录后来想换模型文件路径改了七八处 import血泪经验。gesture_plane/ ├── config.py # 路径、类别名、超参集中管理 ├── collect_data.py # 按类别采集样本 ├── train_cnn.py # 训练与验证 ├── infer_thread.py # 摄像头 推理线程 ├── game/ │ ├── main.py # 游戏主循环 │ └── assets/ # 飞机、子弹、背景图 ├── models/ │ └── gesture_cnn.pth # 训练产出的权重 └── data/ ├── fist/ ├── palm/ └── point/依赖不多但要装对版本。CPU 上跑就够不必强上 CUDApip install torch torchvision --index-url https://download.pytorch.org/whl/cpu pip install opencv-python pygame numpyopencv-python用默认的个人版即可别装opencv-contrib-python和它共存两个包会互相覆盖cv2目录表现是同一个 import 有时能用有时报AttributeError这属于比较经典的玄学问题。config.py里我会把所有会变的东西集中放包括类别映射、图片尺寸、模型路径、平滑窗口大小。这个文件后面改造的时候你会回来改很多次集中管理能省掉大量搜索替换。# config.py import os BASE_DIR os.path.dirname(os.path.abspath(__file__)) IMG_SIZE 64 # 必须训练和推理保持同一个值 NUM_CLASSES 3 # fist / palm / point CLASS_NAMES [fist, palm, point] MODEL_PATH os.path.join(BASE_DIR, models, gesture_cnn.pth) DATA_DIR os.path.join(BASE_DIR, data) # 游戏侧 CAM_INDEX 0 # 多摄像头时改这里 ROI_SCALE 0.5 # 只取画面中心 50% 区域减少背景干扰 SMOOTH_WINDOW 5 # 连续 N 帧一致才认为手势有效 CONF_THRESHOLD 0.75 # 置信度低于此值视为无手势参数说明IMG_SIZE是整条链路的一致性锚点训练用 64、推理用 128 是最常见的翻车点ROI_SCALE解决的是背景误识别手只占画面一小块时全图输入会让模型学到键盘、椅背这些无关纹理CONF_THRESHOLD是防误触的最后一道闸低于阈值就直接输出 IDLE宁可不动也不乱动。2.3 主循环为什么必须拆线程不拆线程的版本我也写过能跑但只能算「演示」。问题出在摄像头读帧上cap.read()在没有新帧的时候会等待这一等就是几毫秒到几十毫秒期间 Pygame 的帧循环被堵死飞机的移动会一顿一顿。改成双线程后识别线程全速跑游戏线程固定 60 FPS。两者共享状态的入口收敛在一个函数里读写都走队列避开了锁的复杂度。# infer_thread.py节选 import threading import queue import cv2 import torch import numpy as np from config import IMG_SIZE, CAM_INDEX, ROI_SCALE, MODEL_PATH, CONF_THRESHOLD result_queue queue.Queue(maxsize1) # 只保留最新一次识别结果 stop_flag threading.Event() def _crop_roi(frame): h, w frame.shape[:2] rw, rh int(w * ROI_SCALE), int(h * ROI_SCALE) x1, y1 (w - rw) // 2, (h - rh) // 2 return frame[y1:y1 rh, x1:x1 rw] def preprocess(frame): frame cv2.flip(frame, 1) # 水平镜像符合用户直觉 roi _crop_roi(frame) gray cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY) gray cv2.GaussianBlur(gray, (5, 5), 0) # 抑制噪点和训练时一致 return cv2.resize(gray, (IMG_SIZE, IMG_SIZE)) def inference_worker(model): cap cv2.VideoCapture(CAM_INDEX) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) while not stop_flag.is_set(): ok, frame cap.read() if not ok: continue img preprocess(frame) tensor torch.from_numpy(img).float().unsqueeze(0).unsqueeze(0) / 255.0 with torch.no_grad(): logits model(tensor) prob torch.softmax(logits, dim1).squeeze() conf, idx torch.max(prob, dim0) payload (int(idx), float(conf)) if conf CONF_THRESHOLD else (-1, float(conf)) try: result_queue.put_nowait(payload) # 满了就丢旧值保证低延迟 except queue.Full: pass cap.release()关键点有三个。torch.no_grad()必须加否则每帧都会构建计算图内存会一直缓慢上涨跑二十分钟后进程被系统杀掉现象像是「游戏自己退了」。unsqueeze(0).unsqueeze(0)是在补 batch 维和 channel 维模型的输入形状是[N, 1, 64, 64]漏一个就会报维度不匹配。put_nowait配queue.Full吞异常是为了让识别线程永远不被阻塞这条比「结果不丢」重要得多。3. 手势数据集与 CNN 训练把「握拳、张掌、竖指」喂给模型3.1 样本采集脚本ROI 裁剪与尺寸归一化模型效果好不好八成取决于数据不取决于网络多深。这个项目只有三类手势理论上每类 300~500 张就够跑出一个能玩的效果。采集脚本要跟推理脚本用同一套预处理函数这句话我要重复一遍同一套。我见过太多人采集时直接存原始帧推理时才做灰度化和缩放训练分布和推理分布直接错开模型在验证集上 98%实际玩起来全是乱跳。# collect_data.py import cv2, os, argparse from config import DATA_DIR, CLASS_NAMES from infer_thread import preprocess # 复用同一份预处理别复制粘贴 def collect(class_name, max_count400): save_dir os.path.join(DATA_DIR, class_name) os.makedirs(save_dir, exist_okTrue) cap cv2.VideoCapture(0) count len(os.listdir(save_dir)) while count max_count: ok, frame cap.read() if not ok: break img preprocess(frame) # 与推理完全一致的 64×64 灰度图 cv2.imshow(preview, img) key cv2.waitKey(1) 0xFF if key ord(s): # 按 s 存一张 cv2.imwrite(os.path.join(save_dir, f{count:04d}.png), img) count 1 elif key ord(q): break cap.release() cv2.destroyAllWindows() if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--cls, choicesCLASS_NAMES, requiredTrue) args parser.parse_args() collect(args.cls)按s手动逐张存看起来笨但比自动连拍好。自动连拍的后果是相邻帧几乎一模一样训练集里充斥着重复样本模型对角度和距离的泛化能力会很差。手动存的时候要有意识地变换手的远近、左右偏、手指张开程度、光照方向、背景。同一个姿势正面对着拍 400 张模型只学会「正面手掌」稍微侧一点就崩。采集时的实操建议每类至少覆盖 5 种手部朝向 × 3 种距离光线别只在一个位置采白天和晚上各采一轮。数据量少的时候数据增强比加网络层数有用得多。3.2 网络结构与训练循环网络不需要深。输入 64×64 单通道三层卷积加两层全连接足够了参数总量控制在 20 万以内CPU 推理单帧 5ms 左右完全跟得上 60 FPS。# train_cnn.py import torch import torch.nn as nn import torch.optim as optim from torch.utils.data import DataLoader from torchvision import datasets, transforms from config import IMG_SIZE, NUM_CLASSES, DATA_DIR, MODEL_PATH class GestureCNN(nn.Module): def __init__(self, num_classesNUM_CLASSES): super().__init__() self.features nn.Sequential( nn.Conv2d(1, 16, 3, padding1), nn.BatchNorm2d(16), nn.ReLU(), nn.MaxPool2d(2), # 64 - 32 nn.Conv2d(16, 32, 3, padding1), nn.BatchNorm2d(32), nn.ReLU(), nn.MaxPool2d(2), # 32 - 16 nn.Conv2d(32, 64, 3, padding1), nn.BatchNorm2d(64), nn.ReLU(), nn.AdaptiveAvgPool2d(1), # 全局池化抗输入尺寸波动 ) self.classifier nn.Sequential( nn.Flatten(), nn.Dropout(0.3), nn.Linear(64, num_classes), ) def forward(self, x): return self.classifier(self.features(x)) def build_loaders(batch_size32): # 训练增强小幅旋转、平移、亮度扰动模拟真实手持变化 train_tf transforms.Compose([ transforms.Grayscale(num_output_channels1), transforms.Resize((IMG_SIZE, IMG_SIZE)), transforms.RandomAffine(degrees10, translate(0.1, 0.1), scale(0.9, 1.1)), transforms.ColorJitter(brightness0.3), transforms.ToTensor(), ]) val_tf transforms.Compose([ transforms.Grayscale(num_output_channels1), transforms.Resize((IMG_SIZE, IMG_SIZE)), transforms.ToTensor(), ]) train_ds datasets.ImageFolder(DATA_DIR, transformtrain_tf) val_ds datasets.ImageFolder(DATA_DIR, transformval_tf) # 简易切分八成训练两成验证 n_train int(len(train_ds) * 0.8) n_val len(train_ds) - n_train train_set, _ torch.utils.data.random_split(train_ds, [n_train, n_val]) _, val_set torch.utils.data.random_split(val_ds, [n_train, n_val]) return (DataLoader(train_set, batch_sizebatch_size, shuffleTrue, num_workers0), DataLoader(val_set, batch_sizebatch_size, num_workers0), train_ds.classes)这里有几个不显眼但影响很大的选择。AdaptiveAvgPool2d(1)替代了展平后接大全连接层参数从几十万降到几百顺带解决了「改输入尺寸就要改 Linear 输入维度」的麻烦。BatchNorm2d在小数据集上能让收敛快一截但推理时一定要model.eval()否则它继续用 batch 统计量单张图推理结果会飘这是个特别隐蔽的坑。num_workers0是 Windows 下的保守选择多进程数据加载在 Windows 上配合 Pygame 容易出问题样本量小的时候单进程完全够。训练循环本身没什么花样def train(epochs30, lr1e-3): device torch.device(cuda if torch.cuda.is_available() else cpu) train_loader, val_loader, classes build_loaders() model GestureCNN(len(classes)).to(device) criterion nn.CrossEntropyLoss() optimizer optim.Adam(model.parameters(), lrlr, weight_decay1e-4) scheduler optim.lr_scheduler.CosineAnnealingLR(optimizer, T_maxepochs) best_acc 0.0 for epoch in range(epochs): model.train() for imgs, labels in train_loader: imgs, labels imgs.to(device), labels.to(device) optimizer.zero_grad() loss criterion(model(imgs), labels) loss.backward() optimizer.step() scheduler.step() model.eval() # 切验证模式冻结 BN 统计量 correct total 0 with torch.no_grad(): for imgs, labels in val_loader: imgs, labels imgs.to(device), labels.to(device) pred model(imgs).argmax(dim1) correct (pred labels).sum().item() total labels.size(0) acc correct / max(total, 1) print(fepoch {epoch1:02d} acc{acc:.4f}) if acc best_acc: best_acc acc torch.save({state_dict: model.state_dict(), classes: classes}, MODEL_PATH) print(fbest{best_acc:.4f} - {MODEL_PATH})scheduler用余弦退火30 个 epoch 内学习率平滑降到接近 0比固定 lr 最后几轮震荡小。保存时把classes一起存进去很重要——ImageFolder是按目录名的字母序生成类别索引的fist / palm / point排出来是 0/1/2但你要是后来加了个ok类索引全乱推理端不读 classes 就会把「握拳」认成「OK」飞出个莫名其妙的结果。3.3 训练结果的判读与模型导出跑完 30 轮验证准确率一般在 0.95 以上就该停手了。如果一直卡在 0.6 左右先别怀疑网络去看数据很可能是某一类样本数量明显少于其他类或者采集时光照全在同一个方向。ImageFolder不做类别均衡少的那类会被压制。另一个信号是训练准确率高但验证低典型的过拟合。这个项目数据量小Dropout 0.3 加上数据增强基本能压住如果还不行把卷积通道数从 16/32/64 降到 8/16/32模型小了反而不容易记住训练集。导出的.pth里存了state_dict和classes两个键推理端加载时要先建同结构的模型再load_state_dict别用torch.load直接当模型对象使新版 PyTorch 默认weights_onlyTrue直接当模型用会报类型错误。4. 推理与游戏对接OpenCV 预处理 手势到按键的胶水层4.1 推理侧预处理必须和训练侧对齐第 3 章说过一遍这里再说一遍具体到代码层面要盯哪些点。训练时transforms.ToTensor()做的是HWC → CHW加除以 255推理时就得手动补上这两步。训练时用了Grayscale推理时就必须cvtColor(BGR2GRAY)而且顺序不能乱先灰度再 resize 和先 resize 再灰度插值方式不同边缘像素值会有细微差异模型对这东西比你想的敏感。# 推理端张量构造与训练 transform 严格对应 tensor torch.from_numpy(img) # img: uint8, shape (64, 64) tensor tensor.float().unsqueeze(0).unsqueeze(0) / 255.0 # 等价于 ToTensor 的 HWC-CHW /255只是这里 HWC 退化成 HW还有一个常被忽略的点model.eval()。加载权重后忘了切 eval 模式BatchNorm 用单张图的统计量做归一化同一只手在不同帧里输出能差出 30 个百分点现象是「手势没变但识别结果乱跳」很多人会误以为是摄像头问题去换驱动、换 USB 口白折腾半天。4.2 手势到动作的映射与去抖动分类模型逐帧输出天然会抖。人手的姿态在两类边界上比如手指半弯会来回横跳如果直接把每帧结果映射成游戏动作飞机会疯狂左右抽搐。处理办法是加一个滑窗投票。维护最近 N 帧的类别队列取众数且要求众数占比超过阈值才切换动作。N 取 5 在 30 FPS 的识别速度下大约 160ms 延迟手感上基本察觉不到但抖动没了。from collections import deque, Counter from config import SMOOTH_WINDOW class GestureSmoother: def __init__(self, windowSMOOTH_WINDOW, ratio0.6): self.buf deque(maxlenwindow) self.ratio ratio self.current -1 def update(self, idx): self.buf.append(idx) if len(self.buf) self.buf.maxlen: return self.current label, cnt Counter(self.buf).most_common(1)[0] # 无手势(-1)占多数时直接释放避免手离开画面后飞机一直动 if cnt / len(self.buf) self.ratio: self.current label return self.currentratio0.6是个经验值调高反应变迟钝调低还是抖。-1参与投票这一点很关键否则手离开画面后缓冲区里残留的最后一个有效手势会一直生效飞机撞墙停不下来这个 bug 我第一次跑的时候盯了十分钟才反应过来。动作映射我倾向于双通道CNN 分类结果负责「动作」开火 / 暂停 / 无手的水平位置负责「方向」。纯分类做方向控制只有「左 / 中 / 右」三档飞机跳着走很难看。# 用轮廓质心算手的水平位置映射到屏幕坐标 def hand_x_ratio(frame): roi _crop_roi(cv2.flip(frame, 1)) gray cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY) _, th cv2.threshold(gray, 60, 255, cv2.THRESH_BINARY_INV) contours, _ cv2.findContours(th, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE) if not contours: return None c max(contours, keycv2.contourArea) if cv2.contourArea(c) 3000: # 太小的是噪声忽略 return None x, y, w, h cv2.boundingRect(c) return (x w / 2) / roi.shape[1] # 0~1 之间阈值 60 是反相二值化适合浅色背景如果你的环境偏暗改成自适应阈值cv2.adaptiveThreshold会稳一些。contourArea 3000的过滤很有必要不然一个晃动的鼠标影子都能被当成手。4.3 Pygame 主循环里的注入方式游戏侧改动很小。主循环每帧从队列取一次最新结果更新平滑器然后套用到玩家精灵上。这里要注意手势线程的输出频率和游戏帧率不一致可能出现一帧内队列为空的情况取不到就沿用上一帧的状态别重置。# game/main.py核心循环节选 import pygame, queue, threading, torch from infer_thread import result_queue, inference_worker, stop_flag, hand_x_ratio from train_cnn import GestureCNN from config import MODEL_PATH ckpt torch.load(MODEL_PATH, map_locationcpu, weights_onlyFalse) model GestureCNN(len(ckpt[classes])) model.load_state_dict(ckpt[state_dict]) model.eval() # 千万别漏 threading.Thread(targetinference_worker, args(model,), daemonTrue).start() pygame.init() screen pygame.display.set_mode((800, 600)) clock pygame.time.Clock() player_x 400.0 fire_cd 0 running True while running: for e in pygame.event.get(): if e.type pygame.QUIT: running False try: idx, conf result_queue.get_nowait() except queue.Empty: idx None # 本帧无新结果沿用旧动作 if idx is not None: action smoother.update(idx) if action 1: # palm开火 fire_cd max(0, fire_cd - 1) if fire_cd 0: spawn_bullet(player_x) fire_cd 8 # 冷却帧数控制射速 # 方向走连续量比三档分类顺滑 ratio hand_x_ratio(current_frame) if current_frame is not None else None if ratio is not None: player_x (ratio * 800 - player_x) * 0.25 # 一阶平滑跟随 draw(player_x) pygame.display.flip() clock.tick(60) stop_flag.set()几个参数值得说。fire_cd 8是射速冷却按 60 FPS 算大约每秒 7 发太快会满屏子弹如果识别线程只有 30 FPS队列取空的频率不低冷却时间可以用「毫秒时间戳」而不是帧数避免不同机器上手感差异过大。0.25是跟随系数越大越紧跟手越小越顺滑但延迟感强实际调到 0.2~0.35 之间比较舒服。还有一个隐藏问题hand_x_ratio每帧都跑一次findContours和 CNN 推理是重复做预处理。真要优化可以在识别线程里把 ROI 灰度图一起放进队列主线程直接用省掉一次完整的轮廓计算。这个改动留到第 6 章讲性能的时候再展开。5. 避坑与排查五条让项目跑不起来的常见故障5.1 摄像头能打开但读不到帧现象cap.isOpened()返回 True但cap.read()一直返回False画面黑的。原因多半是摄像头被别的进程占着。笔记本上常见的是会议软件在后台挂着或者上一次运行的 Python 进程没退干净句柄没释放。opencv-python在某些 Windows 版本上不会主动释放设备。解决办法先把infer_thread.py里的cap.release()放到try/finally里保证异常退出也能释放再用系统任务管理器把残留的 python 进程杀掉。代码里还可以加一个读帧失败计数器连续失败 30 次就重开VideoCapture比死循环卡在那里强。5.2 模型验证准确率很高实际玩起来全是误识别现象训练日志里 accuracy 0.98摄像头前比划半天飞机乱飞。原因训练数据和推理数据的预处理不一致。最常见的三种错位是——采集时存了原图 RGB推理时喂了灰度训练用了Resize((64,64))默认双线性插值推理用了cv2.resize默认也是双线性但缩放比例不同训练时没做镜像推理时做了flip。解决办法把预处理抽成一个函数采集脚本、训练 transform、推理脚本三处都调它或者至少抄同一份参数。debug 的时候可以把推理端的预处理结果cv2.imwrite出来和data/里的训练图肉眼对比一下差别一眼就能看出来。5.3 游戏跑几分钟后越来越卡最后进程消失现象刚启动 60 FPS五分钟后掉到 15 FPS再后来窗口直接没了。原因推理函数里漏了torch.no_grad()。每帧都在构建计算图GPU / CPU 内存持续增长操作系统的 OOM killer 直接把进程干掉日志里什么都没有黑匣子一样。解决办法推理全程包在with torch.no_grad():里另外把队列的put_nowait配上maxsize1防止识别结果堆积。这两条一起做内存曲线就平了。排查这类问题可以挂个psutil定时打印process.memory_info().rss涨不涨一看便知。5.4 手势切换时有明显延迟飞机反应慢半拍现象手已经挥过去了飞机还停在原地一两秒后才动。原因SMOOTH_WINDOW调太大或者识别线程里读帧和推理串行导致实际帧率极低。后者更隐蔽——cap.read()在有些摄像头上单次阻塞能到 100ms再加上 30ms 推理实际只有 7 FPS滑窗 5 帧就是 700ms 延迟。解决办法先把滑窗降到 3 观察如果还是慢就在识别线程里加帧率统计打印每秒处理帧数。低于 15 的话把 ROI 再缩小、IMG_SIZE降到 48、模型通道砍半三招下去 CPU 上轻松上到 25 FPS 以上。5.5 换了新环境重新训练类别全乱了现象加了第四类手势重新训练之前能识别的三类全认错。原因ImageFolder按目录名字母序编号新增一个ok目录后fist从 0 变成 1所有索引后移。推理端如果硬编码idx 0是开火逻辑就全错了。解决办法训练保存时把classes列表一起存进 checkpoint推理端从 checkpoint 里读永远不硬编码数字。映射表用字典写# 从 checkpoint 恢复类别名不硬编码索引 ckpt torch.load(MODEL_PATH, map_locationcpu, weights_onlyFalse) classes ckpt[classes] # [fist, ok, palm, point] ACTION {fist: fire, palm: idle, point: pause, ok: special} action ACTION.get(classes[idx], idle)这样加类、删类都不用改游戏逻辑改一个字典就够。从那以后我每次动数据集第一件事就是确认 checkpoint 里存了classes。6. 二次开发换手势、换模型、提帧率的三条改造路线拿到能跑的版本之后改动方向其实就三条按投入产出排一下。改造方向改动位置工作量效果新增/替换手势类别config.py 采集脚本 ACTION字典半天直接扩大玩法换更轻的模型train_cnn.py的GestureCNN半天帧率提升 30%~60%换推理后端infer_thread.py的前向部分一天上 ONNX Runtime 或量化接入其他游戏game/main.py的事件注入一天复用整套识别链路先说服手感的优化。hand_x_ratio每帧重算一遍预处理其实识别线程已经做过一次 ROI 裁剪和灰度化了。改法是在inference_worker里把裁剪后的 ROI 灰度图随结果一起塞进队列payload (idx, conf, roi_gray)主线程直接拿这张图算轮廓质心。省掉一次cvtColor加一次findContours40ms 左右的预算就回来了代码量不超过十行。再说模型替换。如果你不想装 PyTorch 那套依赖可以把训练好的权重导成 ONNX游戏端只依赖onnxruntime包体从 2GB 降到 100MB 出头适合做成一个能双击运行的小工具。导出脚本大概长这样import torch from train_cnn import GestureCNN ckpt torch.load(models/gesture_cnn.pth, map_locationcpu, weights_onlyFalse) model GestureCNN(len(ckpt[classes])) model.load_state_dict(ckpt[state_dict]) model.eval() dummy torch.randn(1, 1, 64, 64) torch.onnx.export(model, dummy, models/gesture_cnn.onnx, input_names[input], output_names[logits], dynamic_axes{input: {0: batch}})导完一定要做一致性验证同一张图分别用 PyTorch 和 ONNX 推理输出概率的最大绝对差应该小于 1e-4。差值大说明某层算子导得不对最常见的是AdaptiveAvgPool2d在某些 opset 版本上行为不一致那时候要么升 opset要么把它换成nn.AvgPool2d(8)固定尺寸池化。第三条是接入别的游戏。这套识别链路和飞机大战的耦合度其实很低耦合点只有「ACTION字典」和「玩家坐标更新」两处。要接俄罗斯方块把ACTION改成「左移 / 右移 / 旋转 / 快落」四个手势主循环里换成pygame.event.post合成按键事件识别部分一行不动。常见做法是封装一个GestureReader类对外只暴露get_action() - str游戏侧完全不知道底层是 CNN 还是别的。最后留一个我自己的习惯。这个项目我每次改完预处理、改完网络结构、或者换摄像头之后都会强制走一遍三步验证先存 20 张实时图到临时目录肉眼比对它们和训练集的样子再单独跑一次单图推理打印各类别概率最后才启动游戏跑两分钟。跳过前两步直接开游戏等于把排查成本全压在肉眼观察上翻车了也找不到是哪一环的问题。希望帮到你少走点这种弯路。本文还有配套的精品资源点击获取
简介面向计算机视觉入门与课程设计实践的CNN手势识别小项目围绕OpenCV图像处理与卷积神经网络分类展开解决用手势实时操控飞机大战小游戏的问题。压缩包共14个文件以9个png图像素材/运行截图、4个Python脚本和1份README说明为主整体约8.68MB结构紧凑便于快速浏览项目素材与代码组织。已有196人学习适合Python基础尚可、希望把CNN从理论落到交互式小游戏中的学习者参考。代码覆盖摄像头/图像采集、背景去除、轮廓提取与手势分类等环节并把识别结果映射为游戏控制指令README可用于了解运行环境与模块关系png文件则辅助对照预处理效果和识别流程。读者可借此理解OpenCV读图、灰度处理、轮廓分析到CNN推理的完整链路也能改造成手势控制或课程演示项目。1. 摄像头当摇杆一个用 CNN 手势识别控飞机大战小游戏的 Python 项目上周有个读者发来一段录屏人坐在电脑前手在摄像头前左右一晃屏幕里的飞机就跟着平移握一下拳头子弹连发。他问的不是「这炫不炫」而是「这套 Python CNN OpenCV 的手势识别控飞机大战小游戏我拿下来能不能在自己机器上跑通能不能改成别的玩法」。这个问题问得很实在——市面上讲卷积神经网络做手势识别的资料一抓一大把但真正把一个能玩的小游戏从摄像头采集、模型训练、推理循环到游戏对接完整串起来的工程不多。这个项目就属于后者。它的定位很明确用一个轻量级 CNN 把摄像头画面里的手部姿态分成几类再把分类结果翻译成飞机大战的操作指令。适合两类人一是刚学完 PyTorch 基础、想找一个能看见反馈的落地项目练手的二是想把计算机视觉模块塞进已有 2D 游戏、做一个体感 Demo 的。整条链路不长但每一环都有坑尤其是训练和推理的预处理对齐问题翻车的概率比想象中高。2. 整体链路拆解从一帧摄像头画面到一次飞机位移的四层结构2.1 四层职责划分采集、识别、映射、渲染我把这套东西拆成四层来看比直接翻代码清楚得多。采集层负责跟摄像头打交道用 OpenCV 的VideoCapture拿 BGR 帧做水平镜像、感兴趣区域ROI裁剪、尺寸归一化。识别层是 CNN 的地盘输入一张 64×64 的单通道图输出各手势类别的概率。映射层是最容易被忽略但决定手感的一层它把「这一帧识别成什么」翻译成「游戏里该执行什么动作」还要处理识别抖动、连续帧一致性、以及手势消失后的释放逻辑。渲染层就是 Pygame 的飞机大战本体负责精灵移动、子弹生成、碰撞检测、帧率维持。这四层如果全塞在一个while True里跑起来会很难受。摄像头读帧是阻塞的CNN 推理在 CPU 上大概 10~30msPygame 的clock.tick(60)要求你每帧不能超过 16ms。三者节奏完全不一致串行执行最直接的后果就是游戏卡成幻灯片。所以工程上的标准做法是把采集和推理放进一个独立线程主线程只负责游戏循环两边通过一个线程安全的共享变量交换「当前手势」。这里有个取舍用全局变量加锁也行但我一般更习惯用一个单元素的queue.Queue(maxsize1)。原因很简单——识别线程比游戏线程慢的时候队列会堆积旧帧导致画面里的手势和你手上的动作对不上延迟越来越大。maxsize1配合put_nowait失败就丢弃天然做到了「只保留最新结果」这个设计在后面第 5 章还会再提一次。数据流大致是这样摄像头 BGR 帧 → 镜像翻转 ROI 裁剪 → 灰度化 高斯模糊 尺寸缩放 64×64 → CNN 前向推理 → 类别索引 置信度 → 时序平滑连续 N 帧一致才生效 → 当前动作枚举LEFT / RIGHT / FIRE / IDLE → Pygame 事件或直接改玩家坐标2.2 目录结构与依赖清单一个能跑起来的最小工程目录我建议按下面组织。别小看这个结构第一次写的时候我把采集脚本、训练脚本、推理脚本全堆在根目录后来想换模型文件路径改了七八处 import血泪经验。gesture_plane/ ├── config.py # 路径、类别名、超参集中管理 ├── collect_data.py # 按类别采集样本 ├── train_cnn.py # 训练与验证 ├── infer_thread.py # 摄像头 推理线程 ├── game/ │ ├── main.py # 游戏主循环 │ └── assets/ # 飞机、子弹、背景图 ├── models/ │ └── gesture_cnn.pth # 训练产出的权重 └── data/ ├── fist/ ├── palm/ └── point/依赖不多但要装对版本。CPU 上跑就够不必强上 CUDApip install torch torchvision --index-url https://download.pytorch.org/whl/cpu pip install opencv-python pygame numpyopencv-python用默认的个人版即可别装opencv-contrib-python和它共存两个包会互相覆盖cv2目录表现是同一个 import 有时能用有时报AttributeError这属于比较经典的玄学问题。config.py里我会把所有会变的东西集中放包括类别映射、图片尺寸、模型路径、平滑窗口大小。这个文件后面改造的时候你会回来改很多次集中管理能省掉大量搜索替换。# config.py import os BASE_DIR os.path.dirname(os.path.abspath(__file__)) IMG_SIZE 64 # 必须训练和推理保持同一个值 NUM_CLASSES 3 # fist / palm / point CLASS_NAMES [fist, palm, point] MODEL_PATH os.path.join(BASE_DIR, models, gesture_cnn.pth) DATA_DIR os.path.join(BASE_DIR, data) # 游戏侧 CAM_INDEX 0 # 多摄像头时改这里 ROI_SCALE 0.5 # 只取画面中心 50% 区域减少背景干扰 SMOOTH_WINDOW 5 # 连续 N 帧一致才认为手势有效 CONF_THRESHOLD 0.75 # 置信度低于此值视为无手势参数说明IMG_SIZE是整条链路的一致性锚点训练用 64、推理用 128 是最常见的翻车点ROI_SCALE解决的是背景误识别手只占画面一小块时全图输入会让模型学到键盘、椅背这些无关纹理CONF_THRESHOLD是防误触的最后一道闸低于阈值就直接输出 IDLE宁可不动也不乱动。2.3 主循环为什么必须拆线程不拆线程的版本我也写过能跑但只能算「演示」。问题出在摄像头读帧上cap.read()在没有新帧的时候会等待这一等就是几毫秒到几十毫秒期间 Pygame 的帧循环被堵死飞机的移动会一顿一顿。改成双线程后识别线程全速跑游戏线程固定 60 FPS。两者共享状态的入口收敛在一个函数里读写都走队列避开了锁的复杂度。# infer_thread.py节选 import threading import queue import cv2 import torch import numpy as np from config import IMG_SIZE, CAM_INDEX, ROI_SCALE, MODEL_PATH, CONF_THRESHOLD result_queue queue.Queue(maxsize1) # 只保留最新一次识别结果 stop_flag threading.Event() def _crop_roi(frame): h, w frame.shape[:2] rw, rh int(w * ROI_SCALE), int(h * ROI_SCALE) x1, y1 (w - rw) // 2, (h - rh) // 2 return frame[y1:y1 rh, x1:x1 rw] def preprocess(frame): frame cv2.flip(frame, 1) # 水平镜像符合用户直觉 roi _crop_roi(frame) gray cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY) gray cv2.GaussianBlur(gray, (5, 5), 0) # 抑制噪点和训练时一致 return cv2.resize(gray, (IMG_SIZE, IMG_SIZE)) def inference_worker(model): cap cv2.VideoCapture(CAM_INDEX) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) while not stop_flag.is_set(): ok, frame cap.read() if not ok: continue img preprocess(frame) tensor torch.from_numpy(img).float().unsqueeze(0).unsqueeze(0) / 255.0 with torch.no_grad(): logits model(tensor) prob torch.softmax(logits, dim1).squeeze() conf, idx torch.max(prob, dim0) payload (int(idx), float(conf)) if conf CONF_THRESHOLD else (-1, float(conf)) try: result_queue.put_nowait(payload) # 满了就丢旧值保证低延迟 except queue.Full: pass cap.release()关键点有三个。torch.no_grad()必须加否则每帧都会构建计算图内存会一直缓慢上涨跑二十分钟后进程被系统杀掉现象像是「游戏自己退了」。unsqueeze(0).unsqueeze(0)是在补 batch 维和 channel 维模型的输入形状是[N, 1, 64, 64]漏一个就会报维度不匹配。put_nowait配queue.Full吞异常是为了让识别线程永远不被阻塞这条比「结果不丢」重要得多。3. 手势数据集与 CNN 训练把「握拳、张掌、竖指」喂给模型3.1 样本采集脚本ROI 裁剪与尺寸归一化模型效果好不好八成取决于数据不取决于网络多深。这个项目只有三类手势理论上每类 300~500 张就够跑出一个能玩的效果。采集脚本要跟推理脚本用同一套预处理函数这句话我要重复一遍同一套。我见过太多人采集时直接存原始帧推理时才做灰度化和缩放训练分布和推理分布直接错开模型在验证集上 98%实际玩起来全是乱跳。# collect_data.py import cv2, os, argparse from config import DATA_DIR, CLASS_NAMES from infer_thread import preprocess # 复用同一份预处理别复制粘贴 def collect(class_name, max_count400): save_dir os.path.join(DATA_DIR, class_name) os.makedirs(save_dir, exist_okTrue) cap cv2.VideoCapture(0) count len(os.listdir(save_dir)) while count max_count: ok, frame cap.read() if not ok: break img preprocess(frame) # 与推理完全一致的 64×64 灰度图 cv2.imshow(preview, img) key cv2.waitKey(1) 0xFF if key ord(s): # 按 s 存一张 cv2.imwrite(os.path.join(save_dir, f{count:04d}.png), img) count 1 elif key ord(q): break cap.release() cv2.destroyAllWindows() if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--cls, choicesCLASS_NAMES, requiredTrue) args parser.parse_args() collect(args.cls)按s手动逐张存看起来笨但比自动连拍好。自动连拍的后果是相邻帧几乎一模一样训练集里充斥着重复样本模型对角度和距离的泛化能力会很差。手动存的时候要有意识地变换手的远近、左右偏、手指张开程度、光照方向、背景。同一个姿势正面对着拍 400 张模型只学会「正面手掌」稍微侧一点就崩。采集时的实操建议每类至少覆盖 5 种手部朝向 × 3 种距离光线别只在一个位置采白天和晚上各采一轮。数据量少的时候数据增强比加网络层数有用得多。3.2 网络结构与训练循环网络不需要深。输入 64×64 单通道三层卷积加两层全连接足够了参数总量控制在 20 万以内CPU 推理单帧 5ms 左右完全跟得上 60 FPS。# train_cnn.py import torch import torch.nn as nn import torch.optim as optim from torch.utils.data import DataLoader from torchvision import datasets, transforms from config import IMG_SIZE, NUM_CLASSES, DATA_DIR, MODEL_PATH class GestureCNN(nn.Module): def __init__(self, num_classesNUM_CLASSES): super().__init__() self.features nn.Sequential( nn.Conv2d(1, 16, 3, padding1), nn.BatchNorm2d(16), nn.ReLU(), nn.MaxPool2d(2), # 64 - 32 nn.Conv2d(16, 32, 3, padding1), nn.BatchNorm2d(32), nn.ReLU(), nn.MaxPool2d(2), # 32 - 16 nn.Conv2d(32, 64, 3, padding1), nn.BatchNorm2d(64), nn.ReLU(), nn.AdaptiveAvgPool2d(1), # 全局池化抗输入尺寸波动 ) self.classifier nn.Sequential( nn.Flatten(), nn.Dropout(0.3), nn.Linear(64, num_classes), ) def forward(self, x): return self.classifier(self.features(x)) def build_loaders(batch_size32): # 训练增强小幅旋转、平移、亮度扰动模拟真实手持变化 train_tf transforms.Compose([ transforms.Grayscale(num_output_channels1), transforms.Resize((IMG_SIZE, IMG_SIZE)), transforms.RandomAffine(degrees10, translate(0.1, 0.1), scale(0.9, 1.1)), transforms.ColorJitter(brightness0.3), transforms.ToTensor(), ]) val_tf transforms.Compose([ transforms.Grayscale(num_output_channels1), transforms.Resize((IMG_SIZE, IMG_SIZE)), transforms.ToTensor(), ]) train_ds datasets.ImageFolder(DATA_DIR, transformtrain_tf) val_ds datasets.ImageFolder(DATA_DIR, transformval_tf) # 简易切分八成训练两成验证 n_train int(len(train_ds) * 0.8) n_val len(train_ds) - n_train train_set, _ torch.utils.data.random_split(train_ds, [n_train, n_val]) _, val_set torch.utils.data.random_split(val_ds, [n_train, n_val]) return (DataLoader(train_set, batch_sizebatch_size, shuffleTrue, num_workers0), DataLoader(val_set, batch_sizebatch_size, num_workers0), train_ds.classes)这里有几个不显眼但影响很大的选择。AdaptiveAvgPool2d(1)替代了展平后接大全连接层参数从几十万降到几百顺带解决了「改输入尺寸就要改 Linear 输入维度」的麻烦。BatchNorm2d在小数据集上能让收敛快一截但推理时一定要model.eval()否则它继续用 batch 统计量单张图推理结果会飘这是个特别隐蔽的坑。num_workers0是 Windows 下的保守选择多进程数据加载在 Windows 上配合 Pygame 容易出问题样本量小的时候单进程完全够。训练循环本身没什么花样def train(epochs30, lr1e-3): device torch.device(cuda if torch.cuda.is_available() else cpu) train_loader, val_loader, classes build_loaders() model GestureCNN(len(classes)).to(device) criterion nn.CrossEntropyLoss() optimizer optim.Adam(model.parameters(), lrlr, weight_decay1e-4) scheduler optim.lr_scheduler.CosineAnnealingLR(optimizer, T_maxepochs) best_acc 0.0 for epoch in range(epochs): model.train() for imgs, labels in train_loader: imgs, labels imgs.to(device), labels.to(device) optimizer.zero_grad() loss criterion(model(imgs), labels) loss.backward() optimizer.step() scheduler.step() model.eval() # 切验证模式冻结 BN 统计量 correct total 0 with torch.no_grad(): for imgs, labels in val_loader: imgs, labels imgs.to(device), labels.to(device) pred model(imgs).argmax(dim1) correct (pred labels).sum().item() total labels.size(0) acc correct / max(total, 1) print(fepoch {epoch1:02d} acc{acc:.4f}) if acc best_acc: best_acc acc torch.save({state_dict: model.state_dict(), classes: classes}, MODEL_PATH) print(fbest{best_acc:.4f} - {MODEL_PATH})scheduler用余弦退火30 个 epoch 内学习率平滑降到接近 0比固定 lr 最后几轮震荡小。保存时把classes一起存进去很重要——ImageFolder是按目录名的字母序生成类别索引的fist / palm / point排出来是 0/1/2但你要是后来加了个ok类索引全乱推理端不读 classes 就会把「握拳」认成「OK」飞出个莫名其妙的结果。3.3 训练结果的判读与模型导出跑完 30 轮验证准确率一般在 0.95 以上就该停手了。如果一直卡在 0.6 左右先别怀疑网络去看数据很可能是某一类样本数量明显少于其他类或者采集时光照全在同一个方向。ImageFolder不做类别均衡少的那类会被压制。另一个信号是训练准确率高但验证低典型的过拟合。这个项目数据量小Dropout 0.3 加上数据增强基本能压住如果还不行把卷积通道数从 16/32/64 降到 8/16/32模型小了反而不容易记住训练集。导出的.pth里存了state_dict和classes两个键推理端加载时要先建同结构的模型再load_state_dict别用torch.load直接当模型对象使新版 PyTorch 默认weights_onlyTrue直接当模型用会报类型错误。4. 推理与游戏对接OpenCV 预处理 手势到按键的胶水层4.1 推理侧预处理必须和训练侧对齐第 3 章说过一遍这里再说一遍具体到代码层面要盯哪些点。训练时transforms.ToTensor()做的是HWC → CHW加除以 255推理时就得手动补上这两步。训练时用了Grayscale推理时就必须cvtColor(BGR2GRAY)而且顺序不能乱先灰度再 resize 和先 resize 再灰度插值方式不同边缘像素值会有细微差异模型对这东西比你想的敏感。# 推理端张量构造与训练 transform 严格对应 tensor torch.from_numpy(img) # img: uint8, shape (64, 64) tensor tensor.float().unsqueeze(0).unsqueeze(0) / 255.0 # 等价于 ToTensor 的 HWC-CHW /255只是这里 HWC 退化成 HW还有一个常被忽略的点model.eval()。加载权重后忘了切 eval 模式BatchNorm 用单张图的统计量做归一化同一只手在不同帧里输出能差出 30 个百分点现象是「手势没变但识别结果乱跳」很多人会误以为是摄像头问题去换驱动、换 USB 口白折腾半天。4.2 手势到动作的映射与去抖动分类模型逐帧输出天然会抖。人手的姿态在两类边界上比如手指半弯会来回横跳如果直接把每帧结果映射成游戏动作飞机会疯狂左右抽搐。处理办法是加一个滑窗投票。维护最近 N 帧的类别队列取众数且要求众数占比超过阈值才切换动作。N 取 5 在 30 FPS 的识别速度下大约 160ms 延迟手感上基本察觉不到但抖动没了。from collections import deque, Counter from config import SMOOTH_WINDOW class GestureSmoother: def __init__(self, windowSMOOTH_WINDOW, ratio0.6): self.buf deque(maxlenwindow) self.ratio ratio self.current -1 def update(self, idx): self.buf.append(idx) if len(self.buf) self.buf.maxlen: return self.current label, cnt Counter(self.buf).most_common(1)[0] # 无手势(-1)占多数时直接释放避免手离开画面后飞机一直动 if cnt / len(self.buf) self.ratio: self.current label return self.currentratio0.6是个经验值调高反应变迟钝调低还是抖。-1参与投票这一点很关键否则手离开画面后缓冲区里残留的最后一个有效手势会一直生效飞机撞墙停不下来这个 bug 我第一次跑的时候盯了十分钟才反应过来。动作映射我倾向于双通道CNN 分类结果负责「动作」开火 / 暂停 / 无手的水平位置负责「方向」。纯分类做方向控制只有「左 / 中 / 右」三档飞机跳着走很难看。# 用轮廓质心算手的水平位置映射到屏幕坐标 def hand_x_ratio(frame): roi _crop_roi(cv2.flip(frame, 1)) gray cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY) _, th cv2.threshold(gray, 60, 255, cv2.THRESH_BINARY_INV) contours, _ cv2.findContours(th, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE) if not contours: return None c max(contours, keycv2.contourArea) if cv2.contourArea(c) 3000: # 太小的是噪声忽略 return None x, y, w, h cv2.boundingRect(c) return (x w / 2) / roi.shape[1] # 0~1 之间阈值 60 是反相二值化适合浅色背景如果你的环境偏暗改成自适应阈值cv2.adaptiveThreshold会稳一些。contourArea 3000的过滤很有必要不然一个晃动的鼠标影子都能被当成手。4.3 Pygame 主循环里的注入方式游戏侧改动很小。主循环每帧从队列取一次最新结果更新平滑器然后套用到玩家精灵上。这里要注意手势线程的输出频率和游戏帧率不一致可能出现一帧内队列为空的情况取不到就沿用上一帧的状态别重置。# game/main.py核心循环节选 import pygame, queue, threading, torch from infer_thread import result_queue, inference_worker, stop_flag, hand_x_ratio from train_cnn import GestureCNN from config import MODEL_PATH ckpt torch.load(MODEL_PATH, map_locationcpu, weights_onlyFalse) model GestureCNN(len(ckpt[classes])) model.load_state_dict(ckpt[state_dict]) model.eval() # 千万别漏 threading.Thread(targetinference_worker, args(model,), daemonTrue).start() pygame.init() screen pygame.display.set_mode((800, 600)) clock pygame.time.Clock() player_x 400.0 fire_cd 0 running True while running: for e in pygame.event.get(): if e.type pygame.QUIT: running False try: idx, conf result_queue.get_nowait() except queue.Empty: idx None # 本帧无新结果沿用旧动作 if idx is not None: action smoother.update(idx) if action 1: # palm开火 fire_cd max(0, fire_cd - 1) if fire_cd 0: spawn_bullet(player_x) fire_cd 8 # 冷却帧数控制射速 # 方向走连续量比三档分类顺滑 ratio hand_x_ratio(current_frame) if current_frame is not None else None if ratio is not None: player_x (ratio * 800 - player_x) * 0.25 # 一阶平滑跟随 draw(player_x) pygame.display.flip() clock.tick(60) stop_flag.set()几个参数值得说。fire_cd 8是射速冷却按 60 FPS 算大约每秒 7 发太快会满屏子弹如果识别线程只有 30 FPS队列取空的频率不低冷却时间可以用「毫秒时间戳」而不是帧数避免不同机器上手感差异过大。0.25是跟随系数越大越紧跟手越小越顺滑但延迟感强实际调到 0.2~0.35 之间比较舒服。还有一个隐藏问题hand_x_ratio每帧都跑一次findContours和 CNN 推理是重复做预处理。真要优化可以在识别线程里把 ROI 灰度图一起放进队列主线程直接用省掉一次完整的轮廓计算。这个改动留到第 6 章讲性能的时候再展开。5. 避坑与排查五条让项目跑不起来的常见故障5.1 摄像头能打开但读不到帧现象cap.isOpened()返回 True但cap.read()一直返回False画面黑的。原因多半是摄像头被别的进程占着。笔记本上常见的是会议软件在后台挂着或者上一次运行的 Python 进程没退干净句柄没释放。opencv-python在某些 Windows 版本上不会主动释放设备。解决办法先把infer_thread.py里的cap.release()放到try/finally里保证异常退出也能释放再用系统任务管理器把残留的 python 进程杀掉。代码里还可以加一个读帧失败计数器连续失败 30 次就重开VideoCapture比死循环卡在那里强。5.2 模型验证准确率很高实际玩起来全是误识别现象训练日志里 accuracy 0.98摄像头前比划半天飞机乱飞。原因训练数据和推理数据的预处理不一致。最常见的三种错位是——采集时存了原图 RGB推理时喂了灰度训练用了Resize((64,64))默认双线性插值推理用了cv2.resize默认也是双线性但缩放比例不同训练时没做镜像推理时做了flip。解决办法把预处理抽成一个函数采集脚本、训练 transform、推理脚本三处都调它或者至少抄同一份参数。debug 的时候可以把推理端的预处理结果cv2.imwrite出来和data/里的训练图肉眼对比一下差别一眼就能看出来。5.3 游戏跑几分钟后越来越卡最后进程消失现象刚启动 60 FPS五分钟后掉到 15 FPS再后来窗口直接没了。原因推理函数里漏了torch.no_grad()。每帧都在构建计算图GPU / CPU 内存持续增长操作系统的 OOM killer 直接把进程干掉日志里什么都没有黑匣子一样。解决办法推理全程包在with torch.no_grad():里另外把队列的put_nowait配上maxsize1防止识别结果堆积。这两条一起做内存曲线就平了。排查这类问题可以挂个psutil定时打印process.memory_info().rss涨不涨一看便知。5.4 手势切换时有明显延迟飞机反应慢半拍现象手已经挥过去了飞机还停在原地一两秒后才动。原因SMOOTH_WINDOW调太大或者识别线程里读帧和推理串行导致实际帧率极低。后者更隐蔽——cap.read()在有些摄像头上单次阻塞能到 100ms再加上 30ms 推理实际只有 7 FPS滑窗 5 帧就是 700ms 延迟。解决办法先把滑窗降到 3 观察如果还是慢就在识别线程里加帧率统计打印每秒处理帧数。低于 15 的话把 ROI 再缩小、IMG_SIZE降到 48、模型通道砍半三招下去 CPU 上轻松上到 25 FPS 以上。5.5 换了新环境重新训练类别全乱了现象加了第四类手势重新训练之前能识别的三类全认错。原因ImageFolder按目录名字母序编号新增一个ok目录后fist从 0 变成 1所有索引后移。推理端如果硬编码idx 0是开火逻辑就全错了。解决办法训练保存时把classes列表一起存进 checkpoint推理端从 checkpoint 里读永远不硬编码数字。映射表用字典写# 从 checkpoint 恢复类别名不硬编码索引 ckpt torch.load(MODEL_PATH, map_locationcpu, weights_onlyFalse) classes ckpt[classes] # [fist, ok, palm, point] ACTION {fist: fire, palm: idle, point: pause, ok: special} action ACTION.get(classes[idx], idle)这样加类、删类都不用改游戏逻辑改一个字典就够。从那以后我每次动数据集第一件事就是确认 checkpoint 里存了classes。6. 二次开发换手势、换模型、提帧率的三条改造路线拿到能跑的版本之后改动方向其实就三条按投入产出排一下。改造方向改动位置工作量效果新增/替换手势类别config.py 采集脚本 ACTION字典半天直接扩大玩法换更轻的模型train_cnn.py的GestureCNN半天帧率提升 30%~60%换推理后端infer_thread.py的前向部分一天上 ONNX Runtime 或量化接入其他游戏game/main.py的事件注入一天复用整套识别链路先说服手感的优化。hand_x_ratio每帧重算一遍预处理其实识别线程已经做过一次 ROI 裁剪和灰度化了。改法是在inference_worker里把裁剪后的 ROI 灰度图随结果一起塞进队列payload (idx, conf, roi_gray)主线程直接拿这张图算轮廓质心。省掉一次cvtColor加一次findContours40ms 左右的预算就回来了代码量不超过十行。再说模型替换。如果你不想装 PyTorch 那套依赖可以把训练好的权重导成 ONNX游戏端只依赖onnxruntime包体从 2GB 降到 100MB 出头适合做成一个能双击运行的小工具。导出脚本大概长这样import torch from train_cnn import GestureCNN ckpt torch.load(models/gesture_cnn.pth, map_locationcpu, weights_onlyFalse) model GestureCNN(len(ckpt[classes])) model.load_state_dict(ckpt[state_dict]) model.eval() dummy torch.randn(1, 1, 64, 64) torch.onnx.export(model, dummy, models/gesture_cnn.onnx, input_names[input], output_names[logits], dynamic_axes{input: {0: batch}})导完一定要做一致性验证同一张图分别用 PyTorch 和 ONNX 推理输出概率的最大绝对差应该小于 1e-4。差值大说明某层算子导得不对最常见的是AdaptiveAvgPool2d在某些 opset 版本上行为不一致那时候要么升 opset要么把它换成nn.AvgPool2d(8)固定尺寸池化。第三条是接入别的游戏。这套识别链路和飞机大战的耦合度其实很低耦合点只有「ACTION字典」和「玩家坐标更新」两处。要接俄罗斯方块把ACTION改成「左移 / 右移 / 旋转 / 快落」四个手势主循环里换成pygame.event.post合成按键事件识别部分一行不动。常见做法是封装一个GestureReader类对外只暴露get_action() - str游戏侧完全不知道底层是 CNN 还是别的。最后留一个我自己的习惯。这个项目我每次改完预处理、改完网络结构、或者换摄像头之后都会强制走一遍三步验证先存 20 张实时图到临时目录肉眼比对它们和训练集的样子再单独跑一次单图推理打印各类别概率最后才启动游戏跑两分钟。跳过前两步直接开游戏等于把排查成本全压在肉眼观察上翻车了也找不到是哪一环的问题。希望帮到你少走点这种弯路。本文还有配套的精品资源点击获取
