保姆级避坑指南：在Ubuntu 20.04上从零部署3D Gaussian Splatting（含自采数据集实战）
保姆级避坑指南：在Ubuntu 20.04上从零部署3D Gaussian Splatting（含自采数据集实战）
当你第一次接触3D Gaussian Splatting（3DGS）时，可能会被它惊艳的实时渲染效果所吸引。但随之而来的部署过程，往往会让不少开发者和研究者望而却步。本文将带你一步步避开那些常见的"坑"，从环境配置到自建数据集训练，最终实现完整的3D场景重建。
1. 环境准备：避开依赖地狱
在Ubuntu 20.04上部署3DGS，环境配置是最容易出问题的环节。以下是经过实战验证的配置方案：
1.1 CUDA与显卡驱动
首先确认你的NVIDIA显卡驱动版本与CUDA兼容性。建议使用CUDA 11.8，这是我们在多台机器上验证过的稳定版本：
# 检查显卡驱动版本 nvidia-smi # 安装CUDA 11.8 wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run sudo sh cuda_11.8.0_520.61.05_linux.run注意：安装时不要勾选驱动选项，避免与现有驱动冲突
环境变量配置示例：
# 添加到~/.bashrc export PATH=/usr/local/cuda-11.8/bin:$PATH export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH1.2 Conda环境优化方案
官方推荐的conda环境安装经常因网络问题失败。我们改用mamba加速，并调整依赖版本：
# 安装mamba conda install -n base -c conda-forge mamba # 创建环境（修改后的environment.yml） mamba env create -f environment_custom.yml修改后的环境文件关键内容：
name: 3dgs_custom channels: - pytorch - conda-forge dependencies: - python=3.7 - cudatoolkit=11.6 - pip: - torch==1.12.1+cu116 - torchvision==0.13.1+cu116 - opencv-python2. 源码编译：解决submodule安装难题
官方仓库的submodule经常因网络问题无法完整克隆。这里提供两种解决方案：
2.1 完整克隆方案
# 使用递归克隆（推荐网络良好时使用） git clone --recursive https://github.com/graphdeco-inria/gaussian-splatting2.2 手动安装submodules
当递归克隆失败时，可以单独安装三个关键submodule：
- 下载缺失的submodule仓库
- 分别执行本地安装：
cd submodules/diff-gaussian-rasterization pip install . cd ../simple-knn pip install . cd ../fused-ssim pip install .常见错误解决方案：
| 错误类型 | 解决方案 |
|---|---|
| "Could not find a version" | 检查CUDA与PyTorch版本匹配 |
| "Permission denied" | 添加--user参数或使用sudo |
| "Missing header files" | 安装python3-dev包 |
3. COLMAP编译：最棘手的依赖问题
COLMAP的源码编译是最大的挑战之一。我们总结了一套稳定方案：
3.1 基础依赖安装
# 必备依赖（可能需要多次运行） sudo apt-get install -y \ git cmake ninja-build libboost-all-dev \ libeigen3-dev libfreeimage-dev libgflags-dev \ libglew-dev libqt5opengl5-dev libcgal-dev \ libceres-dev libsuitesparse-dev3.2 针对性解决编译错误
问题1：std::filesystem缺失
# 安装GCC 9并设置默认 sudo apt install g++-9 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 90问题2：Eigen3版本冲突
# 移除旧版本，手动安装Eigen 3.4 wget https://gitlab.com/libeigen/eigen/-/archive/3.4.0/eigen-3.4.0.tar.gz tar -xzf eigen-3.4.0.tar.gz cd eigen-3.4.0 mkdir build && cd build cmake .. && make install3.3 最终编译命令
根据你的GPU架构调整：
# 查询GPU架构 nvidia-smi --query-gpu=compute_cap --format=csv # 编译COLMAP（示例为RTX 3090） cd colmap mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release \ -DCUDA_ENABLED=ON \ -DCMAKE_CUDA_ARCHITECTURES=86 \ -DGUI_ENABLED=OFF make -j$(nproc) sudo make install4. 自建数据集实战全流程
4.1 数据准备规范
推荐的项目目录结构：
my_project/ ├── input/ # 原始图像 │ ├── frame_0001.png │ └── ... ├── output/ # 训练输出 └── video.mp4 # 可选源视频视频转图像命令：
ffmpeg -i video.mp4 -q:v 2 input/frame_%04d.png提示：图像数量建议在100-300张之间，分辨率不低于1080p
4.2 完整处理流水线
稀疏重建：
colmap automatic_reconstructor \ --image_path input \ --workspace_path output \ --dense 1转换数据格式：
python convert.py -s output/sparse/0 \ -i input \ -o output/processed开始训练：
python train.py -s output/processed \ -m output/model \ --iterations 30000
关键参数优化建议：
| 参数 | 推荐值 | 作用 |
|---|---|---|
| --iterations | 30000 | 训练迭代次数 |
| --resolution | -1 | 自动选择最佳分辨率 |
| --sh_degree | 3 | 球谐函数阶数 |
4.3 可视化方案
虽然官方Viewer仅支持Windows，但我们可以在Ubuntu上使用替代方案：
# 安装MeshLab（替代可视化） sudo apt install meshlab # 查看PLY文件 meshlab output/model/point_cloud.ply对于需要远程查看的情况，可以考虑：
- 使用CloudCompare进行点云分析
- 通过WebGL开发简易查看器
- 将结果导入Blender进行后期处理
5. 性能优化与高级技巧
5.1 训练加速方案
多GPU训练：
python train.py -s data/input --gpus 0,1混合精度训练： 修改train.py添加：
torch.cuda.amp.autocast(enabled=True)5.2 质量提升技巧
图像预处理：
- 使用HDR图像
- 确保曝光一致
- 移除动态物体
参数调整：
# 在create_from_pcd函数中调整 gaussians.create_from_pcd( pcd, density=0.01, # 增加点密度 isotropic=False # 各向异性缩放 )
5.3 常见问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 训练崩溃 | CUDA OOM | 降低分辨率或batch size |
| 点云稀疏 | 特征点不足 | 增加COLMAP特征点数 |
| 渲染模糊 | 迭代不足 | 增加训练迭代次数 |
| 颜色失真 | 光照变化 | 使用RAW格式图像 |
在GTX 10系显卡上的特殊配置：
# 修改submodules/diff-gaussian-rasterization/cuda_rasterizer/config.h #define MIN_GPU_ARCH 60 # 原为70经过这些步骤，你应该能成功部署3DGS并处理自建数据集。如果在RTX 40系列显卡上遇到问题，可以尝试降低CUDA架构版本到8.9。记住关键一点：所有路径不要包含中文或特殊字符，这能避免90%的奇怪错误。