# (纯C语言)神经网络手写数字识别 **Repository Path**: li_ximing/CNNhandWritenRecognition ## Basic Information - **Project Name**: (纯C语言)神经网络手写数字识别 - **Description**: (纯C语言)神经网络手写数字识别, 训练代码,以及测试代码,仅用于学习。数据集使用MNIST数据集全部数据。 不依赖任何深度学习框架,以C语言源代码方式实现多层神经网络的训练以及测试。 可以帮助在低成本上物联网设备上实现人工智能算法的部署。 - **Primary Language**: C - **License**: GPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 8 - **Forks**: 3 - **Created**: 2024-10-10 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CNN 手写数字识别 纯 C 语言实现的卷积神经网络手写数字识别项目。配套 PyTorch 实现用于对比验证。 ## 项目文件 | 文件 | 说明 | | --- | --- | | **核心 C 程序** | | | `TrainHWRCNN_new.c` | C 训练主程序(修复 BMP 填充 bug 的版本),负责训练流程编排(main) | | `cnn.h` | 公共头文件:常量、结构体(parameter/gradient/velocity/result/sample)与模块接口声明 | | `dataset.c` | BMP 图片加载、标签解析、训练集文件收集与训练集构建 | | `layers.c` | 基础算子:卷积、ReLU、双通道展平拼接、矩阵乘法 | | `forward.c` | 前向传播(双通道卷积 + 全连接 + Softmax) | | `backward.c` | 反向传播(16 步链式求导) | | `optimizer.c` | He 初始化与 SGD + Momentum 参数更新 | | `model_io.c` | 参数文件二进制保存 | | `evaluate.c` | 测试集准确率评估 | | `visualize.c` / `visualize.h` | 训练过程可视化帧导出(每层中间值、卷积核、权重直方图、训练指标) | | `web/` | 可视化 Web 服务:`app.py`(Flask + SSE)与 `static/`(Canvas 热力图前端) | | `TrainHWRCNN.c` | C 训练程序(旧版,含 BMP 填充 bug,仅供对比参考) | | `VerificationHWRCNN.c` | 验证程序,加载训练好的参数对测试集进行全量验证(顺序遍历所有图片) | | `Vonepic.c` | 单张图片识别程序,输入 BMP 文件路径输出识别结果 | | `diagnostic_compare.c` | 诊断对比程序,逐层对比两个程序的 forward 输出,用于定位精度差异根源 | | **PyTorch 训练与转换** | | | `TrainHWRCNN_PyTorch.py` | PyTorch 训练代码,定义 `DualCNN` 模型(结构与 C 实现一致),训练后保存二进制参数文件 | | `convert_to_bin.py` | PyTorch → C 参数转换脚本,将权重导出为 C 可加载的二进制参数文件 | | `debug_compare.py` | PyTorch 与 C 推理逐层对比脚本 | | `check_params.py` | 参数文件检查工具 | | **网络结构可视化** | | | `vis_torchviz.py` | 使用 torchviz 绘制网络计算图 | | `vis_torchinfo.py` | 使用 torchinfo 打印网络各层参数统计 | | `vis_paper_diagram.py` | 论文风格网络结构示意图 | | **编译脚本** | | | `compile.bat` | 批处理编译脚本 | | **参数文件** | | | `network_parameter.txt` | 当前使用的二进制参数文件(1729640 字节) | | `network_parameter_best.txt` | 最优模型参数文件 | | `model_weights.pt` | PyTorch 保存的模型权重 | | `model_weights_best.pt` | PyTorch 最优模型权重 | ## 数据集 基于 MNIST 手写数字数据集: - **C 训练程序**:每类数字 3000 张,共 **30,000** 张训练集 - **PyTorch 训练程序**:每类数字 5421 张,共 **54,210** 张训练集 - **测试集**:MNIST 标准测试集 **10,000** 张 - **训练时自动排除 `Training_set/Test_set` 目录**,避免测试集参与训练造成数据泄漏 - 图片尺寸统一处理为 **30×30** 单通道灰度图,BMP 格式 ## 网络架构 ### 结构总览 ``` 输入图像 (30×30) │ ├── 通道一 ────────────────────────────┐ │ │ │ │ ├─ Conv1_1: 3×3 kernel ─→ 28×28 │ │ ├─ Conv2_1: 3×3 kernel ─→ 26×26 │ │ └─ Conv3_1: 3×3 kernel ─→ 24×24 │ │ │ └── 通道二 ────────────────────────────┤ │ │ ├─ Conv1_2: 3×3 kernel ─→ 28×28 │ ├─ Conv2_2: 3×3 kernel ─→ 26×26 │ └─ Conv3_2: 3×3 kernel ─→ 24×24 │ │ 展平 + 拼接 ───────────────────────── 1152 维 │ ├─ FC1: 1152 → 180 (+ ReLU) ├─ FC2: 180 → 45 (+ ReLU) └─ FC3: 45 → 10 (logits) │ Softmax → 10 类概率 ``` ### 各层详情 | 层 | 输入 | 输出 | 参数量 | | --- | --- | --- | --- | | Conv1\_1 (3×3) | 30×30 | 28×28 | 9 | | Conv1\_2 (3×3) | 30×30 | 28×28 | 9 | | Conv2\_1 (3×3) | 28×28 | 26×26 | 9 | | Conv2\_2 (3×3) | 28×28 | 26×26 | 9 | | Conv3\_1 (3×3) | 26×26 | 24×24 | 9 | | Conv3\_2 (3×3) | 26×26 | 24×24 | 9 | | Flatten + Concat | 24×24 × 2 | 1152 | 0 | | FC1 | 1152 | 180 | 207,360 | | FC2 | 180 | 45 | 8,100 | | FC3 | 45 | 10 | 450 | | Softmax | 10 | 10 | 0 | **总参数量**: ~216K ### 设计特点 - **无池化层**:尺寸缩减完全依靠 valid 卷积的边界效应(每层 -2) - **双通道并行**:两个独立的卷积通道,输出拼接后送入全连接 - **三层全连接**:使用 ReLU 激活函数 - **Softmax 输出**:将 logits 归一化为 10 类概率 ## 性能优化 本项目经过系统性优化,在保持纯 C 实现的前提下大幅提升训练和推理效率。 ### 架构级优化 | 优化项 | 说明 | 效果 | | --- | --- | --- | | 学习率衰减 | `lr = 0.01 / (1 + 0.0001 × epoch)` | 随训练轮次缓慢衰减 | | 交叉熵数值稳定性 | 损失计算为 `-log(p + 1e-15)`,防止 `log(0) → -inf` | 消除 NaN 传播 | | Softmax 数值稳定性 | 减去最大值后计算 exp,缓存 exp 值避免重复计算 | 防止 exp 溢出,减少 50% exp 调用 | | 梯度缓冲复用 | 反向传播直接累加到预分配的梯度结构体,无逐样本临时分配与拷贝 | 消除逐样本 1.7MB 的梯度清零与拷贝开销 | ### 计算优化 | 优化项 | 说明 | 效果 | | --- | --- | --- | | Conv2d 3×3 核展开 | 3×3 卷积内层两重循环直接展开为 9 条赋值语句 | 消除循环分支判断 | | 矩阵乘法循环交换 | `for(j){for(k)}` → `for(k){for(j)}`,使参数矩阵顺序访存 | 提高 CPU 缓存命中率 | | DataLoader 内存优化 | 内层循环 20000 次 malloc/free → 栈变量 | 数据加载阶段加速 | | MatrixExtensionImproved 合并 | 两个 24×24 双重循环合为一个 | 减少循环开销 | | 读/写参数去临时malloc | 消除 ~1.9MB 临时结构体分配和拷贝 | 参数读取/保存加速 | ### 验证推理优化 | 优化项 | 说明 | 效果 | | --- | --- | --- | | 目录预扫描 | 一次扫描收集所有 BMP 文件路径,消除每张图片都遍历目录树 | 理论加速 ~1000× | | 顺序遍历 | 改为按文件列表顺序遍历而非随机抽样,利用 CPU 缓存局部性 | 推理速度提升 5.6 倍 | | 日志精简 | 只在最终输出汇总结果,不逐张打印 | 减少 IO 开销 | ## 运行结果 ### C 模型训练收敛曲线(实际完成 6/50 epochs,因验证中断) | Epoch | Loss | 准确率 | 学习率 | | --- | --- | --- | --- | | 1 | 0.1815 | 87.82% | 0.01000 | | 2 | 0.0881 | 98.00% | 0.00999 | | 3 | 0.0608 | 99.00% | 0.00998 | | 4 | 0.0472 | 98.99% | 0.00997 | | 5 | 0.0385 | 99.40% | 0.00996 | | 6 | 0.0321 | 99.40% | 0.00995 | **训练配置**:SGD + Momentum(0.9),LR=0.01(按 `lr = 0.01/(1+0.0001×epoch)` 缓慢衰减),Batch=32,He 初始化,无正则化 ### PyTorch 模型训练收敛曲线(100 epochs) | Epoch | Loss | 准确率 | 学习率 | | --- | --- | --- | --- | | 22 | 0.5677 | 98.65% | 0.00912 | | 25 | 0.5276 | 98.72% | 0.00881 | | 43 | 0.5136 | 98.78% | 0.00576 | | 65 | 0.5096 | **98.80%** | 0.00234 | | 100 | 0.5077 | 98.68% | 0.00005 | **训练配置**:SGD + Momentum(0.9),Batch=128,余弦退火 + Warmup,Dropout(0.1) + LabelSmoothing(0.1) + WeightDecay(0.0005) ### 验证准确率对比 全量 10000 张 MNIST 测试集: | 模型 | 准确率 | 参数量 | 训练集大小 | 正则化 | | --- | --- | --- | --- | --- | | **C 模型** | **99.40%** | ~216K | 30,000 | 无 | | **PyTorch** | **98.80%** | ~216K | 54,210 | Dropout + LabelSmooth + WeightDecay | ### 推理性能 | 指标 | 值 | | --- | --- | | 全量推理时间(10000 张) | ~3323 ms | | 单张推理时间(平均) | ~0.33 ms | | 推理方式 | 顺序遍历(缓存友好) | ## BMP 填充 Bug 修复 ### 问题描述 在 BMP 格式中,每行数据必须按 4 字节对齐。对于 30×30 的 1 位色图,每行 30 位,需补齐到 32 位(4 字节),末尾 2 位为 padding。训练程序 `TrainHWRCNN.c` 的 `load_bmp_as_double()` 函数错误地将内层循环设为 `col < IMG_SIZE`(=30),导致每行末尾的 2 个 padding 位从未被跳过,从第 2 行开始所有像素偏移 2 个位置。 ### 影响 - 训练时的像素数据与验证程序不一致 - 模型在错误数据上训练,准确率仅 **22.2%** - 修复后准确率提升至 **99.4%** ### 修复 在 `TrainHWRCNN_new.c` 中,将内层循环从 `col < IMG_SIZE` 改为 `col < 32`,增加 `col >= IMG_SIZE` 分支跳过 padding 字节。 ## 运行方法 ### 环境要求 - GCC 编译器(项目自带 `mingw-w64\mingw64\bin\gcc.exe`) - 仅支持 Windows - Python 3.8+(PyTorch 训练,可选) ### 编译 ```bash set PATH=C:\hanwrittingR\mingw-w64\mingw64\bin;%PATH% gcc TrainHWRCNN_new.c dataset.c layers.c forward.c backward.c optimizer.c model_io.c evaluate.c visualize.c -o TrainHWRCNN_new.exe -lm -Wl,--stack=83886080 gcc VerificationHWRCNN.c -o VerificationHWRCNN.exe -lm -Wl,--stack=83886080 gcc Vonepic.c -o Vonepic.exe -lm ``` 或直接运行: ```bash compile.bat ``` ### 训练 ```bash TrainHWRCNN_new.exe ``` 使用 SGD + Momentum 优化器,自动在每轮结束后验证准确率,保存最优参数。 ### 验证 ```bash VerificationHWRCNN.exe ``` 验证程序会: 1. 自动加载 `network_parameter.txt` 参数文件 2. 遍历 `Training_set/Test_set` 目录下所有 BMP 文件 3. 顺序遍历全量 10000 张图片进行推理 4. 输出准确率、总推理时间、平均单张推理时间 ### 单图识别 ```bash Vonepic.exe ``` 按提示输入 BMP 文件路径。 ### PyTorch 训练 ```bash python TrainHWRCNN_PyTorch.py ``` 训练完成后参数自动保存为 `network_parameter.txt`,可直接被 C 验证程序加载。 ## 训练过程实时可视化(2.5D) 训练时把每层网络的中间值实时画成热力图,边训练边在浏览器里看。 主视图是 **2.5D 透视场景**:整张网络拆成前后两块,各自站在一块发光底板上。 ![训练可视化界面](训练可视化界面.jpg) **原理**:`visualize.c` 在训练循环里把当前样本的 `struct result`(各层特征图)、 卷积核权重、权重直方图和 loss/acc 指标写成二进制帧 (`visualize/frames/*.bin`,约 57KB/帧)和一个几十字节的索引 `visualize/current.json`; `web/app.py` 轮询索引,发现帧号变化才去读帧并推给浏览器。 曲线数据另存 `visualize/metrics.csv`,所以帧被轮转删除后损失/准确率曲线仍然完整。 可视化只读取 `struct parameter` / `struct result`,**不参与任何计算,不影响训练结果**。 ### 启动 1. 训练程序(会自动创建 `visualize/` 目录并导出帧) ```bash TrainHWRCNN_new.exe ``` 2. Web 服务(另开一个终端) ```bash cd web pip install -r requirements.txt python app.py ``` 3. 浏览器打开 ### 场景内容 | 区域 | 内容 | | --- | --- | | 卷积区(前台,低处) | input 30×30 → 通道一/通道二两条平行轨道,各 Conv1 28² / Conv2 26² / Conv3 24² 热力图 | | 卷积核贴片 | 6 个 3×3 核悬在对应两层的连线中点(蓝-白-红双向色标,训练中逐渐分化) | | 全连接区(后台,高处) | flatten 1152 → FC1 180 → FC2 45 → FC3 10(10 根 3D 立柱,柱高 ∝ √概率) | | 屏幕空间标签 | 每层名称、两块区块标题、输出层 0–9 刻度(不受 3D 缩放影响,始终清晰) | | 数据流连线 | 层与层之间的虚线 + 流动光点,遇到卷积核贴片自动断开让位 | | 左栏 | 输入样本原图 + 真实/预测/判定 + Softmax 概率条 | | 底部 | 训练曲线(对数 loss + 验证准确率)、4 组权重直方图 | | 回放条 | 拖动滑块回放历史帧 | ### 交互 | 操作 | 行为 | | --- | --- | | 拖拽舞台 | 绕 Y 轴 ±58°、X 轴 -40°~-4° 旋转 | | 滚轮 | 0.2×~2.6× 缩放 | | 点击某层 | 该层放大前移、其余淡化,右上角显示形状 / 最小 / 最大 / 均值 / 最大激活位置 | | `Esc` / 点击空白 | 退出聚焦 | | `←` / `→` | 在层之间切换聚焦 | | 双击 | 复位视角 | | 「正视」按钮 | 切换为无透视的正视布局(两块分上下两行,适合逐个核对数值) | 取景是自适应的:相机按内容包围盒迭代拟合,任意窗口尺寸下都不会裁切。 ### 反向传播演示 点右上角「反向传播」进入演示模式: ![反向传播演示](反向传播演示.jpg) - 场景里 10 个层**同时显示梯度热力图**(蓝-白-红双向色标:负梯度蓝、正梯度红,按每层 max|g| 独立归一化) - 底部演示条按回传顺序列出 **10 个停靠点**,可点击跳转、单步、或自动播放(0.9 s/步) - 当前层的平面会被琥珀色描边高亮,上方给出该步的链式法则 - FC3 立柱高度切换为 |∂L/∂z₃|,负梯度染蓝 - 6 个卷积核贴片从"权重 k"切换为"权重梯度 ∂L/∂k"(3×3 双向色标),走到对应层时该贴片高亮 停靠点顺序:FC3 输出 → FC2 输出 → FC1 输出 → 展平向量 → 通道一/二 Conv3 → 通道一/二 Conv2 → 通道一/二 Conv1。 轨迹来源 `visualize/bp/bp_XXXXXX.bin`(64 字节头 + 输入图 900 + 10 段激活梯度 + 6 个卷积核梯度 54,共 51368 字节),每 `VIS_BP_EVERY`(默认 2048)个样本一份,最多保留 90 份。 ### 可调参数 | 环境变量 / 宏 | 默认 | 说明 | | --- | --- | --- | | `VIS_FRAME_EVERY` | 128 | 每多少个样本导出一帧(调小刷新更快、磁盘占用更大) | | `VIS_MAX_FRAMES` | 800 | 最多保留多少历史帧,超出删最旧的(约 45MB) | | `VIS_BP_EVERY` | 2048 | 每多少个样本留一份反向传播轨迹(`visualize/bp/`,每份约 50KB,最多 90 份) | | `VIS_ENABLE` | 1 | 编译时 `-DVIS_ENABLE=0` 可彻底关闭可视化 | | `VIS_ROOT` | 项目根目录 | Web 服务的数据目录,训练在别处运行时用它指向训练工作目录 | 不需要可视化时,编译命令去掉 `visualize.c` 并加 `-DVIS_ENABLE=0` 即可,训练行为完全不变。 前端文件:`web/static/index.html`(结构)、`style.css`(2.5D 样式)、`scene.js`(场景/相机/连线)、`draw.js`(绘制函数)、`app.js`(数据与 HUD)。 ## 诊断工具 ```bash # 编译诊断程序 gcc diagnostic_compare.c -o diagnostic_compare.exe -lm -Wl,--stack=83886080 # 运行诊断(对比验证程序与训练程序对同一张图的输出) diagnostic_compare.exe ``` 逐层比较两个程序的 forward 输出,用于定位: - BMP 加载差异 - 前向传播计算差异 - 参数加载差异 ## 数据集准备 解压数据到代码目录,目录结构如下: ``` Training_set/ ├── 0/ (数字 0 的图片) ├── 1/ (数字 1 的图片) ├── ... ├── 9/ (数字 9 的图片) └── Test_set/ ├── 0/ ├── 1/ ├── ... └── 9/ ``` 每个子目录下为 `0.bmp`, `1.bmp`, ... 格式的 BMP 文件。 ## 主要修改记录 | 文件 | 修改内容 | | --- | --- | | `TrainHWRCNN_new.c` | 修复 BMP 加载每行末尾 2 字节填充未跳过的 bug;每轮验证准确率;切换控制台编码修复中文乱码 | | 纯 C 训练程序 | 由单文件 `TrainHWRCNN_new.c` 按功能拆分为 `cnn.h` + 7 个 `.c` 模块(dataset / layers / forward / backward / optimizer / model_io / evaluate),训练主流程保留在 `TrainHWRCNN_new.c` | | 纯 C 训练程序(修复) | 训练集不再递归包含 `Test_set`(修复数据泄漏);结尾保存最优轮参数而非最后一轮;特征图改为一维数组消除越界访问;梯度改为直接累加到批次缓冲;同步学习率等文档描述 | | `TrainHWRCNN_PyTorch.py` | 优化器由 Adam 改为 SGD + Momentum,学习率调至 0.01 以匹配 C 训练配置 | | `VerificationHWRCNN.c` | 验证推理由随机抽样改为顺序遍历全量图片;切换控制台编码修复中文乱码 | | `diagnostic_compare.c` | 新增诊断程序,用于逐层对比两个 C 程序的 forward 输出;修复 BMP 填充 bug | | `README.md` | 补充 BMP 填充 bug 修复说明、更新训练/验证结果 | ## 参考文献 1. [Conv_factor / 基于C语言构建CNN的手写数字识别](https://gitee.com/conv-factor/Handwritten-number-recognition) 2. [基于CNN的手写数字识别](https://github.com/IammyselfYBX/Handwritten-digit-recognition-based-on-CNN)