OpenCV xphoto 学习型白平衡算法实战:基于 Gehler-Shi 数据集训练与评估你的模型
OpenCV xphoto 学习型白平衡算法实战:基于 Gehler-Shi 数据集训练与评估你的模型
本文以 OpenCV 扩展模块 xphoto 的官方教程 training_white_balance.markdown 为主线,完整讲解如何基于带真实光照真值(ground-truth illuminant)的大规模数据集训练一个学习型白平衡(learning-based white balance)模型,并给出与经典 Gray-World 算法的客观对比评测方案。读完本文,你将掌握 learn_color_balance.py 与 color_balance_benchmark.py 两个脚本的完整用法、每个训练参数的含义与默认值、模型文件的内部结构,以及如何在 C++ 中加载自训模型完成白平衡。
为什么需要学习型白平衡
传统白平衡算法大多是基于统计假设的:它们依赖"在一张正确白平衡的图像中,某些统计量应当成立"这一前提。最著名的例子是 Gray-World 假设——即一幅自然图像中 RGB 三通道的均值应当趋于灰(中性色),于是用通道均值反推增益来校正色偏。这类方法实现简单、无需任何先验知识,但对大面积单色物体、强色偏场景等"假设失效"的情况容易翻车。
相比之下,学习型方法利用大量"图像 + 真实光照"的标注数据,在监督学习框架下直接拟合图像特征到光源色度之间的映射关系,往往能获得比纯统计方法更好的效果。OpenCV 的 xphoto 模块提供了一个可直接训练、可插拔的 LearningBasedWB 算法:它既内置了一个默认模型(开箱即用),也允许你用自定义数据集训练自己的模型文件。本文正是官方教程的完整展开,带你走通"准备数据 → 训练 → 加载 → 评测"全流程。
算法与模型结构:先理解再训练
在动手跑脚本之前,先弄清楚训练出来的东西到底是什么,这对后续调参会很有帮助。从 white_balance.hpp 的类文档与 learning_based_color_balance.cpp 的实现可以确认:
LearningBasedWB属于WhiteBalancer基类,对外暴露balanceWhite(src, dst)接口;其底层同样是通过对 R/G/B 通道施加不同增益完成校正(与 Gray-World 相同),但增益的计算来源完全不同。- 白平衡前会先做饱和像素掩膜:像素满足
max(R,G,B) / range_max_val < saturation_thresh才会参与统计,用于屏蔽高光过曝区域。 - 算法核心是从图像中提取 4 个 (r,g) 色度特征(
extractSimpleFeatures):- 图像平均 (R,G,B) 元组的色度;
- 最亮 (R,G,B) 元组的色度(忽略饱和像素);
- RGB 直方图中出现次数最多的主色(dominant color)的色度;
- "色度调色板"(取直方图中出现频率最高的 300 种颜色投影到色度平面)的众数,由固定带宽的 Epanechnikov 核密度估计计算得出。
- 预测阶段由**回归树对集成(ensemble of regression tree pairs)**完成:每个特征对应一棵预测 r 分量、一棵预测 g 分量的回归树,所有树的输出综合得到估计光源色度
illuminant,最终增益为gainB = 1.0; gainG = denom / illuminant<a href="https://link.gitcode.com/i/83a7c61091205eb6e42e34b91fc0c2b7" target="_blank">1]; gainR = denom / illuminant[0](其中denom = 1 - illuminant[0] - illuminant[1],见 [balanceWhite 实现)。
需要说明的是,训练脚本与运行时代码解耦:训练阶段用 Python + scikit-learn 拟合回归树,再把树结构序列化成 YAML 模型文件(或直接导出为 C++ 头文件),运行时由 C++ 端 LearningBasedWBImpl 加载并执行预测。这意味着训练一次,之后推理时完全不需要 Python 和 scikit-learn 依赖。
第一步:准备训练数据集
本教程使用 Gehler-Shi 数据集(SFU 计算摄影数据集,共 568 张带真实光源标注的图像):
- 将全部 568 张训练图像解压到同一个文件夹(要求是"最小化处理"的 PNG 图像,未做白平衡校正)。
- 单独下载真值文件
real_illum_568..mat,其中记录了每张图像对应的真实光源 RGB 值。
除了 Gehler-Shi,learn_color_balance.py 还支持 NUS 8-camera 数据集格式。脚本会自动识别真值文件的格式:Gehler-Shi 的 .mat 中包含 real_rgb 字段,且前 87 张图像黑电平为 0、其余为 129;NUS 格式则包含 groundtruth_illuminants 与 darkness_level 字段。训练时脚本会先减去对应黑电平,再做归一化拉伸到 8 bit(默认按 2.5% 分位裁剪)以提取特征。
第二步:训练模型
训练入口是仓库自带的 Python 脚本 learn_color_balance.py。官方教程给出的标准训练命令为:
python learn_color_balance.py -i <path to the folder with training images> -g <path to real_illum_568..mat> -r 0,378 --num_trees 30 --max_tree_depth 6 --num_augmented 0
这条命令的含义:用整个数据集的前 378 张图像(约 2/3)训练,模型规模设为每个特征 30 个回归树对,树最大深度不超过 6,不启用数据增强。训练完成后默认把模型保存到当前目录下的 color_balance_model.yml。
全部参数详解(含默认值)
脚本的完整参数由 argparse 部分定义,以下均以仓库代码为准:
| 参数 | 默认值 | 说明 |
|---|---|---|
-i, --input_folder |
(必填) | 训练图像文件夹路径,脚本会按文件名排序后依序使用 |
-g, --ground_truth |
real_illum_568..mat |
真值 .mat 文件路径,支持 Gehler-Shi 与 NUS 8-camera 两种格式 |
-r, --range |
0,0 |
参与训练的图像索引区间,形式为 <首索引>,<末索引>;0,0 表示使用全部图像 |
-o, --out |
color_balance_model.yml |
输出模型路径。只支持 .yml 与 .hpp 两种后缀:.yml 供运行时 createLearningBasedWB 加载;.hpp 生成可直接编译进主代码的 C 数组 |
--hist_bin_num |
64 |
特征提取时三维 RGB 直方图每个维度的分箱数(bin 数)。高比特深度图像建议增大,如 12 bit 图像用 256 |
--num_trees |
20 |
每个特征对应的回归树对数量,控制模型规模 |
--max_tree_depth |
4 |
回归树的最大深度 |
-a, --num_augmented |
2 |
每张训练图像额外生成的增强样本数。增强会提升模型鲁棒性 |
训练脚本内部发生了什么
为了让参数调优更有据可依,这里简要拆解 learn_regression_tree_ensemble 的核心逻辑:
- 特征提取:对每张图像(减去黑电平、归一化到 8 bit)调用
cv.xphoto.createLearningBasedWB().extractSimpleFeatures()得到 4 组色度特征(脚本初始化时设置rangeMaxVal=255、saturationThreshold=0.98、histBinNum取命令行参数)。 - 数据增强:若
num_augmented > 0,对每张图随机生成R/G/B通道系数(均匀分布于 0.2~5.0),同步缩放图像与真值光源,构造出模拟不同光照强度的合成样本(实现见 L263-L278)。 - 样本组织:按 r 色度排序后切分成若干局部区间,每棵树在其局部区间内对样本额外加权
num_trees倍、再混入全部剩余样本训练,以此保证集成中的每棵树对局部色度区间有更强响应。 - 模型写出:把每棵决策树递归展开为定长数组(特征索引
feature_idx、分裂阈值thresh_vals、叶节点值leaf_vals),YML 格式下分别以uint8/float32类型写入num_trees、num_tree_nodes、feature_idx、thresh_vals、leaf_vals五个键(generate_code 见 L83-L132)。
运行依赖
脚本依赖 numpy、scipy(读取 .mat 真值)、scikit-learn(DecisionTreeRegressor)以及带 cv2.xphoto 的 OpenCV 环境。由于 scipy.io.loadmat 是硬依赖,真值文件必须是标准的 MATLAB v5 .mat 格式。
第三步:用训练好的模型做白平衡
训练完成后,在 C++ 中通过 createLearningBasedWB 传入模型路径即可构建实例:
Ptr<xphoto::LearningBasedWB> wb = xphoto::createLearningBasedWB(modelFilename);
- 若传入模型路径,
LearningBasedWBImpl会尝试用FileStorage打开并解析 YAML 中的num_trees、num_tree_nodes、feature_idx、thresh_vals、leaf_vals(见 构造函数 L90-L127); - 若路径为空,则自动回退到内置的默认模型(编译期写死在 learning_based_color_balance_model.hpp 中),实现开箱即用;
- 运行时可通过
setRangeMaxVal(输入最大值,8 bit 为 255,12 bit 为 4095,16 bit 为 65535)、setSaturationThreshold(饱和阈值,默认 0.98)、setHistBinNum(直方图分箱数,默认 64,训练与推理应保持一致)调节行为; - 输入支持
CV_8UC3与CV_16UC3两种三通道 BGR 图像,最终调用wb->balanceWhite(src, dst)输出校正结果。
Python 侧同样可用(脚本内即如此):wb = cv.xphoto.createLearningBasedWB("color_balance_model.yml") 后调用 wb.balanceWhite(img)。
第四步:评测模型质量
评测使用仓库自带的基准脚本 color_balance_benchmark.py,官方教程给出的命令为:
python color_balance_benchmark.py -a grayworld,learning_based:color_balance_model.yml -m <full path to folder containing the model> -i <path to the folder with training images> -g <path to real_illum_568..mat> -r 379,567 -d "img"
这条命令用数据集剩余的 1/3(索引 379~567)图像,同时评测经典 Gray-World 与你刚训练的学习型模型(通过 learning_based:color_balance_model.yml 语法指定具体模型文件,-m 指向模型所在目录),并把白平衡结果图输出到 img 文件夹。
评测指标与输出产物
- 客观指标:不同算法以"估计光源与真实光源之间的角度误差(angular error)"进行对比。脚本从校正前后的像素比值中恢复估计光源,再计算两向量夹角的弧度值并转换为角度(evaluate 见 L43-L84)。
- 结果报表:汇总统计以 HTML 表格形式写入
white_balance_eval_result.html(默认路径,可用-o修改),表格含每张图的平均耗时与多种误差统计量。 - 可视化对比:指定
-d后,各算法校正结果按图像序号_算法名.jpg命名保存,便于人工定性比较(例如观察学习型算法是否比 Gray-World 更好地还原白色物体)。
评测脚本完整参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-a, --algorithms |
(必填) | 逗号分隔的算法列表。可用值:GT(用真值增益校正,作为理想上界)、learning_based、grayworld、nothing(原图)。学习型算法用冒号指定模型,如 learning_based:model1.yml,learning_based:model2.yml 可一次对比多个模型 |
-m, --model_folder |
空 | 存放学习型模型的文件夹(配合 learning_based:xxx.yml 使用) |
-i, --input_folder |
(必填) | 待评测图像文件夹 |
-g, --ground_truth |
real_illum_568..mat |
真值 .mat 文件 |
-r, --range |
0,0 |
评测图像索引区间,0,0 表示全部 |
-o, --out |
./white_balance_eval_result.html |
输出 HTML 统计表路径 |
-s, --state |
./WB_evaluation_state.json |
评测状态文件。脚本采用增量评测:逐张处理并把结果写入 JSON,中断后可断点续跑 |
-t, --stats |
mean,median,p05,p20,p80,p95 |
要计算的误差统计量:均值、中位数及 5/20/80/95 分位 |
-b, --input_bit_depth |
空 | 输入图像位深(如 12 bit 图像填 12)。指定后按满位深评测,否则先转 8 bit |
-d, --dst_folder |
空 | 指定后用于保存各算法的白平衡输出图 |
另外注意评测脚本内部的实现细节:grayworld 算法使用 createGrayworldWB() 并设置 saturationThreshold=0.95;GT 算法按 gains = gt_illuminant / min(gt_illuminant) 计算理想增益,通过 applyChannelGains 校正,作为理论上限参与对比(见 L46-L66)。评测时 learning_based 的 histBinNum 在 8 bit 下用 64、高位深下用 256,与训练脚本默认值一致。
源码验证与延伸阅读
- 特征提取回归测试:test_learning_based_color_balance.cpp 用 RNG 构造已知统计特性的图像,断言 4 个特征分别逼近手算的理论色度值,并同时覆盖 8 bit 与 16 bit(
rangeMaxVal=65535、histBinNum=128)两种输入,可据此验证你的运行环境行为一致。 - 性能基准:perf_learning_based_color_balance.cpp 对 HD 分辨率、
CV_8UC3/CV_16UC3图像执行balanceWhite计时,可作为调优参考。 - 饱和度阈值的作用:
LearningBasedWBImpl在preprocessing中按saturation_thresh * range_max_val生成非饱和像素掩膜(L174-L250),该阈值同时影响"平均色度""最亮色度"等多个特征的统计范围。 - 相关 API 家族:xphoto 模块还提供
GrayworldWB(Gray-World 增强版,可按饱和度阈值筛选像素)与SimpleWB(通道独立拉伸),定义均位于 white_balance.hpp;本文评测命令中的-a grayworld即对应前者。 - 官方教程原文:training_white_balance.markdown,配合 learn_color_balance.py 与 color_balance_benchmark.py 两个脚本食用效果最佳。
小结
至此,你已经掌握了学习型白平衡的完整闭环:统计型算法的局限 → 学习型算法与回归树模型结构 → Gehler-Shi 数据集准备 → 用 learn_color_balance.py 训练并导出 YAML 模型 → 用 createLearningBasedWB 在 C++ 中加载推理 → 用 color_balance_benchmark.py 以角度误差客观对比算法。无论是复现论文实验、为相机管线定制白平衡模型,还是仅想替换掉开箱即用的默认模型,都可以直接基于本文的命令与参数体系展开。需要提醒的是:训练集与评测集务必划分干净(教程中前 2/3 训练、后 1/3 评测),否则评测结果会失真;实际应用时也建议根据你的目标图像的位深与成像特性,同步调整 hist_bin_num 与 saturation_threshold。