nerfstudio 工程实践速查表

一张可打印的速查表，覆盖安装、训练、评估、导出的核心命令和参数。

🔧 安装

conda create -n nerfstudio -y python=3.8
conda activate nerfstudio
pip install torch==2.1.2+cu118 torchvision==0.16.2+cu118 \
    --extra-index-url https://download.pytorch.org/whl/cu118
conda install -c "nvidia/label/cuda-11.8.0" cuda-toolkit
pip install ninja git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch
pip install nerfstudio
ns-install-cli

📦 数据准备

命令用途
ns-download-data nerfstudio --capture-name=poster下载示例数据集
ns-process-data images --data images/ --output-dir data/从图片生成训练数据
ns-process-data video --data video.mp4 --output-dir data/从视频抽帧生成数据

🚀 训练

# 基础训练
ns-train nerfacto --data data/custom/

# 显存受限
ns-train nerfacto \
    --pipeline.datamanager.train-num-rays-per-batch 2048 \
    --data data/custom/

# 从 checkpoint 恢复
ns-train nerfacto --data data/custom/ \
    --load-dir outputs/.../nerfstudio_models/

# 多 GPU
ns-train nerfacto --machine.num-devices 2 \
    --pipeline.datamanager.train-num-rays-per-batch 2048 \
    --data data/custom/

📊 评估

ns-eval --load-config outputs/.../config.yml --output-path eval.json
指标范围解读
PSNR越高越好，>30 优秀像素级误差，对异常值敏感
SSIM[0,1]，越接近 1 越好结构相似性，接近人眼感知
LPIPS[0,1]，越接近 0 越好感知损失，最贴近主观感受

🎬 渲染与导出

# 渲染视频
ns-render --load-config outputs/.../config.yml --traj spiral

# 导出点云
ns-export pointcloud --load-config outputs/.../config.yml

# 导出网格
ns-export mesh --load-config outputs/.../config.yml

# 启动 Viewer
ns-viewer --load-config outputs/.../config.yml

⚙️ 常用调参

参数路径默认值调整场景
rays per batchpipeline.datamanager.train-num-rays-per-batch4096显存不足/过剩
hash levelspipeline.model.num-levels16场景复杂度
hidden dimpipeline.model.hidden-dim64精度/速度 trade-off
max iterationsmax-num-iterations30000训练时间限制
learning rateoptimizers.fields.lr1e-2训练不稳定
save intervaltrainer.steps-per-save2000磁盘空间

🐛 常见问题速查

CUDA 版本不匹配

确认 nvcc --version 与 PyTorch CUDA 版本一致。不一致时重新安装对应版本 PyTorch。

COLMAP 失败

弱纹理/重复纹理/动态物体导致。增加拍摄角度、避免纯色区域、移除动态元素。

Viewer 无法连接

更换端口 --viewer.websocket-port 7008；远程机器需配置 SSH 端口转发。

训练 loss 不下降

检查 transforms.json 格式；尝试降低学习率；确认数据路径正确。

重建模糊

增加迭代次数；提高 num-levels；检查 COLMAP 位姿质量。

出现鬼影

场景中有移动物体。使用三脚架拍摄，移除动态元素。

📚 关联课程

← 返回课程目录