目标测光曝光控制模块实施记录

2026-09-22 独立测光扩展（1.1.0）

批次 stateless-metering-20260922 配合 MatchVerify 的“采集存档 → 离线灰度统计”接入。库内只增加独立测光能力，没有相机、采图循环、文件读写或曝光控制策略变更；历史 v1 记录保留在下方。

新公开 measureImage(image, roi, hasUsableRegion, config)，输入为 Gray8/BGR8、最终区域、区域有效标志和可选测光配置。无需控制实例、曝光值、时间戳或拍前检查。
新增 Brightness::arithmetic_gray；保留 gray 为目标截尾均值。普通均值来自截尾前同一直方图，不二次扫描图像。配置校验与控制配置共用，非法配置返回 InvalidConfiguration。
控制的 processFrame() 调用公共测光实现。原控制、预测、历史、恢复逻辑未改动；新测试对照执行控制轨迹，确认插入重复独立测光不改变状态和曝光建议。
增加 7 个公开 API 逻辑用例，覆盖已知均值、混合 ROI 并集、无区域／黑图／饱和图、非法输入、非法配置、BGR 步长／全局中央区和状态隔离。安装消费工程直接调用新接口。

当前验证命令由交付辅助脚本执行并记录：

pwsh -NoProfile -File tools/verify.ps1 -BuildRoot E:/05_Temp/TargetExposureControl/capture-metering -OpenCVDir E:/06_EnvConfig/opencv/build/x64/vc16/lib -OpenCVRuntimeDir E:/06_EnvConfig/opencv/build/x64/vc16/bin

验证产物在 E:/05_Temp/TargetExposureControl/capture-metering，其 verification.log 为完整构建／测试／安装消费日志。最终实测结果与当前文件指纹以 .codex/delivery-integrity.json 为准。本批验收仅覆盖离线图像、确定性控制回归及安装接入，不包含实机采集、曝光生效或现场识别率。

原 v1 交付记录

批次：target-exposure-control-v1。实现与自动测试已完成；最终验收状态、实际退出码及当前文件指纹以 .codex/delivery-integrity.json 为准。

用户已批准需求审查稿 A～E。范围为独立 C++17/OpenCV 库、配置、最小示例、中文说明和实际自动测试。三个现有业务库不纳入改动。

本目录原只有需求审查稿，没有 Git 仓库；本批建立独立本地 Git 工作区用于交付指纹，不包含提交或发布动作。

实际验证环境：Windows x64、Visual Studio 2022 Enterprise、MSVC 19.44.35222.0、Windows SDK 10.0.26100.0、OpenCV 4.7.0。构建与安装验证目录为 E:/05_Temp/TargetExposureControl/v1，源码目录不存放编译产物。

验收项及精确验证命令冻结在 .codex/delivery-integrity.json。验证脚本将完成配置、Release 构建、分组 CTest、最小示例、安装，以及只通过安装包引用的独立消费工程构建和测试。

完成交付

独立 C++17 静态库，公开三个生命周期接口、强类型配置、ROI 与输出诊断类型。
Gray8/BGR8 测光，矩形/旋转矩形/mask 并集及截尾统计。
基于真实时间、真实曝光及已知黑电平的 3/5 点预测；不足或不适用时回退当前帧反馈。
原比例/PI/死区控制器，滞回、连续确认、积分抗饱和及两级限幅。
三态状态机、拍照前一次初始化、跨状态的单次恢复预算、重复/乱序反馈拒绝。
源码 CMake target 与可安装的 TargetExposureControl::Control 包，中文说明和可运行模拟调用示例。

验证结果

实际执行命令（也由交付门禁执行并记录）：

pwsh -NoProfile -File tools/verify.ps1 -BuildRoot E:/05_Temp/TargetExposureControl/v1 -OpenCVDir D:/programfile/opencv4.7.0/opencv/build

验证项	已观测结果
MSVC x64 Release 库、测试与示例构建	成功
测光	9/9 用例通过
历史	4/4 用例通过
预测与参与控制	5/5 用例通过
控制器	6/6 用例通过
三态	4/4 用例通过
单次恢复	5/5 用例通过
时间与初始化	6/6 用例通过
新反馈及幂等	5/5 用例通过
配置与实例隔离	2/2 用例通过
分组 CTest 与最小示例	10/10 通过，包含上述 46 个逻辑用例及 1 个示例
安装包独立消费工程	配置、构建成功，运行测试 1/1 通过

预测参与控制的直接证据：当前灰度均为 100、实际曝光均为 1000 us，前两帧趋势分别为 80→90 和 120→110。在相同控制参数（Kp=0.4、Ki=0、连续确认=1）下，下一拍预测分别为 110 和 90；曝光建议分别为 1000 us 和约 1094.915254 us。关闭预测后，两组均为约 1061.016949 us。自动测试校验了这些具体数值，而不只检查预测字段存在。

最初配置失败的原因是 OpenCV 4.7 Windows 包顶层分发脚本不识别本机较新 MSVC；验证脚本改为使用已存在的 x64/vc16/lib/OpenCVConfig.cmake 后成功。未修改或重装依赖。首次编译的测试角度隐式转换警告已通过显式浮点常量修正。

输出位置

当前完整验证日志：E:/05_Temp/TargetExposureControl/v1/verification.log。
库与示例：E:/05_Temp/TargetExposureControl/v1/library/Release/。
可复用安装包：E:/05_Temp/TargetExposureControl/v1/install/。
独立消费工程：E:/05_Temp/TargetExposureControl/v1/consumer/。
源码接入说明：README.md；控制数学及状态语义：docs/控制与状态说明.md。

本批没有连接真实相机，未验证实际曝光设置、真实成像变化或现场识别率；未宣称完成现场验收。示例曝光范围与参数仅为可运行演示值。

本批没有剩余代码验收项。使用方下一步可按 README 将库接入指定业务工程，为实际工况设置曝光范围、经验曝光和预测模型前提；真实相机验证属于后续单独授权的接入工作。

5.8 KiB Raw Blame History Unescape Escape