# MAG160C 热像仪渲染项目交接 - 2026-08-11

项目目录: `C:\Project\MAG160C`

目标: 修复 `csdk\tools\mag160c_demo3.c` 的移动物体鬼影，同时不要破坏当前已经修好的画面问题。

## 1. 当前结论先说

- 黑洞问题已经基本消失。
- 固定遮蔽问题已经消失。
- 最高温点显示黑色的问题已经修掉。
- 当前主要剩余问题: 移动物体会留下鬼影，尤其是“小温差鬼影”擦除很慢。
- 官方 SDK 自己也存在类似“旧位置偏暗/偏黑”的残影，不是 demo3 独有问题。
- 现在最需要做的是: 在不破坏现有稳定画面的前提下，只针对“目标离开后的小残影”加速擦除。

## 2. 设备与构建

- 设备: MAG160C, 160x120, USB, VID `0x833C`
- 官方 SDK: `CoreSDKLib.dll`
- 当前主程序: `C:\Project\MAG160C\csdk\tools\mag160c_demo3.c`
- 输出程序: `C:\Project\MAG160C\build-artifacts\mag160c_demo3.exe`

编译命令:

```powershell
gcc -O2 -w -DMAG160C_STATIC -I"C:\Project\MAG160C\csdk\third_party\libusb\win64" -I"C:\Project\MAG160C\csdk\include" -I"C:\Project\MAG160C\csdk\src" -o "C:\Project\MAG160C\build-artifacts\mag160c_demo3.exe" "C:\Project\MAG160C\csdk\tools\mag160c_demo3.c" "C:\Project\MAG160C\csdk\src\mag160c_display.c" "C:\Project\MAG160C\csdk\src\mag160c_error.c" "C:\Project\MAG160C\csdk\third_party\libusb\win64\libusb-1.0.x64.a" -lgdi32 -luser32
```

重启命令:

```powershell
Stop-Process -Name mag160c_demo3 -Force -ErrorAction SilentlyContinue
Start-Process "C:\Project\MAG160C\build-artifacts\mag160c_demo3.exe" -WorkingDirectory "C:\Project\MAG160C\build-artifacts"
```

日志与抓图:

- `demo3_diag.txt`
- `demo3_auto_*.bmp`

官方抓帧:

```powershell
C:\Project\MAG160C\build-artifacts\tsdk_pair2.exe C:\Project\MAG160C\analysis\pairs_move 12 6000
```

注意:

- 跑 `tsdk_pair2.exe` 前要先停 `demo3`
- 如果报 `no channel`，通常要重插 USB
- 这个工具默认要给官方 SDK 几秒初始化时间，`6000ms` 延时是成功过的

## 3. 官方渲染管线逆向结论

已验证主链路:

```text
USB帧(type=0)
  -> 平滑器 0x41f10 (模式1: 首帧 memcpy + EMA)
  -> f20 (dev+0x41f20)
  -> NUC查表 0x180017200
  -> 输出到 dev+0x270
  -> 窗口 hi/lo (dev+0x4202c / 0x42030)
  -> gray (dev+0x220, 320x240)
  -> palette 256
  -> RGB
```

NUC 查表 `0x180017200` 已确认:

- `d2 = (f20 - ref) >> 1`
- 段阈值在 `dev+0x41858`
- gain/off 表在 `dev+0x41870`
- `shift = 12`
- 输出 clamp 到 `[0, 65535]`

参考帧 `ref`:

- 来自平滑器 `0x41ee0`
- 启动早期采集几帧后冻结
- FFC 后只做全局偏移，不重新采集整帧 ref
- `ref` 和 `live/f20` 同源 mura，能很好抵消固定纹理

FFC:

- 周期约 `1800` 帧，也就是约 `120s`
- 或者传感器温差变化超过阈值时触发
- `FFC(0)` 后约 `9` 帧再 `FFC(1)`
- `type=1` 期间官方会冻结画面

关键逆向修正:

- 原来以为 `0x180017330` 是整帧 3x3 平滑，这是错的
- 现在确认它更像“盲元/坏点补偿”，不是全帧模糊
- 所以 demo3 里已经去掉“整帧 3x3 blur”这条错误路径

## 4. 已经修好的问题

### 4.1 颗粒重

- 原因: NUC 斜率过大
- 修复: `NUC_GAIN=19`

### 4.2 FFC 后颜色跳变

- 原因: FFC(1) 后重采集 ref，把场景吸进参考
- 修复: `REF_REINIT_AFTER_FFC=0`

### 4.3 物体破碎 / 椒盐

- 原因: 固定窗口过窄
- 修复: 改为自适应窗口

### 4.4 蒙层 / mura 感

- 原因: 常数 ref 或错误参考导致 mura 直接显示
- 修复: 启动阶段采集每像素平场 `g_ref_mura`

### 4.5 中上固定遮蔽

- 原因: 动态 badmap / scene-derived bad map 会把错误结构钉在屏幕坐标
- 修复: `BADMAP_ENABLE 0`

### 4.6 右下炫光

- 原因: 误把某层处理当成全帧平滑
- 修复: 去掉整帧 3x3 blur 路径

### 4.7 最高温点变黑

- 原因: 调色或极值像素处理不稳
- 修复:
  - 加了 `idx >= hi -> 1023` 饱和保护
  - 保留保守的 `correct_zero_pixels()`

## 5. 当前稳定基线

请把下面这些当作“目前相对稳定、不要随便一起推翻”的基线:

- `CONSTANT_REF=1`
- `SBNUC_ENABLE=1`
- `BADMAP_ENABLE=0`
- 不启用显示层 `deghost_nuc()`
- 保留 `correct_zero_pixels(g_live)`
- 不使用动态 badmap
- 不重新采集 FFC 后参考
- `g_reference` 由 `g_ref_mura + shift` 生成

当前 `SBNUC` 的核心逻辑仍在 `CONSTANT_REF && g_ref_mura_ready` 分支里。

## 6. 当前主要问题

用户最新稳定反馈是:

- 画面别的问题基本都行
- 主要剩下鬼影
- 大温差目标离开后擦得还可以
- 小温差目标离开后，残影很明显，而且消失慢

也就是说问题已经不是“黑洞”了，而是“低对比度残影消退太慢”。

## 7. 已尝试过的鬼影方案与结果

以下这些路线都试过了，后续模型不要再盲目重复:

### 7.1 直接全局加速 SBNUC

试过:

- 去掉 `df` 条件
- 放宽 `dd` 阈值
- `alpha` 从 `1/64` 提到 `1/16`

结果:

- 对黑洞有帮助
- 但对小温差鬼影改善有限
- 太激进时容易把画面别的东西带坏

### 7.2 用 `dd > 120` 冻结热物体，负残差快速吸收

当前稳定版本里保留了这条思路:

- `dd > 120` 认为是热目标，冻结
- `dd < -120` 用更快步长

结果:

- 黑洞基本缓解
- 但小温差鬼影仍然慢

### 7.3 显示层去鬼影

试过:

- 最近热区 mask
- motion history
- 在显示层替换 ghost 区像素

结果:

- 效果不明显，或者直接把显示搞坏
- 用户明确反馈“显示不对了，有地方看不见了”

结论:

- 不建议再从显示层硬补丁下手

### 7.4 更复杂的热区/静止检测

试过:

- `g_sb_still`
- `g_hot_hist`
- `g_motion_hist`
- `g_disp_hot`

结果:

- 大部分复杂掩码方案收益低，且很容易引入副作用

## 8. 最后一次实际修改

最后一次修改是在当前 `SBNUC` 块上，加入了“最近热像素释放加速”:

- 新增常量:
  - `SB_HOT_T 120`
  - `SB_HOT_SEED 48`
  - `SB_HOT_HOLD 24`
- 逻辑:
  - `dd > SB_HOT_SEED` 时给该像素一个短期热记忆
  - 当像素刚从热态退出，且 `dd < 0` 时
  - 临时把更新步长提高到 `denom = 1` 或 `2`
  - 目标是让“小温差尾巴”比以前更快擦掉

改动位置:

- [mag160c_demo3.c](/abs/path/C:/Project/MAG160C/csdk/tools/mag160c_demo3.c)

这一版已经成功编译并启动过，但还没有得到“明显修好鬼影”的确认。

## 9. 官方抓帧证据

已成功抓到:

- 目录: `C:\Project\MAG160C\analysis\pairs_move`
- 预览图: `C:\Project\MAG160C\analysis\pairs_move\preview`
- 统计表: `C:\Project\MAG160C\analysis\pairs_move\preview\summary.tsv`

已经确认的事实:

- 官方 `f20-ref` 的整帧残差均值并不在 `0` 附近，而是大约 `-5000`
- 官方自身也能看到“人物旧位置偏暗”的形态
- 说明鬼影不是 demo3 独有 bug，而是官方这类冻结参考体系本来就会带来的现象

几个关键数值:

- `pair_000` 到 `pair_011` 的 `d_mean` 大约在 `-5012` 到 `-5249`
- `d_std` 大约在 `735` 到 `993`
- 官方 `gray` 帧间变化大多不高，但在 FFC 附近会跳

重要提醒:

- `tsdk_pair2.c` 里 `.thr/.gain` 有重复写文件的问题
- 前面本来先按指针保存了真实表，后面又被 `dev+0x41848 / 0x41870` 覆盖
- 所以 `pairs_move/*.gain` 不能直接当纯 gain/off 表来解析

## 10. 当前源文件里还留着但未启用的东西

`mag160c_demo3.c` 里还有一些历史试验残留，很多已经不在主路径使用:

- `g_sb_prev_d`
- `g_sb_still`
- `g_hot_hist`
- `g_disp_hot`
- `g_disp_hot2`
- `g_motion_hist`
- `g_disp_prev_live`
- `g_disp_prev_ready`
- `g_disp_cur_hot`
- `g_disp_ghost`
- `g_disp_repl`
- `deghost_nuc()`

其中:

- `g_hot_hist` 现在又被重新用于“最近热像素释放加速”
- `deghost_nuc()` 仍然存在，但调用被注释掉了

## 11. 建议下一步

优先顺序建议如下:

1. 不要再做显示层补丁。
2. 继续只在 `SBNUC`/参考更新层做改动。
3. 重点针对“刚离开热目标后的低对比度负残差”做更稳的状态机。
4. 如果参数法还是没明显改善，直接上 Hardie 风格时域方差门控。

更具体地说:

### 方案 A: 做“退出热目标后的短时释放状态机”

比当前 `g_hot_hist` 更严格一点:

- 进入热目标态: `dd > hot_enter`
- 退出热目标态: 从热态回落到 `dd <= hot_exit`
- 退出后 `N` 帧内:
  - 若 `dd < 0`，快速拉 `g_ref_mura -> g_live`
  - 若再次变热，立刻取消释放

这比单纯看当前 `dd` 更稳，因为它显式编码了“曾经热过，现在走了”。

### 方案 B: Hardie / Kalman 风格时域方差门控

这是最值得上的正路。

对每个像素维护:

- `d = live - ref`
- 短窗均值
- 短窗方差

规则:

- 方差小且接近背景偏移 -> 当作背景，允许吸收
- 方差大 -> 当作运动目标，冻结

这类方法比单阈值 `dd` 更适合处理“小温差但持续可见的鬼影”。

## 12. 不要轻易改的点

后续模型请避免同时改这些东西，否则很难定位:

- `BADMAP_ENABLE`
- `correct_zero_pixels()`
- FFC 重采样策略
- 调色和窗口逻辑
- 显示层 `deghost_nuc()`
- 已验证的官方 LUT / palette 路径

除非有充分证据，否则这次只改 `SBNUC` 块。

## 13. 关键文件

- 主程序: [mag160c_demo3.c](/abs/path/C:/Project/MAG160C/csdk/tools/mag160c_demo3.c)
- 官方抓帧工具: [tsdk_pair2.c](/abs/path/C:/Project/MAG160C/csdk/tools/tsdk_pair2.c)
- 当前交接: [handoff_20260811_full.md](/abs/path/C:/Project/MAG160C/analysis/handoff_20260811_full.md)
- 历史进展: [progress_reverse.md](/abs/path/C:/Project/MAG160C/analysis/progress_reverse.md)
- 官方抓帧预览表: [summary.tsv](/abs/path/C:/Project/MAG160C/analysis/pairs_move/preview/summary.tsv)

## 14. 给下一个模型的直接任务

首选任务:

- 先读本文件
- 再读 `C:\Project\MAG160C\csdk\tools\mag160c_demo3.c`
- 只改 `SBNUC` 块
- 目标是明显改善“小温差鬼影擦除慢”
- 不要碰别的已稳定逻辑
- 改完后编译并启动 demo 给用户实测