# Nerfstudio

**Nerfstudio** 是一个模块化、对研究人员友好的训练和渲染框架，用于 **神经辐射场（NeRF）** —— 一种从二维图像重建照片级真实感三维场景的技术。它在 GitHub 上拥有超过 10,000 颗星，是 NeRF 研究和生产应用的事实标准。将其运行在 Clore.ai 的 GPU 云上，可从您自己的照片或视频重建 3D 场景。

***

## 什么是 Nerfstudio？

NeRF（神经辐射场）将三维场景表示为一个神经网络，该网络在给定相机位置和方向时，输出该点的颜色和密度。通过在不同角度拍摄的数十张照片上进行训练，NeRF 学会了完整的三维表示，可以从任何视角进行渲染。

**Nerfstudio 提供：**

* 多种 NeRF 方法：Nerfacto、Instant-NGP、Splatfacto、TensoRF 等
* 命令行界面（CLI）和 Python API
* 在 7007 端口的交互式网页查看器（Viser）
* 导出为点云、网格和视频飞越
* 通过 COLMAP 集成支持自定义数据集

**使用场景：**

* 从无人机航拍重建 3D 场景
* 从照片进行产品可视化
* 从智能手机拍摄创建虚拟导览
* 新视角合成的研究

***

## 先决条件

| 要求      | 最低要求     | 推荐配置            |
| ------- | -------- | --------------- |
| GPU 显存  | 8 GB     | 16–24 GB        |
| GPU     | RTX 3080 | RTX 4090 / A100 |
| 内存（RAM） | 16 GB    | 32 GB           |
| 存储      | 20 GB    | 50+ GB          |
| CUDA    | 11.8+    | 12.1+           |

{% hint style="info" %}
训练时间随场景复杂度而变化。典型的 100 张户外照片的场景在 RTX 4090 上训练需 10–30 分钟。交互式查看器在训练过程中实时更新。
{% endhint %}

***

## 步骤 1 — 在 Clore.ai 上租用 GPU

1. 登录到 [clore.ai](https://clore.ai).
2. 点击 **市场** 并筛选 VRAM ≥ 16 GB。
3. 选择一台服务器 —— RTX 4090 是 Nerfstudio 的理想选择。
4. 设置 Docker 镜像： **`dromni/nerfstudio:latest`**
5. 设置开放端口： `22` （SSH）和 `7007` （Viser 网页查看器）。
6. 点击 **租用** 并等待实例初始化完成。

{% hint style="info" %}
参数 `dromni/nerfstudio` 镜像是社区维护的官方镜像，包含所有预装依赖（CUDA、tiny-cuda-nn、colmap、ffmpeg）。
{% endhint %}

***

## 步骤 2 — 通过 SSH 连接

```bash
ssh user@<clore-host> -p <assigned-ssh-port>
```

{% hint style="info" %}
参数 `dromni/nerfstudio` 镜像使用 `用户` （不是 `root 用户`）作为默认。使用 `sudo` 执行管理任务。
{% endhint %}

验证安装：

```bash
ns-train --help
ns-render --help
ns-viewer --help
```

***

## 步骤 3 — 准备您的数据集

### 选项 A：使用提供的示例数据集

Nerfstudio 包含内置数据集，可立即进行测试：

```bash
# 下载 poster 数据集（小，适合测试）
ns-download-data nerfstudio --capture-name=poster

# 其他可用数据集：
# ns-download-data nerfstudio --capture-name=egypt
# ns-download-data nerfstudio --capture-name=floating-tree
# ns-download-data nerfstudio --capture-name=stump
```

### 选项 B：处理您自己的图像

如果您有场景的照片或视频：

#### 从图像（COLMAP 流程）：

```bash
# 通过 SCP 上传您的图像
scp -P <port> -r ./my_photos/ user@<clore-host>:/home/user/data/

# 使用 COLMAP 处理以获取相机位姿
ns-process-data images \
    --data /home/user/data/my_photos \
    --output-dir /home/user/data/my_scene
```

#### 从视频：

```bash
# 上传视频
scp -P <port> my_video.mp4 user@<clore-host>:/home/user/data/

# 提取帧并处理
ns-process-data video \
    --data /home/user/data/my_video.mp4 \
    --output-dir /home/user/data/my_scene \
    --num-frames-target 200
```

{% hint style="info" %}
为了获得最佳效果，请使用 **100–300 张照片** 并确保有显著重叠（相邻帧之间 >60%）。围绕物体/场景按系统化模式行走 —— 圆形、网格或八字形都很有效。
{% endhint %}

***

## 步骤 4 — 训练 NeRF

### 使用 Nerfacto 的基础训练（推荐）

Nerfacto 是 Nerfstudio 的旗舰方法，平衡了质量和速度：

```bash
ns-train nerfacto \
    --data /home/user/data/my_scene \
    --viewer.websocket-port 7007 \
    --output-dir /home/user/outputs
```

### 使用 Instant-NGP 训练（最快）

```bash
ns-train instant-ngp \
    --data /home/user/data/my_scene \
    --viewer.websocket-port 7007 \
    --output-dir /home/user/outputs
```

### 使用提供的 poster 数据集进行训练

```bash
ns-train nerfacto \
    --data /home/user/data/nerfstudio/poster \
    --viewer.websocket-port 7007
```

***

## 步骤 5 — 访问交互式查看器

打开浏览器并访问：

```
http://<clore-host>:<public-port-7007>
```

您将看到由以下组件驱动的 3D 查看器： **Viser** 显示内容：

* 实时训练进度
* 当前 NeRF 渲染质量
* 交互式相机控制
* 训练损失曲线

{% hint style="info" %}
查看器在训练期间每隔几秒更新一次。您可以旋转、平移和缩放以在训练过程中检查场景质量。
{% endhint %}

***

## 可用的训练方法

| 方法             | 适用场景 | 速度  | 显存（VRAM） | 说明                       |
| -------------- | ---- | --- | -------- | ------------------------ |
| `nerfacto`     | 高细节  | 高   | 8 GB     | 最佳全能选择                   |
| `instant-ngp`  | 通用使用 | 高细节 | 6 GB     | 训练速度最快                   |
| `splatfacto`   | 通用使用 | 高   | 8 GB     | 高斯点绘（Gaussian splatting） |
| `tensorf`      | 高细节  | 高   | 12 GB    | 适合物体建模                   |
| `mipnerf360`   | 较慢   | 非常高 | 24 GB    | 最佳质量                     |
| `vanilla-nerf` | 非常慢  | 高   | 16 GB    | 研究基线                     |

### 使用 Splatfacto（高斯点绘）训练

```bash
ns-train splatfacto \
    --data /home/user/data/my_scene \
    --viewer.websocket-port 7007 \
    --pipeline.model.num-random 50000
```

***

## 步骤 6 — 评估与渲染

### 检查训练指标

```bash
# 查看训练摘要
ls /home/user/outputs/my_scene/nerfacto/

# 最新检查点
ls /home/user/outputs/my_scene/nerfacto/*/nerfstudio_models/
```

### 渲染视频飞越

```bash
# 交互式：在查看器中设置相机路径，然后导出
# 命令行渲染：

ns-render camera-path \
    --load-config /home/user/outputs/my_scene/nerfacto/<timestamp>/config.yml \
    --camera-path-filename /home/user/data/my_scene/camera_paths/my_path.json \
    --output-path /home/user/renders/output.mp4
```

### 渲染插值螺旋路径

```bash
ns-render interpolate \
    --load-config /home/user/outputs/my_scene/nerfacto/<timestamp>/config.yml \
    --output-path /home/user/renders/spiral.mp4 \
    --render-nearest-camera True \
    --order-poses True
```

***

## 步骤 7 — 导出 3D 几何

### 导出点云

```bash
ns-export pointcloud \
    --load-config /home/user/outputs/my_scene/nerfacto/<timestamp>/config.yml \
    --output-dir /home/user/exports/ \
    --num-points 1000000
```

### 导出网格

```bash
ns-export marching-cubes \
    --load-config /home/user/outputs/my_scene/nerfacto/<timestamp>/config.yml \
    --output-dir /home/user/exports/ \
    --resolution 1024
```

### 导出高斯点绘（PLY）

```bash
ns-export gaussian-splat \
    --load-config /home/user/outputs/my_scene/splatfacto/<timestamp>/config.yml \
    --output-dir /home/user/exports/
```

***

## Python API

用于编程方式的训练与评估：

```python
from nerfstudio.scripts.train import main
from nerfstudio.configs.base_config import ViewerConfig
from nerfstudio.engine.trainer import TrainerConfig

# Python API 训练示例
from nerfstudio.configs.method_configs import method_configs
from pathlib import Path

config = method_configs["nerfacto"]
config.pipeline.datamanager.data = Path("/home/user/data/my_scene")
config.viewer = ViewerConfig(websocket_port=7007, num_rays_per_chunk=1<<15)
config.max_num_iterations = 30000

trainer = config.setup()
trainer.train()
```

***

## 自定义数据集提示

### 相机拍摄最佳实践

| 设置   | 推荐                     |
| ---- | ---------------------- |
| 重叠   | 帧间 ≥ 60%               |
| 图像数量 | 100–300（户外）、50–150（物体） |
| 移动方式 | 缓慢、稳定的移动               |
| 光照   | 保持一致，避免强烈阴影            |
| 对焦   | 全程清晰                   |

### 改善 COLMAP 结果

```bash
# 对于困难场景，使用穷尽匹配（更慢但更准确）
ns-process-data images \
    --data /home/user/data/my_photos \
    --output-dir /home/user/data/my_scene \
    --sfm-tool colmap \
    --matching-method exhaustive
```

***

## 故障排除

### COLMAP 无法找到相机位姿

**将批量大小减小到 1**

* 确保图像具有足够的重叠
* 确认图像清晰（无运动模糊）
* 尝试穷尽匹配： `--matching-method exhaustive`
* 减少 `--num-frames-target` 用于视频以选择更好的帧

### 查看器无法访问

**解决方案：** 确保在 Clore.ai 中已转发 7007 端口。测试连接性：

```bash
ss -tlnp | grep 7007
```

### 训练损失未下降

**将批量大小减小到 1**

* 检查 COLMAP 是否成功（在输出目录中查找 `transforms.json` ）
* 降低学习率： `--pipeline.model.field-implementation hash`
* 检查是否存在占主导的天空（使用 `--pipeline.model.background-color white`)

### 内存不足（Out of Memory）

```bash
# 减小批量大小
ns-train nerfacto \
    --data /home/user/data/my_scene \
    --pipeline.datamanager.train-num-rays-per-batch 2048 \
    --pipeline.datamanager.eval-num-rays-per-batch 1024
```

***

## 下载输出

训练完成后，下载您的渲染和导出文件：

```bash
# 从您的本地机器
scp -P <port> -r user@<clore-host>:/home/user/renders/ ./local-renders/
scp -P <port> -r user@<clore-host>:/home/user/exports/ ./local-exports/
```

***

## 成本估算

| GPU       | 显存（VRAM） | 预计价格       | 100 张图像的场景 |
| --------- | -------- | ---------- | ---------- |
| RTX 3080  | 10 GB    | 约 $0.10/小时 | 约 30–45 分钟 |
| RTX 4090  | 24 GB    | 约 $0.35/小时 | \~10–15 分钟 |
| A100 40GB | 40 GB    | 约 $0.80/小时 | 约 5–8 分钟   |

{% hint style="info" %}
首先使用 Instant-NGP 进行快速预览，然后切换到 Nerfacto 或 MipNeRF360 以获得最终质量。此工作流程可节省大量计算成本。
{% endhint %}

***

## 有用的资源

* [Nerfstudio GitHub](https://github.com/nerfstudio-project/nerfstudio)
* [Nerfstudio 文档](https://docs.nerf.studio)
* [dromni/nerfstudio Docker Hub](https://hub.docker.com/r/dromni/nerfstudio)
* [Nerfstudio 方法比较](https://docs.nerf.studio/nerfology/methods/index.html)
* [COLMAP 文档](https://colmap.github.io/)

***

## Clore.ai 的 GPU 建议

| 在 Clore.ai 上的预估费用 | 开发/测试             | RTX 3090（24GB） |
| ----------------- | ----------------- | -------------- |
| \~$0.12/每 GPU/每小时 | 生产                | RTX 4090（24GB） |
| \~$0.70/每 GPU/每小时 | 大规模               | A100 80GB      |
| 大规模 / 高分辨率 场景     | 💡 本指南中的所有示例均可部署在 | Clore.ai       |

> GPU 服务器上。浏览可用 GPU 并按小时租用 — 无需承诺，提供完整的 root 访问权限。 [Clore.ai](https://clore.ai/marketplace) GPU 服务器。浏览可用 GPU 并按小时租用 — 无需承诺，提供完整的 root 访问权限。