# AI 光疗灯甲面到 LED 通道映射候选 v0.2

此候选补上 AI 灯 SoC 侧从“指甲概率图”到“允许哪些物理 LED 通道”的确定性安全步骤。Amazon 套装页称灯具用摄像头/深度学习定位手指和甲面、包含 61 颗 LED，并使用 365 nm + 405 nm 双波段；这些仍是卖家声明，必须对原机测量和 A/B。来源：[目标套装 B0HBWRZR4G](https://www.amazon.com/dp/B0HBWRZR4G)、[插电 AI Mini B0GR425DGM](https://www.amazon.com/dp/B0GR425DGM)。

## 已实现

- 固定 16×12 个校准网格格点；模型输出每格 0–255 的甲面概率图。
- 每个**实际驱动通道**各自使用辐照分布权重图。双波段 LED 若有独立电气 die，按 122 路分别标定；若驱动/封装将其合并，则按实际通道数建立图，不能把 61 颗封装数直接当成通道数。
- 每通道根据辐照能量落在甲面上的比例做门限筛选；通过时将所请求 PWM 限制到该通道已标定的最大值。
- 无有效光学标定、新鲜帧、模型、手部状态、匹配校准编号或满足门限时，结果保持全零。
- 帧序号必须晚于本次曝光基线、满足 ticket 的最小帧号并大于上次接受的帧号；本模块再次检查这些条件，原 AIW peer 仍负责协议和全局安全会话。

## 复核方式

在此目录运行：

```sh
sh run_test.sh
```

执行记录：C11、`-Wall -Wextra -Werror -pedantic`、AddressSanitizer、UndefinedBehaviorSanitizer；测试通过，5187 项断言。

## 当前工程边界

这不是视觉模型、摄像头驱动或真实灯板光学校准。测试数据是合成概率格和合成辐照图；没有真实 CMOS 新曝光、甲面/皮肤标注集、NPU 推理、365/405 nm 辐照图、逐通道热图、UV 泄漏限值或固化 A/B。生产配置必须在收到原机后测出光斑/辐照分布、做摄像头到灯板的几何标定，再冻结最小甲面能量比例、置信度阈值和每通道最大 PWM。标定数据缺失时不能启用任何灯珠。

模块尚未接入 RV1106 等实际 SoC target build，也未合并到完整 v1.28 工程包或制造数据。它推进了单项软件能力，不能证明 AI 灯功能、视觉准确率、皮肤照射安全、固化效果、外壳适配或量产成本等同。

## AIW peer 集成增量 v0.2

新增 `nail_led_aiw_adapter.c/h`，实现现有 `aiw_soc_infer_fn` 回调：camera/model adapter 交付带版本、光学校准编号及源帧号的模型帧；映射器将合成甲面概率图和逐输出通道辐照权重转换为 AIW 通道 mask/PWM；`aiw_soc_peer` 再执行 ticket、fresh-frame 和 mask 外清零并编码 AI_RESULT。缺少标定、帧与模型错配、低置信度、无手或帧重放均不能产生非零灯输出。

运行 `sh run_test.sh` 可在主机上验证映射器与 AIW peer 的合并路径。`test/reference_peer/` 是只用于可复现测试的 peer/API 快照，来源为本项目 v1.26 候选；它不替代完整工程的最新同名源码，也没有用于目标板构建。集成断言通过只证明软件边界和协议串接，不证明 camera driver、模型精度、真实 365/405 nm 光场或产品固化效果。
