> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/3d-sheng-cheng/nerfstudio.md).

# Nerfstudio

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

***

## 什么是 Nerfstudio？

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

**Nerfstudio 提供：**

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

**适用场景：**

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

***

## 前提条件

| 要求     | 最低       | 推荐              |
| ------ | -------- | --------------- |
| GPU 显存 | 8 GB     | 16–24 GB        |
| GPU    | RTX 3080 | RTX 4090 / A100 |
| 内存     | 16 GB    | 32 GB           |
| 存储     | 20 GB    | 50+ GB          |
| CUDA   | 12.8+    | 12.8+           |

{% 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` 镜像默认使用 `user` （非 `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%）。围绕物体/场景按系统化路径移动——圆形、网格或“8”字形都很有效。
{% 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>
```

你将看到一个由 **Viser** 提供支持的 3D 查看器，它会显示：

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

{% hint style="info" %}
查看器会在训练期间每隔几秒更新一次。你可以旋转、平移和缩放，以便在训练推进时检查场景质量。
{% endhint %}

***

## 可用的训练方法

| 方法             | 速度  | 质量  | 显存    | 备注           |
| -------------- | --- | --- | ----- | ------------ |
| `nerfacto`     | 中等  | 高   | 8 GB  | 综合表现最佳       |
| `instant-ngp`  | 快   | 中等  | 6 GB  | 训练速度最快       |
| `splatfacto`   | 快   | 高   | 8 GB  | 高斯 splatting |
| `tensorf`      | 中等  | 高   | 12 GB | 适合物体         |
| `mipnerf360`   | 慢   | 非常高 | 24 GB | 最佳质量         |
| `vanilla-nerf` | 非常慢 | 高   | 16 GB | 研究基线         |

### 使用 Splatfacto（高斯 splatting）训练

```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 无法找到相机位姿

**解决方案：**

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

### 无法访问查看器

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

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

### 训练损失没有下降

**解决方案：**

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

### 内存不足

```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       | 显存    | 预估价格                              | 100 张图像的场景 |
| --------- | ----- | --------------------------------- | ---------- |
| RTX 3080  | 10 GB | $0.05–0.19/小时                     | 约 30–45 分钟 |
| RTX 4090  | 24 GB | $0.14–0.42/小时                     | 约 10–15 分钟 |
| A100 40GB | 40 GB | [裸机](https://clore.ai/bare-metal) | 约 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 推荐

| 使用场景         | 推荐 GPU         | Clore.ai 预计成本                     |
| ------------ | -------------- | --------------------------------- |
| 开发/测试        | RTX 3090（24GB） | $0.07–0.21/gpu/hr                 |
| 生产环境         | RTX 4090（24GB） | $0.14–0.42/gpu/hr                 |
| 大规模 / 高分辨率场景 | A100 80GB      | [裸机](https://clore.ai/bare-metal) |

> 💡 本指南中的所有示例都可以部署在 [Clore.ai](https://clore.ai/marketplace) GPU 服务器上。浏览可用 GPU 并按小时租用——无需承诺，拥有完整 root 访问权限。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.