简介面向首次在Linux系统下尝试复现三维高斯泼溅3DGS的新手这份Word文档完整记录了环境搭建与实战排错的全流程。内容围绕Ubuntu 20.04.3 LTS、RTX 3080 Ti、CUDA 11.8等配置展开涵盖项目下载、虚拟环境创建、子模块依赖安装、训练前准备等关键环节并针对复现中高频出现的典型问题给出解决思路Linux无法播放MP4视频、PNG图片读取报错、显卡驱动更新后黑屏、colmap编译报错、cudart64_12.dll缺失等。文档还记录了从视频教程获取项目压缩包、解压数据的预处理细节。文档以doc格式打包共1个文件资源大小约96.32MB。全篇采用第一视角记录与error硬磕的过程包含系统版本查询、纯文本与图形界面切换、显卡驱动安装、colmap编译报错的多种排查方法、点云PLY可视化等实用技巧对colmap编译阶段出现“undefined reference to TIFFReadRGBAImage”等报错也给出了多种尝试并附有具体命令与排错思路对同类软硬件环境下复现3DGS的新手很有参考价值。目前已有5056人学习下载。这份文档既是一份踩坑记录也可作为新手复现3DGS时的对照参考。1. 新手复现 3DGS 的第一关不是训练是环境我见过太多人死在 3D Gaussian Splatting以下简称 3DGS复现的第一步——不是模型难不是数据难是连环境都建不起来。明明照着教程一步步走结果 pip install 报错、CUDA 版本对不上、编译 colmap 的时候 undefined reference 满天飞最后在终端里跟 error 硬磕到凌晨。这篇文章把我自己第一次复现 3DGS 的完整过程、踩过的每一个坑、每一个报错的最终解法都拆开讲直接给到可复现步骤和参数。我用的配置是 Ubuntu 20.04.3 LTSx86_64、NVIDIA GeForce RTX 3080 Ti、Python 3.8 虚拟环境、CUDA 11.8、PyTorch 2.4.1cu118、显卡驱动 535.183.01、colmap 3.9。这条路线适用于所有想跑通 3D 高斯三维重建的新手尤其是用笔记本或单卡工作站、显存 12GB 左右的用户。2. 环境准备先把系统和硬件底牌摸清2.1 确认 Linux 发行版、位数和显卡驱动很多人跟我一样只知道自己是 Linux 系统但具体是哪个发行版、多少位根本不清楚。我一开始只知道要用 Ubuntu 20.04但手上的机器到底是不是这个版本心里没底。最稳妥的做法是在终端里执行下面两条命令# 查看 Linux 发行版详细信息 cat /etc/*release # 查看操作系统位数 uname -mcat /etc/*release会输出当前系统的发行版名称、版本号和 ID比如DISTRIB_IDUbuntu、DISTRIB_RELEASE20.04。如果显示的是别的发行版那 3DGS 的很多 apt 安装指令可能要做对应调整。uname -m输出x86_64就表示是 64 位系统目前绝大多数桌面和工作站都是这个架构。接下来检查显卡驱动。3080 Ti 这张卡在 3DGS 训练里表现不错但前提是驱动版本和 CUDA 版本能对上。在终端执行nvidia-smi看右上角的 CUDA Version我的驱动 535.183.01 对应支持的 CUDA 版本上限是 12.2所以我装 CUDA 11.8 完全没问题。注意nvidia-smi显示的 CUDA 版本是驱动支持的最高版本并不代表你已经装了对应版本的 CUDA Toolkit。你真正安装的 CUDA 是给 PyTorch 编译用的那个要额外装。2.2 创建 Python 3.8 虚拟环境3DGS 官方仓库对 Python 版本比较挑剔我用的 3.8 是社区验证过的稳定组合。创建命令如下# 创建 python3.8 虚拟环境dxh 是自定义环境名 conda create -n dxh python3.8 -y # 激活环境 conda activate dxh # 验证当前 python 路径和版本 which python python -Vwhich python这一步特别重要很多人不检查就直接 pip install结果包装到了 base 环境甚至系统 Python 里。我一开始就犯了这个错——没激活虚拟环境就执行pip install simple-knn结果包被装到了 anaconda3 的 python3.7 下白白浪费了十几分钟排查。2.3 安装子模块diff-gaussian-rasterization 和 simple-knn从 GitHub 下载 gaussian-splatting-main 压缩包并解压后进入submodules目录这个文件夹里默认有三个空目录。官方 README 要求安装两个关键子模块在终端执行pip install submodules/diff-gaussian-rasterization pip install submodules/simple-knn但这里有个新手必踩的坑直接执行pip install submodules/diff-gaussian-rasterization会报Neither setup.py nor pyproject.toml found。原因是该子模块还没来得及 clone 子仓库或者路径不对。我当时的处理方案是先用 pip 安装 simple-knn再单独处理 diff-gaussian-rasterization。diff-gaussian-rasterization是 3DGS 的核心负责可微光栅化differential rasterization也就是把 3D 高斯分布投射到 2D 图像并计算梯度。simple-knn则是为每个高斯点寻找最近邻用于后续的自适应密度控制。这两个模块不装好训练时会直接报错。3. 子模块安装实战从源码编译到 import 成功3.1 为什么 pip 装不上No matching distribution found 的全套解法在我确定虚拟环境是 Python 3.8 后重新执行pip install diff-gaussian-rasterization仍然报No matching distribution found。这其实是三个问题叠加造成的我逐个排查后才解决。第一个是 pip 版本过低。2024 年之后的 PyPI 索引策略变了旧版 pip 经常找不到新包。执行下面命令升级python -m pip install --upgrade pip pip install --upgrade pip setuptools wheel pip cache purge第二个是当前环境的 Python 版本与预编译包的 wheel 不匹配。我尝试创建多个虚拟环境分别测试 python3.6、python3.9、python3.10全都不行。原因在于这两个子模块在 PyPI 上没有发布过官方的 wheel 包diff-gaussian-rasterization 的 PyPI 页面至今只有源码形式pip 找不到预编译产物就会干脆报一个笼统的No matching distribution found而不是告诉你应该去编译源码。第三个解决办法也是最终的出路——直接从 GitHub 克隆源码到本地再编译。在submodules目录下打开终端执行# 克隆 diff-gaussian-rasterization 源码--recursive 会一并拉取子模块 git clone --recursive https://github.com/slothfulxtx/diff-gaussian-rasterization.git--recursive参数必须带上因为这个仓库还依赖第三方的 CUDA 扩展代码不用这个参数拉下来就是残缺的。克隆成功后submodules/diff-gaussian-rasterization文件夹里不再是空的能看到setup.py、diff_gaussian_rasterization源码目录这些实际内容。用同样的方式处理 simple-knngit clone --recursive https://github.com/akaparounakis/simple-knn.git3.2 编译前还需要补齐的东西libglm-dev 和 PyTorch克隆完源码后直接编译还会报错缺少 glm 数学库。执行sudo apt-get install libglm-dev这个库是 CUDA 代码里做矩阵运算必需的缺少它编译时报的是各种找不到头文件容易误判成 CUDA 没装好。装完之后还要确认 PyTorch 已安装。我最初测试python -c import diff_gauss时报错原因是当前 Python 环境没有安装 PyTorch。安装命令pip install torch torchvision但注意这里默认装的是 CPU 版本 PyTorch而 3DGS 训练必须要 CUDA 版本。正确做法是去 PyTorch 官网用pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118装 CUDA 11.8 对应版本。我当时在 Python 3.8 环境中装的版本是 2.4.1cu118对应torchvision也要选同一批次的版本否则 import 时报torchvision与torch版本不一致。3.3 编译子模块的正确姿势和验证方法源码就位、依赖装齐之后在submodules/diff-gaussian-rasterization目录里执行编译安装cd submodules/diff-gaussian-rasterization # 激活虚拟环境 conda activate dxh # 编译并安装当前目录为 Python 包 pip install .pip install .的含义是安装当前目录下的 Python 包它会自动读取setup.py执行 build_ext 编译流程。这一步会调用 nvcc 编译 CUDA 内核耗时 3 到 10 分钟不等取决于 CPU 和硬盘速度看到Successfully built diff_gaussian_rasterization就是成了。接着处理 simple-knncd ../simple-knn # 先按 requirements.txt 安装依赖 pip install -r requirements.txt # 再编译安装 pip install .最后用一种“硬核”方式验证是否真的装好了——直接尝试导入模块。注意导入名不是diff_gaussian_rasterization而是diff_gauss这个模块名需要看setup.py里的name字段。验证命令python -c import diff_gauss; print(diff_gauss import ok) python -c import simple_knn; print(simple_knn import ok)如果输出对应的 ok 字符串说明编译安装成功。我在这里卡了将近三个小时才明白pip 安装后的包名和import 名不一定相同以后看到import报错第一件事就是去翻对应仓库的 setup.py。4. colmap 稀疏重建数据从视频帧到稀疏点云的完整链路4.1 数据准备视频抽帧和图像常见问题3DGS 需要多视角图像作为输入官方推荐的路径是把视频抽帧。B 站 UP 主的项目压缩包里有猪猪侠视频数据但解压后双击.MP4无法播放——这是 Ubuntu 缺解码器。我的解决办法sudo apt-get install ubuntu-restricted-extras这个包安装了 Ubuntu 官方默认不带的 MP4/H.264 解码器和 Flash 插件等装完就能正常播放。更阴间的一个问题是 PNG 打不开报错读入 PNG 图像文件时发生严重错误Not a PNG file。我检查后发现那个文件的后缀是.png但实际编码是 JPEG——改后缀名mv wallpaper.png wallpaper.jpg就能打开。这个坑看起来蠢但遇到Not a PNG file时先别怀疑 colmap先确认文件真实格式。常见做法是# 用 file 命令查看文件的真实类型 file data/images/001.png4.2 colmap 3.9 编译安装与 TIFF 报错colmap 是 3DGS 数据预处理的标准工具作用是做运动恢复结构SfM生成相机位姿和稀疏点云。官方推荐 3.9 版本但直接 apt 安装的是 3.6 左右功能不匹配需要源码编译。编译过程中最大的坑是链接时报错undefined reference to TIFFReadRGBAImageLIBTIFF_4.0这是系统自带的 libtiff5 版本与 colmap 源码期望的 LIBTIFF_4.0 符号不匹配。解决思路安装更新的 libtiff 开发版并重写软链接。我在 Ubuntu 20.04 上的处理是# 安装 libtiff 开发包 sudo apt-get install libtiff-dev # 如果还报错手动下载 libtiff 源码编译安装 wget https://download.osgeo.org/libtiff/tiff-4.5.0.tar.gz tar -xzf tiff-4.5.0.tar.gz cd tiff-4.5.0 ./configure --prefix/usr/local make -j8 sudo make install编译完成后设置LD_LIBRARY_PATH指向新安装的 libtiff 路径再重新编译 colmap 就过了。这里有个容易忽略的点改完 libtiff 后不仅要重新编译 colmap还要重新编译 colmap 依赖的其它库比如 ceres-solver 若静态链接了旧 tiff否则同样报错。我当时的做法是干净地删掉 build 目录重新cmake ..一次搞定。4.3 用 colmap 生成 3DGS 需要的 SfM 模型colmap 编译通过后对视频抽帧出的图像序列做稀疏重建命令行如下# 创建项目目录结构 mkdir -p data/pig/data data/pig/sparse # 特征提取 colmap feature_extractor \ --database_path data/pig/data/database.db \ --image_path data/pig/data/input # 特征匹配 colmap exhaustive_matcher \ --database_path data/pig/data/database.db # 稀疏重建 colmap mapper \ --database_path data/pig/data/database.db \ --image_path data/pig/data/input \ --output_path data/pig/sparsefeature_extractor参数中--ImageReader.single_camera 1建议加上因为同一个视频抽出来的帧都来自同一台相机不加的话 colmap 会把每张图都当成独立相机模型重建出的稀疏点云结构会乱3DGS 训练效果差很多。mapper输出目录下会有0子目录里面包含cameras.bin、images.bin、points3D.bin三个二进制文件这就是后续训练要用的 SfM 模型。数据准备的最后一步是转成 3DGS 要求的目录格式。训练代码默认读取input目录下的图像和sparse/0下的 colmap 输出所以目录结构要严格对齐data/pig/ ├── input/ # 所有视频抽帧图像 └── sparse/ └── 0/ # colmap 输出cameras.bin images.bin points3D.bin4.4 点云 ply 可视化确认数据没白做稀疏重建完成后可以用 CloudCompare 或 Open3D 可视化稀疏点云确认重建是否正常。用 conda 装 Open3D 最省事pip install open3d然后在 Python 里写几行脚本验证import open3d as o3d # 读取 colmap 输出的稀疏点云 pcd o3d.io.read_point_cloud(data/pig/sparse/0/points3D.ply) print(f点数: {len(pcd.points)}) # 用红色渲染窗口里能直观看到物体的轮廓就说明重建正常 pcd.paint_uniform_color([1, 0, 0]) o3d.visualization.draw_geometries([pcd])不过 3DGS 训练时不是直接读这个 ply而是读points3D.bin二进制格式。我一般用这个可视化只是为了快速验证重建出来的点云有没有明显的漂移或飞点。如果没有明显的漫天飞点说明 SfM 这步是健康的可以进入训练环节。5. 训练 3DGS 与常见问题排查从跑通到跑稳5.1 train.py 的核心参数与显存控制数据准备好后进入gaussian-splatting-main目录启动训练。我用的命令conda activate dxh python train.py \ -s data/pig \ -m output/pig \ --iterations 30000 \ --test_iterations 5000 15000 30000 \ --save_iterations 7000 15000 30000-s指定数据根目录目录下要有input和sparse子目录-m指定输出目录模型、配置、点云都会存到这里--iterations是总迭代次数官方默认 300003080 Ti 上大概需要 40 到 60 分钟--test_iterations指定在哪些迭代步数跑测试集评估--save_iterations指定保存点云快照的步数我习惯在 7000 和 15000 各存一次万一后面训练崩了还有中间结果可以兜底3080 Ti 是 12GB 显存跑默认分辨率的场景没问题。如果数据图像分辨率很高超过 1600 像素需要加--resolution 2参数意思是每隔 2 个像素采样相当于分辨率减半。不加的话显存很容易爆报错一般是CUDA out of memory。5.2 训练输出文件和收敛判断训练完成后output/pig目录下会生成这些关键文件文件/目录作用point_cloud/iteration_30000/point_cloud.ply最终的高斯点云模型含位置、不透明度、协方差、颜色特征cameras.json所有视角相机的内外参数cfg_args训练参数存档复现实验必备output/pig/conftensorboard 事件文件可查看训练曲线判断训练是否正常的最快方式是开 TensorBoard 看 loss 曲线。在项目根目录执行tensorboard --logdir output/pig浏览器打开http://localhost:6006如果可以看到 loss 从几千降到几十甚至个位数并且曲线整体平滑下降说明训练在正常收敛。如果 loss 曲线出现先降后升的“V 字形”大概率是学习率过大或数据里有异常图像——这时候我会回头检查input目录里的图像有没有模糊帧、纯色帧、重复帧。5.3 训练和渲染后的常见问题这一节专门列我训练 3DGS 时踩得最深的三类问题每个都给原因和对应处理方案。问题一训练时报ImportError: cannot import name get_ray_bbox3d_fn from rasterize现象是训练刚开始几十步就报错看 import 链路是 diff-gaussian-rasterization 的版本与主仓库代码不匹配。原因是 diff-gaussian-rasterization 这些年接口改了好几次而我们这个复现流程用的主仓库代码要求的是 2023 年 12 月之前的那一版接口。解决方法是把submodules/diff-gaussian-rasterization回退到和主仓库匹配的 commitcd submodules/diff-gaussian-rasterization # 查看当前 git 日志找到匹配的版本 git log --oneline -5 # 回退到早期版本2023-09 前后的 commit 比较稳 git checkout 5b784aa # 根据实际日志选择一个旧 commit pip install .问题二CUDA 编译时nvcc fatal : Unsupported gpu architecture compute_903080 Ti 是 Ampere 架构compute_86但有些源码的 setup.py 默认配置里包含 compute_90Hopper甚至 compute_120Blackwell老版本 CUDA 不认识这些新架构就会报错。解决方法是修改setup.py把不需要的架构去掉。在diff-gaussian-rasterization/setup.py中找到类似[compute_86, compute_90]的地方删除compute_90只留extra_compile_args { cxx: [-O3], nvcc: [-O3, --gpu-architecturecompute_86, --gpu-codesm_86], }改完重新pip install .。注意如果源文件里直接写死sm_90需要手动改成sm_86不然编译是通过了跑的时候会报no kernel image available。问题三训练时显存瞬间打满CUDA out of memory3080 Ti 虽然不小但 3DGS 对显存的消耗受图像分辨率影响很夸张。现象是训练刚启动到第 100 步左右nvidia-smi看显存 12GB 全部占满然后进程被杀。原因有两个一是图像分辨率太高且没有加--resolution二是默认的--sh_degree3对显存要求偏高球谐阶数越高存储的系数越多。解决分两步先降分辨率python train.py -s data/pig -m output/pig --resolution 2再不行就减少球谐阶数。球谐函数是描述视角相关颜色比如高光的数学工具sh_degree3是官方默认但如果只是验证流程改成--sh_degree2也可以接受训练速度更快、显存更省只是高光和颜色变化的效果弱一点。5.4 渲染检查点云模型有没有真正学会视角训练结束后需要做一次渲染验证。项目里自带render.py把训练好的模型渲染成视频序列python render.py \ -s data/pig \ -m output/pig \ --iteration 30000渲染出的帧序列存在output/pig/test/ours_30000/下把帧合成为视频的通用做法# 用 ffmpeg 将渲染出的图片合成为 mp4 视频 ffmpeg -framerate 30 -i output/pig/test/ours_30000/r_%d.png -c:v libx264 rendered.mp4这一步如果用 ffmpeg 报找不到r_%d.png是因为render.py输出的文件名可能带了前导零。先ls output/pig/test/ours_30000/看实际命名规律再对应调整通配符。渲染没问题后用 PSNR峰值信噪比来评估质量训练时的测试集评估会自动算这个指标3080 Ti 上跑出新视角渲染的 PSNR 一般在 25 到 32 之间低于 20 说明数据或训练大概率有问题。6. 收尾技巧五个让复现更顺手的习惯第一个习惯是先跑官方数据再跑自己的数据。我第一次复现时直接用自己的视频抽帧结果 colmap 建出乱点云我以为是代码问题其实是数据拍得太随意。后来改用项目自带的数据跑通全流程再把同样的命令套到自己的数据上很快就定位到是数据采集的问题。所以从零复现时先用自带数据把环境、编译、训练、渲染全部验证一遍再换成自己的数据。第二个习惯是每次新建环境时把版本对应关系写在一张纸片上。我踩过最亏的一次是把 simple-knn 装到了 anaconda3 的 python3.7 里导致 diff-gaussian-rasterization 怎么都编译不对。从那以后我每次开新环境都强制走一遍这个核对流程conda activate dxh python -V # 必须是 3.8 或 3.10取决于仓库要求 which python # 必须在虚拟环境目录下 nvidia-smi # 驱动支持的 CUDA 版本必须高于 PyTorch 的 cu118 python -c import torch; print(torch.__version__)第三个习惯是单独保存一份编译好的子模块源码。diff-gaussian-rasterization 的源码编译是真磨人但编译产物是可以保留的。我把submodules目录整体压缩备份一份下次换机器直接解压然后重新pip install .就能秒装不用再经历 git clone、改 setup.py、等 nvcc 编译的流程。git 仓库里的build目录是不用备份的那个跟当前机器绑定直接删掉重编更快。第四个习惯是用 TensorBoard 盯住前 2000 步。3DGS 训练刚开始的迭代可能看不出问题但前 2000 步的 loss 曲线基本能预测最终效果。如果 2000 步时 loss 还在 100 以上而且起伏不定果断 CtrlC 停掉检查数据比干等三十分钟强。训练时我一般会同时开着nvidia-smi -l 1每隔一秒刷新一次显存占用看到显存曲线异常飙高或者掉到 0说明有 batch 崩了。第五个习惯是把失败的终端会话完整保存下来。这是个性价比极高的操作——每次复现碰到新报错先把报错信息完整复制存档再开始改。因为很多报错在搜索引擎里搜不到完全一致的但把多个报错拼在一起AI 和社区大佬才能精准定位根源。这也让我养成了一个习惯每次跑训练前把完整的复现命令写进一个run.sh这样下次回来对照脚本就能快速恢复现场。希望这些从实测里摔出来的经验对你有用能让你的 3DGS 复现少走几个小时的弯路。本文还有配套的精品资源点击获取
