简介面向新手小白的 3D Gaussian Splatting3DGS复现全流程文档以 Ubuntu 20.04.3 LTS 与 RTX 3080 Ti 环境为主线围绕 colmap 编译、显卡驱动更新、MP4/PNG 异常、点云可视化等高频报错给出第一视角排错记录适合首次接触三维重建与 3DGS 的开发者。资源为 1 个 doc 文档大小 96.32MB将环境配置、依赖安装、子模块编译、稀疏重建等环节整理为结构化笔记。该文档已有 5056 人学习对刚入门的读者有真实参考价值。内容结合完整踩坑过程覆盖 Linux 基础命令、虚拟环境搭建、colmap 链接错误、cudart64_12.dll 缺失、PNG 识别错误等典型问题也介绍了纯文本界面与图形界面切换、显卡驱动黑屏恢复等实用经验能帮助读者少走弯路快速在 Linux 下完成 3DGS 环境搭建与示例数据复现。1. 复现3DGS的第一道坎为什么满屏教程你依旧跑不通3D高斯3D Gaussian Splatting简称3DGS在三维重建圈里红得发紫一张显卡就能把一个普通视频变成可以自由旋转的3D场景。可真正动手复现“3DGS复现全流程”的人多半会卡在环境配置或数据集制作上不是CUDA版本不对就是COLMAP崩掉要么训练出来的模型一片糊。这篇笔记不打算重复那些漂亮的效果图而是把你从“拉下代码”到“跑出自己的3D场景”之间会遇到的实际问题拆开讲清楚适合刚接触3D高斯、准备自己动手做数据集的新手。我会按自己踩过的坑来写尽量让你少走弯路。2. 3D高斯溅射的原理与复现前要认清的三个组件从SfM点云到可微渲染先别急着敲命令。复现3DGS最忌讳的就是把train.py当成黑匣子一跑就等结果。你得先明白这个系统由哪几块拼起来否则后面报错你根本不知道去哪查。2.1 3DGS在做什么用一堆椭圆高斯片拼出可任意角度观看的场景3DGS的全称是3D Gaussian Splatting中文常叫“3D高斯泼溅”或“3D高斯溅射”。它的核心思想很直白把三维场景显式地表示成很多个带体积的“小椭圆球”每个球就是单个三维高斯分布。为什么用高斯因为高斯函数数学性质好方便投影到二维图像也方便求梯度。每个高斯球携带的参数有三维位置均值 μ、协方差矩阵 Σ决定形状和朝向、不透明度 α、以及颜色。颜色不是简单的RGB而是一组球谐SH系数用来表达视角相关的颜色变化。渲染时把场景中所有高斯球按深度排序从近到远地往像素上“泼”颜色再用不透明度做加权混合。这个过程是可微的所以我们可以从输入照片出发计算渲染图和真实照片的差异反向传播梯度不断调整每个高斯球的位置、形状、颜色和透明度。训练到后期这些高斯球会从初始的稀疏点云逐渐分裂、克隆、移动最终覆盖整个可见表面。对比NeRFNeRF把场景存在神经网络权重里渲染要沿光线采样很多点。3DGS把场景存在一堆显式参数里渲染时直接对高斯做光栅化速度能到实时。代价是显存占用高、内存里要存放每个高斯球的完整协方差矩阵。理解这一点很重要因为后面所有参数调整都围绕这些高斯球的属性展开。2.2 复现3DGS的最小软件栈PyTorch、CUDA、COLMAP与显卡驱动的版本匹配复现3DGS的环境配置我总结成一句话不要追求最新版本要追求“被最多人验证过”的版本。首先系统推荐Ubuntu 20.04或22.04。Windows也能跑但原版CUDA扩展在Windows上编译需要额外装Visual Studio且路径分割符容易出问题。我一般用WSL2来规避这个坑。然后创建conda环境conda create -n 3dgs python3.8 -y conda activate 3dgsPython 3.8是比较稳妥的版本太高可能导致一些旧依赖不兼容。接着安装PyTorch。原版仓库在PyTorch 1.13.x CUDA 11.8下验证得最多你可以选择安装对应版本pip install torch1.13.1cu118 torchvision0.14.1cu118 \ --extra-index-url https://download.pytorch.org/whl/cu118如果下载慢也可以换成国内镜像源。安装完成后用python -c import torch; print(torch.__version__, torch.version.cuda)确认版本。接着安装COLMAPsudo apt update sudo apt install colmap逻辑说明apt源里的COLMAP版本可能较旧但对于基本流程足够。如果apt里没有可以自己编译不过新手不建议编译浪费时间。旧版COLMAP的特征提取命令是新版feature_extractor加上--ImageReader选项差别不大。然后安装3DGS仓库的依赖pip install -r requirements.txt这个文件里大多是numpy、tqdm、opencv等常规库。如果requirements中没有固定opencv版本建议装一个能用的就行。最后编译CUDA扩展。在仓库根目录python setup.py install这里会编译gaussian_rasterizer等原生模块。编译时需要能看到CUDA的nvcc编译器。确认方法which nvcc nvcc --version如果找不到说明CUDA Toolkit没装全只装了驱动。这时需要去安装CUDA Toolkit建议11.8。为什么底层依赖是这些因为3DGS的提速来自自定义的CUDA光栅化器它不能纯靠PyTorch实现。COLMAP提供初始相机位姿和点云本质上是给优化一个起点。显卡驱动是硬件到软件的桥梁三者缺一不可。2.3 官方仓库拉下来先看什么文件结构与关键脚本拉下仓库后先看目录。我用tree命令列一下关键内容省略编译产物gaussian-splatting/ train.py render.py convert.py arguments/ scene/ gaussian_renderer/ ...train.py是整个流程的入口。它的工作流程是解析参数 - 读取场景数据 - 创建高斯模型 - 进入优化循环 - 定期保存PLY。render.py则是加载训练结果从指定视角渲染图片和计算指标。convert.py负责把一组照片变成3DGS可用的数据内部调用COLMAP并生成降采样图片。arguments/目录里是所有参数的默认值。比如ModelParams控制数据路径和分辨率OptimizationParams控制学习率、密度化阈值、迭代步数。新手想改参数应该先看这里而不是去改代码逻辑。scene/包含数据读取和场景管理代码。scene/dataset_readers.py负责读取COLMAP的sparse目录生成相机列表与初始点云。scene/gaussian_model.py定义了GaussianModel类管理所有高斯球参数以及密度化操作。gaussian_renderer/是核心渲染器前向传播和反向传播都是这里的CUDA代码。新手第一次不需要读源码但至少要能回答这三个问题数据从哪里来模型参数存在哪渲染器在哪这样报错时你能快速定位是数据读取问题、模型初始化问题还是CUDA内核问题。3. 用官方数据跑通最小复现流程从下载到第一个PLY先别做自己的数据集。下载一个已经含COLMAP位姿的数据能帮你把“训练”这条链和“SfM”那条链分开。否则一旦出问题你根本分不清是数据问题还是训练问题。3.1 下载与解压场景数据从nerf_synthetic到tandt_db官方仓库的README里提供了两个常用数据集入口。TandT DB是真实场景包括卡车、火车、花园等有152张到几千张不等的图片已经用COLMAP算好相机参数。NeRF Synthetic是8个合成物体图片分辨率高场景干净适合快速测试。下载后你会看到这样的目录以TandT的truck为例truck/ images/ # 原始图片 sparse/0/ # COLMAP稀疏重建结果 images_2/ # 降采样到1/2 images_4/ # 降采样到1/4 images_8/ # 降采样到1/8如果你下的是“原始”版本可能没有images_2这些目录。3DGS训练默认会读images_4只要这个目录存在所以需要先用convert.py生成。为什么官方数据要降采样因为原始照片可能3000x4000直接喂给训练器不仅显存爆炸训练速度也会奇慢。而降采样后的图像仍保留足够细节用于重建。3.2 训练前的数据转换COLMAP跑出相机位姿与稀疏点云如果你拿到的数据已经包含sparse/0可以直接跳过COLMAP。但自己制作数据集时你需要跑。先手动跑一遍知道每一步在干什么再批量处理。# 特征提取 colmap feature_extractor \ --database_path data/truck/database.db \ --image_path data/truck/images \ --ImageReader.single_camera 1 # 特征匹配 colmap exhaustive_matcher \ --database_path data/truck/database.db # 稀疏重建 colmap mapper \ --database_path data/truck/database.db \ --image_path data/truck/images \ --output_path data/truck/sparse逻辑说明feature_extractor从每张图提取SIFT关键点并写入database.db。single_camera 1告诉COLMAP所有图来自同一相机能提高稳定性和速度。exhaustive_matcher对所有图两两匹配图多时耗时极长。mapper是重建主体输出相机参数和稀疏点云。参数说明打完命令后data/truck/sparse下会生成一个或多个子目录0、1...。3DGS只需要质量最好的那个子目录。通常0就是第一个重建结果但如果有多个可以用COLMAP GUI查看注册率把0复制出来用。3.3 最小训练命令与输出目录3D高斯模型文件长什么样数据就绪后训练命令python train.py \ -s data/truck \ -m output/truck \ --iterations 30000逻辑说明这条命令会读取data/truck/sparse/0的相机参数和稀疏点云用稀疏点云初始化3D高斯集合然后迭代30000次优化每个高斯的中心位置、协方差矩阵、颜色球谐系数和透明度。每1000步会保存一个PLY文件最后一次迭代会生成point_cloud.ply。参数说明-s指定数据根目录-m指定输出目录--iterations是总迭代次数。默认30000次用一张RTX 4090级别显卡对真实场景大概需要20-40分钟。新手可以先加--iterations 10000快速验证流程跑通效果差点没关系后面再拉满。输出目录里最重要的文件point_cloud.ply。这是最终的高斯模型。你可以用它继续渲染也可以用于其他工具。注意这个PLY不是普通点云每个顶点包含多个附加属性所以体积比同等点云大不少。4. 制作自己的3DGS数据集从视频到可训练场景的完整管线官方数据只能帮你验证代码真正让3DGS发挥价值的是自己的数据。热词提到的“3dgs自己制作数据集”是新手复现时最常卡住的地方。这一章我把完整管线讲清楚。4.1 拍摄与预处理视频抽帧、分辨率与帧率的选择自己拍数据最核心的原则相机运动平滑缓慢场景无动态物体。拍摄时不要边走边拍最好用稳定器或固定机位旋转云台。快门速度要快避免运动模糊。对焦锁定到场景中间不要自动对焦。曝光也尽量固定防止照片之间亮度跳变。视频格式建议4K 30fps然后抽帧。抽帧命令ffmpeg -i video.mp4 -vf fps8,scale1600:-1 -qscale:v 1 images/%04d.jpg逻辑说明fps8表示每秒抽8帧。scale1600:-1表示宽度缩放到1600高度按比例。4K视频通常4000多像素宽缩到1600能显著加快COLMAP和训练同时保留足够纹理。如果场景非常简单比如一个物体可以缩到1200。如果场景很大比如一个房间建议保留1600以上。参数说明-qscale:v 1保证输出画质接近无损。抽帧数量控制在200-500张之间。太少则位姿解算不稳太多则匹配时间剧增。如果拍摄一圈只需20秒fps8得160帧比较合适。4.2 用COLMAP自己制作数据集特征提取、匹配、稀疏重建自己数据的COLMAP流程与官方数据类似但有几个注意点colmap feature_extractor \ --database_path dataset/database.db \ --image_path dataset/images \ --ImageReader.single_camera 1 \ --SiftExtraction.max_num_features 16384 \ --SiftExtraction.gpu_index 0 colmap sequential_matcher \ --database_path dataset/database.db \ --SequentialMatching.overlap 15 colmap mapper \ --database_path dataset/database.db \ --image_path dataset/images \ --output_path dataset/sparse逻辑说明sequential_matcher按顺序匹配相邻帧overlap 15表示每帧与前后15帧匹配。这比exhaustive快得多适合视频抽帧数据。max_num_features 16384提高特征上限在纹理丰富的场景能提取更多特征点。参数说明mapper如果失败常见原因是图片序列中断。可以尝试增加overlap到20或者改用exhaustive_matcher试试。另外注意COLMAP的日志在控制台输出里会看到“Registered X / Y images”。如果注册比例低于80%说明数据质量不行需要回头调整拍摄或抽帧。4.3 自定义数据集的目录结构images、sparse与相机参数对齐COLMAP跑完后你应该有dataset/sparse/0。3DGS需要的目录结构如下dataset/ images/ # 原始图片 sparse/0/ # COLMAP输出训练前最好运行官方convert.py来生成降采样版本python convert.py -s dataset逻辑说明convert.py会再做一次COLMAP如果sparse/0不存在并生成images_2、images_4、images_8。如果已经有sparse/0它也会直接使用已有结果。参数说明如果convert.py跑完以后images_4目录生成的时间比images目录晚说明一切正常。接下来就可以训练python train.py -s dataset -m output/my_scene如果训练出来的模型空白多半是相机参数尺度问题。可以用Python快速看一下points3D.bin的坐标范围但新手可以直接看COLMAP GUI里的场景大小。只要数值不是特别夸张基本没问题。5. 3DGS复现避坑指南新手最容易翻车的5个细节这一章写我在复现3DGS全流程中真正踩过的坑每一条都按“现象 → 原因 → 解决”来写。读完这一章你踩坑的概率能降低一半。5.1 显存不足OOM不是只能换显卡现象训练刚开始几百步就报CUDA out of memory或者运行到一半崩掉。原因3DGS在优化过程中会动态增加高斯数量迭代次数越多显存占用越大。默认参数下30000步之后场景中可能有几十万到上百万个高斯。如果你的显卡显存只有8GB默认参数很可能顶不住。解决首要方案不是换显卡而是降低输入图片分辨率。3DGS默认会读取images_4级别的图片如果你的数据集只有images可以用convert.py生成降采样图。其次减少迭代中途的保存频率因为每1000步保存PLY也会瞬间拉高内存。还可以调OptimizationParams里的densification_interval和densify_grad_threshold不过新手不建议乱动。最省事的是训练时加--iterations 10000先跑通再考虑全量。提示如果是8GB显存建议先用--iterations 10000跑通再尝试全量训练。8GB跑小场景比如一个桌子上的物件是够的。5.2 黑屏、白屏、彩色条纹激活函数与数值范围现象训练出来的模型渲染后要么全黑、要么全白要么出现大面积闪光噪点。原因最常见的是相机位姿尺度错乱。3DGS内部对世界坐标的尺度很敏感。如果COLMAP输出的稀疏点云数值单位不对比如毫米 vs 米优化时高斯位置更新会飞掉。另一个原因是学习率太大导致协方差矩阵数值变成NaN。解决检查COLMAP输出的points3D.bin的坐标范围。用COLMAP软件打开sparse/0看点云坐标是否都在合理范围比如几个单位到几十个单位。如果数值是几百上千说明尺度有问题常见做法是在COLMAP重建后用colmap model_converter对模型做相似变换或者干脆重新拍摄把拍摄距离控制均匀。彩色条纹则多半是球谐阶数过高训练数据太少导致的过拟合可以试着把--sh_degree从默认3降到2。5.3 训练中断CUDA版本和编译报错现象编译通过训练到几百步时突然报错forward_flex、flex.grad或assert失败。原因原版3DGS代码中的CUDA扩展是针对特定PyTorch版本编译的。如果你换了PyTorch版本或gcc版本过新编译出来的gaussian_rasterizer扩展在反向传播时可能触发未定义行为。这类错误最玄学因为不是必然发生跟数据量和随机种子都有关。解决最稳妥的方式是用官方README推荐的PyTorch版本创建独立conda环境后重装。装完后手动编译扩展时盯着输出看到undefined symbol或relocation字样就说明编译器不兼容。另外卸载PyTorch后要清理缓存rm -rf ~/.cache/torch否则旧扩展可能残留。5.4 重建质量差点云稀疏与场景空洞现象COLMAP完成后sparse/0里注册的图片只有一小半点云很稀疏训练结果空洞。原因图片清晰度不够、重叠度低或者拍摄时焦距变化比如自动对焦拉风箱。COLMAP对模糊图像的特征点会直接忽略。解决拍摄时固定对焦和曝光手动设置快门时间。把抽帧间隔调小保证相邻帧重叠度在70%以上。如果还是注册少尝试在COLMAP特征提取时提高--SiftExtraction.max_num_features到16384或者降低匹配的置信度阈值。另一个经验是删掉画面中大片天空或纯色墙壁的部分只保留纹理丰富的区域。5.5 训练时间异常高斯数量失控与加速技巧现象同样的场景别人半小时跑完你要两小时。原因主要是高斯数量膨胀太快。优化过程中每100步会统计梯度高于阈值的区域会被克隆和分裂数量可能会涨到几百万。解决不要一开始就盲目砍迭代次数。常见做法是先用默认参数跑3000步观察point_cloud.ply大小增长曲线。如果增长过猛可以调--densify_until_iter例如从默认的15000步降到10000步减少后期的高斯增长。也可以用--position_lr_max_steps控制位置学习率衰减周期周期短收敛快。当然最粗暴有效的是换更好的显卡或者用更小的图片分辨率。6. 把模型“用”起来验证、渲染与导出的小技巧训练完不代表结束新手最容易忽视的是如何快速验证模型质量以及如何把PLY变成能给别人看的东西。6.1 训练完成后先验证render.py和指标文件先用官方提供的render.py做一次离线渲染python render.py -m output/mydata逻辑说明它会加载output/mydata下的模型配置和训练好的PLY从数据集里预留的测试视角渲染图片并把结果写到output/mydata/test目录。同时会把每个视角的PSNR、SSIM等指标汇总到results.json。注意这里的测试视角是数据集中被分出来的一部分不是COLMAP重建用的全部图像。参数说明-m指定输出目录即可无需再传-s因为配置写在cfg_args里。如果你训练时没设置--test_iterations这里可能没有可用测试集需要回训练命令里加上。6.2 把PLY转成普通点云写个十几行脚本如果只想快速看一眼模型形状可以用Python脚本读取PLY的坐标和颜色字段import open3d as o3d # 读取3DGS的PLYopen3d会忽略多余属性 pcd o3d.io.read_point_cloud(output/mydata/point_cloud.ply) # 保存为普通ply方便MeshLab打开 o3d.io.write_point_cloud(output/mydata/cloud_vis.ply, pcd)逻辑说明open3d读取PLY时只保留x、y、z和RGB其余高斯属性会被丢弃所以这个脚本只用于快速目检不能用于继续训练。想保留完整数据还是用原仓库的PLY。参数说明如果PLY文件很大超过几十MB建议先用pcd.voxel_down_sample(voxel_size0.01)降采样否则MeshLab打开会卡死。最后我自己的习惯是每次复现都在项目根目录记一个run_history.md把训练命令、显卡型号、数据集、踩坑现象写下来。3DGS的很多问题不是稳定复现的而是随机翻车没有记录很难定位是环境还是数据的问题。这个习惯帮我省了很多后悔药时间。希望帮到你。本文还有配套的精品资源点击获取