Skip to content

docs: tighten README wording and sync English with Chinese #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chu-jiaming merged 1 commit into from
Nov 7, 2026
Merged

docs: tighten README wording and sync English with Chinese #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 15 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.</sub>
</p>

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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -109,26 +110,24 @@ 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
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

Expand Down
30 changes: 16 additions & 14 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,13 @@
右：联合位姿优化 + 相机学习率 warm-up，22.7 dB。数据相同，均训练 30k 步。</sub>
</p>

这是一项关于 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**。原坐标下的测试指标把场景质量和全局坐标漂移混在了一起。

## 方法

Expand All @@ -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)

<img src="docs/assets/psnr_matrix.png" width="620" alt="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)

Expand All @@ -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)。

## 目录结构

Expand All @@ -107,7 +109,7 @@ scripts/
showcase/ 导入服务器渲染结果，生成 README 图
tests/ CPU 测试（对齐、编排、可移植性）与 GPU 测试
artifacts/ 全部 45 次训练的配置、指标、位姿和报告存档（索引见 artifacts/README.md）
docs/ 实验协议、运行指南、图片
docs/ 实验方案、运行指南、图片
```

## 参考文献
Expand Down
Loading