dromni/nerfstudio

nerfstudio Docker镜像文档

镜像概述与主要用途

本Docker镜像包含nerfstudio及其所有依赖的软件包和工具，提供开箱即用的nerfstudio运行环境。镜像基于CUDA 11.8构建，集成了colmap等第三方软件，无需额外安装依赖即可直接使用nerfstudio的全部功能。

核心功能与特性

• 完整依赖集成：包含nerfstudio运行所需的所有依赖（如colmap、Ceres-solver、glog等），无需手动配置环境

• 多GPU支持：兼容多种NVIDIA GPU架构，具体如下表：

  GPU型号	CUDA架构
  H100	90
  40X0系列	89
  30X0系列	86
  A100	80
  20X0系列	75
  TITAN V / V100	70
  10X0 / TITAN Xp	61
  9X0系列	52

• 灵活使用模式：支持交互式终端操作和直接命令调用两种使用方式

• 缓存持久化：支持挂载本地缓存目录，避免重复下载模型

• Web界面访问：默认映射7007端口，可直接访问nerfstudio的Web UI

• 内存优化：支持主机内存访问模式（--ipc=host），避免默认64MB内存限制

使用场景与适用范围

适用场景

• 神经辐射场（NeRF）模型的训练与推理
• 基于图像/视频的3D场景重建
• 实时3D可视化与交互（通过Web UI）
• 需要GPU加速的计算机视觉研究与开发

适用人群

• 3D计算机视觉研究人员
• NeRF模型开发者
• 需要快速部署nerfstudio环境的技术人员

使用方法与配置说明

前提条件

• 安装Docker Engine（20.10+）
• 安装NVIDIA Container Toolkit（确保容器可访问GPU）
• 本地GPU支持CUDA 11.8及以上（需匹配NVIDIA驱动版本）

1. 交互式容器模式

通过交互式终端启动容器，可在容器内直接执行nerfstudio命令。

基本命令

bash
docker run --gpus all \                                         # 授予容器访问NVIDIA GPU（必需）
            -v /本地数据目录:/workspace/ \                       # 挂载本地数据目录到容器（必需，用于数据处理）
            -v /home/<本地用户名>/.cache/:/home/user/.cache/ \   # 挂载缓存目录（推荐，避免重复下载模型）
            -p 7007:7007 \                                      # 映射Web UI端口（必需，本地端口:容器端口）
            --rm \                                              # 容器退出后自动删除（推荐）
            -it \                                               # 启动交互式终端（必需）
            --ipc=host \                                        # 共享主机内存空间（推荐，避免内存限制）
            dromni/nerfstudio:<标签>                             # Docker镜像名称（如dromni/nerfstudio:1.1.5）

参数说明

2. 直接调用nerfstudio命令

在docker run命令末尾添加nerfstudio命令，直接执行特定任务（无需进入交互式终端）。

示例：处理视频数据

bash
docker run --gpus all \
            -v /本地视频目录:/workspace/ \
            -v /home/<本地用户名>/.cache/:/home/user/.cache/ \
            -p 7007:7007 \
            --rm \
            -it \
            --ipc=host \
            dromni/nerfstudio:1.1.5 \
            ns-process-data video --data /workspace/input.mp4  # nerfstudio命令：处理视频数据

3. 注意事项

跨平台兼容

• Linux：直接使用上述命令，路径使用/分隔
• Windows：路径需用反斜杠\，且挂载目录需加引号避免转义问题，例如：

  bash
  -v 'C:\本地数据目录:/workspace/'  # Windows路径挂载示例
  

数据持久化

• 容器内非挂载目录（如/workspace外的路径）的数据会在容器销毁后丢失，所有输入输出需放在挂载的/workspace目录下。

用户权限

• 容器内默认用户为user（密码user），UID=1000（通常对应Linux系统第一个非root用户）
• 支持sudo命令（无需密码），可通过sudo apt update等命令获取管理员权限

内存配置

• 推荐使用--ipc=host共享主机内存，避免手动指定--shm-size时的内存分配不足问题
• 若需指定共享内存大小，可替换为--shm-size=16gb（根据实际需求调整XX值）

依赖说明

• 镜像基于nvidia/cuda:11.8.0-devel-ubuntu22.04构建，无需本地安装CUDA，仅需匹配NVIDIA驱动版本

变更日志

计划更新

• 将基础镜像升级至CUDA 12.2

main（开发版）

• 不推荐使用！优先选择发布版本，此版本可能不稳定且更新无规律

1.1.5

• 更新gsplat至1.4.0

1.1.4

• 更新gsplat至1.3.0
• 更新colmap至3.10
• 更新glog至0.7.1
• 更新Ceres-solver至2.2.0
• 移除pixel-perfect-SfM

1.1.3

• 更新gsplat至1.0.0

1.1.2

• 无更新

1.1.1

• 移除GARfield（与新版gsplat不兼容）
• 移除SeaThru-NeRF

1.1.0

• 更新gsplat至0.1.11
• 添加BioNeRF支持

1.0.3

• 无更新

1.0.2

• 更新gsplat至0.1.8（2024-03-18）

1.0.0

• 添加gsplat支持（用于nerfstudio viewer中的高斯溅射渲染）
• 更新hloc至v1.4
• 预安装nerfstudio自动补全工具
• 移除pip构建缓存以减小镜像体积
• 移除CUDA架构3.7支持
• 添加GARField.studio支持（[***]

0.3.4

• 将PyTorch升级至2.x

0.3.3

• 移除k-planes（与新版nerfstudio不兼容，修复后将重新添加）

0.3.2

• 添加torchtyping依赖
• 集成外部NeRF模型：LeRF、NeRF-player、k-planes、NeRF2NeRF

0.3.0

• 升级至PyTorch 2.x

0.2.0

• 添加npm（nerfstudio的prettier工具依赖）

0.1.19

• 添加掩码功能临时修复（使用掩码时可能增加VRAM占用）

0.1.18

• 将torch从1.12.1升级至1.13.1
• 将torchvision从0.13.1升级至0.14.1
• 添加hloc（作为ns-process-data的替代特征匹配工具）

0.1.17

• 将CUDA从11.7升级至11.8（提升新GPU计算效率）
• 将colmap从3.7升级至3.8
• 添加用户sudo权限（无需密码）
• 添加curl（用于下载任务）

0.1.16

• 支持本文档顶部列出的多CUDA架构

≤0.1.15

• 无变更记录