简介：这份单目结构光系统标定源码面向计算机视觉学习者与三维重建开发者，聚焦单目相机与投影设备联合标定这一关键环节，帮助消除镜头畸变及投影仪与相机相对位置误差，为后续3D测量与重建提供可靠参数。压缩包共28个文件，约558KB，以cpp与hpp源码为主体，辅以ui界面文件、pro与pri工程配置、ini参数文件及pdf操作说明，整体结构清晰，便于按模块阅读与二次开发。源码覆盖特征点检测、图像采集、投影模型建立、参数估计与结果验证等完整流程，读者可借此理解棋盘格标定、最小二乘优化及内外参求解的具体实现，并体会C语言在计算机视觉中的工程应用。目前已有983人学习下载，适合具备一定图像处理基础、希望深入掌握结构光标定原理与实践的读者参考。
1. 单目结构光系统标定源码.zip 里到底装了什么：从「能跑」到「能用」的分水岭
很多人第一次拿到「单目结构光系统标定源码.zip」这类压缩包，第一反应是解压、找 main、跑起来看结果。但真正决定这套代码能不能用在产线上的，不是它能不能输出一组参数，而是它标定出来的相位到深度映射在 300mm 工作距离上误差是 0.05mm 还是 0.5mm。单目结构光系统的标定，本质上是把相机内参、投影仪「逆向相机」模型、以及两者之间的外参统一到一个坐标系里，再建立相位差到三维坐标的查找关系。它解决的是「我有一台相机加一台投影仪，怎么让它们配合着把物体表面测准」这个问题。适合谁？做 3D 扫描、缺陷检测、焊接引导、鞋底涂胶这类需要非接触式三维测量的工程师，以及正在从双目方案切换到单目结构光、想搞清楚标定链路每一步在干什么的人。这个压缩包里的源码，通常就是把这套链路用 OpenCV 加标定板图像串起来的实现。
2. 标定链路拆解：相机、投影仪、相位到深度的三步走
2.1 为什么单目结构光不需要第二个相机也能测深度
双目立体视觉靠两个相机同时看一个点，用视差算深度。单目结构光把其中一个相机换成了投影仪，投影仪投射的是编码条纹，不是随机纹理。相机看到的是被物体表面调制后的条纹，条纹的相位变化等价于视差。所以核心思路是：把投影仪当成一个「反向相机」，它也有内参和畸变，只不过它的「成像」过程是投射而不是接收。标定的目标就是求出相机内参矩阵、投影仪内参矩阵、以及两者之间的旋转平移关系。一旦这三组参数确定，任何一个相机像素点加上它对应的相位值，就能反推出三维坐标。这里的关键是相位解包裹的精度和标定板的提取精度必须匹配，否则后面深度图会出现周期性波纹。
2.2 相机标定：张正友法在结构光里的参数取舍
相机标定用张正友棋盘格法，OpenCV 里就是calibrateCamera。但在结构光系统里，标定板不仅要被相机看到，还要被投影仪「看到」——也就是投影仪投射的棋盘格或者白光，让标定板上的角点在投影仪图像里也能提取。常见做法是：相机拍一张标定板图，同时投影仪投射全白，相机再拍一张，用这两张图分别提取角点。参数上，CALIB_FIX_ASPECT_RATIO一般打开，因为工业相机的像元是正方形；CALIB_ZERO_TANGENT_DIST建议打开，结构光系统里切向畸变通常很小，固定为零可以减少过拟合。标定图像数量建议 15 到 25 张，覆盖相机视野的四个角和中心，倾斜角度在 ±30° 以内。重投影误差要控制在 0.1 像素以内，超过 0.2 像素说明角点提取有问题，后面深度图一定会有明显噪声。
import cv2 import numpy as np # 棋盘格内角点数，比如 11x8 pattern_size = (11, 8) objp = np.zeros((pattern_size[0] * pattern_size[1], 3), np.float32) objp[:, :2] = np.mgrid[0:pattern_size[0], 0:pattern_size[1]].T.reshape(-1, 2) obj_points = [] # 世界坐标 img_points = [] # 图像坐标 for fname in image_list: img = cv2.imread(fname, cv2.IMREAD_GRAYSCALE) ret, corners = cv2.findChessboardCorners(img, pattern_size, None) if ret: # 亚像素优化，窗口大小 11x11 是经验值 corners = cv2.cornerSubPix( img, corners, (11, 11), (-1, -1), criteria=(cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001) ) obj_points.append(objp) img_points.append(corners) # 标定相机，固定长宽比和切向畸变 ret, K, dist, rvecs, tvecs = cv2.calibrateCamera( obj_points, img_points, img.shape[::-1], None, None, flags=cv2.CALIB_FIX_ASPECT_RATIO + cv2.CALIB_ZERO_TANGENT_DIST )这段代码里cornerSubPix的窗口大小 11 是常用值，太小对噪声敏感，太大在角点附近有干扰时会把角点拉偏。calibrateCamera返回的K是内参矩阵，dist是畸变系数。如果重投影误差大于 0.2 像素，先检查标定板是否平整、光照是否均匀，再考虑增加图像数量。
2.3 投影仪标定：把投射图案当成「反向成像」
投影仪标定的难点在于它不能直接拍照。常见做法是：投影仪投射棋盘格到白板上，相机拍白板，然后提取角点。但这里有个坑——白板不是理想平面，而且投影仪的畸变和相机畸变耦合在一起。更稳的方法是：用相机标定得到的参数，把相机看到的角点反投影到世界坐标系，再结合投影仪投射的图案坐标，建立投影仪的内参方程。具体步骤是：投影仪依次投射水平条纹和垂直条纹，相机拍下每个相位下的图像，用相位解包裹得到每个相机像素对应的投影仪像素坐标。然后用这些对应点对，调用calibrateCamera的变体来标定投影仪。参数上，投影仪的畸变模型通常只用径向畸变k1, k2，切向畸变忽略。投影仪的分辨率要和相机匹配，比如相机 1280x1024，投影仪 1280x720，标定出来的外参矩阵要能正确映射。
# 假设已经得到相机像素点 cam_pts 和对应的投影仪像素点 proj_pts # 用相机内参把 cam_pts 反投影到归一化平面 cam_norm = cv2.undistortPoints(cam_pts, K, dist) # 投影仪标定：把 proj_pts 当成图像点，cam_norm 当成世界点 # 注意这里需要构造投影仪的内参初值 proj_K_init = np.array([[1000, 0, 640], [0, 1000, 360], [0, 0, 1]], dtype=np.float32) ret_proj, proj_K, proj_dist, _, _ = cv2.calibrateCamera( [cam_norm.reshape(-1, 1, 2)], [proj_pts.reshape(-1, 1, 2)], (1280, 720), proj_K_init, None, flags=cv2.CALIB_USE_INTRINSIC_GUESS + cv2.CALIB_FIX_TANGENT_DIST )这里CALIB_USE_INTRINSIC_GUESS必须打开，因为投影仪的内参初值需要根据分辨率估算。proj_K_init里的焦距初值可以按投影仪水平视场角估算，比如 30° 视场角对应焦距约 1200 像素。如果标定结果里主点偏离图像中心超过 50 像素，说明对应点匹配有误，要检查相位解包裹的跳变。
2.4 相位到深度的映射：多项式拟合还是查表
标定完相机和投影仪，下一步是建立相位差到深度的关系。常见做法有两种：一种是多项式拟合，用z = a0 + a1*phi + a2*phi^2 + ...，通常三阶就够；另一种是查表法，把相位差和深度对应关系存成查找表，适合实时性要求高的场景。多项式拟合的系数用最小二乘法从一组已知深度的平面标定数据里求。参数上，拟合阶数不要超过 4，否则会出现龙格现象，深度图边缘振荡。查表法的表分辨率建议 0.1 相位单位，表大小控制在 4096 项以内，否则内存占用大且插值误差反而增加。
# 用已知深度的平面数据拟合相位-深度多项式 # phases: 每个像素的相位差，depths: 对应的真实深度 coeffs = np.polyfit(phases, depths, 3) # 三阶拟合 poly = np.poly1d(coeffs) # 对新的相位差计算深度 depth_map = poly(phase_diff)np.polyfit的第三个参数是阶数，三阶在 300mm 到 800mm 工作距离内通常能把非线性误差压到 0.1mm 以内。如果工作距离超过 1 米，建议分段拟合，每 200mm 一段，段间做线性过渡。
3. 从源码到可复现：编译、配置与第一次标定
3.1 环境依赖与编译选项：OpenCV 版本和 contrib 模块
这类源码通常依赖 OpenCV 4.x，而且要用到opencv_contrib里的structured_light模块。编译时OPENCV_ENABLE_NONFREE要打开，因为有些相位解包裹算法用到了专利算法。CMake 配置里BUILD_opencv_structured_light必须为 ON。如果用的是预编译包，要确认 contrib 模块已经包含。Python 环境下pip install opencv-contrib-python即可，但要注意版本匹配，4.5.x 和 4.8.x 在structured_light的 API 上有差异，源码里如果用了GrayCodePattern，4.8 里参数顺序变了。
# 源码编译 OpenCV 的关键 CMake 参数 cmake -D CMAKE_BUILD_TYPE=RELEASE \ -D CMAKE_INSTALL_PREFIX=/usr/local \ -D OPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules \ -D OPENCV_ENABLE_NONFREE=ON \ -D BUILD_opencv_structured_light=ON \ -D BUILD_EXAMPLES=ON ..OPENCV_EXTRA_MODULES_PATH指向 contrib 模块的modules目录，路径写错会导致structured_light找不到。BUILD_EXAMPLES打开后可以编译出structured_light的示例程序，用来验证环境是否正常。
3.2 标定图像采集：投影图案序列与同步触发
标定图像采集分两步：相机标定图像和投影仪标定图像。相机标定图像是拍棋盘格，投影仪标定图像是拍投影仪投射的条纹。条纹序列通常用三步相移加格雷码，三步相移解相位，格雷码解包裹。采集时相机和投影仪要同步，如果投影仪没有触发输出，可以用相机软触发，但曝光时间要大于投影仪刷新周期。常见参数：投影仪刷新率 60Hz，相机曝光 16.7ms，增益调低，避免条纹过曝。采集 12 到 16 组不同相位的条纹图，每组包含三步相移和格雷码图案。
# 生成三步相移条纹 def generate_phase_shift_patterns(height, width, periods, shifts=3): patterns = [] for i in range(shifts): phase = 2 * np.pi * i / shifts x = np.arange(width) pattern = 0.5 + 0.5 * np.cos(2 * np.pi * periods * x / width + phase) pattern = np.tile(pattern, (height, 1)) patterns.append((pattern * 255).astype(np.uint8)) return patternsperiods是条纹周期数，通常取 16 到 32，周期太少相位精度低，周期太多解包裹容易跳变。shifts=3是最少步数，如果噪声大可以用 4 步或 5 步。
3.3 第一次跑通标定：从图像列表到参数文件
源码里通常有一个calibrate.py或calibration.cpp，输入是图像文件夹路径，输出是camera.yml、projector.yml和system.yml。运行前要检查图像命名是否按顺序，标定板尺寸是否和代码里一致。第一次跑建议先用少量图像（比如 5 张）验证流程，再逐步增加。输出参数里重点看reprojection_error，相机和投影仪都要小于 0.2 像素。如果投影仪误差大，检查相位解包裹的条纹图是否清晰，格雷码解码是否正确。
# 典型运行命令 python calibrate.py --camera_dir ./data/camera --projector_dir ./data/projector \ --pattern_size 11x8 --square_size 10.0 \ --output ./calib_result--square_size是棋盘格方格的实际物理尺寸，单位毫米，必须和打印出来的标定板一致。--pattern_size是内角点数，不是方格数，写错会导致角点提取失败。
4. 避坑与排查：标定结果不稳定的五个血泪经验
4.1 重投影误差忽大忽小：标定板不平或光照不均
现象是同一套图像跑两次，重投影误差差 0.1 像素以上。原因通常是标定板打印后没有贴在平整表面上，或者光源从侧面打过来导致角点一侧亮一侧暗。解决方法是把标定板贴在大理石平台或玻璃板上，用漫射光源从正上方打光，相机曝光调至直方图峰值在 128 附近。
4.2 投影仪标定主点偏移：相位解包裹跳变
现象是投影仪内参的主点偏离图像中心超过 100 像素，深度图出现周期性台阶。原因是格雷码解码时相邻周期边界处相位跳变错误。解决方法是增加格雷码位数，或者在三步相移后加一组四步相移做校验，跳变点用中值滤波剔除。
4.3 深度图出现波纹：多项式拟合阶数过高
现象是平面物体的深度图上有规律的正弦波纹。原因是相位到深度的多项式阶数取到 5 阶以上，拟合出了本不该有的振荡。解决方法是降到 3 阶，如果残差还大，改用分段线性插值，段长 50mm。
4.4 标定参数在另一台设备上失效：相机内参和分辨率绑定
现象是把标定好的camera.yml拿到另一台同型号相机上，深度图完全不对。原因是内参矩阵和图像分辨率绑定，换了相机即使型号相同，主点和焦距也有个体差异。解决方法是每台设备单独标定，或者用cv2.getOptimalNewCameraMatrix做分辨率归一化，但归一化后精度会下降 10% 到 20%。
4.5 实时标定失败：投影仪刷新和相机曝光不同步
现象是采集条纹图时出现明暗带滚动，相位解包裹完全失败。原因是相机曝光时间不是投影仪刷新周期的整数倍。解决方法是把相机设为外触发，触发信号来自投影仪的垂直同步输出，或者把曝光时间设为刷新周期的整数倍，比如 60Hz 投影仪对应 16.7ms 的整数倍。
5. 进阶技巧：用棋盘格一次完成相机和投影仪联合标定
联合标定的思路是：投影仪投射棋盘格到标定板上，相机拍一张，标定板上同时有相机可见的棋盘格和投影仪投射的棋盘格。这样一张图里同时包含相机角点和投影仪角点，用同一组世界坐标点做约束，可以同时优化相机和投影仪的参数。具体做法是：标定板用红外反射材料，相机加红外滤光片，投影仪投射红外棋盘格，这样相机只看到投影仪投射的棋盘格，看不到标定板本身的图案。然后移动标定板，采集 10 到 15 组，每组同时提取相机角点和投影仪角点。优化时用cv2.calibrateCamera的扩展版本，把投影仪内参作为待优化变量，损失函数是相机重投影误差加投影仪重投影误差。
# 联合标定：同时优化相机和投影仪参数 # 假设有 N 组标定板位姿，每组有相机角点 cam_pts 和投影仪角点 proj_pts # 世界坐标 obj_pts 已知 ret, K_cam, dist_cam, K_proj, dist_proj, R, T = cv2.stereoCalibrate( obj_pts, cam_pts, proj_pts, K_cam, dist_cam, K_proj, dist_proj, image_size, flags=cv2.CALIB_FIX_INTRINSIC )cv2.stereoCalibrate在这里被借用，因为相机和投影仪的联合标定在数学上等价于双目立体标定，只不过投影仪的「图像」是它投射的图案。CALIB_FIX_INTRINSIC表示先固定单目标定得到的内参，只优化外参。如果单目标定精度够，这个标志可以打开；如果单目标定误差大，去掉这个标志，让内参和外参一起优化，但迭代次数要增加。
验证联合标定效果的方法：用标定好的参数重建一个已知直径的标准球，看重建出来的球直径误差。如果误差小于 0.1mm，说明标定链路可用。我自己的习惯是每次换镜头或调整投影仪焦距后，先跑一遍联合标定，再跑一遍标准球验证，两个都过了才上产线。希望帮到你。
本文还有配套的精品资源，点击获取
