简介：ProCamCalib是一套用户友好的投影仪-相机系统几何与颜色校准工具，采用Java编写，面向计算机视觉、增强现实及科研实验等应用场景。它支持多台相机与零个或多个投影仪的组合配置，以第一台相机为基准对所有设备进行立体标定，能够同时完成几何与颜色校准；使用中需要标定板在所有相机内保持可见，目前尚未进行全局优化。纯相机系统也可直接使用，等效实现了Fiala的经典标定方法，相关内容可参考作者发表的Procams 2009论文。在搭建多投影显示系统或进行光学测量时，几何与颜色校准是不可或缺的环节，该工具恰好提供一个可运行的参考实现。压缩包包含24个文件，以PNG图片、Java源码、XML配置文件、CMD启动脚本、MD说明文档为主，同时附带JAR可执行包、Maven构建结构和授权/变更记录，便于在Linux、Mac OS X、Windows下直接运行或二次开发；整体体积仅52KB，轻量且结构清晰。目前已有430人学习或下载，适合需要快速搭建投影-相机标定环境、研究多设备联合校准算法细节的中高级视觉开发者。
1. procamcalib：投影仪-相机系统标定，把“看不见的投影仪”变成一台可计算的相机
做结构光三维重建或投影增强现实时，相机和投影仪组合是常见配置。相机标定有现成方案，投影仪却难倒不少人——它只能往外投光，不能主动感知外界，标定参数几乎全靠间接推算。procamcalib 就是解决这个问题的工具：把投影仪当作“逆相机”，用投影图案和相机采集图之间的对应关系，一次性求得相机内参、投影仪内参以及两者的外参。想做三维扫描、投影映射或设备标定的开发者，这款工具能把标定时间从按天算缩短到按小时算。Java 工程里集成它不用重写算法，走子进程调用即可。这篇笔记按实际拆过一遍的流程讲清楚：原理、Java 集成、参数怎么调、哪些坑必须躲。
2. 标定原理与选型：投影仪是“逆相机”，procamcalib 如何描述它
2.1 投影仪的数学模型：内参、外参与畸变系数
先想一个问题：标定相机，是让相机去看位置已知的棋盘格，根据角点的图像坐标反推内参和外参。投影仪没有感光元件，没法直接“看”任何东西。常见做法是给投影仪投一张带特征点的图案，再用已经标定过的相机去拍投影画面，从相机图像里找到投影特征点的像素坐标。这样一来，投影仪的每个像素坐标和它在相机图像中的像素坐标之间形成了一组一一对应关系。
procamcalib 正是基于这一思路设计：把投影仪抽象成“逆相机”模型，投影仪的像素平面就是成像平面，投影光线从光心射出，打在物体表面，反射进相机。数学上，投影仪的投影行为与相机成像共享同一套针孔模型，只是光线方向相反。标定要解的未知量包括投影仪内参矩阵里的 fx、fy（像素焦距）、cx、cy（主点坐标），以及径向畸变系数 k1、k2（可选 k3）和切向畸变系数 p1、p2。外参则是投影仪坐标系相对相机坐标系的旋转矩阵 R 和平移向量 T。
整个映射关系可以拆成两步：三维点变换到相机坐标系，再投影到相机图像平面；同一个三维点也能变换到投影仪坐标系，投到投影仪像素平面。两个投影关系共享同一个三维场景点，因此只要特征点匹配数量足够，就能把相机和投影仪的内外参数一起解出来。这里有个容易漏掉的细节：投影仪的“图像平面”并不是物理上的感光元件，而是 DMD 芯片上的微镜阵列，它的像素坐标是离散的、有明确物理尺寸的，所以标定出来的焦距单位同样是像素，和相机内参可以直接类比。
2.2 特征点方案与选型：procamcalib 用什么找对应点
建立对应关系绕不开特征点这一层。procamcalib 提供两类标定图案：圆点阵列和棋盘格。圆点阵列的质心检测精度高，对投影失焦不敏感；棋盘格角点检测速度快，但投影模糊时角点定位容易漂移。做投影仪标定，我优先选圆点阵列，因为投影仪的景深通常很浅，投出去的画面边缘往往是模糊的，圆点质心在模糊条件下比棋盘格角点稳得多。
这也解释了为什么选 procamcalib 而不是自己在 OpenCV 里拼一个流程。自己拼要处理的事情很琐碎：编解码投影图案、生成格雷码序列或相移序列、对采集图做角点或圆点提取、剔除误匹配、做捆绑调整（Bundle Adjustment）。每一步都有单独的实现，但串起来调通，一两个星期就搭进去了。procamcalib 把特征提取、对应关系建立和参数优化打包成一条完整管线，输入是标定图案和采集图像序列，输出是相机内参、投影仪内参和两者间外参。
从工程集成角度看，procamcalib 本体是 Python 生态，依赖 OpenCV 和 NumPy。Java 工程直接嵌入不现实，我一般用两条路：封装成 Python 命令行工具，Java 用进程调用方式交互，标定参数以 JSON 落盘；或者起一个本地 Python HTTP 服务，Java 通过 REST 接口提交图像、拿回标定结果。前者代码洁癖友好，不引入额外中间件；后者适合图像吞吐量大的场景。两种方式各有边界，选型出发点都在于标定是离线流程，不需要追求毫秒级响应。
3. Java 侧调用 procamcalib：从环境准备到第一步标定结果
3.1 环境准备与标定图案生成
标定之前先把环境装好。Python 环境需要 3.8 以上，装 numpy、opencv-python、pyjson5 等依赖。procamcalib 本体我通常拉源码后直接 import，不装到系统库里，避免和其他项目的 OpenCV 版本打架。装好后第一步是生成标定图案——不能直接用电脑屏幕上的静态图去标定，必须让图案经过投影仪真实投影出来。
生成图案这一步，脚本会输出一张和投影仪分辨率一致的灰度图。投影仪分辨率决定图案的像素尺寸，比如一台 1920×1080 的投影仪，生成图案就该是 1920×1080，否则投出来的特征点像素坐标会和设计坐标对不上，后续对应关系建立时每一组点都带一个系统性偏移。
# 生成标定图案：圆点阵列，编码为可投影的灰度图 import cv2 import numpy as np cols, rows = 15, 11 # 每行列数、行数（不含外边框） dot_diameter = 18 # 圆点直径（像素） pattern = np.zeros((1080, 1920), dtype=np.uint8) # 与投影仪分辨率一致 centers = [] x_start, y_start = 120, 120 spacing_x = (1920 - 2 * x_start) // (cols - 1) spacing_y = (1080 - 2 * y_start) // (rows - 1) for r in range(rows): for c in range(cols): cx, cy = x_start + c * spacing_x, y_start + r * spacing_y centers.append((cx, cy)) cv2.circle(pattern, (cx, cy), dot_diameter // 2, 255, -1) cv2.imwrite("calib_pattern.png", pattern) print("生成图案，圆点总数：", len(centers))这段代码生成一张白底黑点的图案。参数上有一组关联关系要注意：圆点直径越大，抗失焦能力越强，但点间距离会被压缩；点间距太小，投影模糊后相邻圆点可能连成一片，提取时会当成一个椭圆。我一般把圆点直径控制在点间距的 30%～40%，比如点间距 60 像素时，直径取 18～24 像素。投影距离越远，投出的圆点实际尺寸越大，采样时画面上相邻圆点是否粘连，直接决定这组数据能不能用。
3.2 图像采集与 Java 调用流程
图案准备好后，把投影仪对准一面平整的墙或白色平板，相机固定在另一侧，和投影仪形成一个三角关系。接下来至少采集 12～15 组图像，每组包含一张投影图案的相机拍摄图和一张对应的投影图案原图。拍摄时注意变化标定板的位姿——前后移动、左右倾斜、旋转角度都来几组，把视野内不同区域都覆盖到。
采集完成的图像序列交给 Java 后端处理。Java 这边不算标定，而是通过 ProcessBuilder 把图像目录路径传给 Python 脚本，脚本内部跑 procamcalib 标定主流程，最后输出 JSON 文件。以下是 Java 侧调用代码：
// Java 调用 procamcalib 标定脚本，传入图像目录并取回 JSON 结果 import java.io.BufferedReader; import java.io.InputStreamReader; import java.util.ArrayList; import java.util.List; public class ProcamCalibRunner { public static String runCalibration(String pythonScript, String imageDir) throws Exception { // 拼装命令行：python3 脚本路径 图像目录 输出路径 List<String> command = new ArrayList<>(); command.add("python3"); command.add(pythonScript); command.add("--images=" + imageDir); command.add("--output=/tmp/procam_calib_result.json"); ProcessBuilder pb = new ProcessBuilder(command); pb.redirectErrorStream(true); // 把 stderr 合并到 stdout，便于日志排查 Process process = pb.start(); StringBuilder output = new StringBuilder(); try (BufferedReader reader = new BufferedReader( new InputStreamReader(process.getInputStream()))) { String line; while ((line = reader.readLine()) != null) { output.append(line).append("\n"); } } int exitCode = process.waitFor(); if (exitCode != 0) { throw new RuntimeException("标定脚本退出码不为0: " + output); } return output.toString(); } }这段 Java 代码做的事情很直接：拼命令、起子进程、合并读输出、判断退出码。要注意 redirectErrorStream(true) 这一行，如果不加，标定脚本打印到 stderr 的进度和 OpenCV 报错信息会丢失，失败时只看到一个莫名其妙的空输出。另一个常见坑是 ProcessBuilder 的工作目录：脚本里如果用了相对路径导包，必须在执行前通过 pb.directory() 把工作目录切到脚本所在目录，否则 import 直接失败。
3.3 核心参数解析与首轮标定输出解读
跑完标定后，输出 JSON 里最关键的字段是相机内参、投影仪内参和外参。第一次拿到结果别急着往下做，先逐个核对量级。以 1920×1080 的常见配置为例，相机和投影仪的 fx、fy 应该在 1000～2000 之间；主点 cx、cy 应该接近分辨率中心（960、540），偏差超过 200 像素就说明标定过程没收敛。
外参部分读起来不直观，常见做法是把旋转向量转成欧拉角。欧拉角量级取决于装置摆放：投影仪和相机大致平行时，旋转角应在正负 15 度以内；平移距离应该和实际摆放的基线长度一致，偏差超过 50% 就要回查采集环节。
首轮标定结束后，最该看的是重投影误差（reprojection error）。它表示检测到的特征点位置和根据标定参数重投影回去的位置之间的像素偏差。正常应低于 0.6 像素；超过 1.0 先别急，下一章专门说怎么压下来。我通常把首轮输出保存成文件存档，后面每次调参都对比这版基线，判断改动带来的变化是正向还是负向。
4. 参数调优与数据清洗：把重投影误差从 1.0 压到 0.3
4.1 特征提取参数：阈值、窗口与投影光强
第一轮标定跑完，重投影误差偏高是常态。拆过的几个标定场景里，误差高的原因一半在特征提取参数，一半在数据本身。procamcalib 的特征提取环节有一个灰度阈值参数，决定哪些像素被当作圆点候选。投影仪投出来的画面亮度不均、四角偏暗、中心偏亮，用一个全局阈值去切图，中心和四角的检测结果会不一致。
常见解决办法是把全局阈值改成自适应阈值，或者调整投影仪亮度输出，让投出来的灰阶范围稳定在相机图像灰度值的 120～220 之间。相机曝光时间也很关键：曝光太长，圆点溢白，质心计算整体偏移；曝光太短，暗部圆点消失在噪声里。我一般先把投影亮度调到中档，再调相机增益和曝光，确保采集图里圆点和背景对比度不低于 30 个灰度级。具体操作时，可以在相机 SDK 里固定曝光时间，比如设定 8 毫秒到 15 毫秒之间，再根据采集图直方图微调。
另一个被忽略的参数是圆点检测的最小半径和最大半径。投影距离越远，投出的圆点越大，半径范围设置太窄，远处采集的圆点会被过滤掉，相当于白丢一批有效样本。匹配前先看一眼各帧圆点半径分布，跨度超过一倍时就把最小半径和最大半径放宽，这个参数宁可设宽一点，反正后面还有残差筛选把关。
4.2 样本筛选策略：哪些帧该删，哪些帧必须留
数据筛选是标定里最像“玄学”的环节，但背后有规律。核心原则是姿态多样性：整个图像序列里，标定板的位姿必须分布均匀。如果你只平移标定板，所有位姿都在同一平面上旋转，外参的深度信息就约束不住，重投影误差看起来降了，实际用起来却会偏。所谓“看起来降了”，是因为同一平面上的点可以用一个小范围的外参近似解释，是一种过拟合。
经验上，一份合格的 15 组采集数据至少包含：5 组不同距离的正面位姿、5 组左右偏转位姿、5 组上下俯仰位姿。偏转角度在 15 度到 40 度之间合适，太小约束不足，太大圆点透视变形严重，检测精度反而下降。采集顺序我习惯先做一组完整数据，立刻跑一遍标定看每帧误差分布，剔除误差过大的帧后再补拍几组。
删帧标准不看误差绝对值，而是看它是不是离群点。具体做法是先跑一次标定，输出每帧残差图，把残差明显高于整体水平的帧挑出来，检查是哪一个区域的特征点错了——单帧单点错误，删掉这一帧；连续几帧同一个区域都错，那不是数据问题，是标定板那个位置有划痕或反光。还有一种情况必须保留：某一帧残差偏大但位姿是独一无二的（比如大角度俯仰），删了它整个数据集的姿态覆盖就有缺口，这时候要先排查该帧的曝光和清晰度，而不是简单删除。
4.3 数据清洗的量化标准：重投影误差与残差直方图
做完数据筛选后，误差可能不降反升，这是好现象，说明模型没有过度迁就错误对应点的局部约束。之后看残差直方图判断清洗是否到位。把每帧每个圆点的重投影误差画成直方图，正常态近似正态分布，峰值集中在 0.2～0.5 像素，拖尾不超过 1.0 像素。如果直方图呈现双峰，说明样本里掺了两种不同分布的数据源，最常见的是部分帧的圆点检测亚像素精度等级不一致。
还有一类问题靠样本数量补：标定板位姿变化越大，需要的数据量越多，15 帧是下限，精度要求高的场景建议采集 20～25 帧。但也不是越多越好，帧数超过 40 后误差收益递减，反而增加异常样本混入概率。我一般每轮递增多采集 3～5 帧，观察重投影误差均值变化，连续两轮下降幅度小于 0.05 像素就停止加数据。
需要强调一个容易被带偏的点：不要追求重投影误差无限接近 0。相机图像本身有量化噪声，投影仪 DMD 像素也有离散化误差，理论上重投影误差有个下限，大概在 0.1～0.2 像素量级。当误差已经到 0.3 以下时，与其继续加数据不如先检查验证方法是不是够准。强行压低误差到 0.1 以内，往往意味着标定参数在过拟合采集样本的噪声，换了真实场景立刻失效。
5. 常见问题与避坑记录：投影失焦、曝光漂移与特征断裂
5.1 现象：投影画面边缘的圆点被识别成椭圆，质心偏移
做模拟项目 X 的标定时，投出圆点阵列，采集回来的图像里画面边缘的圆点变成了椭圆，procamcalib 检测出的质心总是往内侧偏移，对应关系匹配成功后重投影误差整体抬升 0.3 像素左右。
原因：投影仪存在梯形畸变，加上镜头景深有限，偏离光轴的区域失焦严重，圆点边缘模糊后，二值化阈值的等灰度线已经不再过圆心。
解决：给投影图案加一个轻微的枕形预畸变，把边缘圆点往反方向补偿；或者更简单——缩小标定板的摆放角度，避免把投影画面最边缘的 10% 区域纳入有效数据。第二种方案我用得更多，工程实现成本低，代价是视野覆盖率稍降。
5.2 现象：连续采集时圆点灰度整体漂移，质心位置跳动
采集过程中，投影仪的光源输出随温度漂移。某实验室连续采集 20 帧图像，前 5 帧和后 5 帧的圆点灰度差了接近 40 个灰度级。同一张标定图案，质心计算在不同灰度下会差出 0.1～0.2 个像素。
原因：DLP 投影仪的光源在开机初期输出不稳定，预热不足就开拍，会造成亮度漂移；相机的自动增益也在小幅调整，进一步放大灰度变化。
解决：投影仪开机后至少预热 20 分钟再开始采集，相机全程手动模式，关闭自动增益和自动白平衡。每隔 5 帧拍一张不投影的黑色背景图，用来做暗电流校正，可以把灰度漂移的影响压到 0.05 像素以内。
5.3 现象：投影仪内参主点坐标 cx、cy 与分辨率中心严重偏离
一次标定结果里，投影仪主点跑到 (1053, 723)，而投影仪分辨率是 1920×1080，几何中心在 (960, 540)。这个偏差远超常见范围，如果忽略它继续做三维重建，重建点会出现系统性扭曲。
原因：投影画面没有被完整放进相机视野里。投影仪投出的图案超出相机拍摄范围时，相机只能拍到画面的一部分，对应关系缺失一侧，标定算法为拟合这组不完整对应点，把主点强行拉偏。
解决：采集前先在相机画面里确认能看到完整投影边界，必要时缩小投影面积或拉开相机与投影仪的距离。如果投影区域已超出视野但不想重拍，可以用图案编码标记四条边界位置，在算法里指定有效 ROI，把画面外的像素强制排除。
5.4 现象：重投影误差前一轮好好的，换了一台电脑后突然暴涨
把标定工程从一台机器搬到另一台机器，同样的图像、同样的参数，重投影误差从 0.4 像素变成 2.8 像素。检查 JSON 文件，投影仪内参完全变了。
原因：两台机器的 OpenCV 版本不同，圆点检测的亚像素窗口大小和迭代终止条件不同，提取出的特征点坐标存在系统性差异。标定脚本用的 opencv-python 版本从 4.5 换到 4.8，检测算法行为确实会变化。
解决：环境锁版本，用 requirements.txt 固定 opencv-python、numpy 的精确版本号。我在项目里用写死 patch 版本的方式，比如 opencv-python==4.8.1.78，避免 pip 默认解析时拉到新版本。这种问题看着像玄学，实际就是检测算法细节不一致导致的。从那以后我把依赖版本写进 CI 检查，任何环境变更都会触发一次全量重标定回归。
6. 进阶验证：用多频相移重投影做端到端精度检验
标定完拿到参数只是第一步，验证标定精度能不能支撑实际项目是另一回事。我习惯用多频相移做一次端到端验证：投影仪依次投出三组不同频率的正弦条纹，相机同步采集，从条纹相位中解算每个像素对应的投影仪坐标，再结合标定参数重建三维点。在已知平面（比如平整度很好的墙面或大理石平台）上做重建，实测三维点相对拟合平面的残差就是系统的真实精度。
# 端到端验证：用 3 频 4 步相移解算投影仪坐标 import cv2 import numpy as np freqs = [32, 8, 2] # 频率从高到低，用于时间相位解包裹 projected = [] # 投影条纹的原始像素坐标 observed = [] # 采集图像解包裹后的投影仪坐标 for freq in freqs: for step in range(4): img = np.zeros((1080, 1920), dtype=np.uint8) for x in range(1920): v = 127.5 + 127.5 * np.cos(2 * np.pi * freq * x / 1920 + step * np.pi / 2) img[:, x] = int(v) cv2.imwrite(f"fringe_{freq}_{step}.png", img) # 采集后做相位解包裹：wrapped = arctan2(I3-I1, I0-I2) # 多频外差解开绝对相位，得到每个像素对应的投影仪绝对坐标 # 重建三维点，计算对已知平面的距离残差 plane = fit_plane(points_3d) # 最小二乘拟合理想平面 residuals = np.abs(points_3d - project_to_plane(points_3d, plane)).mean() print("端到端平面残差（mm）：", residuals)这段验证逻辑的要点是：单靠重投影误差不足以说明系统精度，因为重投影误差只评价了特征点回路是否自洽，没有评价三维重建的几何正确性。用相移条纹做端到端验证，误差来源包含投影仪量化误差、相机噪声、标定参数误差，是一个更真实的综合指标。平面残差在 0.3 毫米以内（视工作距离而定）说明标定参数到位；超过 1 毫米，回查标定数据的姿态覆盖度通常比在验证代码里找问题更有效。
从那以后，我每完成一轮相机-投影仪标定，都强制跑一遍这个端到端验证，不再只盯重投影误差一个数。很多参数调优时自我感觉良好的改动，在端到端验证面前立刻现出原形。这个习惯救过我好几轮返工，也希望帮到你。
本文还有配套的精品资源，点击获取
