保姆级避坑指南在Ubuntu 20.04上从零搞定3D Gaussian Splatting环境含CUDA 11.8、OpenCV 4.9.0配置如果你正在Ubuntu 20.04上尝试搭建3D Gaussian Splatting3DGS环境那么这篇文章就是为你准备的。作为一个过来人我深知在这个过程中会遇到多少坑——从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 reboot2. 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 python3.8 -y conda activate 3dgs安装基础Python包pip install numpy scipy matplotlib opencv-python4. 关键依赖的版本管理3DGS对几个关键库的版本有严格要求以下是经过验证的组合依赖项推荐版本安装方法gcc/g9.xsudo apt install gcc-9 g-9CMake≥3.24源码编译安装Eigen3.4.0源码编译安装OpenCV4.9.0源码编译安装4.1 更新gcc/gUbuntu 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 1004.2 安装CMake 3.25wget 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 --version4.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/eigen35. 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_TBBON \ -D WITH_EIGENON \ -D OPENCV_GENERATE_PKGCONFIGON \ -D CMAKE_BUILD_TYPERELEASE \ -D CMAKE_INSTALL_PREFIX/usr/local \ -D OPENCV_EXTRA_MODULES_PATH../opencv_contrib/modules \ -D OPENCV_ENABLE_NONFREEON \ -D BUILD_EXAMPLESOFF \ -D BUILD_TESTSOFF \ -D BUILD_PERF_TESTSOFF ..编译优化 如果你的机器内存足够可以使用-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.txt7. 可视化环境配置进入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_TYPERelease cmake --build build -j$(nproc) --target install常见问题6如果编译过程中出现boost相关错误尝试指定boost版本sudo apt install libboost1.71-dev8. 环境验证Checklist在开始使用3DGS之前运行以下命令验证所有组件是否正常工作CUDA验证nvcc -V应显示release 11.8OpenCV验证python3 -c import cv2; print(cv2.__version__)应显示4.9.0Python环境验证python3 -c import torch; print(torch.__version__, torch.cuda.is_available())应显示torch版本和True3DGS环境验证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编译和可视化工具构建阶段版本选择至关重要。建议严格按照本文的版本组合进行安装可以节省大量排错时间。