124 lines
11 KiB
Markdown
124 lines
11 KiB
Markdown
# 目标测光曝光控制模块实施记录
|
||
|
||
## 2026-09-23 连续控制共享预测稳定规则
|
||
|
||
批次 `prediction-stability-fix-20260923` 为 `ContinuousFrameInput` 追加可选外部预测输入。只在真实区域反馈保持、没有重置或保护抑制时选用预测；预测与实测反馈使用同一个状态控制器，保留死区、迟滞、连续确认、时间确认、PI 和限幅。默认不传预测的调用保持原行为。`feedback_*` 记录真实反馈依据，`metering` 和滤波历史仍由实测更新；`prediction_used` 不表示设备写入。静态库和应用须一起重新编译。
|
||
|
||
新增回归覆盖保持区／迟滞／确认、时间与预测限幅、保护及重置优先级、非法预测不污染状态；独立安装消费工程实际调用新增接口。完整基线由以下命令执行，结果与源码指纹以 `.codex/delivery-integrity.json` 为准：
|
||
|
||
```powershell
|
||
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` 记录：
|
||
|
||
```powershell
|
||
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` 记录：
|
||
|
||
```powershell
|
||
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 步长／全局中央区和状态隔离。安装消费工程直接调用新接口。
|
||
|
||
当前验证命令由交付辅助脚本执行并记录：
|
||
|
||
```powershell
|
||
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` 包，中文说明和可运行模拟调用示例。
|
||
|
||
## 验证结果
|
||
|
||
实际执行命令（也由交付门禁执行并记录）：
|
||
|
||
```powershell
|
||
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 将库接入指定业务工程，为实际工况设置曝光范围、经验曝光和预测模型前提；真实相机验证属于后续单独授权的接入工作。
|