简介这份资源是面向新手的 3D 高斯与 3D Gaussian Splatting 复现全流程文档记录在 Ubuntu 20.04.3 LTS 系统、RTX 3080 Ti 显卡、Python 3.8 与 CUDA 11.8 环境下从环境配置、创建虚拟环境、安装子模块到使用 colmap 做稀疏重建并完成训练的完整过程。文档以第一视角写下一连串新手常见报错和排查方法包括 Linux 系统无法播放 MP4 视频、PNG 图片读取时出现 Not a PNG file、显卡驱动更新后黑屏与闪光标、colmap 编译遇到 undefined reference 错误、simple-knn 安装路径不对等也补充了纯文本界面与图形界面切换、点云 ply 文件可视化说明。对刚接触三维重建、面对 error 容易卡住的入门者来说可以照着操作并借排查思路少走很多弯路。资源为 1 个 doc 文档压缩包约 96.32MB内容包含具体指令、软件版本、参考链接、排错过程与项目路径说明适合在 Linux 上复现 3DGS 前先通读。目前已有 5056 人学习下载是一份接地气的实战参考。1. 新手第一次复现3D高斯3DGS先想清楚再动手第一次听到3D高斯溅射3D Gaussian Splatting简称3DGS这名字的时候我第一反应是这玩意儿到底跟传统的三维重建有多大区别。但真正吃到红利是在某次给某跨平台系统做室内场景数字化的时候用几百张照片一台8GB显存的显卡半小时就拿到一个能自由视角浏览的细腻模型。相比之下传统的神经辐射场NeRF要训练几个小时甚至几天效果还不一定更好。这套技术在2023年发布后迅速成为三维视觉和图形学社区最热的方向之一它用一组带协方差的高斯球来表达场景训练过程是光栅化而不是体渲染所以又快又便宜。如果你正打算第一次复现这个流程手里有带摄像头的东西、一块NVIDIA显卡而且想弄明白从照片到三维场景这条完整链路这篇笔记就是给你准备的。我会用最朴素的方式把环境配置、数据准备、训练、参数调优、踩坑全部铺开来讲保证你跟着走一遍能出结果。2. 环境准备让3DGS跑起来的最小条件与完整安装步骤2.1 硬件和软件的下限显卡、CUDA与PyTorch的三角关系复现3DGS不需要多豪华的机器但有几个硬指标绕不开。显存决定你能训练多大规模的场景官方推荐20GB以上但那是在完整分辨率、6到7万次迭代的条件下。如果只是第一次复现跑通流程8GB显存的显卡也能完成小型场景的训练代价是得降低图像分辨率和迭代次数。CPU方面一颗多核处理器就够用内存16GB起步因为COLMAP做特征匹配时会把大量图像数据同时读入内存。磁盘空间按场景算一个训练场景的图片加上中间产物5GB到10GBSpace很正常如果做视频输出还要预留更多。软件栈是新手最容易翻车的地方。3DGS的官方实现是基于PyTorch的CUDA扩展需要自己编译所以CUDA版本和PyTorch版本必须严格对应。我见过太多人卡在import环节报错全是CUDA与PyTorch不匹配。建议是pyTorch版本选稳定版CUDA Toolkit用11.8或12.1这两个被社区验证最多的版本别追最新。COLMAP作为特征提取和稀疏重建的依赖项安装方式看操作系统Linux建议源码编译Windows直接用安装包即可。整体安装流程我会按Linux环境给你捋清楚Windows会标注差异。2.2 从零搭建conda环境每一步都该知道为什么我一般会先把conda环境建好再逐层装依赖。新建一个Python 3.8的环境是有原因的——某些CUDA扩展在更高Python版本下编译会出现奇怪的std::bad_alloc3.8是被验证最稳的。然后安装PyTorch这里必须显式指定CUDA版本否则pip默认装的CPU版本会让后续所有操作直接失败。装好之后立刻验证GPU可用性很多人在这一步省略结果等到训练才报错白白浪费时间。# 创建并激活环境 conda create -n 3dgs python3.8 -y conda activate 3dgs # 安装PyTorch这里以CUDA 12.1为例 # 注意按你自己的驱动版本和CUDA Toolkit版本选择对应命令 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 验证GPU能被PyTorch识别 python -c import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))这段代码的逻辑很清楚第一行创建隔离环境避免把系统Python搞乱第二行的--index-url参数指定了CUDA版本的PyTorch下载源这是最容易出错的地方。如果输出False先查nvidia-smi看驱动是否正常再确认安装命令里的CUDA版本号是不是写对了。注意啊驱动支持的CUDA版本和PyTorch需要的CUDA版本不是一回事驱动是向下兼容的只要驱动版本够新就行。验证通过之后接下来装的是3DGS核心依赖submodules/diff-gaussian-rasterization和submodules/simple-knn。这两个是训练和渲染时用到自定义CUDA算子必须本地编译。官方仓库的README里给了一条命令装所有依赖但我不建议一口气装完因为MinkowskiEngine这个包在部分系统上编译容易出问题而它只跟语义分割的可选功能有关复现基础流程根本用不到。我会把依赖拆开只装必要的部分这一步能帮你省掉大量排错时间。# 拉取官方代码仓库 git clone https://github.com/graphdeco-inria/gaussian-splatting --recursive cd gaussian-splatting # 只装核心依赖不装MinkowskiEngine等可选包 pip install plyfile tqdm tensorboard # 编译两个CUDA子模块 cd submodules/diff-gaussian-rasterization pip install . cd ../simple-knn pip install .编译过程耗时取决于机器性能一般几分钟到十几分钟。如果编译报错常见原因包括g版本过旧、CUDA Toolkit没装全、或者ninja构建工具的版本问题。一条一条排查就是gcc --version看编译器nvcc --version看CUDA。前两个子模块装好以后pip install .是把你当前的包安装到环境里所以一定要在对应子模块目录下执行。这个顺序不能换因为训练代码import的diff_gaussian_rasterization和simple_knn就来自这两个模块。2.3 COLMAP安装与验证没有它图片就变不成点云3DGS的数据管线里COLMAP负责从一组照片中估计相机位姿并生成稀疏点云这些是训练3DGS的前置条件。安装方式在Ubuntu下可以sudo apt install colmap但这个版本通常偏老部分功能可能带bug。我建议在官网找最新release的Linux安装包或者直接用conda装conda install -c conda-forge colmap。Windows用户直接下载exe安装包即可但需要注意官方仓库的脚本调用的是命令行版本COLMAP装完以后要确认colmap命令在终端里能识别。装好以后做个快速验证用任意一组小照片跑一下特征提取能正常生成数据库文件就说明基本可用。这一步的意义是提前把COLMAP的环境问题暴露出来不至于等到数据准备环节才发现装了个残缺版本。验证命令很简单新建一个文件夹丢几张图进去执行colmap feature_extractor这条命令如果一路跑完没有报错就可以进入下一步了。# 验证COLMAP安装 cd ~/test_colmap mkdir images # 往images里放几张照片 colmap feature_extractor --database_path database.db --image_path images跑完以后目录下会多出一个database.db文件大小在几十到几百KB之间。如果这一步报错最常见的是找不到lib库LD_LIBRARY_PATH没指对或者是CUDA相关库缺失。Ubuntu 22.04上我遇到过COLMAP依赖libboost和libgflags版本不匹配的问题解决方式是sudo apt install libboost-all-dev libgflags-dev之后重装COLMAP。这一步验证完环境准备就算齐活了我们进入数据准备环节。3. 数据采集与预处理几百张照片如何变成可训练的数据集3.1 拍摄质量直接决定重建结果别指望算法救回烂数据3DGS的效果上限在拍摄阶段就已经确定了。我在某图像处理Demo项目里试过用手机随手拍的一圈照片做重建结果训练出来的场景像隔了一层毛玻璃而同一场景用规范拍摄的素材效果直接提升一个档次。拍摄的核心原则就三句话场景光照均匀、相邻照片重叠率60%以上、每张照片都在不同角度拍摄。绕着一个物体或场景中心走一圈相机朝向中心高度可以略作变化这样能覆盖更多视角。室内场景记得开灯补光室外尽量选阴天或傍晚避免高光和大阴影。照片数量不是越多越好。一个小型场景四五十张足够大场景可以到两百张以上。关键是每张照片之间要有足够的视角变化如果站在原地转着拍拍几十张角度几乎一样的照片COLMAP算出来的位姿会漂移后面重建质量直接崩盘。另外照片分辨率控制在1600到3000像素宽比较合适太高会让特征提取和训练都变慢太低则丢失细节。手机相机默认输出往往超过4000像素建议预处理时批量压缩。3.2 COLMAP全自动流程一条命令从图片到稀疏点云官方仓库的自动脚本convert.py把COLMAP的完整流程封装好了从特征提取到稀疏重建一条龙最终输出训练需要的格式。脚本内部会依次调用COLMAP的feature_extractor、sequential_matcher、mapper、bundle_adjuster最后做一次位姿对齐和点云转格式。直接执行python convert.py -s data/scene_name --skip_matching这种形式即可如果图片已经做过特征匹配可以直接跳过那一步。但这里有个重要的坑--skip_matching只适用于你之前已经跑过匹配且生成了带特征的数据的情况新手不建议跳。# 准备目录结构 mkdir -p data/toy_scene/images # 把预处理后的图片拷进images文件夹 # 运行自动转换脚本 python convert.py -s data/toy_scene脚本跑起来会弹出一堆COLMAP日志看到Registering images之类的输出说明在正常建图。整个过程耗时与图片数量、分辨率直接相关几十张图大概几分钟。跑完以后data/toy_scene下会生成sparse和images两个关键目录其中sparse/0里是带校正位姿的相机参数sparse/0/points3D.ply是稀疏点云。训练脚本在数据加载阶段会读取这个目录结构所以不要手动重命名。值得一提的是自动脚本里其实还做了undistortion的步骤把图片畸变校正并且统一内参这一步对最终渲染质量影响很大。所以你在data/toy_scene目录下看到的images文件夹会被替换成去畸变后的图片尺寸可能比原始的略小这是正常的。如果脚本报错说找不到COLMAP可执行文件留意一下sys.path和控制台是否在conda环境内——conda的bin目录没有自动加到PATH里就会这样。3.3 标定结果检查训练之前花两分钟判断数据是否合格在启动训练之前先确认稀疏重建是成功的。看两个指标一是稀疏点云的点数几百张图重建出来至少要有几万个点二是COLMAP日志里Registered images的数量占总数比例如果低于80%说明拍摄质量有问题或者图片序列断档了。打开sparse/0下的points3D.ply直接看可视化是更直观的方式在渲染器里扫一眼如果看到点云大体覆盖了物体的表面形状位姿基本是对的。# 检查重建结果 python -c import plyfile import numpy as np ply plyfile.PlyData.read(data/toy_scene/sparse/0/points3D.ply) vertices ply[vertex] print(f点数: {len(vertices)}) 如果点云数量低到几千个或者形状跟实际场景对不上训练出来的一定是废墟。这时候唯一正确做法是回头补拍或者调整COLMAP的匹配策略。我在实际项目里遇到过一组室内照片排除了半天发现是其中几张照片对焦在窗户外面导致背景清晰、主体模糊重拍以后一次通过。这个检查动作虽然简单但能避免训练几小时后才发现数据不行属于血泪经验换来的习惯。另外如果照片是手机拍的横竖屏混合会让COLMAP的特征匹配出问题建议全部转成统一横屏然后再进流程。EXIF里的旋转信息有些预览工具会忽略但COLMAP会读取不一致时会罢工。网上有些工具能按EXIF自动旋转图片处理完记得人工抽查几张确认方向正确。4. 训练流程跑通3DGS主训练器并看懂关键日志4.1 train.py参数逐项拆解第一次训练用什么配置数据准备完毕就到了整个流程的核心环节——训练3DGS模型。训练脚本train.py的参数不多但每一项都直接影响最终效果和训练耗时。第一次跑通流程建议用保守配置迭代次数设3万次测试和保存间隔设5000这个配置下8GB显存也能撑住小型场景后面再根据效果调整。先看一条完整的训练命令理解每个参数的含义再决定怎么改。# 标准训练命令小场景/低显存 python train.py \ -s data/toy_scene \ -m output/toy_scene \ --iterations 30000 \ --test_iterations 5000 15000 30000 \ --save_iterations 7000 15000 30000 \ --eval \ --resolution 2-s指定数据目录-m指定输出目录。--iterations 30000是总迭代次数3DGS默认是30000官方论文里的结果基于这个配置。--test_iterations表示每隔多少轮在测试集上算一次PSNR指标5000 15000 30000意味着训练过程中在五、十五、三万次时各测一次测试时会多花一点时间但能让你看到模型变好的过程。--save_iterations控制模型检查点保存时机7000 15000 30000意思是这几个节点各存一份方便做对比实验或回溯——别嫌占空间这是你的后悔药。--eval是让脚本预留一小部分图片做测试集不参与训练只在上面的test迭代节点做验证。如果你开了--eval训练日志里每隔固定step会打印一次测试结果。--resolution 2是把图像分辨率除以2再训练即图像缩小为原来的一半。这个参数直接影响显存占用两张3090跑不动的场景用这个参数结合减半迭代8GB显卡也能勉强应对。其实还有更厉害的一招--resolution 4直接缩放四分之一速度翻数倍但细节损失明显适合先跑通验证流程再调正式参数。4.2 训练日志怎么看数值和曲线透露的信息训练一旦跑起来终端会弹出类似这样的输出Step: 1000, Loss: 0.412, SSIM: 0.854, PSNR: 21.34 Step: 5000, Loss: 0.213, SSIM: 0.931, PSNR: 27.12第一个指标Loss是重建损失包含RGB的颜色误差和纹理正则项值越小越好。SSIM是结构相似度范围0到1越高代表结构保真度越好。PSNR是峰值信噪比单位dB越高代表重建质量越好常见好场景在27以上。这三个指标是3DGS训练时的常规观测指标在每个test_iterations》节点打印。需要留意的是测试阶段会暂停训练一段时间所以看到卡顿是正常现象。第一次跑的时候不要一上来就盯着PSNR高低得失先确认Loss能稳定下降。Loss在某些节点不降反升是正常的——自适应密化在增删点云时损失会震荡一下只要整体趋势向下问题不大。我遇到过新手在群里说训练翻车了结果是跑了几千步还没到第一次自适应密化阶段点云还是稀疏的渲染结果当然像雾里看花。3DGS默认在前几百步内就会完成初始点云稠密化你可以用Tensorboard监控Loss曲线命令是tensorboard --logdir output/toy_scene。4.3 训练产物解析checkpoint、点云和渲染输出在哪训练完成后output/toy_scene目录下会多出几个关键产物。point_cloud/iteration_30000里存的是每轮保存的模型点云每个point_cloud/iteration_XXXXX文件夹下一步point_cloud.ply就是该迭代次数对应的模型文件可以用来做静态渲染或导出。test/目录存放的是测试集渲染结果每张测试图片对应的渲染图和GT图都在里面。train/里存放训练集渲染结果主要用来肉眼检查有没有明显的伪影或糊块。cameras.json记录相机参数cfg_args保存训练参数配置——之后用render.py时需要用到这个参数文件。还有一个容易忽略的点训练日志output/toy_scene/下的loss.txt文件记录了每一个step的loss数值可以用任何文本工具打开分析。如果做实验对比直接看这个文件比看终端输出方便多了。想保留中间检查点做继续训练--checkpoint参数配合保存的.ckpt文件可以在中断后恢复不用从头跑。第一次跑通之后我强烈建议试试这个功能训练到一半停了用队checkpoint接着跑省时省力。# 中途续训命令假设在第15000次迭代时中断 python train.py \ -s data/toy_scene \ -m output/toy_scene \ --start_checkpoint output/toy_scene/point_cloud/iteration_15000/checkpoint.ckpt \ --iterations 30000 \ --test_iterations 30000 \ --save_iterations 30000注意--start_checkpoint路径不是随便指要在保存过checkpoint的迭代节点下找。而且续训时迭代数的计算方式是从当前step继续不是从零开始。有些版本在续训时需要把--iterations设成总目标迭代数而不是剩余迭代数具体要看源码里对global_step的初始化逻辑。这个细节经常让人摸不着头脑跑之前看一眼源码能少踩坑。5. 高频踩坑与排查从环境到训练的五个典型翻车场景5.1 CUDA out of memory显存不足时的三板斧现象训练刚开始或者跑到一半终端报CUDA out of memory然后进程直接退出。原因场景点云数量多加上分辨率高显存被打满。3DGS训练过程中会自动增加高斯球数量所以很多场景在初期能跑密化几次之后反而爆显存。解决第一优先级把--resolution从2改成4这是最直接的降显存手段。第二优先级减少迭代次数30000次训练比70000次训练需要的峰值显存低不少因为后期点云数量会增长。第三选择是分块训练或直接换显卡但这两个代价太大不适合第一次复现。另外确认一下没有其他程序占用显存nvidia-smi看一眼就能排除。有个小技巧是关掉Tensorboard监控它本身不占多少显存但对部分显卡会有CUDA context占用。5.2 编译子模块时报错diff-gaussian-rasterization安装失败现象pip install .到diff-gaussian-rasterization时报错内容形如error: command gcc failed with exit code 1或者找不到CUDA头文件。原因编译器版本和CUDA版本不匹配或者CUDA_HOME环境变量没设置。最常见的是系统gcc版本过高对CUDA 11.x支持不好。解决先把gcc切换成9或10版本sudo update-alternatives --config gcc选择正确的版本。然后确认nvcc --version能正常输出设置export CUDA_HOME/usr/local/cuda再重新编译。有些情况是ninja的问题可以pip uninstall ninja之后装上ninja1.10.2这个被社区广泛验证的版本。这个问题没有银弹本质上就是环境匹配问题逐个排查依赖版本心态稳住就好。5.3 训练出来全是糊的或雾状的场景现象训练了好几个小时渲染结果像是隔着毛玻璃看场景边缘和纹理全模糊PSNR一直低于20。原因最大头是数据拍摄问题——相邻照片重叠太少COLMAP重建的相机位姿精度差导致3DGS训练从一开始就在错误的位置投射高斯球。另一个可能是学习率初始值不合适默认--position_lr_init为0.00016如果场景特别大或特别小都得调整。解决先回到sparse/0/points3D.ply可视化确认点云覆盖是否合理。如果点云本身没问题检查训练日志里Loss是否在正常下降如果Loss卡住不动尝试调大--position_lr_init到0.0003或调整密化阈值--densify_grad_threshold从默认的0.0002调低到0.0001让点云更早开始稠密化。这一步属于参数玄学没有固定解建议做几组对照实验观察效果变化。5.4 训练过程突然黑屏或卡死现象训练刚到某个step屏幕上所有内容消失黑屏几分钟后系统闪退。原因显卡驱动在CUDA运算量陡增时崩溃了。3DGS训练过程会大量调用CUDA kernel驱动处理不了就直接重置显卡简单说就是驱动版本太老或者不稳定。解决更新显卡驱动到厂商近期正式版不要用beta版。再有就是降低--resolution减小心算压力避免触发驱动bug。如果场景很大还能试试把迭代次数降低到20000减少运行的时长和强度。这个坑说实话不常遇到但遇到了真的是血泪教训——我在某次连续训练几天的大场景项目里就碰到过最后用更新驱动就解决了。5.5 数据集中有部分图片无法匹配现象COLMAP跑完以后提示某几张照片没有注册到重建中Registered images数量低于总数。原因那些照片的拍摄位置跟其他照片重叠度太低或是光照条件差异太大或者图片本身模糊。COLMAP的特征匹配对这些情况很敏感。解决把未注册的图片找出来检查拍摄角度是不是跳变太大。如果是删除它们重新跑转换流程。不要强行保留这些图片它们不仅没有帮助还可能让相机位姿优化结果变差。另外如果是某些图片有重复纹理比如绿植、地毯这类可能匹配到了错误的位置导致重建扭曲也需要删掉重跑。一个经验是图片数量宁少勿滥四五十张质量好的胜过一百张参差不齐的。6. 进阶验证与效果优化评估渲染质量并让场景更清晰模型训练完别急着关终端render.py和metrics.py这两个脚本能帮你做效果验证。先把测试集渲染成视频走一遍全视角再对比GT图算一下PSNR和SSIM数值。render.py的基本调用方法是# 渲染训练好的3DGS模型 python render.py \ -m output/toy_scene \ --iteration 30000 \ --skip_train # 计算量化指标 python metrics.py -m output/toy_scene--iteration指定用哪个迭代节点保存的模型--skip_train是跳过训练集渲染只做测试集。渲染完去output/toy_scene/test/下看renders文件夹里的PNG图片跟gt文件夹里的原图逐张对比肉眼检查比数字更靠谱——PSNR高但视觉上有明显伪影的情况并不少见。视频导出是验证3DGS第一人称沉浸感的最佳方式。官方仓库里没有现成的视频脚本但社区普遍做法是把render.py修改成按环绕路径输出帧序列再用ffmpeg合成视频。核心是把相机参数改成一条环形的轨迹从主体周围绕一圈拍。这一步能直观感受到3DGS和NeRF体验上的差别3DGS的渲染是实时的转视角几乎没有延迟所见即所得。关于提升质量我最后分享几个参数习惯。场景细节丢失明显时调低--densify_grad_threshold到0.0001左右让算法更积极地增加高斯球。背景虚化的照片把--sh_degree从3降到2减少高斯基函数的自由度防止过拟合到有噪声的光照。训练时间充足的话迭代数从30000提到70000配合--position_lr_max_steps一起调整通常PSNR能再涨0.5到1个dB。这些参数都是可复现的前提是控制变量一次只改一个。第一次跑3DGS这套流程最深的感受是决定上限的是数据和环境决定下限的是参数和耐心。我为做的就是老老实实把每一步跑通从COLMAP到训练再到渲染中间被编译错误和显存不足折磨过不少次但结果是值得的——比起任何文字描述亲手转动的三维视角才是最好的回报。希望这篇笔记能帮你少走一段弯路祝一次跑通。本文还有配套的精品资源点击获取