简介这是一份面向三维重建与人工智能学习者的完整 3D Gaussian Splatting3DGS实现包集成可运行的 Python 预处理/训练脚本并附带 iPhone 手持拍摄的可重建数据集适合希望从代码层面掌握神经辐射场与三维高斯泼溅原理的开发者。资源共 2000 个文件除 hpp、cpp、inl 等 C 核心源码外还包含 Python 脚本、JS/HTML 前端组件、编译好的 dll/exe 以及少量图片、网格与点云模型整体 489MB目录结构完整能支撑从图像序列到 COLMAP 稀疏重建、再到 3DGS 训练与实时可视化的全流程。包内使用教程围绕 convert.py 与 train.py 展开明确给出数据预处理与训练命令并提供 WASD 控制上下左右、UIOJKL 旋转相机的交互预览方式便于直观调节视角检查重建效果。目前已有 757 人学习下载对入门 3DGS、快速跑通真实手持拍摄数据并进一步定制代码具有一定参考价值。 我把完整跑通的 gaussian-splatting 实验目录压缩成了 gaussian-splatting.zip 发给一个刚入坑神经渲染的朋友他解压后第一句话是怎么 scene 目录下面全是空的模型在哪当时我人愣在键盘前才意识到问题出在哪。我自己是在本地用 git clone --recursive 拉的全套仓库又跑完了训练右键压缩的时候完全没考虑别人拿到的只是一个静态 zip 包。zip 确实是分发项目最通用的格式但它不会自动携带 git submodule 内容也不会带上 .git 历史很多在 clone 时一并拉下来的子模块到了 zip 里只剩一个空壳目录。这篇博文就从 gaussian-splatting.zip 这个看似普通、实际埋了不少坑的压缩包说起把 3D 高斯泼溅从解压、装环境、跑训练到打开查看器的完整链路以及我在重复实验里碰到的各种问题一次性聊透。适合正要入坑 3DGS、又喜欢从压缩包项目开始研究的朋友。1. 为什么我用 zip 分享 3DGS 项目时翻车了1.1 zip 和 git clone 的差距最核心的坑就在子模块官方 3DGS 仓库在 GitHub 上给出的标准获取方式是git clone --recursive这个递归参数会顺带拉取所有 submodule。但在页面上直接点 Download ZIP拿到的只是主仓库源码子模块目录不会一起打包。问题在于 gaussian-splatting 并非一锤子代码它的可微渲染核心在 diff-gaussian-rasterization 里密度控制又依赖 simple-knn实时查看部分还需要 SIBR_viewers。这三个都是独立仓库各自对应主仓库里的 submodule 目录。我当时的操作流程是clone 完整仓库、跑通训练、输出点云然后整个目录右键压缩。这个目录里 submodules 文件夹明明是有内容的但压缩成 zip 的过程里如果 submodules 是作为 gitlink 存在的很多压缩工具并不会递归地把里面的实体文件打进包里或者会在别人解压后丢失 git 链接关系。于是朋友解压后看到的 submodules 目录就像一张被抽走了内页的目录外壳看起来存在打开啥也没有。判断一个 zip 项目是否完整第一步就是看根目录有没有.gitmodules文件。这个文件记录了每个子模块对应的远程仓库地址和路径有它就能手动把缺失内容补回来。如果你拿到的 gaussian-splatting.zip 里.gitmodules都在但 submodules 目录空空如也不要慌后面我会讲怎么把它补全。1.2 eocd 报错下载不完整导致的 zip 损坏另一个高频问题跟目录内容无关而是压缩包本身在传输中断裂。很多人下载 zip 时进度条走完了解压却报invalid zip archive: could not find eocd。这句话里的 EOCD 是 End Of Central Directoryzip 格式的结尾中央目录记录。几乎每个 zip 文件的末尾都有一块固定结构记录这个包内有哪些文件、各自偏移量、压缩方式等信息。解压工具就是先读这块记录再顺着偏移去逐一还原文件。下载不完整时最后几十个字节丢失解压工具找不到 EOCD自然只能给你抛错。严格来说报 eocd 错误的 zip 就是不完整的文件没有别的解释空间。也别用记事本去看文件开头有没有 PK 头那只能说明文件开头正常无法证明结尾正常。最靠谱的办法是拿到包之后先跑一句完整性测试unzip -t gaussian-splatting.zipWindows 上也可以用 7-Zip 的测试按钮。如果报错直接删掉重下换支持断点续传的下载工具别在坏文件上浪费时间。另外一个容易忽略的点是磁盘空间解压这个项目包通常需要比压缩包大好几倍的空间尤其当你把 COLMAP 重建结果、训练输出都放进去之后整个目录体积轻松超过 10GB。解压中途磁盘写满也会以各种莫名错误的形式表现出来。2. 解压后先别急着装依赖看清目录结构再动手2.1 官方仓库的目录一眼扫过去拿到完整的 gaussian-splatting 源码根目录应该是这样一个结构路径作用重要程度train.py训练入口负责整个 3D 高斯优化流程核心render.py用训练好的模型渲染图像和深度图核心convert.py调用 COLMAP 处理照片生成稀疏重建自定义数据必需gaussian_renderer/渲染管线和可微光栅化封装核心scene/场景数据加载、高斯模型初始化核心utils/通用工具函数、SSIM/LPIPS 相关辅助通常需要arguments/命令行参数定义通常需要submodules/可微光栅化、KNN 子模块必须补齐data/数据集目录放原始照片或处理后的场景按需output/训练输出目录模型和日志都在这里按需requirements.txtPython 依赖清单核心environment.ymlconda 环境配置可选如果你拿到手的 zip 里只有 train.py、render.py、convert.py 这几个文件而没有 gaussian_renderer 和 scene 目录那这份源码大概率不完整或者是某个 fork 的精简版。这种情况我建议放弃乱补直接找官方原版重新下载。因为自己零散拼文件很容易出现 API 不匹配报错会让你怀疑人生。2.2 哪些东西能删、哪些不能删复现一个项目时我的习惯是先做减法。.git目录是 git 历史对运行没有任何作用可以删output里的中间缓存、__pycache__这些也可以删能省出不少空间。但有两个东西不要乱动一个是.gitmodules另一个是submodules/下的目录占位。很多人看到 submodules 是空的第一反应是这个目录没用删掉这是个大坑。diff-gaussian-rasterization 和 simple-knn 是整个训练和渲染路径的底层依赖删掉之后 train.py 一启动就会报ModuleNotFoundError: No module named diff_gaussian_rasterization。正确的做法是保留目录结构通过源码或 git 把子模块内容补回去。另外要注意 data 目录。有些分享者会把官方测试数据集一起打包整个 data 体积非常夸张而有些压缩包只带源码需要你自己下载数据。先检查 data 下有没有 images 和 sparse 这样的子目录没有就说明要自己准备数据别傻等一个不存在的默认场景。3. 环境搭建与扩展编译让源码真正能跑3.1 版本选型是我建议最先定下来的3DGS 项目对环境的敏感程度在我做过的图形学项目里排得上前三。Python、PyTorch、CUDA 三者版本不匹配编译阶段就会以各种姿势失败。我用了大量实验后觉得最稳的组合是Linux 系统 Python 3.8 或 3.10 PyTorch 2.0.x CUDA 11.8。如果你的显卡较新驱动要求高也可以上 PyTorch 2.1 CUDA 12.1但编码尽量往上靠。组件推荐版本备注Python3.8 / 3.103.11 也能跑但某些依赖编译麻烦PyTorch2.0.1与 11.8 组合很成熟CUDA Toolkit11.8编译扩展需要 nvcc不只是驱动COLMAP3.8自定义数据必须官方也有预编译包创建环境时我习惯直接用 conda隔离性比在系统环境里装一堆包要安全得多conda create -n gs python3.8 -y conda activate gs pip install torch2.0.1cu118 torchvision0.15.2cu118 --index-url https://download.pytorch.org/whl/cu118 pip install -r requirements.txtrequirements.txt 里的依赖比较常规一般是 numpy、matplotlib、opencv-python、tqdm、tensorboard、plyfile 这些。装完别急着训练先确认 PyTorch 能识别 GPUpython -c import torch; print(torch.cuda.is_available(), torch.__version__)输出True再往下走这一步排除掉 90% 的前置问题。3.2 编译扩展为什么 zip 里不能带上通用二进制很多从 zip 入手的朋友会问既然人家都把项目打包好了为什么不直接把 diff-gaussian-rasterization 编译好的 .so 或 .dll 也放进去原因是这种 CUDA 扩展的二进制文件绑定版本非常强。同一个 .so 在 CUDA 11.4 环境里能跑换到 CUDA 12.1 环境可能直接非法内存访问。所以官方子模块基本都是纯源码让大家在本地编译。进入子模块目录逐个执行安装cd submodules/diff-gaussian-rasterization python setup.py install cd ../simple-knn python setup.py install如果子模块目录是空的就照着.gitmodules里记录的仓库地址手动 clonegit clone diff-gaussian-rasterization 的仓库地址 submodules/diff-gaussian-rasterization git clone simple-knn 的仓库地址 submodules/simple-knn编译阶段最常见的失败原因是找不到 nvcc。建议提前确认 CUDA Toolkit 真的装了并且CUDA_HOME环境变量指向正确。Linux 上一般在/usr/local/cudaWindows 上通常是C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8。缺了这一步即使nvidia-smi能输出显卡信息setup.py install也会因为找不到编译器而中断。3.3 SIBR_viewers 可以暂时不碰官方仓库里还带着一个 SIBR_viewers 子模块作用是打开一个实时交互窗口你可以在重建的场景里漫游、旋转视角、喷泉式查看高斯点云。听上去很酷但它需要 CMake 配置和图形界面环境编译时间比前面两个扩展加起来都长。前期验证流程时完全可以不管它。替代方案有两个。一是用 render.py 把模型渲染成图片和深度图这是纯离线渲染无 GUI 也能跑的二是把训练产出的 point_cloud.ply 文件直接拖进 SuperSplat 这种在线查看器也能快速浏览 3D 高斯模型。先把链路跑通再回来补 SIBR 也不迟。4. 跑通第一个场景训练、渲染与查看的完整链路4.1 用自带数据或标准数据集验证环境环境搭好以后先别急着用自己的手机照片冲。找一份格式标准的数据集把整个训练链路跑通确认环境没问题再说。官方项目页提供了一组真实场景数据集结构一般是data/bicycle/ images/ # 原始拍摄照片 sparse/0/ # COLMAP 稀疏重建结果有了这个结构直接开训python train.py -s data/bicycle -m output/bicycle --eval-s指定数据路径-m指定输出路径--eval告诉程序划分出一部分视角作为测试集。训练默认迭代 30000 次中间会每隔一段时间保存一次点云和 checkpoint。我第一次跑的时候全程盯着日志里的 loss 下降看到数字稳步走低才放下心。如果你的显卡显存不是特别充裕可以给 train.py 加--resolution参数把输入图像缩一缩比如--resolution 4表示把加载的图缩小四分之一量级显存压力立刻小很多。也可以先用--iterations 7000短训一轮确认整个流程没有隐藏 bug再跑满 30000 次。4.2 自定义数据convert.py 和 COLMAP 做了什么自己想拍一个场景来重建需要做的准备是用相机或手机绕着目标物体走一圈拍几十张到几百张照片保证相邻照片之间有足够的重叠区域避免光线剧烈变化。把照片统一放到一个目录下data/my_scene/images/然后执行python convert.py -s data/my_scene --resize 1600这一步本质上是调用 COLMAP 做运动恢复结构流程包括特征提取、特征匹配、稀疏点云重建、相机位姿估计。3DGS 的训练需要知道每一张照片对应的相机内外参以及一个初始点云convert.py 负责把这些数据变成程序能直接读取的二进制格式。处理完成后data/my_scene下会多出sparse/0/里面有 cameras.bin、images.bin、points3D.bin 等文件。如果你的电脑没装 COLMAP或者 convert.py 提示找不到可执行文件可以用--colmap_executable参数手动指定路径。Windows 用户尤其容易卡在环境变量上直接写成绝对路径更省心。4.3 渲染验证与可视化查看训练结束后输出的核心模型在output/my_scene/point_cloud/iteration_30000/point_cloud.ply这个 ply 文件包含了所有高斯椭球的位置、形状、颜色、透明度和球谐系数是整个重建的核心产物。想快速出图用 render.pypython render.py -m output/my_scene --iteration 30000渲染结果会生成在输出目录下的 renders 和 depths 子文件夹里。没有 GUI 也能验证模型效果。如果装了 SIBR viewer对应的启动命令是SIBR_gaussianViewerApp -m output/my_scene --iteration 30000它会打开一个窗口你可以像玩游戏一样在场景里走动查看。第一次看到高斯点云从稀疏到稠密、从模糊到清晰的变换过程还是很震撼的。5. 实战中踩过的坑按排查链路走比瞎试快得多5.1 submodule 目录空白模型可以补代码不能缺症状是程序一启动就报ModuleNotFoundError: No module named diff_gaussian_rasterization。排查链路很清晰先看 submodules/diff-gaussian-rasterization 下有没有 setup.py 和 rasterize_impl.cu 这类源码文件。如果只有一个空目录说明 zip 包没把子模块打进来。用.gitmodules里的地址手动 clone 到对应目录再重新执行 setup.py install。同类问题在 simple-knn 上也会出现一次补两个省得来回折腾。5.2 解压失败别再试修复工具重下最快碰到invalid zip archive: could not find eocd先跑unzip -t确认损坏范围。我见过有人用各种所谓修复工具去改 zip 头部字节折腾两个小时最后包还是打不开。说实话这种完整度缺失的包没有修复价值重新下载并且校验哈希更靠谱。如果源文件在远程仓库优先选择带断点续传的下载方式避免大文件长时间下载中断。还有一种隐藏情况是压缩包里文件数太多、体积接近 4GB 时老版本解压工具可能因为 zip64 兼容性问题报奇怪错误这时换 7-Zip 或较新版解压工具就能解决。5.3 编译报错把 CUDA 版本对齐再动手编译 diff-gaussian-rasterization 时最容易遇到的报错是找不到头文件或 undefined symbol。前者通常是 CUDA_HOME 没有配对后者通常是 PyTorch 编译时的 CUDA 版本和当前 nvcc 版本不一致。我建议在执行 setup.py 之前先做两个确认nvcc --version python -c import torch; print(torch.version.cuda)两个输出的 CUDA 版本最好保持一致或者至少是向后兼容的关系。版本不一致时重新创建一个干净环境统一指定 PyTorch 的 CUDA 版本安装而不是继续在脏环境里补包。同一台机器上装了多个 CUDA Toolkit 很正常想在某个环境里用指定版本就把该版本的bin目录放到PATH最前面同时设置好CUDA_HOME。找了半天发现是环境变量优先级问题这种情况一点都不少见。5.4 路径、权限、显存三个看起来不起眼的大坑COLMAP 和 SIBR viewer 这两样东西对中文路径极其不友好。我踩过一次照片放在D:\重建项目\test\imagesconvert.py 一路处理到最后COLMAP 突然打不开数据库文件。把整个目录改成纯英文路径后问题消失。如果你用 zip 解压出来的项目自带中文路径重新解压到D:\gaussian\test这类位置别偷懒。显存不足是另一个劝退点。训练 3DGS 本质是在梯度下降优化几百万个高斯参数显存占用和输入分辨率、训练图像数量强相关。显存不够用时优先降低训练加载分辨率或者减少图像数量、缩短迭代次数验证流程。千万不要一上来就动sh_degree或densify这类和重建质量强相关的参数牺牲的是最终还原度。5.5 快速自查表症状可能原因首选动作ModuleNotFoundError: diff_gaussian_rasterizationsubmodule 缺失或未编译手动 clone 子模块并 setup.py installinvalid zip archive: could not find eocdzip 下载不完整unzip -t 验证后重新下载nvcc 找不到 / 版本报错CUDA Toolkit 或 CUDA_HOME 异常统一 nvcc 与 torch.version.cudaCOLMAP 无法打开数据库中文路径或路径过长改为纯英文短路径CUDA out of memory分辨率或图片数过高加 --resolution 降低训练负载viewer 启动黑屏图形驱动或编译环境问题先用 render.py 离线验证6. 下一步把 zip 变成可复现、可扩展的实验起点6.1 重新打包成干净的可复现包如果你打算把自己的 gaussian-splatting 项目压缩包分享给别人重新打包前先做一次清理。删掉__pycache__、output里的大 checkpoint、临时回环文件只保留源码、requirements.txt、训练好的 point_cloud.ply 和必要的说明文档。submodules 目录一定要保证内容完整最好是在完整 clone 且编译成功后重新打包别人的环境才能少踩坑。压缩时注意一个技术点如果项目里有符号链接直接用zip -r在 Linux 下会把符号链接作为普通文件或直接打成空目录Windows 解压后链接关系就断了。用zip -y保留符号链接属性更稳。分享前顺手在干净环境里试一遍解压和安装花二十分钟能替接收方省两天。如果你拿到的是 GitHub 下载的 zip 而不是 git clone 的项目又想改代码后提交到自己的远程仓库需要先git init再添加 remote。注意这类目录没有共同历史不要指望直接把整个目录 rebase 到远程仓库上历史对不上推的时候一定冲突。要么从远程仓库 fork 后重新拉代码要么把 zip 当临时副本代码最终还是要回到 git 管理里。6.2 从 baseline 出发还能走多远3D 高斯泼溅这个方向在官方 baseline 之上已经发展出了大量变体。有人优化渲染速度有人把静态场景扩展到动态人体和车辆重建也有团队在研究如何用更少的输入视角还原完整场景。但我不建议一上来就追新 repo先把官方默认参数完整跑通理解 point_cloud、iteration、球谐系数这些概念再看别人的改进会有十倍效率。如果对性能有更高要求可以关注一些对内存和显存做了优化的 fork日常场景下体验会比官方版更友好。最后说一个我自己的习惯现在拿到任何 gaussian-splatting.zip我先不急着解压而是先看这个包是源码包还是成品包。成品包直接找 point_cloud.ply 用查看器验证效果源码包就按 submodule、CUDA、路径三件事逐个排查。这套流程测过太多遍基本稳定。3DGS 的门槛其实并没有看起来那么高只要环境对齐剩下的就是让网络自己慢慢迭代。本文还有配套的精品资源点击获取