简介：双目视觉立体标定与校正代码opencv面向正在学习计算机视觉、需要搭建双目相机实验环境的开发者与在校学生，围绕相机内参、外参估计与图像去畸变、极线校正这一常见难点提供可运行的参考。压缩包内仅1个doc文档，约294KB，以源码分析与关键函数讲解为主，重点梳理stereoCalibrate、undistort、stereoRectify等接口的调用顺序与参数含义，并附棋盘格角点提取、标定结果保存等实现细节。文档节选自Learning OpenCV示例，保留了原始授权说明与StereoCalib函数的完整逻辑，便于读者对照自己的图像列表逐步调试。已有2595人学习下载，适合具备一定OpenCV基础的读者用作立体标定流程的入门参考，也可在排查校正结果异常时提供思路对照。
1. 双目立体标定这件事，先跑通再谈精度
拿到一份 OpenCV 双目视觉立体标定与校正的源码，绝大多数人的第一反应是改两个参数直接跑，结果卡在终端打出来的avg err常年几十像素、校正后的视差图一片噪点。这份代码的核心就是一个 C 风格的StereoCalib函数：读一份棋盘格图片清单、找角点、做立体标定、用极线几何自检、再做立体校正和 BM stereo 视差，全流程在一个文件里跑完，中间不依赖任何第三方标定工具。它适合已经摸过摄像头、想把「标定到校正」这条链路彻底吃透的开发者，尤其是要拿它当基线去改自己工位双目模组的同学——代码不长，但每个函数调用背后都是一环扣一环的几何约束，缺一环就是满屏玄学。下面按工程骨架、标定核心、校正与视差、避坑、改造五段拆开讲。
2. 工程骨架与数据流：从图片清单到 StereoCalib 的一次完整流转
这份代码的体量很小，一个源文件加一份文本清单就能跑，但它把双目标定里最容易散的几个部分——图像清单、角点容器、物点像点矩阵、内外参矩阵——全部压在一个函数栈里完成。理解它最好的方式不是从上往下读，而是跟着数据走一遍：清单文件里的一行路径，经过cvLoadImage变成灰度图，经过角点检测变成CvPoint2D32f，最后被cvMat包成矩阵塞进cvStereoCalibrate。这条链路上每一站的容器布局都不同，改错一个维度，后面全是血泪经验。
2.1 图像清单与目录约定：一份 txt 撑起整条链路
这个工程不扫目录、不做文件名排序，而是老老实实读一份纯文本清单，每行一个图像路径，#开头视为注释直接跳过，末尾空白字符会被裁掉。左右视图严格按行号奇偶交替配对：第 0 行是左、第 1 行是右、第 2 行又是左，以此类推。这种写法看着土，实际上是标定工具里最稳的做法，因为相机采图时很容易出现左右数量不齐、某张图缺失的情况，靠文件名排序反而容易把配对搞错。
for(i=0;;i++) { char buf[1024]; int count = 0, result=0; lr = i % 2; // 偶数行左相机，奇数行右相机 vector<CvPoint2D32f>& pts = points[lr]; if( !fgets( buf, sizeof(buf)-3, f )) // 预留 3 字节给 \r\n\0 break; size_t len = strlen(buf); while( len > 0 && isspace(buf[len-1])) // 去掉行尾换行和空格 buf[--len] = '\0'; if( buf[0] == '#' ) // 注释行跳过，但仍占一个 i，慎用 continue; IplImage* img = cvLoadImage( buf, 0 ); // 第二个参数 0 = 强制灰度 if( !img ) break; imageSize = cvGetSize(img); // 图像尺寸以最后一张为准 imageNames[lr].push_back(buf);这段循环里有两个参数值得盯住。cvLoadImage的第二个参数固定传0，意味着所有图一律以 8 位单通道读入，标定阶段本来也不需要颜色信息，省一次转换。imageSize在循环里被反复覆写，最终取的是清单里最后一张图的尺寸——如果左右相机分辨率不同，或者清单里混进了几张不同尺寸的图，imageSize会是错的，而它后面直接喂给了cvStereoCalibrate和cvInitUndistortRectifyMap，错在这里现象会非常隐蔽。我一般会在这行加一个尺寸一致性断言，图省事的话至少打印一次出来肉眼确认。
还有一个容易被忽略的细节：continue跳过的注释行也占用了i，也就是说在清单里插一行注释会打乱后续的左右配对关系。这份代码的清单文件里没有注释，所以没暴露出来，但这属于典型的「今天能跑、明天换份清单就崩」的坑。
2.2 CvMat 内存布局：那些三行数组到底在装什么
代码往下走，是一整片标量数组的声明，然后挨个用cvMat包成矩阵对象。这是旧版 C 接口的标准写法：数据放在栈上的二维数组里，CvMat只是给这块内存加一个类型和行列数的头，不额外分配。理解这一段的关键是记住每一组数组的维度和类型，后面调cvStereoCalibrate的时候参数顺序全靠它们对齐。
// 内参 3x3，畸变 1x5，旋转 3x3，平移 3x1，本征矩阵 3x3，基础矩阵 3x3 double M1[3][3], M2[3][3], D1[5], D2[5]; double R[3][3], T[3], E[3][3], F[3][3]; CvMat _M1 = cvMat(3, 3, CV_64F, M1); // 左相机内参矩阵 CvMat _M2 = cvMat(3, 3, CV_64F, M2); // 右相机内参矩阵 CvMat _D1 = cvMat(1, 5, CV_64F, D1); // 左畸变系数 k1,k2,p1,p2,k3 CvMat _D2 = cvMat(1, 5, CV_64F, D2); // 右畸变系数 CvMat _R = cvMat(3, 3, CV_64F, R); // 右相机相对左相机的旋转 CvMat _T = cvMat(3, 1, CV_64F, T); // 右相机相对左相机的平移（毫米或格子单位） CvMat _E = cvMat(3, 3, CV_64F, E); // 本征矩阵 E = [T]x * R CvMat _F = cvMat(3, 3, CV_64F, F); // 基础矩阵 F = M2^-T * E * M1^-1cvMat(type, rows, cols, data)的签名是「行、列、类型、数据指针」，类型用CV_64F表示双精度单通道，CV_32F表示单精度，CV_32FC3表示三通道单精度。注意_T声明成3x1而不是1x3，因为后面cvStereoCalibrate输出的平移向量按列存储，方向搞反了有些版本会静默算出错误结果。畸变系数固定按k1,k2,p1,p2,k3顺序存五个，如果实际相机是鱼眼或者有高阶畸变，这个长度要改，同时cvStereoCalibrate内部按矩阵列数读取，改长度是安全的。
这些矩阵在调用前有两个必须做的初始化动作：
cvSetIdentity(&_M1); // 内参初始化为单位阵 cvSetIdentity(&_M2); cvZero(&_D1); // 畸变系数初始化为 0 cvZero(&_D2);内参初始化为单位阵、畸变清零，是因为cvStereoCalibrate在没有指定CV_CALIB_USE_INTRINSIC_GUESS时只用它们作为输出容器，但如果 flag 里带了这个位，就要求传入一个足够准的初值，否则优化会跑飞。这份代码没带这个 flag，所以初始化成单位阵只是兜底，属于「写了也不会错」的防御性代码。
2.3 角点链路：cvFindChessboardCorners 的重试与 cvFindCornerSubPix 的细化
角点提取是整个流程里第一个真正决定成败的环节。代码在每张图上做了两层处理：先用cvFindChessboardCorners定位粗角点，再用cvFindCornerSubPix做到亚像素精度。粗定位外面还套了一个尺度重试循环，用maxScale控制最大放大倍数。
for( int s = 1; s <= maxScale; s++ ) { IplImage* timg = img; if( s > 1 ) { timg = cvCreateImage(cvSize(img->width*s, img->height*s), img->depth, img->nChannels); cvResize( img, timg, CV_INTER_CUBIC ); // 三次插值放大，保边缘 } result = cvFindChessboardCorners( timg, cvSize(nx, ny), &temp[0], &count, CV_CALIB_CB_ADAPTIVE_THRESH | // 自适应阈值 CV_CALIB_CB_NORMALIZE_IMAGE); // 先归一化亮度 if( timg != img ) cvReleaseImage( &timg ); if( result || s == maxScale ) for( j = 0; j < count; j++ ) { temp[j].x /= s; // 放大后得到的坐标要除回去 temp[j].y /= s; } if( result ) break; // 找到就跳出尺度循环 }cvSize(nx, ny)传的是棋盘格的内角点数，不是方格子数。一块 10×7 的黑白格棋盘，内角点是 9×6，这个数错了函数永远返回 0。两个 flag 也值得说：CV_CALIB_CB_ADAPTIVE_THRESH让函数用自适应阈值做二值化，对光照不均的现场图很关键；CV_CALIB_CB_NORMALIZE_IMAGE在二值化之前先做一次直方图均衡，对抗过曝和欠曝。这两个位一起打开，是标定场景下的默认组合。
这份代码里maxScale被写死成1，意味着放大重试那段逻辑实际上是死代码。原作者显然预留了「找不到就放大再找」的意图，但没启用。我的习惯是根据格子像素尺寸来定：格子边长在图像上不足 20 像素时，把maxScale设成 2 甚至 3，重试收益很明显；格子够大的时候设成 1 就行，放大一次计算量翻四倍，不值得。
找到粗角点之后紧接着是亚像素细化，这一步不做的话标定精度会明显掉一个档次：
if( result ) { cvFindCornerSubPix( img, &temp[0], count, cvSize(11, 11), // 搜索窗口半径，11 表示 11x11 邻域 cvSize(-1,-1), // 死区，-1 表示不设死区 cvTermCriteria(CV_TERMCRIT_ITER + CV_TERMCRIT_EPS, 30, 0.01) ); // 最多 30 次，精度 0.01 像素 copy( temp.begin(), temp.end(), pts.begin() + N ); }cvSize(11,11)的搜索窗口适合格子边长在 20~60 像素的场景，格子特别小的时候窗口要跟着缩小，否则邻域内会混进旁边的角点，细化反而把点带偏。cvSize(-1,-1)的死区用来忽略窗口中心区域，一般不改。终止条件里30是最大迭代次数、0.01是亚像素级收敛阈值，这两个数在正常光照下够用；噪声大的工业相机图我一般把 eps 放宽到 0.05 换速度，因为再往下抠 0.01 像素对最终重投影误差已经没有实质贡献。
最后是左右点数对齐的处理，这段逻辑很短但设计意图值得学：
N = pts.size(); pts.resize(N + n, cvPoint2D32f(0,0)); // 无论找到没找到，都补满 n 个点 active[lr].push_back((uchar)result); // 记录这一帧是否成功 if( result ) { cvFindCornerSubPix( img, &temp[0], count, ... ); copy( temp.begin(), temp.end(), pts.begin() + N ); }不管result是 0 还是 1，pts都会被强行扩容n = nx*ny个位置，失败的那一帧就留下n个(0,0)的占位点。这样做的好处是左右两侧的点数组长度永远一致，后面构造_imagePoints1/_imagePoints2时不会因为索引错位而整体崩掉。坏处也很直接——占位点会被当真点喂进标定，active数组虽然记录了成败，但后续代码一次都没用它做过滤，这块就是典型的埋雷，第五章会专门讲怎么把它修掉。
到这里，图像清单被解成了两组二维点、一组active标志、一个imageSize，链路的前半段结束。
3. 立体标定：cvStereoCalibrate 的十四个参数逐个拆
角点齐了，接下来是把左右两侧的二维点喂给cvStereoCalibrate，一次性解出内外参、本征矩阵和基础矩阵。这个函数的参数列表长得吓人，但绝大多数人真正需要改的只有最后那个 flag 组合。把参数按「输入 / 输出 / 控制」三类分开看，逻辑就清楚了。
3.1 物点与像点矩阵怎么组织
调用之前要先构造棋盘格的理想三维点。因为标定板上每个角点的物理位置是已知的，只需按格子间距生成一遍，然后复制nframes份即可。
nframes = active[0].size(); // 以左相机的帧数为准 objectPoints.resize(nframes * n); for( i = 0; i < ny; i++ ) for( j = 0; j < nx; j++ ) objectPoints[i*nx + j] = cvPoint3D32f(i*squareSize, j*squareSize, 0); for( i = 1; i < nframes; i++ ) copy( objectPoints.begin(), objectPoints.begin() + n, objectPoints.begin() + i*n );squareSize在源码里写死成1.f，这是「以格子为单位」的标定，输出的平移向量T也是以格子数的形式给出。要得到真实物理尺寸，把这行改成一个格子的实际边长（毫米）即可，相机内参和畸变不受影响，只有T的尺度会跟着变。这一步改错的人不少，改完之后忘了T的单位也跟着变，算出来的基线长度差了十倍还以为是标定失败。
点序的组织方式有个隐含约束：objectPoints[i*nx + j]的外层循环走ny、内层走nx，而cvFindChessboardCorners返回的角点顺序是逐行从左到右、从上到下，一共ny行每行nx个。两者必须严格对应，否则物点和像点就是错位的。这份代码里把x赋给了i（行方向）、y赋给了j（列方向），相当于坐标系旋转了 90 度，只要左右视图用的都是同一套顺序，标定本身仍然收敛，但输出的R、T是在这个旋转坐标系下表达的，后面接三维重建时方向会拧。规范性做法是把x给列、y给行，跟图像坐标系的直觉一致。
然后是把三组点包成矩阵：
CvMat _objectPoints = cvMat(1, N, CV_32FC3, &objectPoints[0]); // N 个三维物点 CvMat _imagePoints1 = cvMat(1, N, CV_32FC2, &points[0][0]); // 左图 N 个二维像点 CvMat _imagePoints2 = cvMat(1, N, CV_32FC2, &points[1][0]); // 右图 N 个二维像点 CvMat _npoints = cvMat(1, npoints.size(), CV_32S, &npoints[0]); // 每帧点数行数统一写1、列数写N，是因为旧接口对于CV_32FC3这种多通道类型，把「元素个数」放在列位置上，cvMat的 rows/cols 描述的是矩阵的逻辑排布，实际步长由类型通道数决定。_npoints记录每一帧贡献多少个点，这份代码里因为失败的帧也补齐了n个位置，所以它被填成了全n的常量数组，cvStereoCalibrate就不知道哪些点是占位的。
3.2 标定 flag 组合的取舍
真正决定标定结果形态的是最后两位参数。源码用的是三个 flag 相或：
cvStereoCalibrate( &_objectPoints, &_imagePoints1, &_imagePoints2, &_npoints, &_M1, &_D1, &_M2, &_D2, imageSize, &_R, &_T, &_E, &_F, cvTermCriteria(CV_TERMCRIT_ITER + CV_TERMCRIT_EPS, 100, 1e-5), CV_CALIB_FIX_ASPECT_RATIO + CV_CALIB_ZERO_TANGENT_DIST + CV_CALIB_SAME_FOCAL_LENGTH );CV_CALIB_FIX_ASPECT_RATIO把fx/fy锁定，只让一个焦距自由度参与优化，理由是绝大多数工业相机像元是方的，长宽比恒为 1。如果用的是模拟相机或者做过非等比缩放的图像，这个位要摘掉。
CV_CALIB_ZERO_TANGENT_DIST强制切向畸变p1 = p2 = 0。切向畸变来自镜头与传感器平面不平行，装配好的模组通常很小，强制为 0 能显著降低参数间的耦合，让标定更稳。但如果镜头明显歪了（比如手工装的模组），保留这两个自由度反而更准，硬锁会让重投影误差压不下去。
CV_CALIB_SAME_FOCAL_LENGTH要求左右相机焦距相同。同一型号、同一批次的双目模组可以直接用；如果左右是两个不同镜头，这个位必须去掉，否则优化会在错误的约束下强行拉平两组焦距，重投影误差会明显偏高。
最后那个终止条件cvTermCriteria(CV_TERMCRIT_ITER + CV_TERMCRIT_EPS, 100, 1e-5)表示最多迭代 100 次或者误差变化小于1e-5就停。100 次对 LM 优化来说足够，1e-5 的收敛阈值在双精度下也合理，一般不用动。
还有一个被忽略的点：cvStereoCalibrate本身有返回值，就是重投影的 RMS 误差，单位是像素。源码直接把它丢掉了，只看后面自检出来的avg err。正常标定 RMS 应该在 0.1~0.5 像素量级，超过 1 像素就说明角点质量或者 flag 组合有问题，这个数比什么都直接，建议改代码的时候第一件事就是把它接出来打印。
3.3 极线几何自检：avg err 是唯一能信的质量指标
标定完不代表结果可信，所以代码紧接着做了一次独立的质量检查：先去畸变，再算极线，最后用极线约束m2^T * F * m1 = 0算平均偏差。
// 先把原始点投影到去畸变后的空间，R 传空、P 传原内参，等于只校正畸变 cvUndistortPoints( &_imagePoints1, &_imagePoints1, &_M1, &_D1, 0, &_M1 ); cvUndistortPoints( &_imagePoints2, &_imagePoints2, &_M2, &_D2, 0, &_M2 ); // 用基础矩阵把左图点映射成右图上的极线，反之亦然 cvComputeCorrespondEpilines( &_imagePoints1, 1, &_F, &_L1 ); cvComputeCorrespondEpilines( &_imagePoints2, 2, &_F, &_L2 ); double avgErr = 0; for( i = 0; i < N; i++ ) { // 点到直线的距离公式：|ax + by + c| double err = fabs(points[0][i].x*lines[1][i].x + points[0][i].y*lines[1][i].y + lines[1][i].z) + fabs(points[1][i].x*lines[0][i].x + points[1][i].y*lines[0][i].y + lines[0][i].z); avgErr += err; } printf( "avg err = %g\n", avgErr/(nframes*n) );cvUndistortPoints的第五、第六个参数分别是旋转矩阵和新投影矩阵，这里传0和不带_M1的_M1，意思就是「不做立体校正，只按原内参做去畸变」，这样点还在原来的像素坐标系里，可以直接和极线做距离运算。如果这里传了校正后的投影矩阵，点就被换到另一个坐标系，跟_L1、_L2算出来的极线对不上了。
cvComputeCorrespondEpilines的第二个参数是 1 或 2，表示输入点是第一幅图还是第二幅图的；传 1 就得到这些点在第二幅图上对应的极线。极线用三个浮点数(a, b, c)表示，满足ax + by + c = 0，所以点到极线的距离直接就是绝对值，不用再除以根号下的模长——因为极线系数已经被归一化过了。
avgErr最后除以nframes * n，得到的是「每个点两侧平均偏差之和」的均值，单位是像素。经验值是低于 0.5 就很健康，0.5~1.0 属于可接受，超过 1.0 基本说明角点或者配对有问题。这个数最大的价值在于它是一个闭环校验：F是cvStereoCalibrate解出来的，如果标定有系统偏差，F就偏，极线就歪，avgErr一定会高。而且它不受cvStereoCalibrate内部优化准则影响，是一个独立指标，比只看 RMS 更可信。
不过这个指标有个盲区：如果失败帧的(0,0)占位点也参与了运算，它们对应的极线距离会非常离谱，把均值抬高。所以如果avg err异常大，第一件事不是去调 flag，而是去数一数有多少帧的active是 0。
4. 校正与视差：Bouguet 与 Hartley 两条路怎么选
标定拿到了内外参和基础矩阵，下一步就是把两幅图「摆正」，让对应点落在同一水平行上。这段代码用useUncalibrated这个参数做了岔路：传0走基于标定参数的 Bouguet 校正，传1或2走基于基础矩阵的 Hartley 非标定校正。两条路最终都输出两张重映射查找表，后面用cvRemap一次算完。
4.1 两条校正路线的分叉点
Bouguet 路线的输入是完整的内外参，通过构造两个虚拟相机平面把两幅图同时旋转到极线水平：
CvMat _R1 = cvMat(3, 3, CV_64F, R1); // 左相机校正旋转 CvMat _R2 = cvMat(3, 3, CV_64F, R2); // 右相机校正旋转 CvMat _P1 = cvMat(3, 4, CV_64F, P1); // 左相机校正后投影矩阵 CvMat _P2 = cvMat(3, 4, CV_64F, P2); cvStereoRectify( &_M1, &_M2, &_D1, &_D2, imageSize, &_R, &_T, &_R1, &_R2, &_P1, &_P2, 0, 0 /* CV_CALIB_ZERO_DISPARITY */ ); isVerticalStereo = fabs(P2[1][3]) > fabs(P2[0][3]);倒数第二个参数是alpha，控制校正后图像的有效像素范围：传0表示只保留能映射到原图的区域，边缘会被裁掉但不会出现黑边；传1则保留全部像素，代价是边缘出现大量无效区域。最后一个参数本该传CV_CALIB_ZERO_DISPARITY，让左右图像在主点上严格零视差对齐，源码里把它注释掉了、传了0，意味着主点视差被保留，后面算出来的视差图会带一个常数偏移。这个改动对结果没坏处，但对后续要做深度计算的人来说，得记住自己减掉这个偏移量。
isVerticalStereo这一行是判断双目是不是上下堆叠的：如果P2平移向量的 y 分量绝对值大于 x 分量，就认为两相机是上下装的。这个判断依赖cvStereoRectify输出的投影矩阵，逻辑上没问题，但如果模组是斜装的，可能误判。上下结构的双目在校正后极线是竖直的，而cvFindStereoCorrespondenceBM只支持水平极线，所以源码在竖直情况下直接跳过了视差计算，这一点在后面的循环里能看到。
Hartley 路线则完全不依赖标定参数，直接从基础矩阵求两个单应矩阵：
cvStereoRectifyUncalibrated( &_imagePoints1, &_imagePoints2, &_F, imageSize, &_H1, &_H2, 3); cvInvert(&_M1, &_iM); cvMatMul(&_H1, &_M1, &_R1); // R1 = H1 * M1 cvMatMul(&_iM, &_R1, &_R1); // R1 = M1^-1 * H1 * M1 cvInvert(&_M2, &_iM); cvMatMul(&_H2, &_M2, &_R2); // R2 = H2 * M2 cvMatMul(&_iM, &_R2, &_R2); // R2 = M2^-1 * H2 * M2第三个参数传3是 RANSAC 的阈值，单位像素，用来剔除基础矩阵估计中的外点。单应H1、H2是像素坐标系下的变换，要转成cvInitUndistortRectifyMap需要的旋转矩阵，必须做一次M^-1 * H * M的相似变换，这就是那两行cvMatMul在干的事。注意cvMatMul的第一个参数在这里被复用成了输出缓冲区，所以第二次调用&_iM, &_R1, &_R1是安全的，但可读性很差，改成三个不同的矩阵更清楚。
两条路的取舍很实际：有可信的内参就用 Bouguet，校正后的图像尺度一致、视差直接可换算成深度；内参不可信或者压根没标过，就退到 Hartley，它只保证极线水平，不保证图像不变形，视差和深度的换算关系也糊了。useUncalibrated == 2时还会额外调一次cvFindFundamentalMat独立算F，用来对比cvStereoCalibrate解出来的那个，算是一个交叉验证手段。
4.2 映射表与 cvRemap：一次预计算反复用
不管走哪条路，最后都落到两个函数上：cvInitUndistortRectifyMap生成查找表，cvRemap按表采样。这种「预计算 + 查表」的结构是实时双目处理的标准做法，因为标定参数在一段时间内是固定的，没必要每帧重新算映射。
CvMat* mx1 = cvCreateMat(imageSize.height, imageSize.width, CV_32F); CvMat* my1 = cvCreateMat(imageSize.height, imageSize.width, CV_32F); // mx2 / my2 同理，分别对应右图 cvInitUndistortRectifyMap(&_M1, &_D1, &_R1, &_P1, mx1, my1); cvInitUndistortRectifyMap(&_M2, &_D2, &_R2, &_P2, mx2, my2);mx1、my1是两个和图像同尺寸的单通道浮点矩阵，每个位置存的是「目标图这个像素该从原图哪个坐标采样」。类型必须是CV_32F，cvRemap需要浮点坐标做双线性插值，用整型表会丢精度。五参数版本里，_M1是原内参、_D1是畸变、_R1是校正旋转、_P1是校正后的新投影矩阵，四者合起来就是一个完整的「去畸变 + 校正」变换。
生成之后就能反复用了：
cvRemap( img1, img1r, mx1, my1 ); // 左图重映射到校正后坐标 cvRemap( img2, img2r, mx2, my2 ); // 右图重映射cvRemap的第四、第五个参数就是刚才生成的表，第六个参数可以指定插值方式，默认是双线性。如果相机不动、只换图像，映射表完全复用，这一步的开销就只剩采样本身，分辨率 1280×720 下大概是毫秒级。
这里顺便提一个源码本身的状态：这份代码在最后拼左右对比图、画水平辅助线的循环处被截断了，cvLine那行写到一半就没了。补全起来很简单，就是按j += 16每隔 16 像素画一条水平线，用来肉眼确认极线是否水平对齐。这个辅助线非常有用，建议动手补上——比任何数值指标都直观。
4.3 StereoBM 七个参数的实际手感
校正做完，最后一步是算视差。源码用的是块匹配cvCreateStereoBMState，参数手动赋值：
CvStereoBMState *BMState = cvCreateStereoBMState(); BMState->preFilterSize = 41; // 预滤波窗口边长 BMState->preFilterCap = 31; // 预滤波输出截断值 BMState->SADWindowSize = 41; // SAD 匹配窗口边长，必须奇数 BMState->minDisparity = -64; // 最小视差，允许负值 BMState->numberOfDisparities= 128; // 视差搜索范围，必须被 16 整除 BMState->textureThreshold = 10; // 纹理阈值，低于此值不算视差 BMState->uniquenessRatio = 15; // 唯一性比率，过滤误匹配SADWindowSize = 41是个偏大的值，大窗口对弱纹理区域更稳但边缘会糊，典型取值是 15~31；41 适合低纹理的墙面、地面场景，代价是细节全丢。numberOfDisparities = 128决定了能测到的最大视差，也就决定了最近可测距离，这个值必须能被 16 整除，否则内部会被截断成最近的小值，是个静默失败点。minDisparity = -64允许负视差，说明这对相机校正后主点偏移比较大，正向搜索可能漏掉近处物体。
uniquenessRatio = 15的意思是「最优匹配代价必须比次优好 15% 才认」，值越小视差图越稠密但误匹配越多，值越大越保守。这个参数和textureThreshold是一对：前者管匹配的置信度，后者管「够不够格参与匹配」，弱纹理场景下把textureThreshold从 10 提到 20 能砍掉一大片噪点。
调用本身就一行：
cvFindStereoCorrespondenceBM( img1r, img2r, disp, BMState ); cvNormalize( disp, vdisp, 0, 256, CV_MINMAX ); // 16 位视差归一化到 8 位显示disp是CV_16S类型，存的是定点视差，真实视差要除以 16。这一步很多人忘了，直接把disp当像素读数用，算出来的深度差了一两个数量级。cvNormalize只是为了显示，把 16 位线性拉伸到 0~255 的 8 位图，跟真实视差值的换算没关系。
5. 避坑与排查：标定跑不出结果的五种典型症状
这份代码短，但踩坑点密度不低，而且大部分失败是静默的——程序不崩，只是结果不对。下面五条是实际拆解时最容易撞上的，按现象、原因、解决三步记。
5.1 症状一：avg err 稳定在几十到上百像素
现象很典型：程序一路跑完，Running stereo calibration ... done也打印了，但avg err = 47.3这种数字怎么调 flag 都下不来。
原因不在标定本身，而在数据入口。前面 2.3 节提过，active记录了每帧是否成功找到角点，但后续代码完全没用它，失败帧的n个(0,0)占位点照样参与了标定和极线自检。只要清单里有几帧因为模糊、反光、格子不全而检测失败，这些零坐标就会被当成真实像点，把基础矩阵拉偏，avg err自然高得离谱。
解决办法是把过滤补上。最小改动是在nframes统计处剔除失败帧，同时重建objectPoints和两组points；更省事的做法是在读图循环结束后打印一次active[0]和active[1]里 0 的个数，如果超过 10% 就直接停下来检查采图质量，别急着调参数。再稳一点的做法是改成cvCalibrateCamera2分别标左右内参，用重投影误差逐帧筛查，把离群帧剔除后再做立体标定。
5.2 症状二：程序在找角点之后直接退出，没有任何报错
现象是终端打出一串点号然后进程结束，Running stereo calibration那行根本没出来。
原因通常出在imageSize。它在读图循环里被每张图覆写，如果清单里最后一张图因为路径写错或者文件损坏导致cvLoadImage返回空，循环会直接break，此时imageSize停留在上一张有效图的值，而points的长度和active的长度对不上，后面的nframes = active[0].size()拿到一个不一致的数，_objectPoints的列数N = nframes * n和实际points[0].size()不匹配，cvMat头指向的缓冲区长度不足，在 Release 下不一定崩，但会读到越界内存，行为随机。
解决办法是在读图循环里对cvLoadImage失败不break而是continue并打印路径，让坏图被跳过而不是中断整个流程；同时统一用一个bool标记「第一张成功图」来初始化imageSize，后续所有图都校验尺寸一致。
5.3 症状三：校正后的图像看着还行，但视差图整体错位
现象是左右图重映射之后单看都正常，可视差图里物体的轮廓整体右移或者左移了一个固定量，深度值系统性偏大或偏小。
原因是cvStereoRectify的最后一个参数。源码里把CV_CALIB_ZERO_DISPARITY注释掉、传了0，意味着校正后两幅图的主点视差没有被归零，残留了一个常数偏移。这个偏移在校正图像上是看不出来的（两幅图各自都「正」），但会直接加到视差上，导致最近可测距离和深度换算全部平移。
解决办法有两个方向：要做深度测量就打开CV_CALIB_ZERO_DISPARITY，让主点严格对齐，代价是有效视差范围变小；要保留最大视场就在算深度前手动减掉这个常数偏移，偏移量可以从P2的主点位置和P1的主点位置之差读出来。
5.4 症状四：视差图整片黑或者整片白，只有零星几个点
现象是disparity窗口打开后基本是纯色，偶尔有几个噪点。
第一个原因是numberOfDisparities没被 16 整除。这个参数不是 16 的倍数时，OpenCV 内部会截断到最近的 16 的倍数，如果实际设的是 100，会被截到 96，看起来问题不大；但如果设成 20，会被截到 16，搜索范围直接砍掉一半以上，远处物体全部落到范围外，视差图就是黑的。检查方式很简单，打印一下BMState->numberOfDisparities看是否等于你设的值。
第二个原因在竖直双目。源码里有这段判断：
if( !isVerticalStereo || useUncalibrated != 0 ) { cvFindStereoCorrespondenceBM( img1r, img2r, disp, BMState ); ... }上下堆叠的双目在 Bouguet 校正后极线是竖直的，而块匹配算法只按水平方向搜索，此时函数要么不执行、要么结果全无效。要用竖直双目，得先把图像转置 90 度变成水平极线，算完视差再转回去。
第三个原因更隐蔽：preFilterSize = 41和SADWindowSize = 41都是大窗口，在近处视差很大的时候，预滤波会把相邻的视差层糊在一起，导致匹配代价区分度不够，uniquenessRatio = 15一卡就把大片区域判为无效。把窗口降到 21 左右往往能救回来。
5.5 症状五：Hartley 分支出来的图比 Bouguet 还歪
现象是把useUncalibrated改成 2，输出图像有明显的倾斜拉伸，极线辅助线看着也不是水平的。
先看这段：
cvInitUndistortRectifyMap(&_M2, &_D1, &_R2, &_M2, mx2, my2);右相机的畸变系数传的是_D1，左相机的。这是原代码里的一个笔误：Hartley 分支的右图映射表用了左相机的畸变参数。两台相机畸变不可能完全一样，尤其视场边缘差异明显，用错之后右图的边缘会校正过度或者不足，跟左图对不上，看起来就是整幅图歪。
解决办法是把第二个&_D1改成&_D2。同时那个分支的第四个参数也传的是原内参_M2而不是新投影矩阵，这意味着不做尺度归一化，两幅校正图的焦距可能不同，视差和深度的换算关系需要额外处理。要做定量测量的话，还是回 Bouguet 路线更省心。
6. 二次开发：把 demo 改造成能反复用的标定工具
这份代码当前状态是「一次性的演示脚本」，参数全写死在函数内部，清单路径硬编码在main里，跑一次就退出。要把它变成能每天用的标定工具，我一般按三步改。
第一步是把参数从函数里提出来，用一个结构体统一承载。最小可用的字段包括棋盘内角点数nx/ny、格子物理边长、清单路径、useUncalibrated、maxScale，再加上输出路径：
struct StereoCalibConfig { int nx = 9; // 内角点列数 int ny = 6; // 内角点行数 float squareSize = 25.f; // 棋盘格边长，单位 mm std::string listFile = "stereo_list.txt"; int useUncalibrated = 0; // 0=Bouguet, 1=Hartley+F, 2=Hartley 独立算 F int minGoodFrames = 10; // 低于这个数的成功帧就直接报错退出 };字段不多，但把最常见的几个错误挡住了：squareSize从 1 改成真实值，T就有了物理意义；minGoodFrames逼着调用方先确认采图质量，而不是拿到一堆占位点就往下跑。
第二步是把标定结果落盘。cvSave几个矩阵到 YAML 或者按自定义的二进制格式写，字段就是M1, D1, M2, D2, R, T, E, F, R1, R2, P1, P2, imageSize。落盘之后，实时处理程序只需要读文件、cvInitUndistortRectifyMap一次、缓存两张表，后面每帧只做cvRemap和 BM，标定和运行彻底解耦。我自己是习惯额外存一个校验字段——把落盘时的avg err一起写进去，加载的时候认为超过 1.0 就直接拒绝使用，避免拿着过期的坏标定跑一整天。
第三步是给 success 帧的active加上过滤，同时把cvStereoCalibrate的 RMS 返回值接出来做双重日志。这两件事一起做，能让「标定到底成没成」从玄学变成两个具体数字。
最后一点改造思路不太属于代码层面：固定一套采图规范。我踩过一次坑，同一个模组两次标定，一次avg err0.3、一次 0.9，查了半天以为代码有随机性，最后发现是第二次拍摄时棋盘被贴在了倾斜的墙面上、部分区域过曝导致角点细化跑偏。从那以后我每次采完图都会先跑一遍带displayCorners = 1的可视化模式，一张张过角点叠加图，确认边缘角点都老老实实贴在内角点上再进标定。这套流程比任何参数调优都管用，也希望帮到你。
本文还有配套的精品资源，点击获取
