Phase 1: Golden Image 回归测试 — Python CI 视觉回归检测

[Cle2ment]

背景

28 个 Catch2 测试验证数学逻辑（GGX 值、Fresnel），但零个验证视觉输出。任何像素级的渲染回归在当前 CI 中完全无法检测。

目标

引入 Python 脚本（Pillow + NumPy），对 CPU 确定性渲染输出做 SSIM + MSE 比对，集成到 CI，作为所有后续渲染改动的安全网。

详细需求

1. Python 测试脚本 scripts/test_golden.py

   • 固定种子运行 CPU 渲染器，输出当前帧
   • 与 test/golden/ 下的参考图像做 SSIM + MSE 比对
   • SSIM > 0.999 通过，CI 直接失败则阻止合并

2. 参考图像生成

   • test/golden/default_scene.png — 默认场景
   • test/golden/emissive_scene.png — 发光材质测试

3. CI 集成

   • 在现有 build.yml 中新增独立 job
   • Debug + Release 均运行
   • pip install Pillow numpy scikit-image 作为前置步骤

4. 确定性保证

   • 固定 PCG 随机种子
   • 必要时回退单线程以消除 std::execution::par 调度不确定性

验收标准

• scripts/test_golden.py 在本地运行通过
• CI 中 Python 测试 job 通过
• SSIM > 0.999 判定标准生效
• 参考图像已提交到 test/golden/

[github-actions]

审查意见

核心问题：无 headless 模式

当前应用始终需要 Vulkan 窗口 + ImGui 才能运行（PeanutApp.cpp:257-276），无法从 Python 脚本通过 CLI 直接调用渲染并输出图像。scripts/test_golden.py 需要用某种方式驱动渲染管线，但目前没有暴露该能力。

建议方案

推荐：C++ 内实现 golden 测试（扩展 RayTracing_test），而非 Python 脚本

理由：

1. CI 已有 test job（build.yml:176-205）——构建并运行 RayTracing_test，不需要 CUDA/Vulkan/OptiX。Python 则需新增 runner、安装依赖、传递二进制路径。
2. 确定性保证已存在——CPU C++ 路径使用 PCG_Hash(pixelIdx * frameIndex + bounce)，同一平台 MSVC x64 上输出完全确定（PathTracerCore.h:36-49）。
3. stb_image_write.h 已通过 xrepo 可用——直接写 PNG 比 Python 的 Pillow/NumPy/scikit-image 更简洁，省去 CI 安装 Python 包的步骤。
4. 像素级比对——m_ImageData 是 std::vector<uint32_t>（ABGR 8-8-8-8），Catch2 内直接逐像素检查 WithinAbs(1) 即可，无需 SSIM 指标。SSIM > 0.999 对于固定种子的确定性渲染是过度设计——bit-exact 比对更直接。
5. C++ 可以引用 Scene.h、Camera.h、CPUBackend.h——无需重构即可创建测试场景。

具体实现路径

1. 在 RayTracing/test/ 下新增 TestGolden.cpp

   • 创建 Scene 对象（手动填充默认场景的 sphere + material 列表——参照 PeanutApp.cpp:93-130）
   • 创建 Camera(45.0f, 0.1f, 100.0f)，固定分辨率 256×256
   • 创建 CPUBackend，调用 OnResize → Render
   • 读出 CPUBackend 的 accumulation buffer 或 Renderer::m_ImageData
   • 与从 test/golden/default_scene.png 读入的参考图像逐像素对比

2. 参考图像生成

   • 在 CI 上首次运行时输出 m_ImageData 为 PNG（用 stb_image_write）存入 CI artifact
   • 人工审核后提交到 test/golden/
   • 或：用 ConvertToRGBA + 已知 seed 推算出预期值（当前 28 个 Catch2 测试已覆盖 ConvertToRGBA 的 bit-exact 行为——TestColor.cpp:9-11）

3. CI 集成

   • 扩展 test job 中的 xmake run RayTracing_test 步骤——无需新增 job
   • 将 stb 包加入 RayTracing_test 依赖（xmake.lua:192-197）

如果坚持用 Python 方案

需要先做以下前置工作：

1. 在 PeanutApp.cpp 添加 --headless CLI 参数解析，跳过窗口创建
2. 渲染完成后调用 stb_image_write 将 m_ImageData 输出为 PNG 文件
3. Python 脚本再读取该 PNG 与 golden 比较

这比 Catch2 方案多 2-3× 工作量，且引入了 Python CI 依赖。

RNG 平台差异注意事项

路径	RandomFloat 实现	与 CPU C++ bit-exact?
CPU C++	float(seed) / UINT32_MAX	基准
GPU CUDA	__uint2float_ru(seed) * 2^-32	❌ 舍入不同
CPU ISPC	float(seed & 0x7FFFFFFF) * 2^-31	❌ 仅 31-bit

Golden 测试必须锁定 CPU C++ 路径（CPUBackend）。ISPC 和 CUDA 路径因浮点舍入差异，即使相同种子也不会产生 bit-identical 输出。

文档参考

• stb_image_write.h 用法：stbi_write_png("output.png", width, height, 4, data, width * 4) — 已在 xrepo 中，版本 2026.03.18
• Catch2 v3 API：TEST_CASE / REQUIRE_THAT / WithinAbs — 参看现有 TestGGX.cpp:13
• 现有 CI test job：build.yml:176-205 — 无 CUDA/Vulkan 依赖，可直接扩展

总结：建议将 golden 测试实现在 C++ Catch2 框架内，而非 Python。 改动范围小、确定性好、复用现有 CI 基础设施。

opencode session  |  github run