wyj/GR-raytracing
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DOC: update video_rendering_plan.md

Browse Source
This commit is contained in:
wyj committed 2026-08-28 12:54:58 -04:00
1 parent 172738d932
commit a71180706f
1 file changed
+27 -14
Download Patch File Download Diff File Expand all files Collapse all files
video_rendering_plan.md
+27 -14
View File
@@ -36,7 +36,22 @@ SampleRequest -> RayPool (SoA, inactive / active / terminated)
一个 refinement pass 必须完成一次从最新到最早的 slab sweep 后，才能由 endpoint 判断是否再加样本。下一 pass 只追踪新样本并重新进行 sweep；绝不能在已经释放早期 slab 后临时创建 ray 再回到相机时间。解析 Minkowski / Schwarzschild backend 可以把 `load_slab` 实现为无 I/O 的逻辑 slab，因此能先验证同一 scheduler，而不为解析时空保留逐帧 special path。 一个 refinement pass 必须完成一次从最新到最早的 slab sweep 后，才能由 endpoint 判断是否再加样本。下一 pass 只追踪新样本并重新进行 sweep；绝不能在已经释放早期 slab 后临时创建 ray 再回到相机时间。解析 Minkowski / Schwarzschild backend 可以把 `load_slab` 实现为无 I/O 的逻辑 slab，因此能先验证同一 scheduler，而不为解析时空保留逐帧 special path。
## Phase A：先建立输入与输出边界，保持单帧兼容 ## 实施状态（2026-08-27）
本节记录已合入代码和当前 regression 实际覆盖的范围；它不将尚未完成的验收项视作已验证。
| Phase | 状态 | 已落地的范围 | 尚缺的工作 |
| --- | --- | --- | --- |
| A | 基本完成 | canonical 21 列 observer-track CSV、插值、movie frame schedule、编号 PNG/PPM 序列和相关 CLI 已实现。 | 输出仍由 `optics` 写入，尚未拆出计划中的 `output.h/.c`；CSV 非有限数、非单调时间和 PNG 序号冲突的独立回归仍需补齐。 |
| B | 部分完成 | Minkowski 恒 proper-acceleration 轨迹生成器、`0..2`/30 fps/61 frame 基准和前向解析 Doppler regression 已实现。 | 尚无逐 frame 诊断 CSV；a=0 全序列、后向红移、tetrad 正交性/有限差分速度和图像连续性回归仍需补齐。 |
| C | 核心路径完成，验收未完成 | `MetricSlab` 接口、SoA `RayPool`、slab 到达时的 lazy ray initialization、倒序 slab sweep、OpenMP 批量推进和 `(frame_id, vertex_id)` endpoint 回填已实现。 | 仍未 compact terminated rays 或支持 RayPool 增长；未记录/测试每 generation 每 slab 一次 load/free；scheduler 与 wrapper 的完整 endpoint/image 对比尚未成为当前测试。 |
| D | 未开始 | 无。 | multi-pass adaptive refinement、请求队列、nmesh slab I/O/ghost-slice/memory contract。 |
| E | 未开始 | 仅有静态 Schwarzschild 单帧和局部 inward boost。 | `30M -> 20M -> 30M` observer track、movie regression 和连续性检查。 |
| F | 未开始 | PNG sequence 是默认 movie 输出。 | FFmpeg 编码命令/目标、解码核验和可选 direct-video backend。 |
当前 `make test` 覆盖 geodesic、frame、Schwarzschild、observer-track/movie 和 catalog prefetch；通过不等价于上述未覆盖验收项已经满足。
## Phase A：先建立输入与输出边界，保持单帧兼容（基本完成）
1. 新增 `observer_track.h/.c`，将目前的 `ObserverState` 提升为可插值的 `ObserverTrack`：每个 sample 保存 `t_coordinate`、`tau`、`x[3]` 和完整 tetrad。提供加载、严格单调时间校验、区间查找、插值和销毁函数。原有固定 observer 构造函数保留，作为只含一个 sample 的兼容快捷方式。 1. 新增 `observer_track.h/.c`，将目前的 `ObserverState` 提升为可插值的 `ObserverTrack`：每个 sample 保存 `t_coordinate`、`tau`、`x[3]` 和完整 tetrad。提供加载、严格单调时间校验、区间查找、插值和销毁函数。原有固定 observer 构造函数保留，作为只含一个 sample 的兼容快捷方式。
2. 第一版轨迹输入采用人可审阅的 21 列 CSV，字段固定为 `t,tau,x,y,z,e0t,e0x,...,e3z`；不在 renderer 内从“速度曲线”临时猜 tetrad。loader 做完整性、有限数与严格单调时间检查；tetrad 的 metric 正交归一由轨迹生成器和 backend-aware regression 验证。另提供生成器工具/模式为测试写出 CSV。这样 NR 生产轨迹、解析测试轨迹和以后离线 trajectory generator 使用完全相同的 renderer 输入。 2. 第一版轨迹输入采用人可审阅的 21 列 CSV，字段固定为 `t,tau,x,y,z,e0t,e0x,...,e3z`；不在 renderer 内从“速度曲线”临时猜 tetrad。loader 做完整性、有限数与严格单调时间检查；tetrad 的 metric 正交归一由轨迹生成器和 backend-aware regression 验证。另提供生成器工具/模式为测试写出 CSV。这样 NR 生产轨迹、解析测试轨迹和以后离线 trajectory generator 使用完全相同的 renderer 输入。
@@ -46,7 +61,7 @@ SampleRequest -> RayPool (SoA, inactive / active / terminated)
验收：原有 `make test` 和两种单帧 backend 的输出保持不变；新测试验证 CSV 拒绝缺列、非有限数与非单调时间，frame 时间表精确包含首帧且不越界，PNG 序号无冲突。此阶段不要求 FFmpeg，也不改变 ray tracing 的调度方式。 验收：原有 `make test` 和两种单帧 backend 的输出保持不变；新测试验证 CSV 拒绝缺列、非有限数与非单调时间，frame 时间表精确包含首帧且不越界，PNG 序号无冲突。此阶段不要求 FFmpeg，也不改变 ray tracing 的调度方式。
## Phase B：用平直时空 accelerated observer 验证 video / tetrad / Doppler ## Phase B：用平直时空 accelerated observer 验证 video / tetrad / Doppler（部分完成）
1. 为 Minkowski 增加“从静止开始、沿相机 forward 轴恒定 proper acceleration”的离线轨迹生成器，且把生成的 samples 写成上述通用 CSV。取初始 event `t=tau=0, x=0`，加速度方向为 forward；以 proper time 参数化： 1. 为 Minkowski 增加“从静止开始、沿相机 forward 轴恒定 proper acceleration”的离线轨迹生成器，且把生成的 samples 写成上述通用 CSV。取初始 event `t=tau=0, x=0`，加速度方向为 forward；以 proper time 参数化：
@@ -61,7 +76,7 @@ SampleRequest -> RayPool (SoA, inactive / active / terminated)
验收：短序列（低分辨率、几十帧）能快速写出 PNG；首尾帧和诊断共同证明从静止到加速的连续变化，没有镜头翻转、时间倒退或每帧亮度无物理原因的跳变。 验收：短序列（低分辨率、几十帧）能快速写出 PNG；首尾帧和诊断共同证明从静止到加速的连续变化，没有镜头翻转、时间倒退或每帧亮度无物理原因的跳变。
## Phase C：以真正的 time-slab scheduler 替换 movie 逐帧追踪 ## Phase C：以真正的 time-slab scheduler 替换 movie 逐帧追踪（核心路径完成，验收未完成）
1. 扩展 `spacetime.h` 为 slab-oriented 接口：source 打开/重置、查询可用时间范围、从 `t_hi` 装载前一个 `MetricSlab`、释放 slab、在 slab 内 `eval` / `classify`。解析 backend 的 slab 是轻量边界对象；nmesh 才在此处进行顺序 I/O。顶层 `movie` 不得检查 backend 类型。 1. 扩展 `spacetime.h` 为 slab-oriented 接口：source 打开/重置、查询可用时间范围、从 `t_hi` 装载前一个 `MetricSlab`、释放 slab、在 slab 内 `eval` / `classify`。解析 backend 的 slab 是轻量边界对象；nmesh 才在此处进行顺序 I/O。顶层 `movie` 不得检查 backend 类型。
2. 新增 `ray.h/.c` 的 SoA `RayPool`。字段至少包含 coordinate time、位置、`Pi_i`、`log(alpha p^0)`、step size、`frame_id`、mesh vertex/sample id 与状态；capacity 可增长但不逐 ray 分配。所有 endpoint 写回使用稳定的 `(frame_id, vertex_id)` 关联。 2. 新增 `ray.h/.c` 的 SoA `RayPool`。字段至少包含 coordinate time、位置、`Pi_i`、`log(alpha p^0)`、step size、`frame_id`、mesh vertex/sample id 与状态；capacity 可增长但不逐 ray 分配。所有 endpoint 写回使用稳定的 `(frame_id, vertex_id)` 关联。
@@ -71,7 +86,7 @@ SampleRequest -> RayPool (SoA, inactive / active / terminated)
验收：对同一 Minkowski 与解析 Schwarzschild observer track，slab scheduler 与旧逐帧 convenience path 的 endpoint status、`n_infinity`、`log g` 及完成图像在容差内一致；增加 instrumentation 证明一个 generation 的每个 slab 只 load/free 一次，而不是每 frame 一次。Minkowski / Schwarzschild 不应出现额外磁盘 I/O。 验收：对同一 Minkowski 与解析 Schwarzschild observer track，slab scheduler 与旧逐帧 convenience path 的 endpoint status、`n_infinity`、`log g` 及完成图像在容差内一致；增加 instrumentation 证明一个 generation 的每个 slab 只 load/free 一次，而不是每 frame 一次。Minkowski / Schwarzschild 不应出现额外磁盘 I/O。
## Phase D：补全多 pass adaptive mesh 与 out-of-core 准备 ## Phase D：补全多 pass adaptive mesh 与 out-of-core 准备（未开始）
1. 给 `FrameLensMesh` 增加稳定 vertex ID、请求队列、triangle level/flags 和“缺失 endpoint”状态。每 pass 只为需要的 edge midpoint/center 产生 `SampleRequest`；安装结果后再判定 mapping interpolation error、orientation consistency 与局部 Jacobian 奇异性。 1. 给 `FrameLensMesh` 增加稳定 vertex ID、请求队列、triangle level/flags 和“缺失 endpoint”状态。每 pass 只为需要的 edge midpoint/center 产生 `SampleRequest`；安装结果后再判定 mapping interpolation error、orientation consistency 与局部 Jacobian 奇异性。
2. 以迭代 queue（可按 frame/root tile 并行、线程本地 request buffer 后 sort/deduplicate）替代递归 task。每一个 pass 完整执行 Phase C sweep；只有所有 frame 都无新请求才进行 catalog splat。 2. 以迭代 queue（可按 frame/root tile 并行、线程本地 request buffer 后 sort/deduplicate）替代递归 task。每一个 pass 完整执行 Phase C sweep；只有所有 frame 都无新请求才进行 catalog splat。
@@ -80,7 +95,7 @@ SampleRequest -> RayPool (SoA, inactive / active / terminated)
验收：构造可控 Schwarzschild strong-lensing case，确认 refinement 只增加必要 samples、多个 image patches 正确产生多像、shared edge 上的星不会重复 splat。记录每 pass 的 ray 数、峰值 active ray 数、slab load 数、peak metric memory 与 wall time，作为未来 nmesh 性能基线。 验收：构造可控 Schwarzschild strong-lensing case，确认 refinement 只增加必要 samples、多个 image patches 正确产生多像、shared edge 上的星不会重复 splat。记录每 pass 的 ray 数、峰值 active ray 数、slab load 数、peak metric memory 与 wall time，作为未来 nmesh 性能基线。
## Phase E：动态 Schwarzschild 视频验证 ## Phase E：动态 Schwarzschild 视频验证（未开始）
1. 首先使用解析 Schwarzschild Kerr--Schild backend 和离线 observer track，不改变 metric 为静态这一事实。首个回归轨迹人为规定为：从静止于 `r=30M` 出发，平滑加速径向向内，到 `r=20M` 附近平滑制动为静止，再按时间反演的同一路径返回 `r=30M`；径向局部速度上限取 `0.5c`（相对每个 event 的 static Schwarzschild tetrad）。轨迹生成器必须同时积分/构造位置和正交 tetrad，而非只对当前 `observer_inward_speed` 逐帧套 boost。 1. 首先使用解析 Schwarzschild Kerr--Schild backend 和离线 observer track，不改变 metric 为静态这一事实。首个回归轨迹人为规定为：从静止于 `r=30M` 出发，平滑加速径向向内，到 `r=20M` 附近平滑制动为静止，再按时间反演的同一路径返回 `r=30M`；径向局部速度上限取 `0.5c`（相对每个 event 的 static Schwarzschild tetrad）。轨迹生成器必须同时积分/构造位置和正交 tetrad，而非只对当前 `observer_inward_speed` 逐帧套 boost。
2. 这条路线远离 horizon，优先测试运动频移、shadow / lensing 的连续形变和回程可逆性；CSV metadata 标注 `prescribed_radial_turnaround`、速度上限与 proper acceleration。renderer 不对其物理来源作假设。逼近 horizon 的路线留到该基准稳定后再加。 2. 这条路线远离 horizon，优先测试运动频移、shadow / lensing 的连续形变和回程可逆性；CSV metadata 标注 `prescribed_radial_turnaround`、速度上限与 proper acceleration。renderer 不对其物理来源作假设。逼近 horizon 的路线留到该基准稳定后再加。
@@ -88,7 +103,7 @@ SampleRequest -> RayPool (SoA, inactive / active / terminated)
验收：前进与后退均显示相对静止 observer 的引力/运动频移和相应 image distortion，且不会因 frame 边界、slab 边界或 tetrad 插值出现闪烁。这里只要求定性图像和定量 ray regressions；具体径向轨迹参数、ODE step、refinement 阈值仍由收敛试验决定。 验收：前进与后退均显示相对静止 observer 的引力/运动频移和相应 image distortion，且不会因 frame 边界、slab 边界或 tetrad 插值出现闪烁。这里只要求定性图像和定量 ray regressions；具体径向轨迹参数、ODE step、refinement 阈值仍由收敛试验决定。
## Phase F：输出视频与运行界面 ## Phase F：输出视频与运行界面（未开始）
1. 保持 PNG sequence 为默认调试/测试产物：任何失败都能定位到具体 frame，也便于逐帧回归与检查 tone mapping。CLI 采用 `--frames-dir`、`--frames-prefix`、`--start-time`、`--duration`、`--fps`、`--observer-track`；单帧 `--output` 继续存在且语义不变。 1. 保持 PNG sequence 为默认调试/测试产物：任何失败都能定位到具体 frame，也便于逐帧回归与检查 tone mapping。CLI 采用 `--frames-dir`、`--frames-prefix`、`--start-time`、`--duration`、`--fps`、`--observer-track`；单帧 `--output` 继续存在且语义不变。
2. 在 PNG 序列稳定后，添加 `make encode` 或单独的 documented FFmpeg invocation，把序列编码为 H.264/H.265/ProRes 等明确选择的容器。编码读取已经 tone-mapped 的 PNG；HDR/EXR 与最终色彩管理是后续独立决策，不悄悄混入首次视频实现。 2. 在 PNG 序列稳定后，添加 `make encode` 或单独的 documented FFmpeg invocation，把序列编码为 H.264/H.265/ProRes 等明确选择的容器。编码读取已经 tone-mapped 的 PNG；HDR/EXR 与最终色彩管理是后续独立决策，不悄悄混入首次视频实现。
@@ -96,15 +111,13 @@ SampleRequest -> RayPool (SoA, inactive / active / terminated)
验收：同一短 PNG 序列可被 FFmpeg 无丢帧编码；解码后帧数、分辨率、帧率与原序列一致。PNG 写出失败或编码器不可用不能影响 tracing 结果的正确性，错误信息应给出可重跑的 PNG 序列位置。 验收：同一短 PNG 序列可被 FFmpeg 无丢帧编码；解码后帧数、分辨率、帧率与原序列一致。PNG 写出失败或编码器不可用不能影响 tracing 结果的正确性，错误信息应给出可重跑的 PNG 序列位置。
## 建议的提交与测试顺序 ## 后续提交与测试顺序
1. `observer track + Movie frame schedule + numbered PNG`, 不改变 ray scheduler。 1. 补齐 A--C 尚缺验收：输入边界、逐帧 Doppler 诊断、scheduler 对比和 slab instrumentation。
2. `Minkowski accelerated-track generator + analytic Doppler regressions`。 2. `multi-pass adaptive refinement`。
3. `slab interface + RayPool + aggregate movie tracing`，先固定 mesh。 3. `Schwarzschild moving observer regressions`。
4. `multi-pass adaptive refinement`。 4. `FFmpeg encoding backend / documentation`。
5. `Schwarzschild moving observer regressions`。 5. `nmesh 4D slab reader`，用数值 Schwarzschild 对解析结果作 regression，最后才接 FOZ4c BBH。
6. `FFmpeg encoding backend / documentation`。
7. `nmesh 4D slab reader`，用数值 Schwarzschild 对解析结果作 regression，最后才接 FOZ4c BBH。
每一步均应保留前一步的 Minkowski 和 Schwarzschild regression；新参数（轨迹采样密度、slab 内存预算、ODE step、refinement 阈值、PNG/视频 tone map）由小型 prototype 或收敛测试选择，而非在本计划中固定。 每一步均应保留前一步的 Minkowski 和 Schwarzschild regression；新参数（轨迹采样密度、slab 内存预算、ODE step、refinement 阈值、PNG/视频 tone map）由小型 prototype 或收敛测试选择，而非在本计划中固定。