简介这份资源面向初次接触三维重建的开发者与在校学生聚焦3D Gaussian Splatting3DGS在Linux环境下的完整复现过程帮助零基础读者跨越从环境配置到训练出结果之间的各类报错障碍。资源包共1个doc文件约96.32MB以图文笔记形式记录了Ubuntu 20.04.3 LTS系统下显卡驱动安装、colmap编译、虚拟环境配置、依赖安装与点云ply文件可视化等关键环节。作者以RTX 3080 Ti为硬件平台逐一梳理了MP4无法播放、PNG读取异常、colmap编译报错、cudart64_12.dll缺失等典型问题的排查思路与解决路径并附有纯文本与图形界面切换等系统操作细节。目前已有5056人学习下载适合希望少走弯路、快速跑通3DGS全流程的读者参考借鉴。1. 从一张 3080 Ti 开始3DGS 复现到底卡在哪手里有张 3080 Ti系统是 Ubuntu 20.04.3 LTSx86_64 架构看到 3D Gaussian Splatting 的渲染效果心里痒于是决定自己复现一遍。结果从解压项目压缩包那一刻起就开始了和 error 硬磕的过程MP4 打不开、PNG 报 Not a PNG file、submodules 装不进去、colmap 编译报 TIFFReadRGBAImage 链接错误、cudart64_12.dll 找不到。这篇笔记不聊论文公式只把 3DGS 从零到能跑通训练这条链路上真正会翻车的地方拆开讲清楚包括环境怎么配、submodules 为什么必须编译安装、colmap 编译报错怎么定位、点云 ply 怎么验证。适合刚接触三维重建、手里有 N 卡、想跑通第一份 3DGS 数据的从业者也适合被 Linux 环境折腾到怀疑人生的新手。2. 环境底座Ubuntu 20.04 CUDA 11.8 PyTorch 2.4.1 的版本对齐3DGS 复现失败十有八九不是算法问题是版本没对齐。官方代码对 CUDA、PyTorch、显卡驱动三者之间的匹配关系很敏感差一个小版本就可能出现编译通过但运行时报符号找不到。先把底座搭稳后面 submodules 编译和 colmap 编译才有意义。2.1 先确认自己到底在什么系统上很多人上来就照着教程敲命令连自己系统版本和位数都没确认。Ubuntu 20.04.3 LTS 内核属于 Linuxx86_64 是 64 位架构这两个信息决定了后面下载哪个驱动、哪个 CUDA 包。# 查看 Linux 发行版具体版本 cat /etc/*release # 查看操作系统位数x86_64 表示 64 位 uname -m # 查看当前显卡和驱动版本 nvidia-smicat /etc/*release会输出 DISTRIB_ID、VERSION_ID 等字段确认是 Ubuntu 20.04。uname -m返回 x86_64 说明是 64 位系统下载驱动和 CUDA 时不能选 32 位包。nvidia-smi右上角显示 Driver Version这里对应 535.183.01右上角 CUDA Version 显示的是驱动支持的最高 CUDA 版本不代表已安装。3080 Ti 属于 Ampere 架构算力 8.6CUDA 11.8 完全支持。2.2 显卡驱动黑屏这件事先留好后悔药Ubuntu 20.04.3 LTS 更新显卡驱动时遇到纯黑屏或者闪光标黑屏是新手最容易劝退的一步。原因是驱动安装过程中与 nouveau 开源驱动冲突或者安装后没有正确重建 initramfs。常见做法是进 GRUB 恢复模式卸载旧驱动再重装。# 进入 tty 文本界面CtrlAltF3 切换 # 先卸载已有 nvidia 驱动 sudo apt-get purge nvidia-* # 禁用 nouveau sudo bash -c echo blacklist nouveau /etc/modprobe.d/blacklist-nvidia-nouveau.conf sudo bash -c echo options nouveau modeset0 /etc/modprobe.d/blacklist-nvidia-nouveau.conf sudo update-initramfs -u # 重启后安装指定版本驱动 sudo apt-get install nvidia-driver-535purge比remove更彻底会清掉配置文件。禁用 nouveau 后必须update-initramfs -u重建内核镜像否则重启还是会加载 nouveau。安装完驱动重启nvidia-smi能正常输出就说明驱动层通了。纯文本界面和图形界面切换用 CtrlAltF3 和 CtrlAltF1黑屏时先切到 tty 看日志别急着重装系统。2.3 CUDA 11.8 与 PyTorch 2.4.1cu118 的对应关系PyTorch 版本号里的 cu118 表示它编译时链接的是 CUDA 11.8。如果本机装的是 CUDA 12.xPyTorch 仍然能用自带的 CUDA runtime但 submodules 编译时会调用系统 nvcc版本不一致就会报符号错误。# 查看 CUDA 编译器版本 nvcc -V # 查看 PyTorch 实际使用的 CUDA 版本 python -c import torch; print(torch.version.cuda); print(torch.cuda.is_available())nvcc -V显示的是系统 CUDA Toolkit 版本torch.version.cuda显示的是 PyTorch 编译时用的版本两者最好一致。torch.cuda.is_available()返回 True 才说明 PyTorch 能调用显卡。如果返回 False先检查驱动再检查 PyTorch 是不是装成了 CPU 版。虚拟环境建议用 conda 创建 python3.8这是官方代码验证过的版本3.7 和 3.9 都可能在编译 submodules 时出问题。3. submodules 编译diff-gaussian-rasterization 与 simple-knn 装不进去的真相3DGS 项目根目录下有个 submodules 文件夹里面 diff-gaussian-rasterization 和 simple-knn 是 CUDA 扩展必须编译安装不是普通 pip 包。很多人直接pip install submodules/diff-gaussian-rasterization报 Neither setup.py nor pyproject.toml found就是因为路径或者环境不对。3.1 为什么 pip install 会找不到 setup.pypip 安装本地包时会去指定路径找 setup.py 或 pyproject.toml。如果路径写错、当前目录不对、或者文件夹是空的就会报这个错。更隐蔽的问题是pip 默认装到当前激活的 Python 环境如果没激活虚拟环境它会装到 anaconda3 下面的 base 环境里看起来装成功了实际项目用的环境里没有。# 先确认当前 python 是哪个 which python python -V # 激活自己创建的虚拟环境名字按实际改 conda activate dxh # 再次确认 which python python -Vwhich python输出路径里带 anaconda3/envs/dxh 才说明激活成功。python -V显示 3.8 才符合要求。如果显示 3.7说明还在 base 环境。激活后再进 submodules 目录执行安装才能装到正确位置。3.2 正确编译 diff-gaussian-rasterization 的步骤直接 pip install 本地目录经常因为缺少编译依赖失败。更稳的做法是从源码 clone进目录编译安装。注意模块名不一定是文件夹名要看 setup.py 里的定义。# 进入 submodules 目录 cd gaussian-splatting-main/submodules # 克隆源码注意用官方或可信镜像 git clone --recursive https://github.com/slothfulxtx/diff-gaussian-rasterization.git # 进入仓库目录 cd diff-gaussian-rasterization # 激活虚拟环境 conda activate dxh # 编译安装 pip install . # 验证能否导入模块名看 setup.py python -c import diff_gaussgit clone --recursive会同时拉取子模块diff-gaussian-rasterization 依赖 glm 等第三方库不加 recursive 会缺文件。pip install .里的点表示当前目录会读取 setup.py 编译 CUDA 扩展。import diff_gauss里的模块名要和 setup.py 中name字段一致不是文件夹名。如果报缺 glm先sudo apt-get install libglm-dev。3.3 simple-knn 的安装与 requirements 处理simple-knn 相对简单但同样要装到正确环境。clone 下来后目录里有 requirements.txt先装依赖再编译。# 回到 submodules 目录 cd .. # 克隆 simple-knn git clone --recursive https://github.com/akaparounakis/simple-knn.git # 进入目录 cd simple-knn # 安装依赖 pip install -r requirements.txt # 编译安装 pip install . # 验证 python -c import simple_knnpip install -r requirements.txt会安装该扩展需要的 Python 依赖比如 numpy。pip install .编译 CUDA 部分。验证时模块名同样以 setup.py 为准。两个扩展都装好后submodules 文件夹下不再是空目录训练脚本才能正常调用。提示如果 pip 版本过低会报 No matching distribution found先执行python -m pip install --upgrade pip setuptools wheel再清理缓存pip cache purge重试。4. colmap 编译TIFFReadRGBAImage 链接错误与依赖排查3DGS 训练前需要 colmap 做稀疏重建生成相机位姿和点云。colmap 3.9 版本在 Ubuntu 20.04 上编译最容易卡在 TIFFReadRGBAImage 未定义引用本质是 libtiff 链接顺序或版本问题。4.1 编译报错 undefined reference to TIFFReadRGBAImage 的定位这个报错出现在链接阶段说明编译器找到了头文件但没找到库实现。常见原因是系统里装了多个 libtiff或者 CMake 链接顺序把 libtiff 放在了依赖它的库后面。# 查看系统已安装的 libtiff dpkg -l | grep libtiff # 查看 libtiff 实际路径 find /usr -name libtiff* # 安装开发包 sudo apt-get install libtiff-dev libtiff5-devdpkg -l | grep libtiff能看到装了哪些版本。find确认库文件位置。libtiff-dev提供头文件和链接库。如果已经装了还报错检查 CMakeLists.txt 里 target_link_libraries 的顺序把 tiff 放到依赖它的库后面。4.2 colmap 编译依赖清单与 CMake 参数colmap 依赖较多缺一个就编译失败。按官方文档把依赖装齐再用 CMake 配置。# 安装基础依赖 sudo apt-get install \ git cmake ninja-build build-essential \ libboost-program-options-dev libboost-filesystem-dev libboost-graph-dev \ libboost-reprogram-sources-dev libboost-system-dev libboost-test-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 # 创建构建目录 mkdir build cd build # CMake 配置关闭 CUDA 可先验证 CPU 编译 cmake .. -DCMAKE_BUILD_TYPERelease # 编译-j 后跟核心数 make -j8 # 安装 sudo make installlibboost-reprogram-sources-dev是 colmap 需要的 boost 组件。libceres-dev提供优化库。cmake ..生成 Makefilemake -j8并行编译加快速度。如果 CUDA 相关报错先确认 nvcc 可用再检查 CUDA 架构参数是否包含 8.6。4.3 编译通过后的验证与常见收尾问题编译完成后colmap -h能输出帮助信息说明安装成功。如果报找不到动态库执行sudo ldconfig刷新链接缓存。# 验证 colmap colmap -h # 刷新动态库缓存 sudo ldconfig # 查看 colmap 版本 colmap --versioncolmap -h列出所有子命令说明可执行文件在 PATH 里。ldconfig更新 /etc/ld.so.cache解决刚装完库找不到的问题。colmap --version确认版本是 3.9 左右。如果之前编译失败残留了 build 目录先rm -rf build再重新 cmake避免缓存干扰。5. 避坑与排查那些让我和 error 硬磕到底的瞬间这一章记录复现过程中真实踩过的坑每条按现象、原因、解决写清楚。新手照着排查能省不少时间。5.1 Linux 无法播放 MP4 视频现象双击 data 文件夹里的猪猪侠 MP4播放器打不开或者提示缺少解码器。 原因Ubuntu 默认没装 H.264 等专利编码的解码器。 解决sudo apt-get install ubuntu-restricted-extras一行命令装齐常用解码器视频就能播放。5.2 PNG 报 Not a PNG file现象从网站下载的 PNG 壁纸打不开报读入 PNG 图像文件时发生严重错误 Not a PNG file。 原因文件扩展名是 png实际内容可能是 jpg 或其他格式或者下载不完整。 解决用file 图片名查看真实格式把后缀改成实际格式比如改成 jpg 就能显示。批量处理可以用mogrify -format jpg *.png。5.3 submodules 装到了 base 环境现象pip install simple-knn提示成功但项目环境里 import 失败。 原因没激活虚拟环境pip 装到了 anaconda3 的 base 环境。 解决conda activate 环境名后再which python确认路径重新安装。5.4 cudart64_12.dll 找不到现象Windows 下运行报找不到 cudart64_12.dll重新安装程序也没用。 原因CUDA 12 的运行时库没在 PATH 里或者装的是 CUDA 11 但代码找 12 的库。 解决确认 CUDA 版本把对应 bin 目录加入 PATH或者重装匹配版本的 CUDA Toolkit。Linux 下对应的是 libcudart.so用ldconfig刷新。5.5 colmap 编译缓存导致反复报错现象改了依赖重新编译还是报同样的 TIFFReadRGBAImage 错误。 原因build 目录里 CMake 缓存了旧的链接配置。 解决rm -rf build删掉重建重新cmake ..和make。6. 点云 ply 可视化与训练结果验证训练跑完后输出目录里会有 point_cloud.ply 文件这是 3DGS 生成的带高斯参数的点云。验证它是否正常比看训练日志更直观。6.1 用 CloudCompare 打开 ply 文件CloudCompare 是跨平台点云查看工具Linux 下可以直接装。# 安装 CloudCompare sudo apt-get install cloudcompare # 命令行打开 ply cloudcompare.CloudCompare 点云路径/point_cloud.ply打开后能看到点云分布如果是一团乱麻或者空白说明训练没收敛或者相机位姿有问题。正常结果应该能看出场景轮廓比如猪猪侠的形状。6.2 用 Python 快速检查 ply 内容不想装图形工具可以用 open3d 读一下点云数量和范围。import open3d as o3d import numpy as np # 读取 ply pcd o3d.io.read_point_cloud(point_cloud.ply) # 点数 print(点数:, len(pcd.points)) # 坐标范围 points np.asarray(pcd.points) print(X 范围:, points[:, 0].min(), points[:, 0].max()) print(Y 范围:, points[:, 1].min(), points[:, 1].max()) print(Z 范围:, points[:, 2].min(), points[:, 2].max()) # 可视化 o3d.visualization.draw_geometries([pcd])read_point_cloud读取 plylen(pcd.points)看点数正常几万到几百万不等。坐标范围能判断尺度是否合理如果范围是 0 到 1 这种归一化值说明可能没还原到真实尺度。draw_geometries弹出窗口旋转查看。6.3 训练参数与显存边界3080 Ti 12GB 显存跑 3DGS 默认参数一般够用但场景大了会 OOM。关键参数在 train.py 里。参数默认值作用3080 Ti 建议iterations30000训练迭代次数保持默认resolution-1图像分辨率-1 为原图显存不够改 2 或 4densify_until_iter15000致密化截止迭代显存紧张调小evalTrue是否划分验证集数据少设 Falseresolution设为 2 表示下采样 2 倍显存占用降为四分之一。densify_until_iter控制高斯点增长调小能省显存但可能影响质量。训练时用nvidia-smi -l 1实时看显存接近 12GB 就要考虑降分辨率。从那以后我每次复现新项目都强制先跑一遍which python和nvcc -V确认环境和版本对齐再动手省下的时间比折腾报错多得多。希望帮到你。本文还有配套的精品资源点击获取