From 78d5c9f2ecca3a0ea5a8634a32e864b576833037 Mon Sep 17 00:00:00 2001 From: chu-jiaming Date: Sat, 7 Nov 2026 21:02:12 +0800 Subject: [PATCH] docs: tighten README wording and sync English with Chinese - Simplify the CamP-style note, limitations list and quickstart/release text - Fix grammar and phrasing in both READMEs - Replace "controlled study" with plainer wording Co-Authored-By: Claude Opus 5.5 --- README.md | 31 +++++++++++++++---------------- README.zh-CN.md | 30 ++++++++++++++++-------------- 2 files changed, 31 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 96a8a87..ebcf212 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,11 @@ English | [中文](README.zh-CN.md) Right: joint pose optimization with a camera learning-rate warm-up, 22.7 dB. Same data, same 30k steps.

-A controlled study of NeRF under noisy camera poses: **45 training runs** -(9 pose-noise levels × 5 methods) on Nerfstudio's vanilla-NeRF, plus pose audits -and a Sim(3) alignment diagnostic that separates *worse reconstruction* from -*a reconstruction that is fine but sits in a shifted coordinate frame*. +A side-by-side comparison of NeRF under noisy camera poses, with everything +else held fixed: **45 training runs** (9 pose-noise levels × 5 methods) on +Nerfstudio's vanilla-NeRF, plus pose audits and a Sim(3) alignment diagnostic +that separates *worse reconstruction* from *a reconstruction that is fine but +sits in a shifted coordinate frame*. ## TL;DR @@ -48,8 +49,8 @@ flowchart LR - **Naive:** a 6-D SO(3) × R³ correction per training camera, optimized jointly with the radiance field. - **CamP-style:** the same correction in a preconditioned space, δ = Pz, where P - whitens the projection Jacobian of each camera - ([CamP](https://camp-nerf.github.io/), re-implemented from the idea, not the original code). + whitens the projection Jacobian of each camera (re-implemented following + [CamP](https://camp-nerf.github.io/)). - **Warm-up:** the camera learning rate ramps from 1e-8 to 1e-3 over the first 2,500 steps instead of starting at 1e-3. - **Alignment diagnostic:** fit a similarity transform between GT and optimized @@ -109,16 +110,13 @@ Details: [paired analysis](artifacts/analysis/warmup/report.md), ## Limitations -One scene (Lego), one seed (42). CamP-style is a controlled re-implementation. -The warm-up changes the whole camera learning-rate schedule, so the early phase -alone is not isolated. Full aligned rendering covers the GT condition only. The -alignment is a diagnostic of how test metrics are measured, not a new training -method. These results do not establish behavior on other scenes or seeds. +1. One scene (Lego), one seed (42). +2. The warm-up changes the whole camera learning-rate schedule, so the early + phase alone is not isolated. +3. Full aligned rendering covers the GT condition only. ## Quickstart -Re-check the published numbers on a CPU, with no dataset or checkpoint needed: - ```bash uv sync --extra analysis uv run python scripts/analysis/analyze_warmup_results.py --plots @@ -126,9 +124,10 @@ uv run python -m unittest discover -s tests -p "test_alignment.py" -v ``` The seven final checkpoints behind the GT alignment table and the T5 comparison -are on the [release](https://github.com/chu-jiaming/PoseGuard-NeRF/releases/tag/v1.0.0), -with SHA-256 sums and loading steps. Training, resuming, auditing and aligned -rendering need a CUDA GPU. See [docs/RUNNING.md](docs/RUNNING.md). +are published on the [release page](https://github.com/chu-jiaming/PoseGuard-NeRF/releases/tag/v1.0.0). + +Training, resuming, auditing and aligned rendering need a CUDA GPU. See +[docs/RUNNING.md](docs/RUNNING.md). ## Repository layout diff --git a/README.zh-CN.md b/README.zh-CN.md index 2af1f9e..86e953b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -17,13 +17,13 @@ 右：联合位姿优化 + 相机学习率 warm-up，22.7 dB。数据相同，均训练 30k 步。

-这是一项关于 NeRF 在相机位姿有误差时表现的受控实验：基于 Nerfstudio vanilla-NeRF 完成 **45 次训练**（9 种位姿扰动 × 5 种方法），并做了位姿审计和 Sim(3) 对齐诊断，用来区分两种情况：**重建本身变差了**，和**重建没问题、只是整体坐标系偏了**。 +本项目在相同设置下做了一组对比实验，研究 NeRF 在相机位姿有误差时的表现：基于 Nerfstudio vanilla-NeRF 完成 **45 次训练**（9 种位姿扰动 × 5 种方法），并做了位姿审计和 Sim(3) 对齐诊断，用来区分两种情况：**重建本身变差了**，和**重建没问题、只是整体坐标系偏了**。 ## 要点 - **很小的位姿误差就能让固定相机的 NeRF 失效。** 测试 PSNR 从 27.1 dB 降到 14.1 dB（5% 平移扰动）和 12.0 dB（5° 旋转扰动）。 -- **联合位姿优化能找回大部分损失。** 加上 2,500 步相机学习率 warm-up 后，Naive 方法在 **9/9** 种条件下都更好，平均 +4.3 dB；5% 平移扰动下从 14.1 dB 提升到 22.7 dB。 -- **但从完全正确的位姿出发打开优化，PSNR 反而从 27.1 降到 17.9 dB。** 诊断结果是重建发生了整体漂移：冻结网络，只用训练相机中心拟合一个 Sim(3)，Naive 就能找回 **+5.5 dB**，CamP-style 找回 **+6.1 dB**。原坐标下的测试指标，把场景质量和全局坐标漂移混在了一起。 +- **联合位姿优化能找回大部分损失。** 加上 2,500 步相机学习率 warm-up 后，Naive 方法在 **9/9** 种条件下都优于不加 warm-up 的版本，平均 +4.3 dB；5% 平移扰动下从 14.1 dB 提升到 22.7 dB。 +- **但从完全正确的位姿出发优化，PSNR 反而从 27.1 降到 17.9 dB。** 诊断结果是重建发生了整体漂移：冻结网络，只用训练相机中心拟合一个 Sim(3)，Naive 就能找回 **+5.5 dB**，CamP-style 找回 **+6.1 dB**。原坐标下的测试指标把场景质量和全局坐标漂移混在了一起。 ## 方法 @@ -36,27 +36,27 @@ flowchart LR ``` - **Naive：** 每台训练相机一个六维 SO(3) × R³ 修正量，与辐射场联合优化。 -- **CamP-style：** 同样的修正量，但放在预条件空间里优化，δ = Pz，P 用来白化每台相机的投影 Jacobian。这是按 [CamP](https://camp-nerf.github.io/) 的思路做的受控复现，不是原始代码。 +- **CamP-style：** 同样的修正量，但放在预条件空间里优化，δ = Pz，P 用来白化每台相机的投影 Jacobian。按 [CamP](https://camp-nerf.github.io/) 的思路复现。 - **Warm-up：** 相机学习率在前 2,500 步从 1e-8 逐渐升到 1e-3，而不是一开始就用 1e-3。 - **对齐诊断：** 用 GT 和优化后的**训练**相机中心拟合一个相似变换，把它应用到**测试**相机上再重新渲染。拟合不使用任何测试图像，也不更新任何权重。 -完整实验协议见 [docs/EXPERIMENTS.md](docs/EXPERIMENTS.md)（英文）。 +完整实验方案见 [docs/EXPERIMENTS.md](docs/EXPERIMENTS.md)。 ## 结果 -### 1. 位姿扰动让固定相机失效，位姿优化把质量找回来 +### 1. 位姿扰动让固定相机失效，位姿优化把质量补回来 ![5% 平移和 5° 旋转扰动下，五种方法在同一测试视角的渲染](docs/assets/perturbation_grid.png) 9 种位姿条件 × 5 种方法的测试 PSNR 热力图 -固定相机只在位姿完全正确或只有 0.5% 平移扰动时最好。其余 7 种扰动条件里，Naive + warm-up 在 6 种中最好，剩下的 2° 旋转条件下只比 CamP-style + warm-up 低 0.09 dB。 +固定相机只在位姿完全正确或仅有 0.5% 平移扰动时最好。其余 7 种扰动条件里，Naive + warm-up 在 6 种中最好，剩下的 2° 旋转条件下只比 CamP-style + warm-up 低 0.09 dB。 -从恢复出的相机位置可以看出原因：联合优化把带噪声的训练相机拉回到平均距 GT 0.025 个场景单位以内（原始扰动为 0.16）；再去掉一个全局相似变换，误差降到 0.016。 +从恢复出的相机位置可以看出原因：联合优化把带噪声的训练相机中心与 GT 的平均距离从 0.16 拉回到 0.025 个场景单位；再去掉一个全局相似变换，误差降到 0.016。 ![联合位姿优化前后的训练相机中心误差（放大 10 倍显示）](docs/assets/camera_correction.png) -### 2. "从正确位姿出发反而变差"，主要是坐标漂移 +### 2. “从正确位姿出发反而变差”，主要是坐标漂移 ![GT、固定相机、Naive 原坐标与 Naive 对齐后的渲染及逐像素误差图](docs/assets/hero_drift.png) @@ -81,19 +81,21 @@ Naive 的渲染本身是清晰的，只是整体偏了位置，所以误差集 ## 局限 -只有一个场景（Lego）、一个随机种子（42）。CamP-style 是受控复现，不是原始实现。Warm-up 改变的是整个相机学习率日程，没有单独隔离前期阶段的作用。完整的对齐渲染只覆盖了 GT 条件。对齐是对测试指标测量方式的诊断，不是一种新的训练方法。这些结果不能推广到其他场景或其他随机种子。 +1. 只有一个场景（Lego）、一个随机种子（42）。 +2. Warm-up 改变的是整个相机学习率调度，没有单独隔离前期阶段的作用。 +3. 完整的对齐渲染只覆盖了 GT 条件。 ## 快速开始 -在 CPU 上就能复核已发布的数字，不需要数据集或 checkpoint： - ```bash uv sync --extra analysis uv run python scripts/analysis/analyze_warmup_results.py --plots uv run python -m unittest discover -s tests -p "test_alignment.py" -v ``` -GT 对齐表和 T5 对比所用的 7 个最终 checkpoint 发布在 [Release](https://github.com/chu-jiaming/PoseGuard-NeRF/releases/tag/v1.0.0)，附 SHA-256 校验和与加载步骤。训练、断点续跑、位姿审计和对齐渲染都需要 CUDA GPU，步骤见 [docs/RUNNING.md](docs/RUNNING.md)（英文）。 +GT 对齐表和 T5 对比所用的 7 个最终 checkpoint 发布在 [Release](https://github.com/chu-jiaming/PoseGuard-NeRF/releases/tag/v1.0.0)。 + +训练、断点续跑、位姿审计和对齐渲染都需要 CUDA GPU，步骤见 [docs/RUNNING.md](docs/RUNNING.md)。 ## 目录结构 @@ -107,7 +109,7 @@ scripts/ showcase/ 导入服务器渲染结果，生成 README 图 tests/ CPU 测试（对齐、编排、可移植性）与 GPU 测试 artifacts/ 全部 45 次训练的配置、指标、位姿和报告存档（索引见 artifacts/README.md） -docs/ 实验协议、运行指南、图片 +docs/ 实验方案、运行指南、图片 ``` ## 参考文献