保姆级避坑指南：在Ubuntu 20.04上从零搞定3D Gaussian Splatting环境（含CUDA 11.8、OpenCV 4.9.0配置）-深圳市維司達科技有限公司

保姆级避坑指南：在Ubuntu 20.04上从零搞定3D Gaussian Splatting环境（含CUDA 11.8、OpenCV 4.9.0配置）

如果你正在Ubuntu 20.04上尝试搭建3D Gaussian Splatting（3DGS）环境，那么这篇文章就是为你准备的。作为一个过来人，我深知在这个过程中会遇到多少坑——从CUDA版本冲突到OpenCV编译失败，从依赖库版本不兼容到环境变量配置错误。本文将分享我在搭建3DGS环境时遇到的所有问题及其解决方案，帮助你少走弯路，快速完成环境配置。

1. 系统准备与基础依赖安装

在开始之前，确保你的Ubuntu 20.04系统已经更新到最新状态：

sudo apt update && sudo apt upgrade -y

常见问题1：很多教程会直接让你安装CUDA，但忽略了系统基础依赖。实际上，缺少某些基础库会导致后续安装失败。

必须安装的基础开发工具：

sudo apt install -y build-essential git cmake pkg-config libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev libx264-dev libgtk-3-dev libatlas-base-dev gfortran python3-dev python3-numpy libtbb2 libtbb-dev libdc1394-22-dev libopenexr-dev libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev

提示：建议一次性安装上述所有依赖，避免后续因缺少某个库而中断编译过程。

显卡驱动检查：在安装CUDA之前，先确认你的NVIDIA驱动已经正确安装：

nvidia-smi

如果这个命令报错或没有显示显卡信息，你需要先安装NVIDIA驱动：

sudo ubuntu-drivers autoinstall sudo reboot

2. CUDA 11.8的安装与配置

官方推荐使用CUDA 11.8，因为已知11.6版本存在问题。以下是经过验证的安装方法：

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

关键避坑点：

安装时不要勾选驱动安装选项（如果已经安装了驱动）
确保安装路径是默认的/usr/local/cuda-11.8

安装完成后，配置环境变量：

echo 'export PATH=/usr/local/cuda-11.8/bin${PATH:+:${PATH}}' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc source ~/.bashrc

验证安装：

nvcc -V

常见问题2：如果nvcc -V显示"command not found"，可能是环境变量没有正确配置。检查~/.bashrc文件中的路径是否正确，特别是CUDA版本号是否匹配。

3. 创建Python虚拟环境

为了避免系统Python环境被污染，我们使用conda创建一个独立的虚拟环境：

conda create -n 3dgs python=3.8 -y conda activate 3dgs

安装基础Python包：

pip install numpy scipy matplotlib opencv-python

4. 关键依赖的版本管理

3DGS对几个关键库的版本有严格要求，以下是经过验证的组合：

依赖项	推荐版本	安装方法
gcc/g++	9.x	`sudo apt install gcc-9 g++-9`
CMake	≥3.24	源码编译安装
Eigen	3.4.0	源码编译安装
OpenCV	4.9.0	源码编译安装

4.1 更新gcc/g++

Ubuntu 20.04默认的gcc版本是9.x，通常不需要更改。但如果你的系统版本不同：

sudo apt install gcc-9 g++-9 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 100 sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-9 100

4.2 安装CMake 3.25

wget https://cmake.org/files/v3.25/cmake-3.25.0-linux-x86_64.tar.gz tar -zxvf cmake-3.25.0-linux-x86_64.tar.gz sudo mv cmake-3.25.0-linux-x86_64 /opt/cmake-3.25.0 sudo ln -sf /opt/cmake-3.25.0/bin/* /usr/bin/

验证：

cmake --version

4.3 Eigen 3.4.0安装

wget https://gitlab.com/libeigen/eigen/-/archive/3.4.0/eigen-3.4.0.zip unzip eigen-3.4.0.zip cd eigen-3.4.0 mkdir build && cd build cmake .. sudo make install sudo cp -r /usr/local/include/eigen3 /usr/include/

常见问题3：后续安装其他库时可能会提示Eigen版本冲突。如果遇到这种情况，可以尝试：

sudo rm -rf /usr/include/eigen3 sudo ln -s /usr/local/include/eigen3 /usr/include/eigen3

5. OpenCV 4.9.0编译安装

这是最容易出问题的环节，按照以下步骤可以避免大多数坑：

git clone https://github.com/opencv/opencv.git cd opencv git checkout 4.9.0 git clone https://github.com/opencv/opencv_contrib.git cd opencv_contrib git checkout 4.9.0 cd .. mkdir build && cd build

关键配置命令：

cmake -D WITH_TBB=ON \ -D WITH_EIGEN=ON \ -D OPENCV_GENERATE_PKGCONFIG=ON \ -D CMAKE_BUILD_TYPE=RELEASE \ -D CMAKE_INSTALL_PREFIX=/usr/local \ -D OPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules \ -D OPENCV_ENABLE_NONFREE=ON \ -D BUILD_EXAMPLES=OFF \ -D BUILD_TESTS=OFF \ -D BUILD_PERF_TESTS=OFF ..

编译优化：如果你的机器内存足够，可以使用-j参数加速编译：

sudo make -j$(nproc) sudo make install

环境配置：

sudo sh -c 'echo "/usr/local/lib" >> /etc/ld.so.conf.d/opencv.conf' sudo ldconfig echo 'export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib/pkgconfig' >> ~/.bashrc source ~/.bashrc

验证安装：

pkg-config --modversion opencv4

常见问题4：如果在编译过程中出现"undefined reference"错误，通常是依赖库缺失或版本不匹配。确保所有前面提到的基础依赖都已安装。

6. 3D Gaussian Splatting源码获取与配置

git clone --recursive https://github.com/graphdeco-inria/gaussian-splatting.git cd gaussian-splatting

关键点：--recursive参数必须加上，否则会缺少关键子模块。

创建conda环境（如果之前没有创建）：

conda env create --file environment.yml conda activate gaussian_splatting

常见问题5：如果conda环境创建失败，可能是因为某些包的版本冲突。可以尝试手动安装：

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu118 pip install -r requirements.txt

7. 可视化环境配置

进入SIBR_viewers目录：

cd SIBR_viewers

对于Ubuntu 20.04，需要切换分支：

git checkout fossa_compatibility

安装依赖：

sudo apt install -y libglew-dev libassimp-dev libboost-all-dev libgtk-3-dev libglfw3-dev libavdevice-dev libavcodec-dev libxxf86vm-dev libembree-dev

编译安装：

cmake -Bbuild . -DCMAKE_BUILD_TYPE=Release cmake --build build -j$(nproc) --target install

常见问题6：如果编译过程中出现boost相关错误，尝试指定boost版本：

sudo apt install libboost1.71-dev

8. 环境验证Checklist

在开始使用3DGS之前，运行以下命令验证所有组件是否正常工作：

CUDA验证：
```
nvcc -V
```
应显示：release 11.8

OpenCV验证：

python3 -c "import cv2; print(cv2.__version__)"

应显示：4.9.0

Python环境验证：

python3 -c "import torch; print(torch.__version__, torch.cuda.is_available())"

应显示torch版本和True

3DGS环境验证：
```
cd gaussian-splatting python train.py -h
```
应显示帮助信息而无错误

9. 实际训练与可视化

准备好数据集后，开始训练：

python train.py -s /path/to/scene -m /path/to/output

训练完成后，使用可视化工具查看结果：

./SIBR_gaussianViewer_app -m /path/to/output

性能优化技巧：

训练时添加-r 3参数可以提高渲染质量
使用--iterations 30000可以延长训练迭代次数
在强大的GPU上，可以增加--batch_size提升训练速度

在完成所有环境配置后，我花了三天时间反复测试不同版本的组合，最终发现上述配置在Ubuntu 20.04上最为稳定。特别是在OpenCV编译和可视化工具构建阶段，版本选择至关重要。建议严格按照本文的版本组合进行安装，可以节省大量排错时间。

保姆级避坑指南：在Ubuntu 20.04上从零搞定3D Gaussian Splatting环境（含CUDA 11.8、OpenCV 4.9.0配置）