简介面向计算机相关专业期末大作业与实战练习场景这份基于PythonOpenCV的手写数字识别项目代码与文档齐全适合作为课程设计或期末大作业参考。包内共2000个文件1995张jpg图片为手写数字样本与识别过程图像4个py文件包含主程序、图像预处理及识别脚本1个md文件为项目说明文档整体仅22.76MB目录简洁易查阅。目前已有235人学习/浏览。该项目为导师指导并获99分高分认可价值在于可直接下载运行利用真实样本验证数字定位、特征提取与分类识别流程附带文档说明可帮助理解关键步骤、调整参数并整理答辩报告适合需要快速完成同类设计或补齐实验细节的学习者。1. 手写数字识别期末大作业的“标配”但要交的不是一个能跑的玩具期末周你大概率会在各类免费 python 源码大全里翻到这门课的大作业基于 Python 和 OpenCV 的手写数字识别。项目体积不大一般就十几个 .py 文件和一份 Word 版文档说明但背后的技术链条并不短——图像预处理、轮廓分割、特征提取、分类器训练、模型持久化、测试评估每一环都有老师设置的扣分点。这个标题解决的是“把 0~9 的手写数字图像自动识别成文本”的问题适合第一次做图像处理课程设计、或想用 OpenCV 做个能讲明白的经典模式识别项目的人。本文不评价哪份源码写得最好只讲怎么把它读懂、跑通、写进文档里并且让它不像一个黑匣子。2. 核心思路从像素到数字的四步流水线KNN 为什么够用手写数字识别不是一个“输入图片、输出数字”的单步操作而是一条完整的图像处理流水线灰度化 → 二值化 → 切分出单个数字 → 特征向量 → 分类器。期末大作业的项目源码绝大多数遵循这套结构只是分类器可能从 KNN 换成 SVM。理解这条流水线你读源码的速度会快一倍改参数时也不会两眼一抹黑。2.1 为什么是 OpenCV 自带 KNN 而不是 CNN期末作业要的是可解释性很多同学第一反应是上 CNN因为 MNIST 上卷积神经网络准确率轻松到 99%。但期末大作业的性质不同老师要的是你能把每一行代码讲清楚。CNN 一旦调完你面对的是卷积核、池化层、dropout被问一句“为什么这个参数有效”就容易卡壳而 KNNK 近邻的原理就是“找最像的 K 个样本投票”一句话能说完。OpenCV 在cv2.ml模块里直接封装了 KNN 和 SVM不需要额外装 sklearn这对只装 opencv-python 和 numpy 的期末项目来说非常友好。KNN 训练也几乎不需要“训练”——它本质上是把训练集存下来预测时逐条计算输入样本与每个训练样本的距离。手写数字是 28×28 的灰度图展开成 784 维向量后欧氏距离就能很好地度量“像不像”。在小样本几百到几万场景下KNN 准确率能做到 90% 上下足够交一份漂亮的期末报告。SVM 是另一种常见选择它的思路是找一个“间隔最大”的分界面用过 OpenCV 的cv2.ml.SVM_create()就能搭。相比 KNNSVM 对特征缩放更敏感参数更多核函数、C、gamma新手调起来容易翻车。我的习惯是只要文档里没强制要求“学习算法”优先用 KNN把省下来的时间拿去做图像预处理和文档截图性价比更高。2.2 图像预处理四板斧灰度、模糊、大津阈值、归一化拿到一张手写数字照片第一步永远是cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)转灰度。原因很简单颜色信息对识别数字几乎没有帮助反而会增加计算量而且灰度化是后面所有形态学操作的前提。第二步是去噪。常见做法是用cv2.GaussianBlur(gray, (5, 5), 0)核大小取 5×5标准差填 0 让函数根据核自动计算。不要小看这一步手写图片上常有铅笔灰、纸纹噪点不模糊直接二值化噪点会变成一个个孤立的小连通域轮廓检测时你会多出一堆“假数字”。第三步是二值化。项目源码里几乎清一色写这一行_, binary cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV | cv2.THRESH_OTSU)THRESH_OTSU是让算法自动找最优阈值参数0此时只是占位符THRESH_BINARY_INV表示反向二值化把黑色数字变成白色、白色背景变成黑色。为什么要反色因为 OpenCV 的findContours默认找白色区域的外轮廓反色之后数字本身变成白色切分时可以直接用轮廓把每个数字圈出来。第四步是归一化。特征向量里的像素值如果不缩放到 0~1KNN 算欧氏距离时高值的维度会主导结果低值维度的差异被淹没。常见做法是features features.astype(np.float32) / 255.0。有些源码会额外做均值方差归一化对 KNN 来说不是必须但做了也没什么坏处。下面是一张常用预处理参数速查表我把它贴在文档里能省很多口舌处理环节常见参数典型值改动后可能发生什么灰度化cv2.COLOR_BGR2GRAY固定不改高斯模糊核大小5×5核太小去不掉噪点核太大数字边缘模糊二值化阈值方法Otsu固定阈值在光照不均时容易整图失效缩放尺寸目标尺寸28×28太小丢特征太大会让 KNN 距离计算变慢归一化数据类型float32 / 255不做的话准确率可能掉几个百分点这些参数看着简单但“坑”往往藏在更细节的地方比如轮廓切分时面积阈值怎么设、MNIST 原始文件怎么读下一章我们直接把能抄的代码写出来。3. 复现路径把项目源码从“能看”变成“能跑”的最小闭环拿到一个手写数字识别的期末大作业源码第一件事不是读代码而是先把环境搭起来、让训练脚本跑通。很多同学一上来就打开 main.py 从头读结果被一堆自定义函数绕晕最后连入口在哪都没找到。我的顺序是先装环境再跑训练再跑单张图片预测最后回头读代码。3.1 环境准备Python 3.8 opencv-python numpy别再碰源码编译先说结论直接用 pip 安装 opencv-python不要自己去编译 OpenCV。网上搜 opencv 安装教程很容易看到 ubuntu install opencv 的源码编译教程那是给需要 CUDA、contrib 扩展模块的工程场景用的。期末大作业用不到那些源码编译一次动辄半小时中间还容易因为 cmake 版本、依赖库缺失而失败纯属给自己挖坑。建议用 Python 3.8 或 3.10配 4.5.x 版本的 opencv-python。为什么不是最新版因为有些老项目源码是在import cv2之后直接调用cv2.ml模块的OpenCV 新版虽然也保留了这个模块但部分内部接口行为有变动你如果中途遇到“属性不存在”之类的报错很难分辨是代码问题还是版本问题。# 在项目根目录创建虚拟环境Windows 用 venv python -m venv venv # 激活环境Windows 用 .\venv\Scripts\activateLinux/macOS 用 source venv/bin/activate pip install opencv-python4.5.5.64 numpy matplotlib # 验证安装 python -c import cv2; print(cv2.__version__)这段命令里的关键点venv是 Python 自带的虚拟环境不需要额外装 virtualenvopencv-python4.5.5.64固定了版本避免以后升级造成行为变化numpy必装因为 OpenCV 的图像对象本质就是 numpy 数组。如果pip install很慢可以在命令后加-i指定国内 pip 镜像这不在代码逻辑里但能省你几分钟。装完之后用python -c import cv2验证如果打印出了 4.5.x 版本号环境就绪。我见过最多的环境问题是用 PyCharm 的同学给解释器选了系统 Python而 pip 却装进了另一个 Python 里结果import cv2永远报ModuleNotFoundError。解决办法只有一条——让 pip 和 python 来自同一个解释器在虚拟环境里操作就不会有这个烦恼。3.2 读取 MNIST 原始数据IDX 格式的大端序陷阱手写数字识别的通用训练集是 MNIST它包含 60000 张训练图和 10000 张测试图文件是 IDX 格式。IDX 不是常见图片格式没有 PNG/JPEG 的文件头也不直接能被 cv2.imread 读进来。源码里通常有一个load_mnist()函数干这件事。import numpy as np import struct def load_mnist_images(path): # IDX 文件头magic(4字节) num_images(4字节) rows(4字节) cols(4字节) with open(path, rb) as f: magic, num, rows, cols struct.unpack(IIII, f.read(16)) data np.frombuffer(f.read(), dtypenp.uint8) return data.reshape(num, rows * cols) def load_mnist_labels(path): # 标签文件头magic(4字节) num_labels(4字节)之后每个字节是一个标签 with open(path, rb) as f: magic, num struct.unpack(II, f.read(8)) labels np.frombuffer(f.read(), dtypenp.uint8) return labelsstruct.unpack(IIII, f.read(16))里的表示大端序这是 IDX 格式最容易踩的坑——如果你的电脑是 x86 小端序漏了读出来的图片数量直接变成十亿级别程序要么卡死要么立刻报错。np.frombuffer(f.read(), dtypenp.uint8)是零拷贝读取数据量少时没问题数据量大时建议复制一份因为frombuffer返回的数组只读后面做归一化需要.copy()。训练集和标签文件分开存放常见文件名是train-images-idx3-ubyte和train-labels-idx1-ubyte。要注意文件路径里不要带中文open()本身能处理中文路径但后续如果和 cv2.imread 混用问题会一起暴露。读完之后可以验证一下print(images.shape, labels.shape)正确输出是(60000, 784)和(60000,)。3.3 从一张手写图片切出单个数字findContours 的面积过滤识别的对象不一定是 MNIST期末作业常常要求“拍一张纸上的多个数字自动识别”。这时要把图像里的每个数字单独切出来。核心函数是cv2.findContours和cv2.boundingRect。import cv2 import numpy as np def split_digits_from_image(img_path, min_area50): # 中文路径用 imdecode 读imread 直接读会是 None img cv2.imdecode(np.fromfile(img_path, dtypenp.uint8), cv2.IMREAD_COLOR) gray cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) blur cv2.GaussianBlur(gray, (5, 5), 0) _, binary cv2.threshold(blur, 0, 255, cv2.THRESH_BINARY_INV | cv2.THRESH_OTSU) # OpenCV 4.x 返回两个值OpenCV 3.x 返回三个值 contours, _ cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE) digits [] for c in contours: area cv2.contourArea(c) if area min_area: continue # 面积太小当成噪点丢掉 x, y, w, h cv2.boundingRect(c) # 过滤掉明显不是数字的细长条比如纸张边缘的横线 if w 5 or h 5 or h binary.shape[0] * 0.9: continue digit binary[y:y h, x:x w] digit cv2.resize(digit, (28, 28), interpolationcv2.INTER_AREA) digits.append(digit.reshape(1, 784)) return np.vstack(digits) if digits else np.empty((0, 784))参数min_area50的作用是滤掉小噪点但若你的图片拍照时光线不好噪点面积可能超过 50这时要调高到 100 甚至 200。cv2.RETR_EXTERNAL表示只找外部轮廓不找内部嵌套轮廓——数字内部一般没有洞这个参数够用且更安全CHAIN_APPROX_SIMPLE压缩水平、垂直、对角方向的线段只保存端点减少内存占用。cv2.resize的interpolationcv2.INTER_AREA是专门用于缩小的插值方法直接缩小 28×28 时轮廓边缘会比较干净如果改用默认的INTER_LINEAR缩小后的数字边缘容易产生灰色过渡带影响二值化后的清晰度。这段代码返回的digits是一个二维数组每行是 784 维的特征向量可以直接作为 KNN 的输入。注意w 5 or h 5的条件过滤因为数字如果太细很可能是污渍或者笔画断掉后的碎片。3.4 KNN 训练、保存模型、预测一条龙模型部分直接使用 OpenCV 的机器学习模块不需要自己写距离计算。import cv2 import numpy as np def train_knn(train_data, train_labels): # KNN 训练本质是保存数据OpenCV 要求 float32 特征 int32 标签 knn cv2.ml.KNearest_create() knn.train(train_data.astype(np.float32), cv2.ml.ROW_SAMPLE, train_labels.astype(np.int32)) knn.save(mnist_knn.xml) return knn def load_knn(model_pathmnist_knn.xml): return cv2.ml.KNearest_load(model_path) def predict_digit(knn, feature_vector, k5): # feature_vector 是 1×784 的 float32 ret, result, neighbours, dist knn.findNearest(feature_vector, k) return int(result[0][0])cv2.ml.ROW_SAMPLE告诉 OpenCVtrain_data 的每一行是一个样本而不是每一列。如果你把数据转置再传进去训练不会报错但识别率会惨不忍睹这也是一个隐蔽坑点。findNearest返回四个值result的形状是(1, 1)取result[0][0]才是最终预测标签。关于k值的选取k5是常见默认值。k 取 1 时模型对单个样本的噪声极其敏感属于典型的过拟合测试集上可能掉 2%~3% 的准确率k 取太大比如 15又会把距离较远的“不像”样本也拉进投票导致欠拟合。我一般会让 k 在 3、5、7 之间各跑一次输出测试集准确率选最高的那个。注意 k 通常取奇数避免投票时两类票数相同。4. 期末大作业最常见的 5 个坑从运行报错到识别率翻车这个项目的源码本身不复杂但运行环境、依赖版本、手写图片质量这三个方面的坑会让同一份代码在不同人手里表现天差地别。下面 5 条是我见过的真实踩坑记录每一条都按“现象 → 原因 → 解决”来写你可以直接当成排查手册用。4.1 现象pip 装完 cv2import 还是报 ModuleNotFoundError这是出现频率最高的报错没有之一。常见场景是在 PyCharm 里创建了项目用 IDE 的终端执行了pip install opencv-python结果运行脚本时依然提示ModuleNotFoundError: No module named cv2。原因几乎总是同一个——当前 shell 里的 python 和 pip 不是同一个解释器。PyCharm 的解释器配置、系统级 Python、虚拟环境三者的 pip 路径不一致包装到了 A 环境而脚本用的是 B 环境。解决的顺序先看两个命令# 查看 python 可执行文件路径 where python # Windows 命令 which python # Linux/macOS 命令 # 查看当前 shell 的 pip 装到了哪里 python -m pip show opencv-pythonpython -m pip show显示的是当前 python 对应的包信息。如果显示“not found”说明装到了别处。最省心的做法是只留一个环境用 venv 创建项目虚拟环境每次打开终端先激活再用python -m pip install ...安装以后所有依赖都锁在项目内部换电脑也不怕。4.2 现象cv2.imread 返回 None读图失败但文件确实存在Windows 用户最容易中招的场景是图片路径含中文比如“C:\Users\张三\Desktop\数字 3.jpg”。OpenCV 的imread底层用的是 C 接口不支持非 ASCII 路径直接返回None。你如果用print(img)去检查会看到None随后任何对 img 的操作都会抛TypeError。解决方法是改用cv2.imdecode配合np.fromfileimg cv2.imdecode(np.fromfile(img_path, dtypenp.uint8), cv2.IMREAD_COLOR)np.fromfile以二进制方式把文件读成 numpy 数组绕过了 C 接口的路径解析imdecode再从内存里解码图片。注意这种方法读出来的图没有任何 EXIF 方向信息手机拍的照片如果方向不对需要提前旋转好。4.3 现象MNIST 数据解析后 image 数组全是 0或者数量不对新手从网上下载的 MNIST 文件偶尔会被浏览器加了个.txt后缀或者压缩包路径不对导致f.read(16)读到的字节顺序错误。另一个常见原因是struct.unpack格式写成了IIII漏掉了。在没有的 x86 机器上大端序的 4 个字节会被倒序解释num变成一个天文数字程序瞬间卡死——这不是程序死循环而是它真的试图分配一个巨大的数组。验证方法很直接读完之后打印data.nbytes如果发现比磁盘文件本身还大几十倍说明字节序解释错了。修正就是加上。另外 MNIST 的标签文件里每个标签占 1 字节范围 0~9如果你解析出来的标签有 0 和 10那也是读偏移错了——标签文件只有 8 字节文件头不要用读图片的 16 字节去套。4.4 现象模型准确率虚高测试集上 97%但识别自己手写的图时一塌糊涂这个坑几乎每个人都踩过原因是用训练集当测试集。KNN 在训练集上预测是一条直线——它直接存下了训练数据查询时自己在训练集里找邻居距离为 0 的就是它本身准确率自然接近 100%。老师如果看到报告里写“准确率 99%”一问你测试方法就穿帮。正确做法是把 MNIST 的官方测试集单独拿出来或者自己从训练集里切出 20% 作为验证集。另一个虚低的原因是自己拍的图片质量太差纸张阴影、倾斜、笔画断裂都会让预处理后的图和 MNIST 的风格差异巨大。解决方向有三个一是拍照时尽量正对纸张、光线均匀二是将图片中的数字先抠出来再放大到 28×28三是给预处理代码加入“将黑色数字居中到画布中央”的逻辑因为 MNIST 的数字是居中的如果你的数字偏在图像角落距离会明显变大。4.5 现象findContours 报 “not enough values to unpack (expected 3, got 2)”这是一条典型的版本报错。OpenCV 3.x 的findContours返回(image, contours, hierarchy)三个值OpenCV 4.x 返回(contours, hierarchy)两个值。网上找到的旧项目源码多半写成_, contours, hierarchy cv2.findContours(...)在 4.x 下解包失败。解决方式是统一按当前版本改写为contours, hierarchy cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)如果要兼容两个版本可以用 try/except 强行兼容不过期末项目没必要固定环境版本即可。比报错更麻烦的是版本不同导致的隐式行为差异比如某些轮廓选项在新版里对自相交轮廓的处理方式不一样——这种差异不会报任何错误只是切出来的框略有偏移很难排查。我建议在 README 里明确写明opencv-python4.5.5.64让跟你连代码的人不要踩同一个雷。5. 文档说明怎么写到让老师挑不出毛病七段式结构与避雷指南期末大作业的“文档说明”往往占比 30% 甚至更高它是老师了解你工作量的唯一窗口。很多同学的文档是从网上复制粘贴的板块顺序乱、运行截图缺失、环境版本对不上号代码跑得再好也可能被扣分。文档不是论文不用写得太“高屋建瓴”但要让老师相信你真的理解自己在做什么。5.1 文档说明必须有的七个小节结构、内容与字数建议我见过最稳妥的期末大作业文档结构是下面这套七个部分层次清楚不需要创新能力照着填就能及格以上小节内容要点建议篇幅1. 项目概述项目功能、输入输出、适合的应用场景1 段2. 环境依赖Python 版本、opencv-python、numpy、matplotlib写清版本号半页3. 目录结构源码文件清单、模型文件位置、数据文件位置半页4. 核心原理流水线四步预处理、切分、特征、分类器原理1~2 页5. 运行步骤从安装依赖到跑通识别的完整命令1 页6. 实验结果测试集准确率、单张图片识别效果截图、误判案例1~2 页7. 问题与反思踩过的坑、遇到的问题、为什么这样解决1 页每一节内容都要与源码一一对应。比如“环境依赖”里写opencv-python4.5.5.64那源码里就不能出现只兼容 3.x 的写法“目录结构”里列出的文件必须在压缩包里真实存在。老师抽查时最喜欢做的事就是照着文档命令逐条执行一旦出现“文档说要装 numpy 但 requirements.txt 里没有”之类的情况印象分会大减。核心原理部分不要写“本系统采用了先进的机器学习技术”这类空话直接把关键代码片段贴进去配两三行解释。例如贴 KNN 训练的截图下面写“KNN 将训练数据存储为 784 维特征向量预测时按欧氏距离选取最近的 k 个样本投票”。老师看到的是你真正掌握了原理而不是复制粘贴。5.2 把老师最关心的问题提前写清楚准确率、误判和你的处理过程期末大作业文档最容易翻车的地方恰恰是“实验结果”这一节。很多同学只写一句“测试集准确率 95%”然后贴一张截图就没有然后了。老师接着会问误判的是哪些数字为什么误判你做了什么改进这三个问题一个都答不上来实验部分等于白写。我的写法是准备一张 10×10 的混淆矩阵图横轴是真实标签纵轴是预测标签对角线上越亮越好矩阵之外的散点就是误判集中区。你不需要手工做完整矩阵用 sklearn 的confusion_matrix或者 matplotlib 的imshow都能画一张图就能说清“哪些数字容易互相混淆”。“问题与反思”部分写你实际踩过的 2~3 个坑就好比如“最初用固定阈值二值化光照不均时识别率跳水改用 Otsu 后稳定”。这种内容不需要编造你在前面第 4 章踩过的任何一个坑都能拿来写。“过程”比“结果”更能拉高印象分——每年期末项目一大半人交的都是二手作品只有你把实验过程的细节写出来老师才觉得这不是网上抄的。注意一个常见误区文档里不要大段贴网上找的算法原理尤其是那种“什么是机器学习”的科普级内容。期末大作业的读者是课程老师他已经知道 KNN 是什么他要看的是你的实现里做了哪些取舍。把这块篇幅省下来给截图和参数表效果更好。6. 几个让识别结果更稳一点的实战小技巧形态学、排序与验证最后分享三个我在处理手写数字时常用的“加分小技巧”它们不改变算法主体但能让识别率稳定爬升一到两个点也让你的代码在文档里有更多亮点可写。6.1 用形态学开运算处理粘连笔画手写数字最常见的预处理问题是笔画粘连比如“0”和“2”写得太近或者纸张上的折痕让两个数字被一条细线连起来。这时二值化后的图像只有一个大连通域findContours会把它当成一个整体切出来的框里装着两个数字。kernel cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3)) binary cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)开运算等于先腐蚀再膨胀它会先把细小的连接线腐蚀掉再把数字主体膨胀回原来的大小。注意核大小不要超过 3×3否则数字本身的笔画也会被断开。这个方法无法解决完全重叠的数字但对绝大多数手写体之间的细微接触已经够用。6.2 按轮廓的 x 坐标排序保证识别顺序和书写顺序一致切分完轮廓后OpenCV 返回的轮廓顺序是随机的直接按顺序预测会得到一串乱序数字。比如你写的是“2019”输出可能变成“9102”。所以切分后立刻排序contours sorted(contours, keylambda c: cv2.boundingRect(c)[0])cv2.boundingRect(c)返回(x, y, w, h)取第 0 位就是轮廓最左边的 x 坐标按它排序后左到右的轮廓次序就和你的书写顺序一致。如果一行里有高低起伏再叠加一个按 y 坐标排序的 pass不过期末项目直接按 x 排序就够。6.3 验证预处理的中间结果不要直接跳过我见过的最后一个高频问题是调了半天参数准确率毫无变化于是开始怀疑算法本身。实际上手写数字识别很少是算法问题而是预处理环节出了问题。我给你一个粗暴又有效的验证习惯在预处理函数里加一行cv2.imwrite(debug.png, binary)跑完直接看这张二值化图——如果图里数字边缘残缺、有大量黑斑说明阈值或模糊参数不对如果数字清晰居中再去怀疑模型。这个方法帮我排查过至少五次“玄学准确率波动”现在成了我的固定动作。做这个项目我反复养成的习惯是不急着改算法先验证每一层的输入输出是否正常不急着跑全量数据先跑通一张图的最小样例。这套思路在手写数字识别上帮我省下过几个晚上的 debug 时间最后说一句——文档里永远诚实标注你试过但失败的方向那才是老师真正看得上的实验记录。希望帮到你。本文还有配套的精品资源点击获取
