# 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 访问权限。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/nerfstudio.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.