简介面向新手小白的3D高斯3DGS复现全流程实战记录以Linux/Ubuntu 20.04.3 LTS为背景围绕NVIDIA GeForce RTX 3080 Ti显卡、CUDA 11.8与PyTorch环境完整记录从零开始跑通gaussian-splatting项目的全过程。文档从环境配置与版本确认入手覆盖虚拟环境创建、两个子模块安装、colmap编译与安装、显卡驱动更新及图形界面切换等关键环节并针对新手高频报错逐一给出排查思路如MP4视频无法播放、PNG文件读入失败、驱动更新后黑屏、colmap报undefined reference to TIFFReadRGBAImage、cudart64_12.dll缺失、点云PLY可视化失败等均提供具体解决方向。资源共1个doc文档大小约96.32MB内容以步骤记录、命令示例和排错截图为主适合首次接触三维重建或3DGS复现但缺乏经验的学习者参照操作。目前已有5056人学习/下载按文档顺序执行可显著减少环境搭建与编译安装阶段的试错时间快速跑通完整复现流程。1. 新手复现3D高斯与3DGS之前先想清楚它到底在做什么第一次复现3DGS3D Gaussian Splatting3D高斯场景表示方法时大多数人以为最难的是训练模型实际翻车几乎全在环境编译和数据准备这两步。所谓“复现全流程”就是拿一组自己拍摄的图片让程序重建出一个可以从任意视角实时渲染的3D场景最终得到可旋转查看、可导出点云的高斯模型。这个方向很适合刚接触神经渲染和3D重建的开发者一张8GB显存的普通显卡就能跑通但它对工具链版本、目录结构和相机位姿校验的依赖非常强。下面按“原理→环境→数据→训练→排查→进阶”的顺序把第一次能完整走通的路写出来。2. 从原理到选型3DGS为什么值得你花一个周末复现2.1 3DGS 复现的核心思想场景是一组会“油漆”像素的高斯3D Gaussian Splatting 把整个场景表示成一大团3D高斯函数每个高斯可以理解成一个有位置、有形状、有颜色、有透明度的“软糖球”。渲染时相机把视野里所有的高斯按从近到远的顺序“溅射”到成像平面上用alpha合成的方式叠加颜色最终得到一张完整图像。因为这一步是纯光栅化操作不需要像NeRF那样沿射线大量采样所以单帧渲染速度能快到实时。每个高斯的可学习参数包括中心坐标xyz、协方差用旋转矩阵和缩放向量表示决定这个高斯的形状和朝向、颜色基色加上球谐系数用来表达视角变化带来的颜色差异、以及不透明度。训练时把渲染图与真实照片做像素级对比梯度会反传到以上所有参数上让每个高斯一点点挪位置、改形状、调颜色。训练过程中还有一个非常重要的机制叫“自适应密度控制”在欠重建的区域自动克隆高斯在过重建的区域自动分裂高斯同时定期剔除不透明度接近0的“空壳”高斯。这解释了为什么最终的模型点数不是一个固定值而是训练过程中动态增长的。复现时理解这个机制就够了不需要自己改实现。初始化的第一代高斯并不是随机生成的而是由COLMAP稀疏重建产生的点云作为种子。这也是新手复现时最容易忽略的因果关系COLMAP跑得好不好直接决定训练起点和最终效果后面专门说。2.2 为什么首选的复现对象是它而不是 NeRF对新手来说第一次复现一个渲染类项目3DGS 的综合体验比 NeRF 友好太多。NeRF 的体渲染需要对每条光线采样几十上百个点训练一个场景在单卡上动辄几小时起步而且推理也要逐像素走前向做交互预览很吃力。3DGS 的splatting本质上是对每个高斯做一次投影再加透明度合成官方实现单场景训练十几分钟就能出不错的结果实时查看器可以流畅旋转视角。从工程复现角度看3DGS 的代码结构也相对清楚核心训练逻辑集中在几个文件里两个CUDA扩展负责光栅化数据的输入输出格式明确。NeRF 类项目模型变体多、参数杂跑通一个 baseline 不难但搞清楚为什么有效要花更多时间。下面用一个表把两者在复现角度最关心的差异列出来。对比维度NeRF 类方法3D Gaussian Splatting场景表示隐式神经场显式可微高斯集合渲染方式体渲染积分沿光线采样光栅化splatting逐高斯投影单帧渲染速度慢通常需要多次前向快可实时交互训练速度相对较慢相对快适合反复验证可导出内容网格需要额外提取直接导出ply点云转网格相对直观新手门槛概念简单但调试反馈慢概念要一点功夫调试反馈直接结论很明确如果你只有一块主流游戏显卡想在有限时间得到“能看到、能旋转、能导出点云”的成果3DGS 是更稳的选择。2.3 动眼前先盘清楚的三件事显存、CUDA 与预期产出第一显存决定了你能玩多大场景。8GB 显存跑官方仓库默认参数是可以的但图像分辨率最好限制在 1600 左右场景图片数量控制在 100 到 200 张16GB 会从容很多。只有 4GB 的卡训练大场景基本会炸要么降分辨率要么换 GPU这是最现实的一道门槛。第二版本对齐是复现的地基。你需要知道的不多显卡驱动的版本、CUDA runtime 的版本、PyTorch 预编译包对应的 CUDA 版本以及 C 编译器版本。四者只要有一个对不上编译扩展的时候就报错。更具体的检测命令下一章直接给。第三想清楚自己复现成功的标准是什么。不是模型文件生成出来就算成功而是要在实时查看器里能看到一个成型的场景并且能导出一份 point_cloud.ply。对着这个标准你才知道训练日志里的指标到底意味着什么。接下来直接进入第一道坎环境搭建。3. 环境搭建与扩展编译第一次跑通 train.py 的最短路径3.1 检查显卡驱动、CUDA 与 Python让版本先对齐环境问题的根源在于三个版本要互相匹配显卡驱动支持的最高 CUDA 版本、本机安装的 CUDA Toolkit 版本、PyTorch 编译链接的 CUDA 版本。新手常犯的误会是“我装了 PyTorch 的 cu118 版本是不是就不用管 CUDA 了” 运行 PyTorch 模型确实可以不管但编译扩展时需要 nvcc 编译器它来自 CUDA Toolkit。所以最省心的做法是直接把本机 CUDA Toolkit 装好。先按下面命令把现状摸清楚# 查看显卡型号、驱动版本、驱动支持的最高CUDA版本 nvidia-smi # 查看当前命令行能调用的CUDA编译器版本 nvcc --version # 查看Python版本 python --version # 创建独立环境避免把系统Python环境搞乱 conda create -n gaussian python3.10 -y conda activate gaussian # 安装与CUDA对应的PyTorch示例是CUDA 11.8对应版本 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118命令逻辑说明nvidia-smi 里的 “CUDA Version” 是驱动支持的上限不代表本机已经装了对应运行时nvcc 才是你编译 CUDA 代码会用到的工具。PyTorch 的 cu118 后缀表示这个包是用 CUDA 11.8 编译的训练时驱动会用 JIT 方式加载它。编译扩展时系统得能找到 CUDA Toolkit 的 include 和 lib 路径所以建议把 CUDA Toolkit 安装版本和 PyTorch 的 CUDA 版本保持一致避免出现头文件版本冲突。参数说明Python 版本建议选 3.10太高或太低都可能遇到某些依赖没有预编译包torch 版本要结合驱动支持的最高 CUDA 来选择驱动较老就选 cu118驱动较新可以选 cu121 甚至 cu124。安装完用python -c import torch; print(torch.__version__, torch.cuda.is_available())验证一下输出 True 再继续。3.2 创建环境、克隆仓库并安装依赖环境准备好之后接下来把官方仓库拉下来。仓库地址以官方实现为准不建议去拉各种二次修改版因为你不知道别人改了什么出了问题连对照文档都难。# 进入工作目录 cd ~/work # 克隆官方仓库 git clone 官方仓库地址 # 进入仓库目录 cd gaussian-splatting # 安装Python依赖 pip install -r requirements.txt逻辑说明requirements.txt 里主要包含 plyfile、tqdm、tensorboard 这些常用库以及训练过程中用来记录指标和写点云文件的工具。依赖安装一般不会报错如果某一步下载慢或者失败重复执行 pip install 即可不需要换什么神秘加速源。参数说明实际使用中requirements.txt 里如果固定了某个子模块版本请不要手动改动。后续编译的两个 CUDA 扩展不会装到 conda 环境里是正常现象它们是作为独立包安装Python 在运行时按名字导入。3.3 编译两个子模块diff-gaussian-rasterization 与 simple-knn这是整个复现流程里新手最头疼的一步。3DGS 的渲染核心是自定义的 CUDA 光栅化算子官方仓库把它放在 submodules 目录下需要现场编译成 Python 可调用的扩展。常见做法是仓库根目录下有两个 submodules 文件夹分别编译安装。# 编译并安装主要的光栅化CUDA算子 pip install submodules/diff-gaussian-rasterization # 编译并安装辅助的KNN工具用于训练时近邻查询 pip install submodules/simple-knn # 验证扩展是否导入成功 python -c import diff_gaussian_rasterization; print(rasterization ok)逻辑说明pip install 遇上含 CUDA 代码的目录会调用本机的 nvcc 和 C 编译器现场构建。编译成功时日志里能明显看到 “Building wheel” 和 “Successfully built” 字样。失败时最后几行日志会直接告诉你缺什么最常见的是 “CUDA_HOME not set” 或 “cuda_runtime.h not found”。参数说明如果本机装了多个 CUDA 版本建议在编译前显式指定 CUDA 路径例如在 Linux 下执行export CUDA_HOME/usr/local/cuda-11.8Windows 下确认环境变量 CUDA_PATH 指向目标版本。Linux 用户还需要保证 gcc 版本在 9 以上Windows 用户需要安装 Visual Studio 的“使用 C 的桌面开发”工作负载编译器版本太老会直接不认新版 CUDA 头文件。提示这一步如果失败不要反复用同一套环境重试。先把nvcc --version和 gcc/cmake 版本贴到报错搜索里或者问身边跑通过的人要一份环境对照。把版本对齐编译基本一次过。4. 数据准备与训练全流程COLMAP 稀疏重建到模型输出4.1 数据采集要点用手机也能出好看的重建训练3DGS的数据就是一组带重叠视角的照片。采集质量比数量重要。当你拿着手机绕着一个物体或场景转一圈拍摄时记住几个原则焦距固定不变不要中途缩放移动速度放慢避免运动模糊相邻两帧画面重叠度保持在70%以上尽量避开大面积纯色、镜面反射和玻璃光照不要剧烈变化。满足这些条件普通手机拍60到150张照片就足够跑通一个场景。如果你习惯录视频可以事后抽帧。下面是用 ffmpeg 抽帧的命令按需调整抽帧频率保证最终图片数在100张左右最合适。# 从30秒视频里按每秒2帧抽帧得到约60张图片 ffmpeg -i input.mp4 -vf fps2 -qscale:v 2 images/%04d.jpg逻辑说明fps2表示每秒抽取2帧%04d.jpg表示输出文件名按四位数字编号0001.jpg、0002.jpg。抽完帧后把明显模糊、光照突变、重复度过高的照片删掉这一步能帮你避开很多训练翻车问题。参数说明qscale:v 2是 JPEG 质量控制参数数值越小画质越高2 到 4 都够用。如果拍的是静态物体抽帧频率可以降低保证每一帧视角都有明显变化否则后续 COLMAP 的特征匹配会很尴尬。采集完成后把图片统一复制到一个干净的目录比如data/my_scene/input后续所有处理都围绕这个目录。4.2 用 COLMAP 生成相机参数与稀疏点云3DGS 的训练需要每个视角的相机内外参以及用于初始化高斯的稀疏点云这套东西由 COLMAP 提供。新手第一次跑建议直接用 COLMAP 的图形界面操作一遍看到每一步产出的中间结果比纯命令行有感觉。但命令行版本更适合脚本化复现下面给出标准流程。COLMAP 的整个流程分三步特征提取、特征匹配、稀疏重建。实际操作时可以用 COLMAP 的命令行工具也可以用官方仓库推荐的 convert.py 脚本统一处理。常见做法是图片放进data/input然后跑命令重建最后运行仓库里的 convert.py 做畸变校正和目录整理。# 进入场景目录 cd data/my_scene # 特征提取为每张图片提取关键点 colmap feature_extractor \ --database_path database.db \ --image_path input \ --ImageReader.single_camera 1 # 特征匹配找出图片之间的对应关系 colmap exhaustive_matcher \ --database_path database.db # 稀疏重建估计相机位姿并生成点云 colmap mapper \ --database_path database.db \ --image_path input \ --output_path sparse # 完成畸变校正并把结果整理成官方仓库要求的目录结构常见做法 python convert.py -s .逻辑说明feature_extractor负责从每张图提取特征点single_camera 1表示所有图片都来自同一台相机可以共享同一套内参对手机拍摄场景非常关键如果漏掉这个参数每张图都会被当成不同相机重建极容易分裂。exhaustive_matcher对全图做两两匹配图片量大时很费内存但效果最稳。mapper做增量式稀疏重建生成 bin 格式的相机位姿和点云。convert.py做的事其实不止整理目录它会读取 mapper 的输出、做图像畸变校正最终生成data/images和data/sparse/0两个目录这是训练脚本默认读取的结构。如果你不用 convert.py就必须自己保证 images 目录下的图片和 sparse 目录里的相机参数一一对应新手很容易在这里踩坑。参数说明图片数量较多时可以把exhaustive_matcher换成sequential_matcher它对相邻帧做匹配速度快很多但前提是你的照片是按拍摄顺序命名的。手机绕场拍摄时推荐 sequential扫描场景时推荐 exhaustive。4.3 train.py 训练命令与关键参数数据准备好后训练就是一条命令的事。官方仓库根目录下有训练脚本起步阶段直接用默认参数不要改优化器和学习率相关的东西。# 在仓库根目录下执行 python train.py \ -s data/my_scene \ -m output/my_scene \ --iterations 30000 \ --test_iterations 1000 3000 7000 \ --save_iterations 10000 30000逻辑说明-s指定场景数据根目录必须包含images和sparse/0-m指定实验输出目录训练好的模型和中间结果都会写在这里。--iterations是总迭代次数官方默认值 30000 对大多数场景都够。--test_iterations表示在这些迭代节点上跑一次测试集评估输出 PSNR 等指标--save_iterations表示在这些节点保存检查点文件方便中途恢复或加载不同阶段的模型。参数说明如果显存吃紧给train.py加-r 0.5这会按一半分辨率加载图像显存占用能降到原先的四分之一左右适合显卡只有 8GB 的情况。另外--sh_degree默认是 3表示球谐阶数最高到 3 阶初学者不用动它只有想压缩模型大小时才会考虑调低。第一次训练时建议开一台电脑刷着日志。日志里最值得看的信息是每一轮迭代输出的 PSNR、当前高斯点数量、当前显存占用。如果 PSNR 在前 1000 次迭代里没有上涨的迹象说明数据准备有问题而不是模型问题。4.4 训练输出与结果验证训练结束后output/my_scene目录下会有不少文件。新手要学会一眼认出哪些真正有用不要被中间文件吓到。下面列的是最常见的几类文件。文件或目录内容用途test/测试视角渲染结果与真实图对比快速看重建质量train/训练视角渲染结果确认训练是否收敛visual/可视化辅助图帮助定位欠重建区域point_cloud/iteration_30000/point_cloud.ply最终的高斯点云可导入其他工具或二次处理chkpnt30000.pth检查点文件可从中断处继续训练ckpt_30000.pth模型权重加载后做渲染或微调验证训练效果最直接的方式是打开test目录对比真实照片和渲染图的差异。如果两者在纹理和轮廓上非常接近基本就算复现成功。初次跑通不要追求指标超过别人先确认全流程没有断点。官方仓库还有一个实时查看器在仓库的 SIBR_viewers 目录下编译需要额外依赖。第一次复现不要求把查看器编出来先看静态图跑通主流程后再回来折腾查看器。查看器能流畅旋转视角时你才算真正体验到 3DGS 的实时渲染能力。5. 复现路上的常见问题与排查让训练稳定出图的5个修复方向5.1 扩展编译报错找不到 cuda_runtime.h 或 nvcc现象执行pip install submodules/diff-gaussian-rasterization时日志抛出一大段fatal error: cuda_runtime.h: No such file or directory或者干脆提示nvcc not found。原因CUDA Toolkit 没有安装或者安装了但命令行当前环境找不到。pip 编译时不会自动去扫描显卡驱动目录它依赖常规的CUDA_HOME环境变量。解决先执行nvcc --version如果提示没有这个命令就安装和 PyTorch 版本匹配的 CUDA Toolkit。Linux 下安装后把/usr/local/cuda/bin加进 PATHWindows 下确认环境变量CUDA_PATH存在。改完环境变量后记得重新打开终端再重新执行编译。还有一个很容易忽略的坑如果同时装了多个 CUDA 版本pip 可能选错建议安装前显式export CUDA_HOME/usr/local/cuda-11.8指定一次。5.2 训练启动后背景发黑模型只长出一小团东西现象训练日志正常刷新但渲染出来的图几乎全黑只有正中间有一小团模糊色块。查看器里场景完全不成型。原因绝大多数情况下是 COLMAP 稀疏重建失败导致相机位姿错乱或者点云太稀疏。初始化时高斯数量严重不足后面的密度控制再怎么补偿也补不回来。还有一种可能是 convert.py 输出目录里sparse/0下的点云文件点数极少这说明特征匹配环节就出了问题。解决回查 COLMAP 的中间产物。最简单的方法是直接看input图片如果图像之间重叠度不够或者大量图片几乎是同一视角特征匹配自然失效。重新采集数据保证绕场时有明显的视角推进。也可以用 COLMAP 图形界面重新跑一遍观察右下角点云重建进度。确认稀疏点云有几百几千个点再进训练。5.3 显存溢出训练到一半被系统杀掉现象训练刚开始还能跑几百次迭代后终端提示CUDA out of memory或者直接进程消失操作系统杀掉了进程。原因图像分辨率太高或场景图片数量太多。默认加载原图分辨率一张 4000x3000 的照片在训练时非常占显存同时梯度还要保留多个版本的高斯参数。解决给训练命令加-r 0.5把图片降到一半分辨率显存占用会大幅下降。如果还是不够降到-r 0.25也是可以的只是最终纹理精度会下降。另外检查是否同时开了多个训练任务或别的 GPU 程序。第一次复现尽量选一个几十张图片的小场景把流程跑通再上高分辨率。5.4 COLMAP 生成不了模型特征点数量极少现象COLMAP 的mapper阶段报了No good image pairs found或者生成的点云只有几十个点。原因图片质量或内容的问题。拍摄时运动过快产生模糊、画面全是天空或白墙、室内场景光照太暗都会导致特征提取失败。还有一个隐蔽原因图片分辨率太高时 COLMAP 默认降采样特征点本身也受影响。解决回到数据侧。把明显模糊的照片删掉用手机拍摄时尽量等对焦完成再移动场景里加上一些有纹理的物体或海报给特征匹配提供锚点。如果照片是用视频抽帧得到的试试把抽帧间隔拉大保证相邻帧视角差异明显。COLMAP 对“视角连续但变化很小”的图像很敏感重叠度太高反而匹配不出有效约束。5.5 加载检查点后推图得到全白或乱码现象训练完成后用加载模型渲染视频或导出点时结果是一片纯色或花屏。原因最常见的是训练参数和加载参数不一致。比如训练时用了--sh_degree 3但加载时脚本里写死了其他阶数或者直接加载了不同数据集训练出来的检查点相机内参完全对不上。解决加载模型时保持训练时用的--sh_degree、分辨率等参数一致。如果检查点来自某一次中途中断的训练还要确认它和当前场景数据目录是同一条数据链。做渲染验证时尽量用官方仓库自带的渲染脚本自己写加载逻辑容易漏掉归一化细节。注意遇到报错不要先怀疑代码先怀疑数据和环境版本。血泪经验是这个项目的报错信息往往不是真正的原因日志往上翻几行通常能看到更早暴露的警告。6. 进阶把复现结果用起来才算真正跑通了全流程训练跑通只是开始下一步是把模型当成一个可用的场景资产。最直观的验证方式是用实时查看器打开训练产物如果仓库自带的查看器在你的机器上能编译出来就编译一次。它会让你迅速理解“可微高斯集合”和“实时渲染”之间的对应关系原来每个高斯的颜色和位置就是屏幕上那些彩色光斑的真身。如果查看器编译太费劲还有一个更轻量的验证技巧写一段脚本加载训练好的point_cloud.ply在点云播放器里浏览。虽然看不到高质量渲染效果但能确认场景结构是完整的。进阶玩法是走一遍自动旋转视角渲染把模型从多个方位渲染成视频用这个视频快速判断哪些区域重建得干净、哪些区域有漂浮物这样不用等查看器就能完成质量评估。调参方面我不建议一上手就乱调学习率。值得先调的是两个地方--densify_grad_threshold控制密度控制触发的敏感度场景细节不够时把阈值从 0.0002 调到 0.00005能让模型长出更多高斯--sparse_density控制初始化时给每个点周围撒的高斯数量默认 0.01 偏低如果想加快收敛可以调大。每次只改一个变量记录 PSNR 和显存变化不要一次改好几个。另外一个很实用的习惯把复现环境的版本信息和训练命令存成run_config.txt。下次隔几天再跑环境变量可能已经变了至少能查到当初是什么组合跑通的。3DGS 的坑大多是环境问题模型本身其实很皮实。我自己的习惯是每次跑新场景前先看一眼之前存的环境记录不急着重新编译扩展。希望帮到你。本文还有配套的精品资源点击获取
简介面向新手小白的3D高斯3DGS复现全流程实战记录以Linux/Ubuntu 20.04.3 LTS为背景围绕NVIDIA GeForce RTX 3080 Ti显卡、CUDA 11.8与PyTorch环境完整记录从零开始跑通gaussian-splatting项目的全过程。文档从环境配置与版本确认入手覆盖虚拟环境创建、两个子模块安装、colmap编译与安装、显卡驱动更新及图形界面切换等关键环节并针对新手高频报错逐一给出排查思路如MP4视频无法播放、PNG文件读入失败、驱动更新后黑屏、colmap报undefined reference to TIFFReadRGBAImage、cudart64_12.dll缺失、点云PLY可视化失败等均提供具体解决方向。资源共1个doc文档大小约96.32MB内容以步骤记录、命令示例和排错截图为主适合首次接触三维重建或3DGS复现但缺乏经验的学习者参照操作。目前已有5056人学习/下载按文档顺序执行可显著减少环境搭建与编译安装阶段的试错时间快速跑通完整复现流程。1. 新手复现3D高斯与3DGS之前先想清楚它到底在做什么第一次复现3DGS3D Gaussian Splatting3D高斯场景表示方法时大多数人以为最难的是训练模型实际翻车几乎全在环境编译和数据准备这两步。所谓“复现全流程”就是拿一组自己拍摄的图片让程序重建出一个可以从任意视角实时渲染的3D场景最终得到可旋转查看、可导出点云的高斯模型。这个方向很适合刚接触神经渲染和3D重建的开发者一张8GB显存的普通显卡就能跑通但它对工具链版本、目录结构和相机位姿校验的依赖非常强。下面按“原理→环境→数据→训练→排查→进阶”的顺序把第一次能完整走通的路写出来。2. 从原理到选型3DGS为什么值得你花一个周末复现2.1 3DGS 复现的核心思想场景是一组会“油漆”像素的高斯3D Gaussian Splatting 把整个场景表示成一大团3D高斯函数每个高斯可以理解成一个有位置、有形状、有颜色、有透明度的“软糖球”。渲染时相机把视野里所有的高斯按从近到远的顺序“溅射”到成像平面上用alpha合成的方式叠加颜色最终得到一张完整图像。因为这一步是纯光栅化操作不需要像NeRF那样沿射线大量采样所以单帧渲染速度能快到实时。每个高斯的可学习参数包括中心坐标xyz、协方差用旋转矩阵和缩放向量表示决定这个高斯的形状和朝向、颜色基色加上球谐系数用来表达视角变化带来的颜色差异、以及不透明度。训练时把渲染图与真实照片做像素级对比梯度会反传到以上所有参数上让每个高斯一点点挪位置、改形状、调颜色。训练过程中还有一个非常重要的机制叫“自适应密度控制”在欠重建的区域自动克隆高斯在过重建的区域自动分裂高斯同时定期剔除不透明度接近0的“空壳”高斯。这解释了为什么最终的模型点数不是一个固定值而是训练过程中动态增长的。复现时理解这个机制就够了不需要自己改实现。初始化的第一代高斯并不是随机生成的而是由COLMAP稀疏重建产生的点云作为种子。这也是新手复现时最容易忽略的因果关系COLMAP跑得好不好直接决定训练起点和最终效果后面专门说。2.2 为什么首选的复现对象是它而不是 NeRF对新手来说第一次复现一个渲染类项目3DGS 的综合体验比 NeRF 友好太多。NeRF 的体渲染需要对每条光线采样几十上百个点训练一个场景在单卡上动辄几小时起步而且推理也要逐像素走前向做交互预览很吃力。3DGS 的splatting本质上是对每个高斯做一次投影再加透明度合成官方实现单场景训练十几分钟就能出不错的结果实时查看器可以流畅旋转视角。从工程复现角度看3DGS 的代码结构也相对清楚核心训练逻辑集中在几个文件里两个CUDA扩展负责光栅化数据的输入输出格式明确。NeRF 类项目模型变体多、参数杂跑通一个 baseline 不难但搞清楚为什么有效要花更多时间。下面用一个表把两者在复现角度最关心的差异列出来。对比维度NeRF 类方法3D Gaussian Splatting场景表示隐式神经场显式可微高斯集合渲染方式体渲染积分沿光线采样光栅化splatting逐高斯投影单帧渲染速度慢通常需要多次前向快可实时交互训练速度相对较慢相对快适合反复验证可导出内容网格需要额外提取直接导出ply点云转网格相对直观新手门槛概念简单但调试反馈慢概念要一点功夫调试反馈直接结论很明确如果你只有一块主流游戏显卡想在有限时间得到“能看到、能旋转、能导出点云”的成果3DGS 是更稳的选择。2.3 动眼前先盘清楚的三件事显存、CUDA 与预期产出第一显存决定了你能玩多大场景。8GB 显存跑官方仓库默认参数是可以的但图像分辨率最好限制在 1600 左右场景图片数量控制在 100 到 200 张16GB 会从容很多。只有 4GB 的卡训练大场景基本会炸要么降分辨率要么换 GPU这是最现实的一道门槛。第二版本对齐是复现的地基。你需要知道的不多显卡驱动的版本、CUDA runtime 的版本、PyTorch 预编译包对应的 CUDA 版本以及 C 编译器版本。四者只要有一个对不上编译扩展的时候就报错。更具体的检测命令下一章直接给。第三想清楚自己复现成功的标准是什么。不是模型文件生成出来就算成功而是要在实时查看器里能看到一个成型的场景并且能导出一份 point_cloud.ply。对着这个标准你才知道训练日志里的指标到底意味着什么。接下来直接进入第一道坎环境搭建。3. 环境搭建与扩展编译第一次跑通 train.py 的最短路径3.1 检查显卡驱动、CUDA 与 Python让版本先对齐环境问题的根源在于三个版本要互相匹配显卡驱动支持的最高 CUDA 版本、本机安装的 CUDA Toolkit 版本、PyTorch 编译链接的 CUDA 版本。新手常犯的误会是“我装了 PyTorch 的 cu118 版本是不是就不用管 CUDA 了” 运行 PyTorch 模型确实可以不管但编译扩展时需要 nvcc 编译器它来自 CUDA Toolkit。所以最省心的做法是直接把本机 CUDA Toolkit 装好。先按下面命令把现状摸清楚# 查看显卡型号、驱动版本、驱动支持的最高CUDA版本 nvidia-smi # 查看当前命令行能调用的CUDA编译器版本 nvcc --version # 查看Python版本 python --version # 创建独立环境避免把系统Python环境搞乱 conda create -n gaussian python3.10 -y conda activate gaussian # 安装与CUDA对应的PyTorch示例是CUDA 11.8对应版本 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118命令逻辑说明nvidia-smi 里的 “CUDA Version” 是驱动支持的上限不代表本机已经装了对应运行时nvcc 才是你编译 CUDA 代码会用到的工具。PyTorch 的 cu118 后缀表示这个包是用 CUDA 11.8 编译的训练时驱动会用 JIT 方式加载它。编译扩展时系统得能找到 CUDA Toolkit 的 include 和 lib 路径所以建议把 CUDA Toolkit 安装版本和 PyTorch 的 CUDA 版本保持一致避免出现头文件版本冲突。参数说明Python 版本建议选 3.10太高或太低都可能遇到某些依赖没有预编译包torch 版本要结合驱动支持的最高 CUDA 来选择驱动较老就选 cu118驱动较新可以选 cu121 甚至 cu124。安装完用python -c import torch; print(torch.__version__, torch.cuda.is_available())验证一下输出 True 再继续。3.2 创建环境、克隆仓库并安装依赖环境准备好之后接下来把官方仓库拉下来。仓库地址以官方实现为准不建议去拉各种二次修改版因为你不知道别人改了什么出了问题连对照文档都难。# 进入工作目录 cd ~/work # 克隆官方仓库 git clone 官方仓库地址 # 进入仓库目录 cd gaussian-splatting # 安装Python依赖 pip install -r requirements.txt逻辑说明requirements.txt 里主要包含 plyfile、tqdm、tensorboard 这些常用库以及训练过程中用来记录指标和写点云文件的工具。依赖安装一般不会报错如果某一步下载慢或者失败重复执行 pip install 即可不需要换什么神秘加速源。参数说明实际使用中requirements.txt 里如果固定了某个子模块版本请不要手动改动。后续编译的两个 CUDA 扩展不会装到 conda 环境里是正常现象它们是作为独立包安装Python 在运行时按名字导入。3.3 编译两个子模块diff-gaussian-rasterization 与 simple-knn这是整个复现流程里新手最头疼的一步。3DGS 的渲染核心是自定义的 CUDA 光栅化算子官方仓库把它放在 submodules 目录下需要现场编译成 Python 可调用的扩展。常见做法是仓库根目录下有两个 submodules 文件夹分别编译安装。# 编译并安装主要的光栅化CUDA算子 pip install submodules/diff-gaussian-rasterization # 编译并安装辅助的KNN工具用于训练时近邻查询 pip install submodules/simple-knn # 验证扩展是否导入成功 python -c import diff_gaussian_rasterization; print(rasterization ok)逻辑说明pip install 遇上含 CUDA 代码的目录会调用本机的 nvcc 和 C 编译器现场构建。编译成功时日志里能明显看到 “Building wheel” 和 “Successfully built” 字样。失败时最后几行日志会直接告诉你缺什么最常见的是 “CUDA_HOME not set” 或 “cuda_runtime.h not found”。参数说明如果本机装了多个 CUDA 版本建议在编译前显式指定 CUDA 路径例如在 Linux 下执行export CUDA_HOME/usr/local/cuda-11.8Windows 下确认环境变量 CUDA_PATH 指向目标版本。Linux 用户还需要保证 gcc 版本在 9 以上Windows 用户需要安装 Visual Studio 的“使用 C 的桌面开发”工作负载编译器版本太老会直接不认新版 CUDA 头文件。提示这一步如果失败不要反复用同一套环境重试。先把nvcc --version和 gcc/cmake 版本贴到报错搜索里或者问身边跑通过的人要一份环境对照。把版本对齐编译基本一次过。4. 数据准备与训练全流程COLMAP 稀疏重建到模型输出4.1 数据采集要点用手机也能出好看的重建训练3DGS的数据就是一组带重叠视角的照片。采集质量比数量重要。当你拿着手机绕着一个物体或场景转一圈拍摄时记住几个原则焦距固定不变不要中途缩放移动速度放慢避免运动模糊相邻两帧画面重叠度保持在70%以上尽量避开大面积纯色、镜面反射和玻璃光照不要剧烈变化。满足这些条件普通手机拍60到150张照片就足够跑通一个场景。如果你习惯录视频可以事后抽帧。下面是用 ffmpeg 抽帧的命令按需调整抽帧频率保证最终图片数在100张左右最合适。# 从30秒视频里按每秒2帧抽帧得到约60张图片 ffmpeg -i input.mp4 -vf fps2 -qscale:v 2 images/%04d.jpg逻辑说明fps2表示每秒抽取2帧%04d.jpg表示输出文件名按四位数字编号0001.jpg、0002.jpg。抽完帧后把明显模糊、光照突变、重复度过高的照片删掉这一步能帮你避开很多训练翻车问题。参数说明qscale:v 2是 JPEG 质量控制参数数值越小画质越高2 到 4 都够用。如果拍的是静态物体抽帧频率可以降低保证每一帧视角都有明显变化否则后续 COLMAP 的特征匹配会很尴尬。采集完成后把图片统一复制到一个干净的目录比如data/my_scene/input后续所有处理都围绕这个目录。4.2 用 COLMAP 生成相机参数与稀疏点云3DGS 的训练需要每个视角的相机内外参以及用于初始化高斯的稀疏点云这套东西由 COLMAP 提供。新手第一次跑建议直接用 COLMAP 的图形界面操作一遍看到每一步产出的中间结果比纯命令行有感觉。但命令行版本更适合脚本化复现下面给出标准流程。COLMAP 的整个流程分三步特征提取、特征匹配、稀疏重建。实际操作时可以用 COLMAP 的命令行工具也可以用官方仓库推荐的 convert.py 脚本统一处理。常见做法是图片放进data/input然后跑命令重建最后运行仓库里的 convert.py 做畸变校正和目录整理。# 进入场景目录 cd data/my_scene # 特征提取为每张图片提取关键点 colmap feature_extractor \ --database_path database.db \ --image_path input \ --ImageReader.single_camera 1 # 特征匹配找出图片之间的对应关系 colmap exhaustive_matcher \ --database_path database.db # 稀疏重建估计相机位姿并生成点云 colmap mapper \ --database_path database.db \ --image_path input \ --output_path sparse # 完成畸变校正并把结果整理成官方仓库要求的目录结构常见做法 python convert.py -s .逻辑说明feature_extractor负责从每张图提取特征点single_camera 1表示所有图片都来自同一台相机可以共享同一套内参对手机拍摄场景非常关键如果漏掉这个参数每张图都会被当成不同相机重建极容易分裂。exhaustive_matcher对全图做两两匹配图片量大时很费内存但效果最稳。mapper做增量式稀疏重建生成 bin 格式的相机位姿和点云。convert.py做的事其实不止整理目录它会读取 mapper 的输出、做图像畸变校正最终生成data/images和data/sparse/0两个目录这是训练脚本默认读取的结构。如果你不用 convert.py就必须自己保证 images 目录下的图片和 sparse 目录里的相机参数一一对应新手很容易在这里踩坑。参数说明图片数量较多时可以把exhaustive_matcher换成sequential_matcher它对相邻帧做匹配速度快很多但前提是你的照片是按拍摄顺序命名的。手机绕场拍摄时推荐 sequential扫描场景时推荐 exhaustive。4.3 train.py 训练命令与关键参数数据准备好后训练就是一条命令的事。官方仓库根目录下有训练脚本起步阶段直接用默认参数不要改优化器和学习率相关的东西。# 在仓库根目录下执行 python train.py \ -s data/my_scene \ -m output/my_scene \ --iterations 30000 \ --test_iterations 1000 3000 7000 \ --save_iterations 10000 30000逻辑说明-s指定场景数据根目录必须包含images和sparse/0-m指定实验输出目录训练好的模型和中间结果都会写在这里。--iterations是总迭代次数官方默认值 30000 对大多数场景都够。--test_iterations表示在这些迭代节点上跑一次测试集评估输出 PSNR 等指标--save_iterations表示在这些节点保存检查点文件方便中途恢复或加载不同阶段的模型。参数说明如果显存吃紧给train.py加-r 0.5这会按一半分辨率加载图像显存占用能降到原先的四分之一左右适合显卡只有 8GB 的情况。另外--sh_degree默认是 3表示球谐阶数最高到 3 阶初学者不用动它只有想压缩模型大小时才会考虑调低。第一次训练时建议开一台电脑刷着日志。日志里最值得看的信息是每一轮迭代输出的 PSNR、当前高斯点数量、当前显存占用。如果 PSNR 在前 1000 次迭代里没有上涨的迹象说明数据准备有问题而不是模型问题。4.4 训练输出与结果验证训练结束后output/my_scene目录下会有不少文件。新手要学会一眼认出哪些真正有用不要被中间文件吓到。下面列的是最常见的几类文件。文件或目录内容用途test/测试视角渲染结果与真实图对比快速看重建质量train/训练视角渲染结果确认训练是否收敛visual/可视化辅助图帮助定位欠重建区域point_cloud/iteration_30000/point_cloud.ply最终的高斯点云可导入其他工具或二次处理chkpnt30000.pth检查点文件可从中断处继续训练ckpt_30000.pth模型权重加载后做渲染或微调验证训练效果最直接的方式是打开test目录对比真实照片和渲染图的差异。如果两者在纹理和轮廓上非常接近基本就算复现成功。初次跑通不要追求指标超过别人先确认全流程没有断点。官方仓库还有一个实时查看器在仓库的 SIBR_viewers 目录下编译需要额外依赖。第一次复现不要求把查看器编出来先看静态图跑通主流程后再回来折腾查看器。查看器能流畅旋转视角时你才算真正体验到 3DGS 的实时渲染能力。5. 复现路上的常见问题与排查让训练稳定出图的5个修复方向5.1 扩展编译报错找不到 cuda_runtime.h 或 nvcc现象执行pip install submodules/diff-gaussian-rasterization时日志抛出一大段fatal error: cuda_runtime.h: No such file or directory或者干脆提示nvcc not found。原因CUDA Toolkit 没有安装或者安装了但命令行当前环境找不到。pip 编译时不会自动去扫描显卡驱动目录它依赖常规的CUDA_HOME环境变量。解决先执行nvcc --version如果提示没有这个命令就安装和 PyTorch 版本匹配的 CUDA Toolkit。Linux 下安装后把/usr/local/cuda/bin加进 PATHWindows 下确认环境变量CUDA_PATH存在。改完环境变量后记得重新打开终端再重新执行编译。还有一个很容易忽略的坑如果同时装了多个 CUDA 版本pip 可能选错建议安装前显式export CUDA_HOME/usr/local/cuda-11.8指定一次。5.2 训练启动后背景发黑模型只长出一小团东西现象训练日志正常刷新但渲染出来的图几乎全黑只有正中间有一小团模糊色块。查看器里场景完全不成型。原因绝大多数情况下是 COLMAP 稀疏重建失败导致相机位姿错乱或者点云太稀疏。初始化时高斯数量严重不足后面的密度控制再怎么补偿也补不回来。还有一种可能是 convert.py 输出目录里sparse/0下的点云文件点数极少这说明特征匹配环节就出了问题。解决回查 COLMAP 的中间产物。最简单的方法是直接看input图片如果图像之间重叠度不够或者大量图片几乎是同一视角特征匹配自然失效。重新采集数据保证绕场时有明显的视角推进。也可以用 COLMAP 图形界面重新跑一遍观察右下角点云重建进度。确认稀疏点云有几百几千个点再进训练。5.3 显存溢出训练到一半被系统杀掉现象训练刚开始还能跑几百次迭代后终端提示CUDA out of memory或者直接进程消失操作系统杀掉了进程。原因图像分辨率太高或场景图片数量太多。默认加载原图分辨率一张 4000x3000 的照片在训练时非常占显存同时梯度还要保留多个版本的高斯参数。解决给训练命令加-r 0.5把图片降到一半分辨率显存占用会大幅下降。如果还是不够降到-r 0.25也是可以的只是最终纹理精度会下降。另外检查是否同时开了多个训练任务或别的 GPU 程序。第一次复现尽量选一个几十张图片的小场景把流程跑通再上高分辨率。5.4 COLMAP 生成不了模型特征点数量极少现象COLMAP 的mapper阶段报了No good image pairs found或者生成的点云只有几十个点。原因图片质量或内容的问题。拍摄时运动过快产生模糊、画面全是天空或白墙、室内场景光照太暗都会导致特征提取失败。还有一个隐蔽原因图片分辨率太高时 COLMAP 默认降采样特征点本身也受影响。解决回到数据侧。把明显模糊的照片删掉用手机拍摄时尽量等对焦完成再移动场景里加上一些有纹理的物体或海报给特征匹配提供锚点。如果照片是用视频抽帧得到的试试把抽帧间隔拉大保证相邻帧视角差异明显。COLMAP 对“视角连续但变化很小”的图像很敏感重叠度太高反而匹配不出有效约束。5.5 加载检查点后推图得到全白或乱码现象训练完成后用加载模型渲染视频或导出点时结果是一片纯色或花屏。原因最常见的是训练参数和加载参数不一致。比如训练时用了--sh_degree 3但加载时脚本里写死了其他阶数或者直接加载了不同数据集训练出来的检查点相机内参完全对不上。解决加载模型时保持训练时用的--sh_degree、分辨率等参数一致。如果检查点来自某一次中途中断的训练还要确认它和当前场景数据目录是同一条数据链。做渲染验证时尽量用官方仓库自带的渲染脚本自己写加载逻辑容易漏掉归一化细节。注意遇到报错不要先怀疑代码先怀疑数据和环境版本。血泪经验是这个项目的报错信息往往不是真正的原因日志往上翻几行通常能看到更早暴露的警告。6. 进阶把复现结果用起来才算真正跑通了全流程训练跑通只是开始下一步是把模型当成一个可用的场景资产。最直观的验证方式是用实时查看器打开训练产物如果仓库自带的查看器在你的机器上能编译出来就编译一次。它会让你迅速理解“可微高斯集合”和“实时渲染”之间的对应关系原来每个高斯的颜色和位置就是屏幕上那些彩色光斑的真身。如果查看器编译太费劲还有一个更轻量的验证技巧写一段脚本加载训练好的point_cloud.ply在点云播放器里浏览。虽然看不到高质量渲染效果但能确认场景结构是完整的。进阶玩法是走一遍自动旋转视角渲染把模型从多个方位渲染成视频用这个视频快速判断哪些区域重建得干净、哪些区域有漂浮物这样不用等查看器就能完成质量评估。调参方面我不建议一上手就乱调学习率。值得先调的是两个地方--densify_grad_threshold控制密度控制触发的敏感度场景细节不够时把阈值从 0.0002 调到 0.00005能让模型长出更多高斯--sparse_density控制初始化时给每个点周围撒的高斯数量默认 0.01 偏低如果想加快收敛可以调大。每次只改一个变量记录 PSNR 和显存变化不要一次改好几个。另外一个很实用的习惯把复现环境的版本信息和训练命令存成run_config.txt。下次隔几天再跑环境变量可能已经变了至少能查到当初是什么组合跑通的。3DGS 的坑大多是环境问题模型本身其实很皮实。我自己的习惯是每次跑新场景前先看一眼之前存的环境记录不急着重新编译扩展。希望帮到你。本文还有配套的精品资源点击获取
