zhangben1207/CommonLibraries
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
CommonLibraries/TargetExposureControl/实施记录.md

11 KiB
Raw Permalink Blame History

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

2026-09-23 连续控制共享预测稳定规则

批次 prediction-stability-fix-20260923 为 ContinuousFrameInput 追加可选外部预测输入。只在真实区域反馈保持、没有重置或保护抑制时选用预测；预测与实测反馈使用同一个状态控制器，保留死区、迟滞、连续确认、时间确认、PI 和限幅。默认不传预测的调用保持原行为。feedback_* 记录真实反馈依据，metering 和滤波历史仍由实测更新；prediction_used 不表示设备写入。静态库和应用须一起重新编译。

新增回归覆盖保持区／迟滞／确认、时间与预测限幅、保护及重置优先级、非法预测不污染状态；独立安装消费工程实际调用新增接口。完整基线由以下命令执行，结果与源码指纹以 .codex/delivery-integrity.json 为准：

pwsh -NoProfile -File tools/verify.ps1 -BuildRoot E:/05_Temp/agent/ci/tmp/MatchVerifyFix-01a0cd3e/actual-library-build -OpenCVDir E:/06_EnvConfig/opencv/build/x64/vc16/lib -OpenCVRuntimeDir E:/06_EnvConfig/opencv/build/x64/vc16/bin

所有输入为内存图像和模拟时间，未连接真实相机、部署或提交推送。应用内的时序拟合与等待 60 秒加处理耗时边界由 MatchVerify 集成回归覆盖。

2026-09-22 现场光照分析测光扩展（1.3.0）

批次 daylight-metering-20260922 为独立测光接入 Gray16 和有效图像掩膜，保留已有连续控制与原控制的策略行为。公开 measureImage 追加可选第五参数 validImageMask；原三／四参数源码调用继续可用。Brightness 追加原始普通均值、源位深和满量程，既有普通／截尾均值仍采用统一 0～255 标度。公开 kVersion 供分析输出记录库版本。

  • Gray16 在源像素直方图上先计算精确普通／截尾均值，之后线性归一；不会先量化成 8 位。近黑／饱和阈值按统一标度映射到源像素，边界用整数比较。
  • 有效图像掩膜同时与全局及目标并集取交，非零即有效；格式错误、空交集、目标像素不足分别报告明确状态。默认无掩膜保持整图，不自动排除黑像素。
  • 新增 6 个独立测光逻辑用例，覆盖 16 位已知样本／小数精度／阈值边界／非连续存储、8 与 16 位混合区域掩膜交集、全局中央区与目标独立、非法与空掩膜、8 与 16 位同标度控制回归。安装消费工程直接验证 Gray16 和第五参数。

验证使用以下隔离命令，最终结果和文件指纹由 .codex/delivery-integrity.json 记录：

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

完整日志为 E:/05_Temp/TargetExposureControl/daylight-analysis/verification.log；上一批合同备份在同目录 previous-delivery-integrity.json。本批验收仅含软件测光、控制回归和安装接入，不涉及真实设备、一天现场数据的效果验收、曝光策略变更、提交或推送。

2026-09-22 连续在线反馈扩展（1.2.0）

批次 continuous-feedback-20260922 面向 MatchVerify 的连续采集自动曝光应用。新增独立 ContinuousExposureControl::update，以已测光结果、显式来源、单调时间和真实曝光读回为输入，复用原比例／PI、死区、迟滞和限幅实现；原 ExposureControl 的预测、状态机和单次无目标恢复语义不变。

  • 支持 Global、ManualRoi、YoloRegions；有效区域优先，无区域或无效区域明确回退全局，目标与全局参考独立可配。没有工件存在判断或伪造检测计数。
  • 连续无目标也可逐帧按全局亮度调节；实际来源切换、配置变化和闲置清积分。严格校验时间、真实曝光、测光数值／数量／比例，不把建议值当实际值。
  • 输出请求／实际来源、回退与重置原因、反馈状态、完整误差／积分／同向计数／限幅跟踪，以及原测光统计，供应用保存详细策略日志。
  • 新增 11 个连续反馈逻辑用例，覆盖模拟线性场景多帧收敛、手动／YOLO 优先及全局回退、积分切换、独立参考、黑图／饱和／边界、配置／闲置重置、时间水位、非法输入、真实反馈及抗积分饱和；安装消费工程直接使用公开连续 API。

验证命令与结果由 .codex/delivery-integrity.json 记录：

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

隔离产物位于 E:/05_Temp/TargetExposureControl/online-auto-exposure，完整日志为 verification.log；上一批交付合同备份为同目录 previous-delivery-integrity.json。验收边界仅为软件、内存图像、模拟曝光响应与安装接入，不含真实相机曝光生效、光源控制或现场识别率；本批不提交、不推送。

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 将库接入指定业务工程，为实际工况设置曝光范围、经验曝光和预测模型前提；真实相机验证属于后续单独授权的接入工作。