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

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