3D Gaussian Splatting (3DGS) 从入门到精通:安装、训练与常见问题全解析
3D Gaussian Splatting (3DGS) 从入门:安装、训练与常见问题全解析
3D Gaussian Splatting (3DGS) 作为一种新兴的实时神经渲染技术,以其惊人的渲染速度和高质量的视觉效果迅速获得了社区的关注。然而,从环境配置到数据准备,再到模型训练和结果导出,整个流程中充满了各种可能令人困惑的“坑”。
本文旨在为您提供一份全面的 3DGS 安装与使用指南,汇总了从环境搭建到最终结果产出的每个环节中可能遇到的常见问题、原因分析及详细解决方案。无论您是初学者还是经验丰富的开发者,这份指南都将助您一臂之力,顺利踏上 3DGS 的探索之旅。
1. 环境与依赖安装:打好地基
成功的 3DGS 之旅始于正确的环境配置。PyTorch、CUDA 版本匹配以及 Python 依赖是这里的关键。
1.1 推荐环境配置
-
操作系统: Ubuntu 20.04/22.04 LTS 版本。
-
Python 版本: 3.8+,强烈建议使用 Conda (Miniconda/Anaconda) 进行环境管理,以隔离项目依赖,避免与系统或其他项目发生冲突。
-
CUDA 版本: 11.8 或 12.x 系列。CUDA 版本需要与您安装的 PyTorch 版本严格匹配,这是 GPU 加速计算的基石。
1.2 Conda 环境与 PyTorch 最佳实践
使用 Conda 管理环境可以避免“依赖地狱”。在安装 PyTorch 时,请务必注意版本匹配。
典型安装命令
Bash
# 1. 创建并激活新的Conda环境
conda create -n 3dgs python=3.8 # 建议使用Python 3.8或3.10
conda activate 3dgs# 2. 安装与您的CUDA版本严格匹配的PyTorch、torchvision和torchaudio
# 这里的CUDA 12.1仅为示例,请根据您的实际CUDA版本调整!
# 务必从PyTorch官方的轮子(whl)文件地址安装,而不是通过conda安装PyTorch,因为conda可能无法提供最新的或与您的CUDA精准匹配的版本。
pip install torch==2.1.0+cu121 torchvision==0.16.0+cu121 torchaudio==2.1.0+cu121 --extra-index-url https://download.pytorch.org/whl/cu121# 3. 安装其他必要的Python库
# 注意:numpy建议使用1.x版本,因为某些科学计算包可能与numpy 2.x存在兼容性问题。
pip install numpy<2.0 matplotlib tqdm open3d
常见问题与解决
-
PyTorch + CUDA 不兼容:
-
报错现象: 常见的错误信息包括
libcudart.so not found
、CUDA driver version is insufficient
或ABI mismatch
。 -
原因分析: 这通常意味着您安装的 PyTorch 版本与系统或环境中实际的 CUDA Runtime Library 版本不匹配。
-
解决方案: 彻底卸载 PyTorch、torchvision 和 torchaudio,然后重新按照官方推荐的
pip install --extra-index-url
方式,安装与您 确切 CUDA 版本 相对应的 PyTorch 版本。有时,也需要卸载并重装所有涉及 C++/CUDA 扩展的库。
-
-
numpy
2.x 版本冲突:-
报错现象: 部分依赖科学计算的 Python 包可能会因为
numpy
升级到 2.x 版本而报错。 -
解决方案: 降级
Bashnumpy
版本。pip install numpy==1.26.4 # 或其他1.x的稳定版本
-
-
torchvision==0.15.1+cu121
找不到:-
报错现象: 安装
torchvision
时,如果指定了+cuXX
后缀,可能会提示找不到该版本。 -
原因分析:
torchvision
或torchaudio
的某些版本可能并没有为所有 CUDA 版本提供带有+cuXX
后缀的特定预编译轮子。在这种情况下,安装不带后缀的基础版本即可,它通常会依赖于已安装的 PyTorch 的 CUDA Runtime。 -
解决方案: 尝试安装不带
+cu121
后缀的torchvision
版本,例如pip install torchvision==0.15.1
。
-
2. COLMAP 与 Ceres Solver 编译:前置基石
3DGS 模型训练需要 COLMAP 提供的相机内参、外参和稀疏点云作为初始数据。因此,COLMAP 及其核心依赖 Ceres Solver 的顺利编译至关重要。
2.1 核心依赖问题
COLMAP 和 Ceres Solver 依赖大量的科学计算库和图形库。缺失或版本不兼容是常见问题。
典型依赖安装命令
Bash
# 更新apt源
sudo apt-get update# 安装核心库的开发包
sudo apt-get install \libeigen3-dev \ # Eigen3:线性代数库libgtest-dev \ # GTest:Google测试框架,Ceres编译可选libabsl-dev \ # Abseil-CPP:Google基础库,Ceres强依赖libmetis-dev \ # METIS:图分区库,COLMAP依赖libboost-all-dev \ # Boost:C++通用库libopencv-dev \ # OpenCV:计算机视觉库libglew-dev \ # GLEW:OpenGL扩展加载库libassimp-dev \ # ASSIMP:3D模型导入库,部分工具可能依赖libglfw3-dev \ # GLFW3:OpenGL上下文创建库libsuitesparse-dev \ # SuiteSparse:稀疏矩阵库,Ceres依赖libgoogle-glog-dev \ # Glog:Google日志库libopengl-dev \ # OpenGL:图形渲染库libsqlite3-dev \ # SQLite3:嵌入式数据库liblapack-dev \ # LAPACK:线性代数子程序库libblas-dev # BLAS:基础线性代数子程序
常见报错与解决
-
abslConfig.cmake
或abslConfigVersion.cmake
缺失/版本不匹配:-
报错现象: CMake 提示找不到 Abseil 的配置或版本不兼容。
-
解决方案: 这通常发生在您手动编译 Abseil 和 Ceres 后。请参考 COLMAP 编译指南 中关于 Abseil 版本匹配和
abslConfig.cmake
文件手动创建或修改的详细说明。确保PACKAGE_VERSION
在.cmake
文件中正确设置。
-
-
CUDA 编译报错(如
unsupported GNU version
):-
报错现象: CUDA 编译时报错,指示当前 GCC/G++ 版本不受支持(例如,CUDA 12.x 可能不支持 GCC 13+)。
-
解决方案: 确保您安装了与 CUDA 版本兼容的 GCC/G++ 版本(如 GCC 12)。在 CMake 命令中明确指定使用兼容的编译器:
Bashcmake .. -DCMAKE_C_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12 [其他参数]
如果系统默认编译器版本过高,您可能需要使用
update-alternatives
命令临时切换或配置。
-
-
CMake 找不到
ASSIMP
/GLFW3
/OpenCV
等:-
报错现象: CMake 提示
Could NOT find ASSIMP
、Could NOT find GLFW3
或Could NOT find OpenCV
。 -
解决方案: 这通常是由于缺少对应的开发包(
-dev
后缀)。请执行上述apt-get install
命令。如果安装后仍无法找到,可以尝试在 CMake 时手动指定库的路径,例如-DASSIMP_DIR=/usr/local/lib/cmake/assimp
。
-
-
embree
版本不符警告:-
警告现象: 编译时可能出现关于
embree
版本的警告。 -
解决方案: 通常,如果不是专门进行光线追踪或需要
embree
加速的特定功能,这些警告可以安全忽略,不会影响 COLMAP 核心功能。
-
3. COLMAP 重建与数据集转换:为 3DGS 准备数据
COLMAP 处理原始图像,生成稀疏点云和相机参数,这些是 3DGS 模型训练的输入。
3.1 视频转图片帧
如果您有视频数据,需要先将其转换为一系列图片帧:
Bash
# -i input.mp4:指定输入视频文件
# -qscale:v 2:设置视频质量,2通常表示高质量
# frames/%05d.jpg:输出文件命名格式,%05d表示5位数字序列,如00001.jpg, 00002.jpg
# 注意:先创建frames目录
ffmpeg -i input.mp4 -qscale:v 2 frames/%05d.jpg
3.2 COLMAP 稀疏重建
使用 COLMAP GUI 或命令行执行以下核心步骤:
-
特征提取 (Feature Extraction): 从每张图片中提取关键点和描述符。
-
特征匹配 (Feature Matching): 在不同图像之间匹配特征点,建立图像间的几何关系。
-
稀疏重建 (Sparse Reconstruction / Bundle Adjustment): 利用匹配结果估计相机姿态、内参和稀疏三维点云。
输出目录结构: 完成这些步骤后,COLMAP 通常会在您的项目目录下生成 images/
(原始图像)和 sparse/
目录,其中 sparse/
包含 cameras.bin
、images.bin
和 points3D.bin
文件。
3.3 数据集转换脚本 colmap2gs_dataset.sh
3DGS 训练脚本通常期望一个特定的数据组织结构和文件格式。使用一个转换脚本是最佳实践。
这是一个假设的 colmap2gs_dataset.sh
脚本,用于将 COLMAP 的原始输出转换为 3DGS 训练所需的格式:
Bash
#!/bin/bash# colmap_image_dir: 原始COLMAP图片目录
# colmap_sparse_dir: COLMAP稀疏模型输出目录 (如project_path/sparse)
# output_dir: 转换后的3DGS数据集输出目录 (如project_path/undistorted)colmap_image_dir=$1
colmap_sparse_dir=$2
output_dir=$3if [ -z "$colmap_image_dir" ] || [ -z "$colmap_sparse_dir" ] || [ -z "$output_dir" ]; thenecho "Usage: $0 <colmap_image_dir> <colmap_sparse_dir> <output_dir>"exit 1
fiecho "--- 开始清理输出目录: $output_dir ---"
rm -rf "$output_dir"/*
mkdir -p "$output_dir"/imagesecho "--- 将原始图片链接到输出目录 ---"
# 确保output_dir/images下的图片是原始图片,而非undistorted后的
ln -sf "$(realpath $colmap_image_dir)"/* "$output_dir"/images/echo "--- 检查COLMAP稀疏模型目录结构并整理 ---"
# COLMAP导出时可能直接在sparse/下,也可能在sparse/0/下
if [ -d "$colmap_sparse_dir/0" ]; thensparse_model_path="$colmap_sparse_dir/0"
elsesparse_model_path="$colmap_sparse_dir"
fiif [ ! -f "$sparse_model_path/cameras.bin" ] || [ ! -f "$sparse_model_path/images.bin" ] || [ ! -f "$sparse_model_path/points3D.bin" ]; thenecho "错误: COLMAP稀疏模型文件未找到。请检查 $sparse_model_path 目录。"exit 1
fimkdir -p "$output_dir"/sparse/0
cp "$sparse_model_path"/cameras.bin "$output_dir"/sparse/0/
cp "$sparse_model_path"/images.bin "$output_dir"/sparse/0/
cp "$sparse_model_path"/points3D.bin "$output_dir"/sparse/0/echo "--- 数据集转换完成,3DGS训练可使用目录: $output_dir ---"
使用方法:
Bash
bash colmap2gs_dataset.sh /path/to/your_colmap_project/images /path/to/your_colmap_project/sparse /path/to/your_colmap_project/undistorted
常见问题与解决
-
undistorted/images
目录已存在导致崩溃或文件冲突:-
原因分析: COLMAP 的
Image Undistorter
工具在处理时,如果目标目录已存在文件,可能会报错或覆盖。 -
解决方案: 确保在运行
colmap2gs_dataset.sh
脚本前,目标output_dir
目录(例如undistorted/
)是空的,或脚本能自动清理。上述脚本已包含清理逻辑。
-
-
sparse/0/
目录未生成或文件缺失:-
报错现象: 训练脚本提示
FileNotFoundError: images.bin/images.txt
。 -
原因分析: 有时 COLMAP 的输出直接在
sparse/
目录下,没有嵌套0/
文件夹。或 COLMAP 的Image Undistorter
步骤没有正确生成bin
文件。 -
解决方案: 确保 COLMAP 的输出在
sparse/0/
或sparse/
路径下包含cameras.bin
,images.bin
,points3D.bin
。上述colmap2gs_dataset.sh
脚本已考虑两种情况,并将其整理到output_dir/sparse/0/
以确保兼容性。
-
4. 3DGS 训练与渲染:核心环节
数据准备就绪后,就可以进入 3DGS 模型的核心训练和渲染步骤。
4.1 训练 3DGS 模型
在 3DGS 代码库的根目录(通常是 gaussian-splatting/
),执行训练脚本:
Bash
# -s:指定数据集根目录,该目录下需包含 images/ 和 sparse/0/
# -m:指定模型输出目录的名称
python train.py -s /path/to/your_undistorted_dataset -m output_folder_name
常见问题与解决
-
FileNotFoundError: images.bin/images.txt
:-
原因分析: 训练脚本无法在
-s
参数指定的目录下找到 COLMAP 导出的.bin
或.txt
文件。 -
解决方案: 确认
sparse/0/
目录下包含cameras.bin
,images.bin
,points3D.bin
,并且-s
参数指向的是包含images/
和sparse/
的根目录。请务必使用上文提供的colmap2gs_dataset.sh
脚本进行数据整理。
-
-
CUDA / PyTorch 扩展
ABI
不兼容:-
报错现象: 常见于更新 PyTorch 或 CUDA 后,提示
CUDA_HOME
、nvcc
或 PyTorch 的某些扩展库ABI
不匹配。 -
原因分析: Python 环境中的某些 C++ 或 CUDA 编译的扩展库没有与当前 PyTorch/CUDA 版本同步更新。
-
解决方案: 重新安装所有涉及 C++/CUDA 编译的 PyTorch 相关扩展,通常包括
torch
、torchvision
、torchaudio
,有时还需要重新编译diff-gaussian-rasterization
或simple-knn
等 3DGS 内部的 CUDA 模块。最彻底的方法是删除 Conda 环境并重装。
-
4.2 渲染 3DGS 结果
训练完成后,您可以渲染训练好的模型以生成图像或视频:
Bash
# --model_path:指向训练输出目录中包含模型检查点的点云目录
# --config:通常指向输出目录中的 cameras.json 或其他配置文件
python render.py --model_path output/xxxxxx/point_cloud/iteration_30000/ --config output/xxxxxx/cameras.json
请注意,output/xxxxxx/
是您训练时 -m
参数指定的输出目录。iteration_30000/
是您想要渲染的特定迭代步的模型。
常见问题与解决
-
AttributeError: Namespace
没有model_path
/config
等:-
报错现象: 运行时提示 Namespace 对象没有某个属性,例如
Namespace object has no attribute 'model_path'
。 -
原因分析:
render.py
脚本的命令行参数名称可能发生了变化,或者您输入的参数名有误。 -
解决方案: 使用
Bash--help
参数查看当前render.py
脚本支持的所有参数名称和用法:python render.py --help
-
-
Config file not found
:-
报错现象: 渲染时提示找不到
cameras.json
或其他配置文件。 -
原因分析:
cameras.json
或其他必要的配置文件没有在output_folder_name
或其子目录中正确生成。 -
解决方案: 检查
output_folder_name
目录下是否存在cameras.json
或其他 COLMAP 转换工具生成的配置文件。如果缺失,可能需要检查 COLMAP 数据转换步骤是否有问题。
-
5. FFmpeg 生成视频:将图片序列化为动态影像
3DGS 渲染通常会输出一系列图片帧。要将这些图片帧组合成视频,ffmpeg
是最常用的工具。
5.1 标准视频合成命令
进入渲染输出目录(例如 output/xxxxxx/renders/
),然后执行:
Bash
cd output/xxxxxx/renders# -framerate 10:设置输入图片序列的帧率(每秒10帧)
# -i %05d.png:指定输入图片文件命名格式(如00001.png, 00002.png等)
# -vf "pad=ceil(iw/2)*2:ceil(ih/2)*2":视频滤镜,确保宽度和高度都是偶数,避免编码器报错
# -c:v libx264:使用libx264编码器
# -pix_fmt yuv420p:设置像素格式,保证广泛兼容性
# -r 10:设置输出视频的帧率
# video.mp4:输出视频文件名称
ffmpeg -framerate 10 -i %05d.png -vf "pad=ceil(iw/2)*2:ceil(ih/2)*2" -c:v libx264 -pix_fmt yuv420p -r 10 video.mp4
常见问题与解决
-
height not divisible by 2
/width not divisible by 2
:-
报错现象: FFmpeg 提示视频的宽度或高度不是偶数,无法进行编码。
-
解决方案: 在
ffmpeg
命令中添加-vf "pad=ceil(iw/2)*2:ceil(ih/2)*2"
参数。这个视频滤镜会自动将图像的宽度和高度补齐为最近的偶数,从而解决编码兼容性问题。
-
-
视频播放速度过快/过慢:
-
原因分析:
-framerate
参数(输入帧率)和-r
参数(输出帧率)设置不当。 -
解决方案: 调整
-framerate
和-r
参数的值。通常这两个值保持一致。例如,如果希望视频以 30 帧每秒的速度播放,则将两者都设为 30。
-
6. SIBR_viewer 编译与 3D 可视化:实时探索场景
如果您需要一个独立的三维查看器来实时加载和探索 COLMAP 或 3DGS 生成的场景,SIBR_viewer 是一个不错的选择
6.1 依赖问题与子模块处理
SIBR_viewer 同样依赖大量库,且可能包含 Git 子模块。
常见问题与解决
-
ASSIMP
/GLEW
/GLFW3
找不到:-
原因分析: 缺少对应的开发包。
-
解决方案: 参照本文 2.1 节,安装
libassimp-dev
、libglew-dev
和libglfw3-dev
等。
-
-
Git 子模块卡住或失败:
-
报错现象:
git submodule update --init --recursive
命令长时间无响应或报错。 -
原因分析: 这通常是由于网络连接问题(如防火墙)导致无法访问 Git 子模块的仓库。
-
解决方案:
-
确保您的网络连接稳定,并尝试使用科学上网工具。
-
如果仍有问题,可以尝试手动克隆卡住的子模块仓库,然后将其内容复制到
SIBR_viewer
期望的子模块路径下。
-
-
-
编译前需清理
build
目录:-
原因分析: 与 COLMAP 类似,编译工具的缓存可能导致问题。
-
解决方案: 每次重新编译前,进入
SIBR_viewer
的build
目录,执行rm -rf *
或rm -rf CMakeCache.txt CMakeFiles
。
-
-
无 GUI 环境无法查看:
-
现象: 在没有桌面环境的服务器上,无法直接运行
SIBR_viewer
。 -
解决方案: 在服务器上完成 3DGS 训练和渲染后,将生成的图片或视频文件下载到本地机器进行查看。或者,考虑使用一些基于 Web 的 3D 可视化解决方案。
-
7. 3DGS 结果 Mesh/贴图导出:通往传统 3D 模型
3DGS 直接输出的是高斯点云(.ply
文件,其中每个“点”代表一个高斯球),而不是传统的三角网格模型。如果您的应用场景需要标准的带贴图的 Mesh 模型,则需要额外的步骤。
7.1 导出标准 Mesh
-
从高斯点云到 Mesh:
-
工具: 您可以使用 MeshLab、CloudCompare 或 Open3D 等工具,将 3DGS 输出的
.ply
文件(高斯点云)导入,然后应用点云重建算法(如泊松重建、Delaunay 网格化、Alpha Shapes 等)来生成三角网格。 -
注意: 3DGS 的
.ply
文件包含高斯参数,并非标准的点云格式,直接重建可能效果不佳。理想的流程是先将高斯点云渲染成深度图或传统点云,再进行重建。
-
-
生成带贴图的 Mesh:
-
COLMAP 稠密重建 + Mesh 纹理化: 通常的做法是回到 COLMAP 的稠密重建阶段,生成高质量的稠密点云 (
fused.ply
)。然后,使用 OpenMVS(Open Multi-View Stereo)的TextureMesh
模块或 MeshLab 等工具,将 COLMAP 生成的网格(或从fused.ply
重建的网格)与原始图像进行纹理投影,生成带贴图的 Mesh 模型。 -
当前挑战: 截至目前,3DGS 或 NeRF 本身并没有“一键”直接导出高质量带贴图 Mesh 的成熟方案。这是社区正在积极探索的方向。
-
8. 端口、代理与网络问题:远程编译的常见障碍
远程服务器上的编译和数据传输常常受到网络环境的影响。
-
git clone
慢或失败:-
原因分析: GitHub 在国内访问速度可能不稳定,或者存在防火墙限制。
-
解决方案:
-
使用
Bashghproxy
等代理服务加速git clone
。git config --global url."https://ghproxy.com/https://github.com/".insteadOf "https://github.com/"
-
或者在本地网络良好的环境下克隆项目,然后通过
scp
、rsync
或其他文件传输工具上传到服务器。
-
-
-
GitHub 已禁用
git://
协议:-
原因分析: GitHub 已经停止支持不安全的
git://
协议。 -
解决方案: 确保您的
git clone
命令使用https://
或ssh://
协议。
-
-
取消/恢复 Git 代理配置:
-
恢复代理:
Bashgit config --global url."https://ghproxy.com/https://github.com/".insteadOf "https://github.com/"
-
取消代理:
Bashgit config --global --unset url."https://ghproxy.com/https://github.com/".insteadOf
-
9. 常用命令速查:快速回顾
任务 | 命令示例 |
视频转图片 |
|
COLMAP转3DGS |
|
3DGS 训练 |
|
3DGS 渲染 |
|
视频合成 |
|
10. 其他建议:提高效率与解决问题
-
训练/渲染前清理输出目录: 在开始新的训练或渲染任务前,习惯性地清空目标输出目录。这可以避免文件冲突、旧文件干扰和意外的数据混淆。
-
查阅官方
README
和issues
: 遇到任何新问题时,3DGS 官方 GitHub 仓库的README
文档是第一手资料。同时,查看其issues
页面,很可能您遇到的问题前人已经遇到并解决了。 -
耐心与尝试: 3DGS 涉及多学科知识,编译和训练过程复杂。遇到问题时保持耐心,仔细阅读报错信息,并尝试多种解决方案。
-
硬件条件: 3DGS 对 GPU 显存要求较高。如果显存不足,尝试降低输入图像分辨率、减小批次大小或寻求更高配置的 GPU。
希望这份详尽的指南能帮助您攻克 3DGS 安装与使用过程中的所有挑战。