简介：这是一份面向FPGA开发者与计算机视觉学习者的双目视觉硬件实现代码包，基于Verilog语言构建，覆盖从图像采集到深度计算的全流程。内容涉及图像采集接口、相机标定参数查询、特征匹配、半全局匹配（SGM）立体匹配、视差转深度及后处理、串行与并行接口输出等核心模块，适合机器人导航、自动驾驶、无人机避障等对实时性要求较高的场景，也适合作为课程设计或竞赛项目的参考实现。压缩包共151个文件，约5.77MB，以vho、vhd等Verilog与VHDL源码为主，辅以obj、prj、xmsgs等工程与综合文件，以及cpp、h等上位机串口通信代码，另含bit、ncd、pdf等烧录与说明资料，结构完整。目前已有634人学习下载。读者可借此理解双目视觉在FPGA上的流水线设计与并行加速思路，掌握各模块的硬件实现方式与工程组织方法，为自主搭建实时立体视觉系统提供可复用的代码基础与排错参考。
1. 双目视觉FPGA代码：从「跑通」到「跑稳」的工程路径
双目视觉FPGA代码，核心就一件事：把左右两路图像在硬件里对齐、匹配、算出视差，最终输出深度。很多人第一次接触这个方向，以为难点在算法，实际落地才发现，真正的坑在时序、带宽和资源三者的拉扯。我见过太多团队在PC上把SGM跑得漂漂亮亮，一上FPGA就翻车——不是帧率掉到个位数，就是BRAM爆掉，再不然就是左右图对不齐导致视差图全是噪点。这篇笔记面向两类人：一是刚拿到开发板、想把双目视觉FPGA代码跑通的新手；二是已经在做但卡在某个环节、想看看别人怎么设参数的老手。我会按「先立住理论、再动手复现、最后避坑」的顺序，把这条链路拆开讲清楚。你不需要有现成的源码包，跟着思路和参数走，就能在自己的板子上搭出可用的版本。
2. 双目视觉FPGA代码的算法选型与硬件映射
2.1 为什么SGM是FPGA上的主流选择
双目视觉的匹配算法大致分三类：块匹配（BM）、半全局匹配（SGM）、全局匹配（如图割）。BM在FPGA上最容易实现，资源占用小，但视差图在弱纹理区域碎得厉害，后处理代价高。全局匹配效果好，但迭代求解不适合流水线硬件。SGM处在中间：它用多方向一维代价聚合近似二维全局优化，既能流水线化，又能拿到比BM好得多的视差图。常见做法是选4方向或8方向聚合，FPGA上4方向已经能覆盖大部分场景，8方向资源翻倍但提升有限。
选SGM还有一个工程原因：它的参数和中间结果都是可观测的。代价计算、聚合、视差选择、后处理，每一级都能单独抓出来看波形或存图验证。这对调试至关重要——你不可能在硬件里单步，只能靠分级验证。
2.2 从C模型到RTL的映射步骤
直接写RTL容易失控，我一般先搭一个C/C++参考模型，把算法跑通并确定所有参数，再逐级映射到硬件。步骤如下：
第一步，用OpenCV或自写C代码实现SGM，输入左右图，输出视差图。这一步确定视差范围、代价函数、聚合路径数、惩罚系数。
第二步，把C模型拆成硬件友好的流水级：代价计算→代价聚合→视差选择→后处理。每一级的数据流和控制流要明确。
第三步，为每一级设计接口和缓存。代价计算需要左右图窗口，聚合需要行缓存和方向缓存，视差选择需要代价缓存。
第四步，写RTL并用仿真对比C模型输出。逐级对比，不要等全链路搭完再调。
下面是一个C参考模型的核心片段，用于确定参数：
// 简化SGM C参考模型：代价计算 + 4方向聚合 // 输入：左图left[H][W]，右图right[H][W]，视差范围D // 输出：视差图disp[H][W] #define PENALTY1 10 // 小惩罚，视差连续变化 #define PENALTY2 60 // 大惩罚，视差跳变 #define D 64 // 视差搜索范围 void cost_compute(uint8_t left[H][W], uint8_t right[H][W], uint16_t cost[H][W][D]) { for (int y = 0; y < H; y++) for (int x = 0; x < W; x++) for (int d = 0; d < D; d++) { int xr = x - d; if (xr < 0) { cost[y][x][d] = 65535; continue; } // 绝对差作为代价，可换成Census或AD-Census cost[y][x][d] = abs(left[y][x] - right[y][xr]); } } void aggregate_4dir(uint16_t cost[H][W][D], uint16_t agg[H][W][D]) { // 方向1：从左到右 for (int y = 0; y < H; y++) for (int x = 0; x < W; x++) for (int d = 0; d < D; d++) { uint16_t min_prev = 65535; if (x == 0) { agg[y][x][d] = cost[y][x][d]; continue; } for (int dp = 0; dp < D; dp++) { uint16_t penalty = (abs(d - dp) == 1) ? PENALTY1 : (abs(d - dp) > 1) ? PENALTY2 : 0; uint16_t v = agg[y][x-1][dp] + penalty; if (v < min_prev) min_prev = v; } agg[y][x][d] = cost[y][x][d] + min_prev - (min_prev > 0 ? 0 : 0); // 简化，实际需减最小值防溢出 } // 方向2、3、4类似，分别从右到左、从上到下、从下到上 }这段代码的关键参数是PENALTY1和PENALTY2。PENALTY1控制视差在小范围内连续变化的代价，太小会导致视差图噪声大，太大会让斜面变成阶梯。PENALTY2控制视差跳变的代价，太小会让前景背景混在一起，太大则无法处理真实跳变。经验值：8位灰度图，PENALTY1取8~15，PENALTY2取40~80。视差范围D根据基线、焦距和最近探测距离算，常见64或128。
2.3 硬件映射时的资源估算
在写RTL前，先估算BRAM和DSP用量。以1280x720、视差64为例：
- 代价计算：需要左右图行缓存，每行1280像素，8位，约2.5KB。Census变换需要窗口，额外几行缓存。
- 代价聚合：4方向聚合，每个方向需要保存上一行或上一列的聚合代价。代价位宽通常16位，视差64，则每像素128字节。一行1280像素就是160KB，4个方向如果并行需要多份，但可以分时复用。
- 视差选择：需要当前像素所有视差的聚合代价，128字节，可放在寄存器或小BRAM。
总BRAM需求很容易超过芯片容量。常见做法是降分辨率、降视差范围，或者用行分块处理，一次只处理若干行。我一般先按640x480、视差64做原型，跑通后再扩。
3. 在FPGA上跑通双目视觉代码的最小系统
3.1 搭建仿真验证环境
不要一上来就上板。先搭一个纯仿真的testbench，用C模型生成的左右图作为输入，把RTL输出和C模型输出逐像素对比。工具用Verilator或商业仿真器都行。关键是要有自动对比脚本，每次改RTL都能快速回归。
# 用Verilator编译并运行testbench的示例命令 verilator --cc --exe --build -j 4 \ -Irtl/ \ rtl/top.sv \ tb/tb_top.cpp \ -o sim_top ./obj_dir/sim_top +left=left.pgm +right=right.pgm +disp=disp_out.pgm这个命令把RTL和C++ testbench一起编译。+left和+right传入左右图，+disp输出视差图。testbench里读PGM文件，按像素时钟送入，收集输出写文件。逻辑说明：Verilator把SystemVerilog转成C++，testbench用C++写激励和比对，速度比传统仿真器快很多。参数说明：-j 4是并行编译线程数，--cc生成C++模型，--exe生成可执行文件，--build自动调用make。
3.2 图像输入输出的接口设计
双目视觉FPGA代码的输入通常是两路摄像头或两路DDR读出的图像。最小系统可以用两个FIFO模拟图像源，testbench往FIFO里写，RTL从FIFO里读。输出视差图可以写回FIFO或直接存BRAM，testbench再读出。
接口时序要明确：像素时钟、行有效、帧有效。左右图必须同步，否则匹配全错。常见做法是用同一个像素时钟，左右图各一个FIFO，读的时候同时读。如果左右图来自不同传感器，需要先做同步，比如用帧同步信号对齐。
// 左右图同步读取的简化逻辑 module stereo_sync ( input logic clk, input logic rst_n, input logic left_valid, input logic right_valid, output logic left_rd, output logic right_rd ); // 只有左右都有效时才同时读，保证对齐 assign left_rd = left_valid & right_valid; assign right_rd = left_valid & right_valid; endmodule这段逻辑很简单，但实际中左右传感器的有效信号可能不同步。如果不同步，需要加FIFO做弹性缓冲，或者用帧同步信号强制对齐。我一般会在FIFO前加一个小的异步FIFO，深度不用大，几行即可，用来吸收左右路的微小延迟差。
3.3 上板调试：从ILA抓波形到存图验证
仿真通过后，上板。第一步不是看视差图，而是用ILA抓关键信号：左右图有效、代价计算输出、聚合输出、视差输出。先确认时序对齐，再确认数据合理。
常见做法是加一个BRAM抓取一帧视差图，通过UART或以太网传到PC存成PGM。这样能看到实际场景的视差图，比看波形直观。如果视差图全黑或全白，先查视差范围是否设对，再查代价计算是否溢出。
// 用BRAM抓取一帧视差图的简化逻辑 module disp_capture ( input logic clk, input logic rst_n, input logic disp_valid, input logic [5:0] disp, output logic [5:0] bram_data, output logic [18:0] bram_addr, output logic bram_we ); logic [18:0] addr_cnt; always_ff @(posedge clk or negedge rst_n) begin if (!rst_n) begin addr_cnt <= 0; bram_we <= 0; end else if (disp_valid) begin bram_addr <= addr_cnt; bram_data <= disp; bram_we <= 1; addr_cnt <= addr_cnt + 1; end else begin bram_we <= 0; end end endmodule这段逻辑把有效视差按顺序写入BRAM。addr_cnt是地址计数器，disp_valid是视差有效信号。注意BRAM深度要够存一帧，640x480需要307200个地址，19位地址够用。抓完后通过UART读出来，PC端脚本转成PGM。
4. 双目视觉FPGA代码的避坑与排查
4.1 视差图全是噪点或空洞
现象：视差图看起来像雪花，或者大片空洞。原因通常是代价计算或聚合的参数不对。先查PENALTY1和PENALTY2，如果PENALTY1太小，噪声会被放大；如果PENALTY2太大，弱纹理区域无法聚合出正确视差。解决：用标准数据集（如Middlebury）调参，先保证C模型输出正常，再对比RTL。另一个原因是左右图未对齐，检查同步逻辑和FIFO延迟。
4.2 资源爆掉，布局布线失败
现象：综合后BRAM或DSP超过芯片容量，布局布线报错。原因通常是代价缓存太大。解决：降分辨率、降视差范围、分时复用聚合方向。我一般先把视差降到32，分辨率降到640x480，跑通后再逐步加。另一个技巧是用8位代价代替16位，但要注意溢出。
4.3 帧率远低于预期
现象：仿真通过，上板后帧率只有几帧。原因通常是关键路径太长，时钟频率上不去。解决：在代价聚合和视差选择之间加流水线寄存器，把长组合逻辑切开。用时序报告找关键路径，针对性优化。常见做法是把聚合的min操作树拆成两级。
4.4 左右图对齐但视差偏移
现象：视差图整体偏移一个固定值。原因通常是视差计算时的坐标偏移没算对。检查代价计算中右图坐标xr = x - d，如果xr越界处理不对，会导致偏移。解决：在C模型和RTL中统一越界处理逻辑，越界时代价设最大值。
4.5 上板后图像闪烁或撕裂
现象：视差图部分区域闪烁或撕裂。原因通常是BRAM读写冲突或时钟域交叉。解决：检查BRAM是否用了双端口，读写是否在不同时钟域。如果跨时钟域，加异步FIFO。另外，抓图BRAM的写使能要和视差有效严格对齐，避免写错地址。
5. 把双目视觉FPGA代码推到可交付的几个技巧
5.1 用参数化设计覆盖不同分辨率
不要硬编码分辨率和视差范围。用parameter定义IMG_WIDTH、IMG_HEIGHT、DISP_RANGE，在综合时传入。这样一套代码可以跑640x480和1280x720，只需改参数和约束。注意BRAM深度也要参数化，用$clog2算地址位宽。
module stereo_top #( parameter IMG_WIDTH = 640, parameter IMG_HEIGHT = 480, parameter DISP_RANGE = 64, parameter COST_WIDTH = 16 ) ( // 端口省略 ); localparam ADDR_WIDTH = $clog2(IMG_WIDTH * IMG_HEIGHT); // 内部逻辑使用参数 endmodule参数说明：IMG_WIDTH和IMG_HEIGHT决定图像尺寸，DISP_RANGE决定视差搜索范围，COST_WIDTH决定代价位宽。ADDR_WIDTH自动计算抓图BRAM的地址位宽。这样改分辨率时只需改例化参数，不用动内部逻辑。
5.2 分级验证：C模型→RTL仿真→上板抓图
每一级都要有自动对比。C模型输出作为黄金参考，RTL仿真输出逐像素对比，上板抓图再和仿真对比。三级一致才算通过。我一般写一个Python脚本，读PGM文件，算均方误差和坏点率。坏点率超过5%就要查。
import numpy as np def compare_disp(ref_path, test_path): ref = np.loadtxt(ref_path, dtype=np.uint8) test = np.loadtxt(test_path, dtype=np.uint8) valid = ref > 0 mse = np.mean((ref[valid].astype(float) - test[valid].astype(float)) ** 2) bad = np.sum(np.abs(ref[valid].astype(int) - test[valid].astype(int)) > 2) bad_rate = bad / np.sum(valid) print(f"MSE: {mse:.2f}, BadRate: {bad_rate:.4f}") return mse, bad_rate这个脚本读两个视差图，算有效区域的均方误差和坏点率。valid排除无效视差（通常为0）。坏点率阈值一般设0.05，超过就要查。参数说明：>2是坏点判定阈值，可视精度要求调整。
5.3 时序收敛的实用手段
时序收敛是双目视觉FPGA代码上板的最后一关。常用手段：加流水线寄存器、降低时钟频率、优化组合逻辑。我一般先看时序报告，找WNS最差的路徑，然后在中间插寄存器。代价聚合的min树是常见关键路径，可以拆成两级：先算局部min，再算全局min。另外，BRAM输出自带寄存器，可以打拍改善时序。
5.4 一个我常犯的教训
早期做双目视觉FPGA代码时，我总想一次把8方向聚合全塞进去，结果BRAM爆了，布局布线跑了几个小时还失败。后来改成先做4方向，跑通后再评估是否加方向。另一个教训是忽略左右图同步，仿真时用理想数据没问题，上板后左右路延迟差几个像素，视差图直接废掉。现在我会在FIFO前加异步缓冲，并用ILA确认左右有效信号的对齐关系。这些血泪经验归结成一句话：先跑通最小闭环，再逐步加复杂度。希望帮到你。
本文还有配套的精品资源，点击获取
