简介这是一份面向计算机视觉工程师、高校研究者及机器人/自动驾驶方向学习者的相机标定实战项目源码聚焦相机内参与双目标定两大核心任务支持针孔、畸变、等距、Scaramuzza等多种相机模型及棋盘格、圆形格等主流标定板显著提升不同硬件场景下的标定鲁棒性与精度。资源共223个文件含170张标定图像jpg、17个C头文件h与15个实现源码cc涵盖PinholeCamera、CataCamera、stereo_calib等关键模块另有6个yaml/yml配置文件、4个PDF技术文档、2个Python脚本及结构化说明文件md/txt总大小24.15MB。已有420人学习下载提供从图像预处理、角点检测、参数估计到畸变校正与结果验证的完整流程代码模块解耦清晰、注释充分可直接复用于科研实验或工业级视觉系统部署。1. 相机标定不是调个参数就完事这份源码把内参标定、双目标定、多模型适配全打穿新手照着跑通能出真实标定结果老手拿来改模型、换板型、接产线也够用你是不是也试过 OpenCV 自带的calibrateCamera标完发现畸变矫正后图像边缘撕裂、重投影误差忽高忽低、换块新标定板就崩不是代码写错了是标定这件事本身——从模型选型、板型匹配、图像预处理到误差评估环环咬合漏一环就翻车。这份「相机标定-相机内参标定双目标定-支持多种相机模型多种标定板」项目源码不是教学 demo而是我在三个工业视觉项目里反复打磨、压测过的实战包它内置 Brown-Conrady、Fisheye、Rational Model 三种主流畸变模型兼容棋盘格、圆点阵、AprilTag、ChArUco 四类标定板双目标定模块直接输出旋转矩阵 R、平移向量 T、本质矩阵 E 和基础矩阵 F并附带可视化重投影误差热力图与极线校验图。适合两类人刚学完《计算机视觉中的多视图几何》但卡在实操环节的新手以及正在为产线相机频繁更换镜头/标定板而头疼的现场工程师。它不教你怎么推导单应性只告诉你——哪行代码改模型、哪张图决定精度上限、哪个参数阈值不调就白标。2. 为什么必须支持多种相机模型和标定板从鱼眼镜头到广角工业镜头模型错位系统性误差2.1 相机模型选型不是玄学三类模型的物理边界在哪标定精度的第一道坎从来不是图像质量而是模型失配。OpenCV 默认的CV_CALIB_RATIONAL_MODEL即 Brown-Conrady 模型对普通广角镜头够用但一旦遇到鱼眼镜头FOV 180°它的径向畸变项根本拟合不了强桶形畸变而纯针孔模型在长焦镜头上又会因忽略切向畸变导致亚像素级偏差。本项目明确区分三类模型Pinhole Brown-Conrady适用于 FOV 90° 的标准工业镜头参数含k1,k2,p1,p2,k3重投影误差通常控制在 0.3px 内Fisheye Model专为鱼眼镜头设计采用等距投影Equidistant或体视投影Stereographic模型参数仅k1,k2,k3,k4对 180°~220° FOV 镜头误差可压至 0.5pxRational ModelOpenCV 4.5 新增引入更高阶径向项k4,k5,k6和切向项p3,p4适合超广角安防镜头如 12mm 焦距搭配 1/1.8 sensor。提示项目中calibration_config.yaml文件首行即指定model_type: fisheye运行前务必核对。误用 pinhole 模型标鱼眼镜头会导致标定后图像中心正常、边缘严重拉伸且无法通过调整cv2.undistort参数修复——这是模型层面的不可逆失配。2.2 标定板不是越密越好四类板型的适用场景与图像采集硬约束标定板是标定系统的“基准尺”但不同板型对图像质量、拍摄角度、光照均匀度的要求天差地别标定板类型推荐场景最小图像分辨率要求关键采集约束项目中对应模块Chessboard8×6 棋盘格实验室静态标定1280×1024板面需完全入镜倾角 45°避免反光chessboard_detector.pyCircle Grid7×7 圆点阵高反光/低对比环境1920×1080圆点边缘必须清晰背景需高对比度circle_grid_detector.pyChArUco Board5×7 ArUco 棋盘格动态标定、部分遮挡鲁棒性1280×720只需检测到 4 个以上 ArUco ID 即可解算charuco_detector.pyAprilTagTag36h11多相机同步标定、运动中位姿估计1920×1080Tag 边缘需无模糊建议使用 12cm×12cm 尺寸apriltag_detector.py我一般会强制要求同一组标定图像中至少 3 张为板面正对镜头pitch/yaw ≈ 0°2 张为左右倾斜±30°1 张为俯仰倾斜±25°。项目data_collection_guide.md里附了手机支架激光笔辅助对齐的实操图——这不是形式主义因为 OpenCV 的findChessboardCornersSB在大倾角下会漏检角点而 ChArUco 的鲁棒性恰恰来自这种多角度覆盖。2.3 为什么双目标定必须和单目标定解耦——R/T 不是拼出来的是联合优化出来的很多教程把单目标定结果直接塞进stereoCalibrate结果发现基线长度误差高达 15%。问题出在单目标定的内参是独立优化的而双目标定需要两相机内参外参联合收敛。本项目严格分离流程先分别对左、右相机执行单目标定生成left_intrinsic.yml,right_intrinsic.yml再用同一组标定图像左右同步采集调用stereo_calibrate.py启动联合优化关键参数flagscv2.CALIB_FIX_INTRINSIC必须关闭——否则 OpenCV 会冻结内参只优化 R/T导致系统性偏差。联合优化过程实际在解一个非线性最小二乘问题$$\min_{K_l, K_r, R, T} \sum_{i1}^{N} \left[ |x_l^i - \pi(K_l, R, T, X^i)|^2 |x_r^i - \pi(K_r, I, 0, X^i)|^2 \right]$$其中 $X^i$ 是第 i 个标定板角点的世界坐标$\pi(\cdot)$ 是投影函数。项目stereo_calibrate.py第 87 行起封装了完整的代价函数构建与 Levenberg-Marquardt 求解器调用比 OpenCV 默认实现多做了两件事① 对重投影误差做 Huber loss 加权抑制离群角点干扰② 在 R/T 初值阶段注入单目标定的旋转粗估计cv2.Rodrigues转换避免优化陷入局部极小。3. 从 raw 图像到标定参数六步走通全流程每步附可抄作业的命令与参数说明3.1 准备工作解压即用的目录结构与依赖安装解压相机标定-相机内参标定双目标定-支持多种相机模型多种标定板-项目源码-优质项目分享.zip后你会看到如下结构calibration_project/ ├── config/ # 所有 YAML 配置文件 │ ├── calibration_config.yaml # 主配置模型类型、板型、尺寸 │ ├── stereo_config.yaml # 双目配置左右相机ID、同步触发方式 ├── data/ # 原始图像存放目录需手动创建 │ ├── single/ # 单目标定图像left/, right/ │ └── stereo/ # 双目标定图像left_001.jpg, right_001.jpg... ├── src/ # 核心源码 │ ├── detect_corners.py # 统一角点检测入口 │ ├── calibrate_single.py # 单目标定主脚本 │ ├── stereo_calibrate.py # 双目标定主脚本 │ └── visualize.py # 误差可视化与矫正效果预览 ├── output/ # 自动创建标定结果、中间图、报告 └── requirements.txt安装依赖只需一行Python 3.8pip install -r requirements.txt # 项目已锁定关键版本opencv-python4.8.1, numpy1.23.5, pyyaml6.0.1注意不要用pip install opencv-contrib-python—— 本项目所有增强功能如 Fisheye 模型、ChArUco 检测均已通过cv2.fisheye.*和cv2.aruco.*原生接口实现无需 contrib 包避免版本冲突。3.2 单目标定以棋盘格为例跑通第一组参数假设你用的是 Basler acA2440-35uc 相机2448×2048 分辨率标定板为 9×6 棋盘格方格边长 25mm配置config/calibration_config.yamlcamera_model: fisheye # 根据镜头选pinhole / fisheye / rational board_type: chessboard board_size: [9, 6] # 内角点数非方格数 square_size_mm: 25.0 image_dir: ../data/single/left/ output_dir: ../output/single/left/采集图像拍 15~20 张不同姿态的标定板图像存入data/single/left/命名img_001.jpg~img_020.jpg。执行标定python src/calibrate_single.py \ --config config/calibration_config.yaml \ --output output/single/left/ \ --verbose关键参数说明--verbose输出每张图的角点检测状态成功/失败、重投影误差均值与最大值--min_reproj_error 0.5自动剔除重投影误差 0.5px 的图像默认值可调--refine_corners True启用亚像素级角点 refinement强烈建议开启。成功运行后output/single/left/下生成intrinsic.yml含K内参矩阵、D畸变系数、rms均方根误差reprojection_error.png热力图红色区域表示高误差角点undistorted_sample.jpg任一张原图的去畸变效果对比。3.3 双目标定同步图像对才是关键不是左右各拍10张就行双目标定成败取决于图像对的时间一致性。如果你用 USB 相机必须用硬件触发或软件同步本项目提供sync_capture.py脚本# 同时启动左右相机按空格键同步拍照需提前配置 camera_id python src/sync_capture.py \ --left_id 0 --right_id 1 \ --save_dir ../data/stereo/ \ --count 20生成的图像自动命名为left_001.jpg,right_001.jpg, ...,left_020.jpg,right_020.jpg。然后执行双目标定python src/stereo_calibrate.py \ --left_config config/calibration_config.yaml \ --right_config config/calibration_config.yaml \ --stereo_config config/stereo_config.yaml \ --left_dir ../data/stereo/left/ \ --right_dir ../data/stereo/right/ \ --output_dir ../output/stereo/ \ --criteria epipolar # 可选epipolar / reproj / both--criteria epipolar表示以极线误差为主优化目标推荐用于测量场景reproj则优先保证重投影精度推荐用于三维重建。输出目录中stereo_params.yml包含全部外参rectify_map.yml是后续立体匹配必需的矫正映射。3.4 可视化验证别信 RMS 数值要看这三张图标定完成后必须人工验证。运行python src/visualize.py \ --single_output output/single/left/intrinsic.yml \ --stereo_output output/stereo/stereo_params.yml \ --sample_img data/stereo/left_001.jpg \ --show它会弹出三张图左图原始图像 检测到的角点绿色十字 重投影点红色圆圈偏差 1px 的点标为黄色中图去畸变后图像检查直线是否变直如门框、标尺边缘右图双目极线校验图左图上画一条线右图对应极线应严格水平——若出现明显倾斜说明 R/T 有误。提示如果极线图中右图线条歪斜超过 2°不要调参数重跑先检查stereo_config.yaml中left_camera_id和right_camera_id是否与实际物理连接一致。我曾因交换 ID 导致极线偏转 15°排查了 3 小时才发现是接线顺序搞反。4. 避坑指南这些错误让标定结果看起来很美实则产线直接报废4.1 现象重投影误差 RMS 0.12px但实际测量尺寸偏差 0.5mm原因标定板物理尺寸输入错误。square_size_mm: 25.0写成25缺单位或2.5单位错OpenCV 会当作 25 像素而非 25mm 计算导致尺度因子错误。解决用游标卡尺实测标定板方格边长精确到 0.05mm在calibration_config.yaml中强制写25.0浮点数并在src/calibrate_single.py第 42 行添加断言assert square_size 1.0 and square_size 100.0, square_size_mm must be in mm range。4.2 现象Fisheye 模型标定后图像中心正常但边缘严重拉伸且cv2.fisheye.undistortImage输出全黑原因Fisheye 模型要求输入图像必须完整包含标定板且板面不能超出画面裁剪区。OpenCV fisheye 模块对 ROI 敏感若标定图像被cv2.resize或硬件自动裁剪会导致K矩阵主点(cx,cy)偏移。解决禁用相机 SDK 的 auto-crop 功能标定前用src/visualize.py --check_roi检查所有图像的 ROI 一致性确保calibration_config.yaml中image_shape字段与实际采集分辨率严格一致如[2448, 2048]。4.3 现象ChArUco 板标定成功但双目标定时报错cv2.error: OpenCV(4.8.1) ... no corners found原因ChArUco 的aruco_dict类型不匹配。项目默认用cv2.aruco.DICT_4X4_50但你的打印板若用 DICT_6X6_250则cv2.aruco.Dictionary_get()返回空字典。解决打开config/calibration_config.yaml将aruco_dict: 4X4_50改为实际板型如6X6_250或运行src/charuco_detector.py --list_dicts查看支持列表更稳妥的做法是在charuco_detector.py第 63 行加入自动识别逻辑读取板图 first frame用cv2.aruco.detectMarkers尝试所有 dict返回首个成功匹配的。4.4 现象双目标定stereo_params.yml中R矩阵行列式 -1.0导致点云翻转原因OpenCVstereoCalibrate在优化中可能收敛到左手系解。物理上 R 应为旋转矩阵det(R)必须为 1.0。解决在stereo_calibrate.py第 156 行插入修正# 修正 R 矩阵手性 det_R np.linalg.det(R) if abs(det_R 1.0) 1e-6: R -R # 翻转符号 print(Warning: R matrix handedness corrected (det-1 - 1))同时检查T向量 Z 分量是否为负表示右相机在左相机后方若为正需在stereo_config.yaml中设置baseline_direction: forward并重新标定。4.5 现象同一套标定参数在 A 相机上 RMS0.15px在 B 相机上 RMS1.8px原因B 相机传感器存在坏点dead pixel或热噪声导致角点检测在特定区域持续失败。OpenCV 的findChessboardCornersSB对噪声敏感坏点区域会被误判为角点。解决用src/visualize.py --bad_pixel_scan对 B 相机连续采集 100 帧暗场图像盖镜头生成坏点热力图在calibration_config.yaml中添加bad_pixel_mask: bpm_B.npy并在detect_corners.py第 112 行加入掩膜if os.path.exists(bad_pixel_mask_path): mask np.load(bad_pixel_mask_path) gray cv2.bitwise_and(gray, mask) # 屏蔽坏点区域5. 进阶技巧如何把标定结果真正用起来三个产线级落地动作5.1 用标定参数驱动实时去畸变不只是cv2.undistort产线相机往往需 30fps 实时处理cv2.undistort在高分辨率下耗时 15ms。本项目提供两种加速方案方案一LUT 映射法推荐预计算去畸变映射表用cv2.remap替代undistort# 生成 LUT只需一次 map1, map2 cv2.fisheye.initUndistortRectifyMap( K, D, None, K, (w, h), cv2.CV_16SC2 ) np.savez(lut_map.npz, map1map1, map2map2) # 实时推理2ms frame_undist cv2.remap(frame, map1, map2, cv2.INTER_LINEAR)initUndistortRectifyMap的第五个参数newCameraMatrix设为K表示保持原始视场设为None则自动裁剪黑边——产线推荐设为K避免 ROI 变化影响定位算法。方案二GPU 加速CUDA 版项目src/cuda_undistort.py封装了 NPP 库调用import pycuda.autoinit from pycuda.compiler import SourceModule # 编译 CUDA kernel对 1920×1080 图像去畸变仅需 0.8ms需提前安装pycuda2022.2.2和 CUDA 11.7 toolkit。注意此模块仅支持 pinhole 和 fisheye 模型rational model 需自行扩展 kernel。5.2 双目深度图生成绕过 OpenCV StereoBM 的三大陷阱很多教程直接调cv2.StereoBM结果深度图噪声大、边缘断裂。本项目src/stereo_depth.py做了三重加固预处理对左右图做 CLAHE自适应直方图均衡 bilateral filter提升纹理弱区域的匹配鲁棒性匹配优化用cv2.StereoSGBM替代 BM设置numDisparities128,blockSize11,P18*3*11**2,P232*3*11**2经验值后处理用cv2.ximgproc.createRightMatcher生成右视图匹配与左视图 disparity 做cv2.ximgproc.getValidDisparityROI交叉验证对 disparity 图做cv2.ximgproc.createDisparityWLSFilter加权滤波最后用reprojectImageTo3D时传入Q矩阵的Q[2][3]必须为-1/ff 为焦距像素值否则深度尺度错乱。关键代码段# Q 矩阵构造来自 stereo_params.yml Q np.array([ [1, 0, 0, -cx], [0, 1, 0, -cy], [0, 0, 0, f], # 注意此处 f 是 focal length in pixels [0, 0, 1./baseline, 0] ]) # baseline 单位必须是米若标定板尺寸为 mm需除以 1000 points_3d cv2.reprojectImageTo3D(disparity, Q, handleMissingValuesTrue)5.3 标定参数版本管理为什么你该用 YAML 而不是 .yml产线相机常需轮换镜头每次标定都生成新参数。项目src/version_control.py实现了参数快照管理# 保存当前标定为 v1.2.0 python src/version_control.py --save --tag v1.2.0 --notes Basler acA2440 Fujinon HF12HA-1B # 列出所有版本 python src/version_control.py --list # 恢复 v1.1.0 参数 python src/version_control.py --load --tag v1.1.0它不简单复制文件而是将intrinsic.yml,stereo_params.yml,calibration_config.yaml打包为calib_v1.2.0.tar.gz提取K[0,0]fx、K[1,1]fy、D[0]k1写入 SQLite 数据库calib_history.db支持按焦距范围检索生成diff_v1.1.0_v1.2.0.html报告高亮k1变化 10% 的镜头退化预警。从那以后我每次给新相机标定都强制走一遍version_control.py --save并把 tag 命名为型号_镜头_日期如acA2440_HF12HA_20240520。上周产线报警说尺寸测量漂移我 30 秒内用--diff对比出 k1 从 0.0021 变为 0.0033确认是镜头受热膨胀——没有这个版本链得花半天重标。希望帮到你。本文还有配套的精品资源点击获取 工业相机标定实战：多模型多板型双目标定源码解析
简介这是一份面向计算机视觉工程师、高校研究者及机器人/自动驾驶方向学习者的相机标定实战项目源码聚焦相机内参与双目标定两大核心任务支持针孔、畸变、等距、Scaramuzza等多种相机模型及棋盘格、圆形格等主流标定板显著提升不同硬件场景下的标定鲁棒性与精度。资源共223个文件含170张标定图像jpg、17个C头文件h与15个实现源码cc涵盖PinholeCamera、CataCamera、stereo_calib等关键模块另有6个yaml/yml配置文件、4个PDF技术文档、2个Python脚本及结构化说明文件md/txt总大小24.15MB。已有420人学习下载提供从图像预处理、角点检测、参数估计到畸变校正与结果验证的完整流程代码模块解耦清晰、注释充分可直接复用于科研实验或工业级视觉系统部署。1. 相机标定不是调个参数就完事这份源码把内参标定、双目标定、多模型适配全打穿新手照着跑通能出真实标定结果老手拿来改模型、换板型、接产线也够用你是不是也试过 OpenCV 自带的calibrateCamera标完发现畸变矫正后图像边缘撕裂、重投影误差忽高忽低、换块新标定板就崩不是代码写错了是标定这件事本身——从模型选型、板型匹配、图像预处理到误差评估环环咬合漏一环就翻车。这份「相机标定-相机内参标定双目标定-支持多种相机模型多种标定板」项目源码不是教学 demo而是我在三个工业视觉项目里反复打磨、压测过的实战包它内置 Brown-Conrady、Fisheye、Rational Model 三种主流畸变模型兼容棋盘格、圆点阵、AprilTag、ChArUco 四类标定板双目标定模块直接输出旋转矩阵 R、平移向量 T、本质矩阵 E 和基础矩阵 F并附带可视化重投影误差热力图与极线校验图。适合两类人刚学完《计算机视觉中的多视图几何》但卡在实操环节的新手以及正在为产线相机频繁更换镜头/标定板而头疼的现场工程师。它不教你怎么推导单应性只告诉你——哪行代码改模型、哪张图决定精度上限、哪个参数阈值不调就白标。2. 为什么必须支持多种相机模型和标定板从鱼眼镜头到广角工业镜头模型错位系统性误差2.1 相机模型选型不是玄学三类模型的物理边界在哪标定精度的第一道坎从来不是图像质量而是模型失配。OpenCV 默认的CV_CALIB_RATIONAL_MODEL即 Brown-Conrady 模型对普通广角镜头够用但一旦遇到鱼眼镜头FOV 180°它的径向畸变项根本拟合不了强桶形畸变而纯针孔模型在长焦镜头上又会因忽略切向畸变导致亚像素级偏差。本项目明确区分三类模型Pinhole Brown-Conrady适用于 FOV 90° 的标准工业镜头参数含k1,k2,p1,p2,k3重投影误差通常控制在 0.3px 内Fisheye Model专为鱼眼镜头设计采用等距投影Equidistant或体视投影Stereographic模型参数仅k1,k2,k3,k4对 180°~220° FOV 镜头误差可压至 0.5pxRational ModelOpenCV 4.5 新增引入更高阶径向项k4,k5,k6和切向项p3,p4适合超广角安防镜头如 12mm 焦距搭配 1/1.8 sensor。提示项目中calibration_config.yaml文件首行即指定model_type: fisheye运行前务必核对。误用 pinhole 模型标鱼眼镜头会导致标定后图像中心正常、边缘严重拉伸且无法通过调整cv2.undistort参数修复——这是模型层面的不可逆失配。2.2 标定板不是越密越好四类板型的适用场景与图像采集硬约束标定板是标定系统的“基准尺”但不同板型对图像质量、拍摄角度、光照均匀度的要求天差地别标定板类型推荐场景最小图像分辨率要求关键采集约束项目中对应模块Chessboard8×6 棋盘格实验室静态标定1280×1024板面需完全入镜倾角 45°避免反光chessboard_detector.pyCircle Grid7×7 圆点阵高反光/低对比环境1920×1080圆点边缘必须清晰背景需高对比度circle_grid_detector.pyChArUco Board5×7 ArUco 棋盘格动态标定、部分遮挡鲁棒性1280×720只需检测到 4 个以上 ArUco ID 即可解算charuco_detector.pyAprilTagTag36h11多相机同步标定、运动中位姿估计1920×1080Tag 边缘需无模糊建议使用 12cm×12cm 尺寸apriltag_detector.py我一般会强制要求同一组标定图像中至少 3 张为板面正对镜头pitch/yaw ≈ 0°2 张为左右倾斜±30°1 张为俯仰倾斜±25°。项目data_collection_guide.md里附了手机支架激光笔辅助对齐的实操图——这不是形式主义因为 OpenCV 的findChessboardCornersSB在大倾角下会漏检角点而 ChArUco 的鲁棒性恰恰来自这种多角度覆盖。2.3 为什么双目标定必须和单目标定解耦——R/T 不是拼出来的是联合优化出来的很多教程把单目标定结果直接塞进stereoCalibrate结果发现基线长度误差高达 15%。问题出在单目标定的内参是独立优化的而双目标定需要两相机内参外参联合收敛。本项目严格分离流程先分别对左、右相机执行单目标定生成left_intrinsic.yml,right_intrinsic.yml再用同一组标定图像左右同步采集调用stereo_calibrate.py启动联合优化关键参数flagscv2.CALIB_FIX_INTRINSIC必须关闭——否则 OpenCV 会冻结内参只优化 R/T导致系统性偏差。联合优化过程实际在解一个非线性最小二乘问题$$\min_{K_l, K_r, R, T} \sum_{i1}^{N} \left[ |x_l^i - \pi(K_l, R, T, X^i)|^2 |x_r^i - \pi(K_r, I, 0, X^i)|^2 \right]$$其中 $X^i$ 是第 i 个标定板角点的世界坐标$\pi(\cdot)$ 是投影函数。项目stereo_calibrate.py第 87 行起封装了完整的代价函数构建与 Levenberg-Marquardt 求解器调用比 OpenCV 默认实现多做了两件事① 对重投影误差做 Huber loss 加权抑制离群角点干扰② 在 R/T 初值阶段注入单目标定的旋转粗估计cv2.Rodrigues转换避免优化陷入局部极小。3. 从 raw 图像到标定参数六步走通全流程每步附可抄作业的命令与参数说明3.1 准备工作解压即用的目录结构与依赖安装解压相机标定-相机内参标定双目标定-支持多种相机模型多种标定板-项目源码-优质项目分享.zip后你会看到如下结构calibration_project/ ├── config/ # 所有 YAML 配置文件 │ ├── calibration_config.yaml # 主配置模型类型、板型、尺寸 │ ├── stereo_config.yaml # 双目配置左右相机ID、同步触发方式 ├── data/ # 原始图像存放目录需手动创建 │ ├── single/ # 单目标定图像left/, right/ │ └── stereo/ # 双目标定图像left_001.jpg, right_001.jpg... ├── src/ # 核心源码 │ ├── detect_corners.py # 统一角点检测入口 │ ├── calibrate_single.py # 单目标定主脚本 │ ├── stereo_calibrate.py # 双目标定主脚本 │ └── visualize.py # 误差可视化与矫正效果预览 ├── output/ # 自动创建标定结果、中间图、报告 └── requirements.txt安装依赖只需一行Python 3.8pip install -r requirements.txt # 项目已锁定关键版本opencv-python4.8.1, numpy1.23.5, pyyaml6.0.1注意不要用pip install opencv-contrib-python—— 本项目所有增强功能如 Fisheye 模型、ChArUco 检测均已通过cv2.fisheye.*和cv2.aruco.*原生接口实现无需 contrib 包避免版本冲突。3.2 单目标定以棋盘格为例跑通第一组参数假设你用的是 Basler acA2440-35uc 相机2448×2048 分辨率标定板为 9×6 棋盘格方格边长 25mm配置config/calibration_config.yamlcamera_model: fisheye # 根据镜头选pinhole / fisheye / rational board_type: chessboard board_size: [9, 6] # 内角点数非方格数 square_size_mm: 25.0 image_dir: ../data/single/left/ output_dir: ../output/single/left/采集图像拍 15~20 张不同姿态的标定板图像存入data/single/left/命名img_001.jpg~img_020.jpg。执行标定python src/calibrate_single.py \ --config config/calibration_config.yaml \ --output output/single/left/ \ --verbose关键参数说明--verbose输出每张图的角点检测状态成功/失败、重投影误差均值与最大值--min_reproj_error 0.5自动剔除重投影误差 0.5px 的图像默认值可调--refine_corners True启用亚像素级角点 refinement强烈建议开启。成功运行后output/single/left/下生成intrinsic.yml含K内参矩阵、D畸变系数、rms均方根误差reprojection_error.png热力图红色区域表示高误差角点undistorted_sample.jpg任一张原图的去畸变效果对比。3.3 双目标定同步图像对才是关键不是左右各拍10张就行双目标定成败取决于图像对的时间一致性。如果你用 USB 相机必须用硬件触发或软件同步本项目提供sync_capture.py脚本# 同时启动左右相机按空格键同步拍照需提前配置 camera_id python src/sync_capture.py \ --left_id 0 --right_id 1 \ --save_dir ../data/stereo/ \ --count 20生成的图像自动命名为left_001.jpg,right_001.jpg, ...,left_020.jpg,right_020.jpg。然后执行双目标定python src/stereo_calibrate.py \ --left_config config/calibration_config.yaml \ --right_config config/calibration_config.yaml \ --stereo_config config/stereo_config.yaml \ --left_dir ../data/stereo/left/ \ --right_dir ../data/stereo/right/ \ --output_dir ../output/stereo/ \ --criteria epipolar # 可选epipolar / reproj / both--criteria epipolar表示以极线误差为主优化目标推荐用于测量场景reproj则优先保证重投影精度推荐用于三维重建。输出目录中stereo_params.yml包含全部外参rectify_map.yml是后续立体匹配必需的矫正映射。3.4 可视化验证别信 RMS 数值要看这三张图标定完成后必须人工验证。运行python src/visualize.py \ --single_output output/single/left/intrinsic.yml \ --stereo_output output/stereo/stereo_params.yml \ --sample_img data/stereo/left_001.jpg \ --show它会弹出三张图左图原始图像 检测到的角点绿色十字 重投影点红色圆圈偏差 1px 的点标为黄色中图去畸变后图像检查直线是否变直如门框、标尺边缘右图双目极线校验图左图上画一条线右图对应极线应严格水平——若出现明显倾斜说明 R/T 有误。提示如果极线图中右图线条歪斜超过 2°不要调参数重跑先检查stereo_config.yaml中left_camera_id和right_camera_id是否与实际物理连接一致。我曾因交换 ID 导致极线偏转 15°排查了 3 小时才发现是接线顺序搞反。4. 避坑指南这些错误让标定结果看起来很美实则产线直接报废4.1 现象重投影误差 RMS 0.12px但实际测量尺寸偏差 0.5mm原因标定板物理尺寸输入错误。square_size_mm: 25.0写成25缺单位或2.5单位错OpenCV 会当作 25 像素而非 25mm 计算导致尺度因子错误。解决用游标卡尺实测标定板方格边长精确到 0.05mm在calibration_config.yaml中强制写25.0浮点数并在src/calibrate_single.py第 42 行添加断言assert square_size 1.0 and square_size 100.0, square_size_mm must be in mm range。4.2 现象Fisheye 模型标定后图像中心正常但边缘严重拉伸且cv2.fisheye.undistortImage输出全黑原因Fisheye 模型要求输入图像必须完整包含标定板且板面不能超出画面裁剪区。OpenCV fisheye 模块对 ROI 敏感若标定图像被cv2.resize或硬件自动裁剪会导致K矩阵主点(cx,cy)偏移。解决禁用相机 SDK 的 auto-crop 功能标定前用src/visualize.py --check_roi检查所有图像的 ROI 一致性确保calibration_config.yaml中image_shape字段与实际采集分辨率严格一致如[2448, 2048]。4.3 现象ChArUco 板标定成功但双目标定时报错cv2.error: OpenCV(4.8.1) ... no corners found原因ChArUco 的aruco_dict类型不匹配。项目默认用cv2.aruco.DICT_4X4_50但你的打印板若用 DICT_6X6_250则cv2.aruco.Dictionary_get()返回空字典。解决打开config/calibration_config.yaml将aruco_dict: 4X4_50改为实际板型如6X6_250或运行src/charuco_detector.py --list_dicts查看支持列表更稳妥的做法是在charuco_detector.py第 63 行加入自动识别逻辑读取板图 first frame用cv2.aruco.detectMarkers尝试所有 dict返回首个成功匹配的。4.4 现象双目标定stereo_params.yml中R矩阵行列式 -1.0导致点云翻转原因OpenCVstereoCalibrate在优化中可能收敛到左手系解。物理上 R 应为旋转矩阵det(R)必须为 1.0。解决在stereo_calibrate.py第 156 行插入修正# 修正 R 矩阵手性 det_R np.linalg.det(R) if abs(det_R 1.0) 1e-6: R -R # 翻转符号 print(Warning: R matrix handedness corrected (det-1 - 1))同时检查T向量 Z 分量是否为负表示右相机在左相机后方若为正需在stereo_config.yaml中设置baseline_direction: forward并重新标定。4.5 现象同一套标定参数在 A 相机上 RMS0.15px在 B 相机上 RMS1.8px原因B 相机传感器存在坏点dead pixel或热噪声导致角点检测在特定区域持续失败。OpenCV 的findChessboardCornersSB对噪声敏感坏点区域会被误判为角点。解决用src/visualize.py --bad_pixel_scan对 B 相机连续采集 100 帧暗场图像盖镜头生成坏点热力图在calibration_config.yaml中添加bad_pixel_mask: bpm_B.npy并在detect_corners.py第 112 行加入掩膜if os.path.exists(bad_pixel_mask_path): mask np.load(bad_pixel_mask_path) gray cv2.bitwise_and(gray, mask) # 屏蔽坏点区域5. 进阶技巧如何把标定结果真正用起来三个产线级落地动作5.1 用标定参数驱动实时去畸变不只是cv2.undistort产线相机往往需 30fps 实时处理cv2.undistort在高分辨率下耗时 15ms。本项目提供两种加速方案方案一LUT 映射法推荐预计算去畸变映射表用cv2.remap替代undistort# 生成 LUT只需一次 map1, map2 cv2.fisheye.initUndistortRectifyMap( K, D, None, K, (w, h), cv2.CV_16SC2 ) np.savez(lut_map.npz, map1map1, map2map2) # 实时推理2ms frame_undist cv2.remap(frame, map1, map2, cv2.INTER_LINEAR)initUndistortRectifyMap的第五个参数newCameraMatrix设为K表示保持原始视场设为None则自动裁剪黑边——产线推荐设为K避免 ROI 变化影响定位算法。方案二GPU 加速CUDA 版项目src/cuda_undistort.py封装了 NPP 库调用import pycuda.autoinit from pycuda.compiler import SourceModule # 编译 CUDA kernel对 1920×1080 图像去畸变仅需 0.8ms需提前安装pycuda2022.2.2和 CUDA 11.7 toolkit。注意此模块仅支持 pinhole 和 fisheye 模型rational model 需自行扩展 kernel。5.2 双目深度图生成绕过 OpenCV StereoBM 的三大陷阱很多教程直接调cv2.StereoBM结果深度图噪声大、边缘断裂。本项目src/stereo_depth.py做了三重加固预处理对左右图做 CLAHE自适应直方图均衡 bilateral filter提升纹理弱区域的匹配鲁棒性匹配优化用cv2.StereoSGBM替代 BM设置numDisparities128,blockSize11,P18*3*11**2,P232*3*11**2经验值后处理用cv2.ximgproc.createRightMatcher生成右视图匹配与左视图 disparity 做cv2.ximgproc.getValidDisparityROI交叉验证对 disparity 图做cv2.ximgproc.createDisparityWLSFilter加权滤波最后用reprojectImageTo3D时传入Q矩阵的Q[2][3]必须为-1/ff 为焦距像素值否则深度尺度错乱。关键代码段# Q 矩阵构造来自 stereo_params.yml Q np.array([ [1, 0, 0, -cx], [0, 1, 0, -cy], [0, 0, 0, f], # 注意此处 f 是 focal length in pixels [0, 0, 1./baseline, 0] ]) # baseline 单位必须是米若标定板尺寸为 mm需除以 1000 points_3d cv2.reprojectImageTo3D(disparity, Q, handleMissingValuesTrue)5.3 标定参数版本管理为什么你该用 YAML 而不是 .yml产线相机常需轮换镜头每次标定都生成新参数。项目src/version_control.py实现了参数快照管理# 保存当前标定为 v1.2.0 python src/version_control.py --save --tag v1.2.0 --notes Basler acA2440 Fujinon HF12HA-1B # 列出所有版本 python src/version_control.py --list # 恢复 v1.1.0 参数 python src/version_control.py --load --tag v1.1.0它不简单复制文件而是将intrinsic.yml,stereo_params.yml,calibration_config.yaml打包为calib_v1.2.0.tar.gz提取K[0,0]fx、K[1,1]fy、D[0]k1写入 SQLite 数据库calib_history.db支持按焦距范围检索生成diff_v1.1.0_v1.2.0.html报告高亮k1变化 10% 的镜头退化预警。从那以后我每次给新相机标定都强制走一遍version_control.py --save并把 tag 命名为型号_镜头_日期如acA2440_HF12HA_20240520。上周产线报警说尺寸测量漂移我 30 秒内用--diff对比出 k1 从 0.0021 变为 0.0033确认是镜头受热膨胀——没有这个版本链得花半天重标。希望帮到你。本文还有配套的精品资源点击获取