Ubuntu 22.04 从零复现 3DGS：colmap 安装与稀疏重建完整指南

简介这份文档面向初次接触三维重建的开发者与在校学生聚焦3D Gaussian Splatting3DGS在Linux环境下的完整复现路径帮助零基础读者跨越从环境配置到训练出结果之间的各类报错障碍。资源包共1个doc文件约96.32MB以图文笔记形式记录了Ubuntu 20.04.3 LTS搭配RTX 3080 Ti的实操过程涵盖显卡驱动安装、colmap编译、虚拟环境搭建、依赖安装与点云ply文件可视化等关键环节。内容中整理了多个典型问题的排查思路例如colmap编译时TIFFReadRGBAImage链接错误、cudart64_12.dll缺失、PNG图像读取异常以及Linux下MP4无法播放等并给出对应解决方向。目前已有5056人学习下载适合希望少走弯路、快速跑通3DGS流程的新手参考也可作为环境配置与报错排查的对照手册。1. 第一次复现 3DGS从 Ubuntu 22.04 到跑通 colmap 的完整路径很多人第一次听到 3D Gaussian Splatting3DGS时以为它像 NeRF 一样需要一整套训练管线结果打开仓库发现第一步就卡在 colmap 上。我见过太多人在 Ubuntu 22.04 里装完驱动、配完环境变量却在colmap命令行报错时直接放弃。3DGS 的核心思路是用一堆三维高斯椭球去表达场景训练快、渲染实时但它的输入不是随便拍几张照片就能直接喂进去的——需要先做稀疏重建拿到相机位姿再转成 3DGS 能读的格式。这篇笔记面向第一次复现 3DGS 的新手从系统准备、colmap 安装、数据组织到训练启动把每一步的命令、参数和常见翻车点讲清楚。如果你手里有一台带 NVIDIA 显卡的 Ubuntu 机器或者准备用 VMware 虚拟机装 Ubuntu 22.04跟着走能少走两三天弯路。2. 环境准备Ubuntu 22.04、显卡驱动和 CUDA 的选型理由2.1 为什么优先选 Ubuntu 22.04 LTS 而不是 20.043DGS 官方仓库对 CUDA 版本有硬性要求而 CUDA 又和显卡驱动、GCC 版本绑在一起。Ubuntu 22.04 LTS 默认 GCC 11能直接编译 PyTorch 2.x 和 3DGS 的 CUDA 扩展Ubuntu 20.04 默认 GCC 9编译某些扩展时会报unsupported GNU version。另外 22.04 的软件源里libglew-dev、libboost-program-options-dev这些 colmap 依赖版本更新装起来更顺。如果你已经在用 Ubuntu 20.04也不是不能跑但需要手动升级 GCC 或者用 conda 隔离编译环境新手容易在这里卡住。虚拟机方案要特别注意VMware 或 VirtualBox 里装 Ubuntu 22.04 可以跑通 colmap 的 CPU 部分但 3DGS 训练必须用 NVIDIA 显卡直通否则 CUDA 不可用。如果你只是想在虚拟机里熟悉 Linux 常用命令和 colmap 安装流程那没问题真要训练建议物理机装 Ubuntu 22.04或者用云上的 GPU 实例。2.2 显卡驱动和 CUDA 的安装顺序顺序错了会反复卸载重装这是血泪经验。正确顺序是先装 NVIDIA 驱动再装 CUDA Toolkit最后装 cuDNN如果 PyTorch 需要。Ubuntu 22.04 可以用ubuntu-drivers自动推荐驱动# 查看推荐的显卡驱动版本 ubuntu-drivers devices # 自动安装推荐驱动比如 nvidia-driver-535 sudo ubuntu-drivers autoinstall # 重启后验证 nvidia-sminvidia-smi右上角显示的CUDA Version是驱动支持的最高 CUDA 版本不是已安装的 CUDA。接下来装 CUDA Toolkit建议用 runfile 或 apt 都行但要注意不要和驱动冲突。如果nvidia-smi报Failed to initialize NVML多半是驱动没装好或者 Secure Boot 拦截了进 BIOS 关掉 Secure Boot 再重装。CUDA 装完后配置环境变量编辑~/.bashrcexport PATH/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH然后source ~/.bashrc用nvcc -V验证。如果nvcc找不到检查 PATH 是否写对。环境变量配置错误是新手高频翻车点写错一个字符就会导致后面 PyTorch 找不到 CUDA。2.3 conda 环境与 PyTorch 版本匹配3DGS 官方推荐 PyTorch 2.x CUDA 11.8 或 12.1。用 conda 建独立环境避免污染系统 Pythonconda create -n gs3d python3.10 conda activate gs3d # 以 CUDA 11.8 为例 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118装完验证import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果torch.cuda.is_available()返回 False先检查驱动和 CUDA 版本是否匹配再检查 conda 环境里是否装了 CPU 版 PyTorch。常见错误是 pip 源没指定默认装了 CPU 版。3. colmap 安装与稀疏重建从源码编译到跑通第一个数据集3.1 colmap 的三种安装方式对比方式命令优点缺点apt 安装sudo apt install colmap快依赖自动处理版本旧可能不支持某些特性源码编译cmake make版本新可定制依赖多编译时间长conda 安装conda install -c conda-forge colmap环境隔离版本不一定最新新手建议先用 apt 装一个能跑的版本等流程跑通后再考虑源码编译。如果 apt 版本太旧导致 3DGS 转换脚本报错再换源码编译。源码编译 colmap 的依赖安装sudo apt update sudo apt install -y git cmake build-essential libboost-program-options-dev \ libboost-filesystem-dev libboost-graph-dev libboost-system-dev \ libeigen3-dev libflann-dev libfreeimage-dev libmetis-dev \ libgoogle-glog-dev libgtest-dev libsqlite3-dev libglew-dev \ qtbase5-dev libqt5opengl5-dev libcgal-dev libceres-dev然后编译git clone https://github.com/colmap/colmap.git cd colmap mkdir build cd build cmake .. -DCMAKE_CUDA_ARCHITECTURESnative make -j$(nproc) sudo make installCMAKE_CUDA_ARCHITECTURESnative让 cmake 自动检测本机显卡架构避免编译出不支持的版本。make -j$(nproc)用满 CPU 核心加速编译但内存小于 16G 时可能爆内存可以改成-j4。3.2 用 colmap 做稀疏重建的完整命令假设你的照片放在~/data/scene/images输出到~/data/scene/sparse# 1. 特征提取 colmap feature_extractor \ --database_path ~/data/scene/database.db \ --image_path ~/data/scene/images \ --ImageReader.camera_model OPENCV \ --SiftExtraction.use_gpu 1 # 2. 特征匹配 colmap exhaustive_matcher \ --database_path ~/data/scene/database.db \ --SiftMatching.use_gpu 1 # 3. 稀疏重建 mkdir -p ~/data/scene/sparse colmap mapper \ --database_path ~/data/scene/database.db \ --image_path ~/data/scene/images \ --output_path ~/data/scene/sparsecamera_model选OPENCV适合大多数手机和相机如果照片有鱼眼畸变选OPENCV_FISHEYE。use_gpu 1开启 GPU 加速没有 NVIDIA 显卡就改成 0。exhaustive_matcher适合照片数量少几十张的场景照片多时用sequential_matcher更快。重建完成后sparse/0目录下会有cameras.bin、images.bin、points3D.bin。用colmap gui可以可视化检查colmap gui --database_path ~/data/scene/database.db \ --image_path ~/data/scene/images \ --import_path ~/data/scene/sparse/0如果 GUI 里看到点云稀稀拉拉或者相机位置乱飞说明匹配失败需要检查照片是否有足够重叠、光照是否变化太大。3.3 把 colmap 输出转成 3DGS 能读的格式3DGS 官方仓库提供了一个转换脚本在convert.py里。假设你已经 clone 了 3DGS 仓库python convert.py -s ~/data/scene这个脚本会调用 colmap 做重建如果还没做然后生成~/data/scene/input和~/data/scene/sparse/0的软链接结构。如果报错colmap: command not found检查 colmap 是否在 PATH 里如果报错No such file or directory: sparse/0说明前面的 mapper 没跑成功。转换完成后目录结构应该是scene/ ├── images/ ├── sparse/ │ └── 0/ │ ├── cameras.bin │ ├── images.bin │ └── points3D.bin └── input/input目录是 3DGS 训练时实际读取的路径里面通常是指向images的软链接。4. 3DGS 训练与渲染参数怎么设、显存怎么省4.1 克隆仓库与安装依赖git clone https://github.com/graphdeco-inria/gaussian-splatting.git --recursive cd gaussian-splatting conda activate gs3d pip install -r requirements.txt # 安装 CUDA 扩展 pip install submodules/diff-gaussian-rasterization pip install submodules/simple-knn--recursive必须加否则子模块是空的。如果diff-gaussian-rasterization编译报错多半是 CUDA 版本和 PyTorch 不匹配检查nvcc -V和torch.version.cuda是否一致。4.2 训练命令与关键参数python train.py \ -s ~/data/scene \ -m ~/data/output/scene \ --iterations 30000 \ --eval-s是源数据路径-m是输出模型路径。--iterations 30000是默认训练轮数新手先用默认值跑通。--eval会划分训练集和测试集方便看指标。如果显存不够加--resolution 2降采样或者减小--densify_until_iter。训练过程中会输出 loss 和点数变化。如果 loss 不下降检查 colmap 重建是否成功如果点数爆炸增长可能是--densify_grad_threshold设太小默认 0.0002 一般够用。4.3 渲染与可视化训练完成后用render.py生成渲染图python render.py -m ~/data/output/scene然后用metrics.py算 PSNR、SSIMpython metrics.py -m ~/data/output/scene如果想实时看可以用 SIBR viewer但需要单独编译新手先用渲染图验证效果即可。5. 避坑与排查新手最容易翻车的 5 个地方5.1 colmap 报错Could not find CUDA现象运行colmap feature_extractor时提示找不到 CUDA。原因colmap 编译时没开 CUDA或者驱动没装好。解决重新编译 colmapcmake 时加-DCMAKE_CUDA_COMPILER/usr/local/cuda/bin/nvcc并确认nvidia-smi正常。5.2 训练时显存不足 OOM现象torch.cuda.OutOfMemoryError。原因图像分辨率太高或点数太多。解决加--resolution 2或--resolution 4降采样减小--densify_until_iter到 5000换更大显存的显卡。5.3convert.py报No module named colmap现象转换脚本找不到 colmap 的 Python 绑定。原因colmap 的 Python 包没装或者 conda 环境里没有。解决pip install colmap不一定有用建议直接用 colmap 命令行做重建然后手动组织目录结构跳过convert.py的自动调用。5.4 渲染结果全黑或全白现象render.py输出的图片没有内容。原因相机位姿不对或者训练没收敛。解决用 colmap GUI 检查相机位置确认训练 loss 降到合理范围检查cameras.bin里的内参是否合理。5.5 Ubuntu 环境变量配置错误导致命令找不到现象nvcc: command not found或colmap: command not found。原因PATH 没配或配错。解决echo $PATH检查编辑~/.bashrc加正确路径source ~/.bashrc后重开终端。注意不要重复添加导致 PATH 过长。6. 进阶技巧用 3DGS 做自己的数据集并验证质量跑通官方示例后下一步是用自己拍的照片做重建。拍摄时注意围绕物体或场景拍 50 到 100 张重叠度 70% 以上避免运动模糊和反光表面。如果场景是室外的尽量在均匀光照下拍避免阴影剧烈变化。验证质量时除了看 PSNR还可以用 colmap GUI 对比稀疏点云和 3DGS 渲染的深度图。如果深度图边缘和点云对不上说明相机位姿有偏差需要重新做 colmap 重建。我一般会先用--iterations 7000快速跑一遍看渲染图有没有明显结构错误再决定是否跑满 30000 轮。另一个技巧是调整--position_lr_init和--position_lr_final默认值适合大多数场景但如果场景尺度很大可以适当增大学习率。显存不够时用--densify_grad_threshold 0.0004减少点数增长代价是细节可能丢失。最后如果你在 Ubuntu 22.04 上遇到ubuntu安装gcc失败或ubuntu显卡驱动卸载不掉这类系统问题优先用apt --fix-broken install修复依赖再重装驱动。别急着重装系统很多问题只是包管理器的状态乱了。希望帮到你。本文还有配套的精品资源点击获取