简介：ProCamCalib是一套用于投影仪-相机系统几何与颜色校准的用户友好型Java工具，面向计算机视觉研究者、工业视觉工程师及高校实验室，尤其适用于投影交互、结构光重建、多相机与投影仪协同标定等场景，可有效解决坐标对齐和颜色一致性问题。压缩包共含24个文件，以Java源码、XML配置、PNG/GIF图像、cmd启动脚本及Markdown文档为主，涵盖核心算法、配置项、实验可视化与使用说明，整体仅52KB，轻量便于携带与二次开发。目前已有430人学习/下载。同时附带完整工程源码与跨平台运行脚本（支持Linux、Mac OS X、Windows），并通过配套说明文档阐述校准思路：以第一台相机为参考进行立体标定，校准板需在所有相机中保持可见，支持多相机与投影仪配置，亦适用于纯相机系统的Fiala方法拓展。对于需要搭建投影-相机标定实验环境的开发者，可直接运行、可修改学习，是实用的参考工具包。
1. procamcalib 到底解决了什么问题：从一次投影歪斜说起
做互动投影或结构光三维重建的工程师，多半都经历过这种场面：投影仪明明投得很正，相机也拍到了画面，可一叠加虚拟内容，边界就是错位的。手动调投影梯形校正，调完一个角度又歪了。这个问题的本质是相机和投影仪之间的几何关系没有建立起来，也就是没有做系统标定。procamcalib 就是一套专门用来校准相机与投影仪-相机系统的工具包，它把整个标定流程打包成图像采集、角点检测、对应点映射、参数优化几个环节，输出相机和投影仪的内外参以及两者之间的单应性矩阵。适合要做投影增强现实、三维扫描、投影互动墙，又不想从零啃数学原理的开发者。它用 Java 实现，接入现有系统比较方便。
2. 相机-投影仪标定的数学原理：单应性、内参和畸变，一个都不能少
2.1 为什么不能拿相机标定流程硬套投影仪
相机标定的经典流程是让相机拍摄不同位姿的棋盘格，通过角点对应关系求解内参和畸变。但投影仪不是成像设备，它不会自己“看”棋盘格，它只能投射棋盘格图案。从硬件结构看，投影仪可以理解为一个逆相机——光线走向相反，镜头模型和针孔模型一致，原理上可以用同样的数学模型描述。问题在于，相机标定时棋盘格的物理位置已知，而投影仪标定时，投影出来的棋盘格被投影到某个平面上，它的物理坐标取决于投影仪内参和平面位置，是个未知量。
所以常见的做法是引入相机作为中介：让投影仪投射图案到某个平面上，相机同时拍摄这个图案。因为相机已经单独标定过，可以借助相机图像坐标反推出投影仪像素坐标在相机图像平面的位置，再建立投影仪像素与相机像素的对应关系，进而把投影仪当作一台“反向相机”来标定。procamcalib 内部就是按这个思路组织流程的。如果不理解这层关系，直接拿相机标定代码跑投影仪数据，结果往往是内参矩阵收敛到错误值，重投影误差看起来很低，实际投影却对不上。这是一个很典型的“黑匣子”陷阱——数值结果漂亮但不代表物理正确。
2.2 单应性矩阵与投影仪像素映射的计算要点
当标定平面固定不动时，相机图像平面和投影仪图像平面之间存在一个平面单应性变换。假设平面上一点的三维坐标为 (X, Y, Z)，它在相机图像上的齐次坐标为 [u_c, v_c, 1]^T，在投影仪图像上的齐次坐标为 [u_p, v_p, 1]^T。因为点都在同一个平面，Z = 0，所以两者之间可以用一个 3×3 的矩阵 H 来表示：
[u_p, v_p, 1]^T = H · [u_c, v_c, 1]^T
这里 H 就是所谓的单应性矩阵。单应性矩阵的自由度是 8，理论上只需要 4 对非共线的对应点就能求解。实际中为了抑制噪声，会采集几十对点，再用直接线性变换加 RANSAC 或最小二乘来估计，OpenCV 的findHomography就是这个套路。
// 假设已经检测到相机棋盘格角点列表 cameraCorners // 以及对应的投影仪角点列表 projectorCorners // 用 OpenCV Java 接口计算单应性矩阵 Mat H = Calib3d.findHomography(cameraCorners, projectorCorners, Calib3d.RANSAC, 3.0); // 第三个参数是方法，第四个参数是重投影误差阈值这段代码里的cameraCorners是相机图像上棋盘格角点的坐标，projectorCorners是同一角点在投影仪图像坐标中的位置。这里有一个关键点：投影仪图像坐标不是直接测量出来的，而是通过投影编码图案解码得到的。后面会讲这一步怎么实现。findHomography返回的是一个 3x3 的矩阵，保存成文件后，运行时直接做矩阵乘法就能把相机坐标换算成投影仪坐标。注意 RANSAC 的误差阈值设在 2.0 到 4.0 像素之间比较合适，太严会丢掉过多点，太松会把错误匹配当成内点。
3. procamcalib 的模块拆解：从图像采集到参数输出
3.1 图像采集与棋盘格检测：保证多视角覆盖
procamcalib 的第一步是准备一组标定板图像。标定板通常是一个平面棋盘格，可以打印出来贴在硬板上。相机单独拍摄棋盘格在不同位姿下的图像，用来获得相机自身的标定结果，以及提取角点作为后续对应的基准。这一步的核心不在于拍多少张，而在于覆盖视角的多样性——四个角落、中间区域、倾斜角度、远近变化，至少要拍 15 到 20 张。如果全部对着一个方向，后续优化时概率上会退化，内参在某个方向上精度很差。
常见做法是：把棋盘格贴在刚性平整的底板上，或者直接使用校准好的显示屏显示棋盘格，但投影仪标定场景下尽量用物理打印板，避免屏幕反光干扰相机。每个位姿拍一张照片，拍照时确保棋盘格完全在相机视野内，同时让投影仪投射的图案不要照亮棋盘格，否则会影响角点检测。拍完后，用 OpenCV 的findChessboardCorners自动检测角点，如果检测失败就调整阈值或补拍，不要硬凑数量。
// Java 示例：读取一张标定图片，检测棋盘格角点 Mat img = Imgcodecs.imread("calib_01.jpg", Imgcodecs.IMREAD_GRAYSCALE); Size boardSize = new Size(9, 6); // 棋盘格内角点数量，9列6行 MatOfPoint2f corners = new MatOfPoint2f(); boolean found = Calib3d.findChessboardCorners(img, boardSize, corners); if (found) { // 亚像素细化，提高角点精度 TermCriteria criteria = new TermCriteria(TermCriteria.EPS + TermCriteria.MAX_ITER, 30, 0.001); Imgproc.cornerSubPix(img, corners, new Size(5, 5), new Size(-1, -1), criteria); }注意这里的boardSize是内角点数量，不是棋盘格方块数量。比如 9x6 表示角点排列是 9 列 6 行。亚像素细化很关键，投影场景下图像可能会有点糊，粗略角点直接用于计算会导致单应性矩阵的精度下不去。
3.2 投影仪对应点建立：编码图案与相位映射
要标定投影仪，必须知道投影仪像素坐标和相机图像坐标的对应关系。这个关系没办法直接拍摄得到，因为投影仪投出的图案经过平面反射才进入相机，中间有相机内外参和平面畸变。最常用的方案是投射一组结构光编码图案，让每个相机像素都能解码出它接收到的是来自投影仪的哪个像素。
procamcalib 常用的编码方式有两种：格雷码和相移条纹。格雷码是一系列黑白相间的条纹图，按二进制编码，比如投 8 幅图就能编码出 2^8 = 256 个横向坐标；相移条纹则用多步相移图，通过相位计算得到亚像素精度。实际工程中一般把两者结合：先用格雷码做粗定位，再用相移做亚像素细化。这样每个相机像素都能得到投影仪像素坐标，精度能到 0.1 像素级别。
这一步的坑在于：解码时要注意投影仪的伽马响应和相机的曝光一致性。如果曝光过度，条纹的黑白区域会失真，相位计算会发生跳变。我通常会在正常曝光基础上降一档曝光，保证白色条纹不至于饱和。解码后的对应关系可以表示成一个三维数组：相机坐标 (u, v) 对应投影仪坐标 (u_p, v_p)。你在采集时只要同步保存相机拍摄的编码图序列，后处理阶段逐像素计算即可。
3.3 参数优化与输出：LM 迭代与重投影误差验证
有了投影仪对应点之后，剩下的工作就是联合优化相机和投影仪的内参、畸变系数以及每一帧标定板相对于相机的姿态。这里用到的是经典的光束平差法，具体实现中通常封装了 Levenberg-Marquardt 迭代。procamcalib 把这一步做成了黑盒，你只需要传入标定板角点、投影仪对应点和初始内参猜测值，工具会输出最终的相机内参、投影仪内参、畸变系数以及每一帧的外参。
优化过程要关注两个指标：一个是相机自身的重投影误差，另一个是投影仪的重投影误差。相机重投影误差是 3D 角点投影回相机图像的误差，投影仪重投影误差是把对应点投影到投影仪图像后的误差。理想情况下两者都应该低于 0.5 像素。如果投影仪重投影误差明显大于相机，通常说明编码解码阶段的亚像素精度不够，或者投影仪的畸变模型没有选对。procamcalib 默认使用径向畸变加切向畸变的 5 参数模型，但在某些短焦投影仪上可能需要额外的系数，这一点在配置里可以调整。
4. 用 Java 复现一个最小校准流程：代码与参数
4.1 环境准备与依赖
既然关键词是 Java，我们就按 Java + OpenCV 的环境来准备。首先确保你机器上有 JDK 8 或更高版本，然后下载 OpenCV 的 Java 绑定包，里面包含opencv-xxx.jar和对应的libopencv_java520.so或.dll文件。如果用 Maven 管理依赖，可以引入 OpenCV 的封装库，但更常见的是直接把 jar 放进classpath，并把原生库路径添加到 JVM 启动参数里。
-Djava.library.path=/path/to/opencv/libs我用过org.bytedeco:javacv这类封装，但对初中级用户来说，官方 OpenCV Java 绑定最省心。下面是本地目录的依赖结构，很清晰，不用纠结版本冲突：
/lab /lib opencv-520.jar libopencv_java520.so /src ProcamCalib.java /data /captures运行前把相机拍摄的标定板图片放到data/captures目录。这个路径在配置里可以改，但建议一开始就用绝对路径避免摸不着头脑。
4.2 核心代码：角点检测与单应性计算
下面这段代码是我习惯的最小实现：读取所有棋盘格图片，检测角点，建立相机坐标列表。实际 procamcalib 会额外读取投影仪对应点，但这里先演示相机侧的流程，让新手能跑通第一步。
import org.opencv.core.*; import org.opencv.imgcodecs.Imgcodecs; import org.opencv.calib3d.Calib3d; import org.opencv.imgproc.Imgproc; import java.io.File; import java.util.ArrayList; import java.util.List; public class ProcamCalib { public static void main(String[] args) { System.loadLibrary(Core.NATIVE_LIBRARY_NAME); Size patternSize = new Size(9, 6); // 棋盘格内角点 List<Mat> imagePoints = new ArrayList<>(); List<String> fileList = getAllFiles("data/captures", ".jpg"); for (String file : fileList) { Mat img = Imgcodecs.imread(file, Imgcodecs.IMREAD_GRAYSCALE); MatOfPoint2f corners = new MatOfPoint2f(); if (Calib3d.findChessboardCorners(img, patternSize, corners)) { TermCriteria criteria = new TermCriteria( TermCriteria.EPS + TermCriteria.MAX_ITER, 30, 0.001); Imgproc.cornerSubPix(img, corners, new Size(5, 5), new Size(-1, -1), criteria); imagePoints.add(corners); // 收集这一帧的所有角点 } else { System.out.println("跳过" + file + "（未检测到棋盘格）"); } } System.out.println("有效图像数量: " + imagePoints.size()); } private static List<String> getAllFiles(String dir, String suffix) { List<String> list = new ArrayList<>(); File folder = new File(dir); if (folder.isDirectory()) { for (File f : folder.listFiles()) { if (f.getName().endsWith(suffix)) list.add(f.getAbsolutePath()); } } return list; } }代码逻辑很直接：patternSize是角点规模，cornerSubPix是亚像素细化，TermCriteria.EPS + MAX_ITER表示同时用误差阈值和迭代次数控制结束条件。30是最大迭代次数，0.001是角点位置变化的阈值。这个参数不用反复调，默认值在绝大多数场景都够用。如果检测失败，优先检查棋盘格打印是否清晰、光照是否均匀，而不是去调整算法参数。
4.3 运行参数说明与结果解读
运行上述代码后，控制台会打印有效图像数量。正常来说，你准备的 20 张图里至少有 15 张能检测通过。如果只有个位数，说明拍照质量有问题——可能是棋盘格反光、图片模糊或者棋盘格占比太小。
接下来引入投影仪对应点数据后，procamcalib 会输出一个标定文件，内容大致是下面的结构：
cameraMatrix: [fx 0 cx; 0 fy cy; 0 0 1] distCoeffs: [k1, k2, p1, p2, k3] projectorMatrix: [fx_p 0 cx_p; 0 fy_p cy_p; 0 0 1] projectorDistCoeffs: [...] extrinsics: [R | t] // 每帧一个拿到这些参数后，验证方式很简单：投影仪投射一个点，相机里找这个点的图像坐标，然后用单应性矩阵把相机坐标映射回投影仪坐标，看映射结果和实际投影位置差多少。如果误差在 1 像素以内，说明标定合格；如果差 5 像素以上，先不要怀疑参数文件，回头查一下解码环节。
5. 避坑指南：五个校准翻车现场与排查方法
5.1 现象：重投影误差很低，但投影总是歪的
原因：单应性矩阵只描述了某一特定平面的映射关系，如果你的系统规划是用在非固定距离的平面上，单靠单应性是不够的，还需要完整的相机-投影仪外参和平面位置。有些工具只输出单应性，拿到手后换了投影距离就不准了。
解决：请确认你使用的标定结果是否包含相机内参、投影仪内参和两者外参。如果只有单应性，那只能用于平面固定场景。procamcalib 里如果选择了“完整标定模式”，输出里会有两张表：一张是单应性矩阵（给平面场景用），一张是完整的相机-投影仪参数（给任意场景用）。平面互动投影用单应性就够了，结构光重建必须用完整参数。
5.2 现象：棋盘格角点检测全乱，不少图被跳过
原因：最常见的是打印的棋盘格不干净，或者拍照时棋盘格部分被遮挡；另一个高频原因是棋盘格在图像里的面积太小，角点被压缩成一片模糊。
解决：让棋盘格占据图像画面的 50% 以上；拍照时保证棋盘格平整，不要有纸张褶皱；如果背景有强反光物，调整灯光方向或使用偏光镜。我在一次拍摄中，因为背景有白墙，反光导致棋盘格边缘发白，角点检测率直接降到 30%，后来把背景用黑色绒布遮挡就好了。
5.3 现象：拍出来的编码图案过曝，相位信息丢失
原因：编码图案里白色区域像素值饱和到 255，解码时相位计算出现平台区，条纹边缘出现跳变，最后的对应点会有大量离群值。
解决：降低曝光时间或增益，观察直方图，让白色区域像素值在 220 到 245 之间。很多相机默认自动曝光，记得关掉自动曝光，锁定手动曝光参数。再不行就调低投影仪亮度。这一步看起来简单，却是最多人翻车的点。
5.4 现象：投影仪光斑影响相机白平衡，颜色波动导致角点提取不稳定
原因：投影仪的光源色温不稳定，或者相机开了自动白平衡，导致不同编码图案下灰度值整体偏移，检测器使用固定阈值时不稳定。
解决：关掉相机自动白平衡，改为手动设置。如果相机没有手动白平衡，可以投一张全白图，用相机拍摄后做单通道灰度归一化，抵消光照不均匀。更彻底的做法是用灰色编码图案代替彩色编码，减少色温影响。
5.5 现象：标定板不平整，标定结果反复变化
原因：纸张贴在硬纸板上时如果有微小弯曲，或者标定板放在不平的桌面，角点的三维坐标就不在一个平面上，破坏了单应性模型的假设。
解决：把棋盘格打印后用双面胶贴在一个高平整度的铝板上，标定过程中不要移动标定板位置，只转动方向。另外，不要用手去按压棋盘格中间。曾经有一次我的标定板中间有个小气泡，重投影误差始终在 0.8 像素附近波动，换上刚性底板后直接降到 0.3，说明问题出在板上而不是算法上。
6. 进阶技巧：先粗标定再精标定，用重投影误差自动筛选图像
在标定样本质量参差不齐时，全量图像参与优化反而会拖垮结果。我的习惯是分两轮走：第一轮用所有检测成功的图像做一次粗标定，拿到相机内参和畸变；第二轮计算每幅图像的重投影误差，把误差最大的几幅图剔除掉，只保留误差小于阈值的图像做精标定。这个方法不需要额外硬件，效果却立竿见影。
for (int i = 0; i < imagePoints.size(); i++) { double err = Calib3d.computeReprojectionErrors( objectPoints.get(i), imagePoints.get(i), rvecs.get(i), tvecs.get(i), cameraMatrix, distCoeffs); if (err < 0.3) { // 阈值按项目精度要求调整 goodImages.add(imagePoints.get(i)); } else { System.out.println("剔除误差过大图像: " + i + " 误差=" + err); } }computeReprojectionErrors会把你当前标定的相机参数投影到图像空间，和实际检测到的角点求平均距离。误差单位是像素，0.3 对一个 200 万像素的相机来说是中等严格程度。如果整套流程重投影误差都不超过 0.3，说明图像质量已经很好，可以继续精标定；如果普遍在 0.5 以上，说明某一步的系统误差没有消除，先不要筛选，回头检查曝光和对应点解码。
这个筛选逻辑同样适用于投影仪对应点数据。一次完整的 procamcalib 流程中，我的建议是：先粗标定，再剔除重投影误差最大的 20% 的图像，然后精标定。这样做的代价只是多跑一遍迭代，收益是参数稳定性大幅提升。从那以后我每次标定都会强制走一遍这个筛选，宁可少几张图也不让坏数据污染整体解。希望这个做法能帮你把标定时间缩到原来的一半，少走几次“误差低但投影歪”的弯路。
本文还有配套的精品资源，点击获取
