1. 3DGS/ODGS部署环境准备
在Windows系统上部署3D高斯泼溅(3DGS)和全景高斯泼溅(ODGS)项目时,环境配置是最容易出问题的环节。我使用的是Windows 11系统,搭配CUDA 12.9和MSVC 2025(预览版),这种非标准组合带来了不少挑战。
注意:官方推荐使用Linux环境进行3DGS相关项目的开发,Windows下的兼容性问题较多,需要额外处理。
1.1 硬件与基础软件要求
我的测试平台配置如下:
- CPU: Intel i7-13700K
- GPU: NVIDIA RTX 4090 (24GB显存)
- 内存: 64GB DDR5
- 存储: 1TB NVMe SSD
软件依赖:
- Python 3.10.11
- PyTorch 2.2.0 (CUDA 12.1兼容版本)
- CUDA 12.9
- cuDNN 8.9.7
- MSVC 2025 Preview (17.8+)
这里有个关键点:虽然我安装的是CUDA 12.9,但PyTorch官方尚未提供对应的预编译版本。经过测试,PyTorch 2.2.0 (CUDA 12.1)可以正常工作,但需要注意运行时库的兼容性问题。
1.2 子模块获取与替换
原始3DGS项目的simple-knn子模块仓库已失效,这是部署时遇到的第一个障碍。解决方法有两种:
-
使用ODGS项目中的simple-knn子模块
- 来源:https://github.com/camenduru/simple-knn
- 这个版本经过ODGS项目验证,兼容性较好
-
手动指定历史提交版本
bash复制git submodule add https://github.com/vincentfpgarcia/simple-knn.git submodules/simple-knn cd submodules/simple-knn git checkout da5f991fb5b4146531b3912d8084162cf1485701
我选择了第一种方案,因为ODGS本身也是我的目标项目,其子模块已经过适配测试。
2. Windows下的编译问题解决
Windows平台最大的挑战在于CUDA编译器(nvcc)与MSVC的版本兼容性问题。我的环境是CUDA 12.9 + MSVC 2025,这组合官方并不支持。
2.1 编译器版本不匹配问题
当运行python setup.py install时,会遇到如下错误:
code复制nvcc fatal : Unsupported Microsoft Visual Studio version!
这是因为nvcc会检查MSVC版本,而CUDA 12.9官方只支持到MSVC 2022。解决方案是双管齐下:
- nvcc侧:添加
--allow-unsupported-compiler参数 - MSVC侧:添加
/D_ALLOW_COMPILER_AND_STL_VERSION_MISMATCH宏定义
对于simple-knn项目,修改后的setup.py关键部分如下:
python复制extra_compile_args={
"nvcc": ["--allow-unsupported-compiler"], # 绕过nvcc版本检查
"cxx": ["/D_ALLOW_COMPILER_AND_STL_VERSION_MISMATCH", "/wd4624"]
}
2.2 M_PI常量未定义问题
在编译odgs-gaussian-rasterization时,会遇到新错误:
code复制error: identifier "M_PI" is undefined
这是因为Windows平台默认不提供M_PI等数学常量定义。解决方法是在编译参数中添加_USE_MATH_DEFINES宏:
python复制if os.name == 'nt':
cxx_compile_args.append("/D_USE_MATH_DEFINES")
nvcc_compile_args.append("-D_USE_MATH_DEFINES")
经验:Windows下编译CUDA扩展时,数学函数和常量的处理与Linux不同,需要特别注意这类平台差异。
3. 完整安装流程
3.1 simple-knn安装
- 修改setup.py:
python复制from setuptools import setup
from torch.utils.cpp_extension import CUDAExtension, BuildExtension
import os
cxx_compiler_flags = []
if os.name == 'nt':
cxx_compiler_flags.append("/D_ALLOW_COMPILER_AND_STL_VERSION_MISMATCH")
cxx_compiler_flags.append("/wd4624")
setup(
name="simple_knn",
ext_modules=[
CUDAExtension(
name="simple_knn._C",
sources=["spatial.cu", "simple_knn.cu", "ext.cpp"],
extra_compile_args={
"nvcc": ["--allow-unsupported-compiler"],
"cxx": cxx_compiler_flags
})
],
cmdclass={'build_ext': BuildExtension}
)
- 执行安装:
bash复制python -m pip install ./submodules/simple-knn --no-build-isolation
3.2 odgs-gaussian-rasterization安装
- 修改setup.py:
python复制from setuptools import setup
from torch.utils.cpp_extension import CUDAExtension, BuildExtension
import os
nvcc_compile_args = ["-I" + os.path.join(os.path.dirname(os.path.abspath(__file__)), "third_party/glm/")]
cxx_compile_args = []
if os.name == 'nt':
cxx_compile_args.extend([
"/D_ALLOW_COMPILER_AND_STL_VERSION_MISMATCH",
"/D_USE_MATH_DEFINES"
])
nvcc_compile_args.extend([
"--allow-unsupported-compiler",
"-D_USE_MATH_DEFINES"
])
setup(
name="odgs_gaussian_rasterization",
packages=['odgs_gaussian_rasterization'],
ext_modules=[
CUDAExtension(
name="odgs_gaussian_rasterization._C",
sources=[
"cuda_rasterizer/rasterizer_impl.cu",
"cuda_rasterizer/forward.cu",
"cuda_rasterizer/backward.cu",
"rasterize_points.cu",
"ext.cpp"],
extra_compile_args={
"nvcc": nvcc_compile_args,
"cxx": cxx_compile_args
})
],
cmdclass={'build_ext': BuildExtension}
)
- 执行安装:
bash复制python -m pip install ./submodules/odgs-gaussian-rasterization --no-build-isolation
4. 常见问题与解决方案
4.1 编译错误排查表
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| Unsupported Microsoft Visual Studio version | MSVC版本过高 | 添加--allow-unsupported-compiler和/D_ALLOW_COMPILER_AND_STL_VERSION_MISMATCH |
| identifier "M_PI" is undefined | Windows数学常量未定义 | 添加_USE_MATH_DEFINES宏 |
| LNK1181: cannot open input file 'kernel32.lib' | VC++目录未正确设置 | 检查VS安装的SDK版本,确保环境变量正确 |
| CUDA error: no kernel image is available for execution | 架构不匹配 | 检查CUDA_ARCH参数是否匹配你的GPU |
4.2 性能优化建议
-
编译优化:在nvcc参数中添加
-O3优化选项python复制nvcc_compile_args.extend(["-O3", "--expt-relaxed-constexpr"]) -
并行编译:设置环境变量加速编译
bash复制set MAX_JOBS=8 # 根据CPU核心数调整 -
调试信息:开发时可添加
-G参数生成调试信息,但会显著降低性能python复制# nvcc_compile_args.append("-G") # 调试时启用
4.3 其他注意事项
-
Python环境隔离:建议使用conda或venv创建独立环境
bash复制
conda create -n 3dgs python=3.10 conda activate 3dgs -
依赖版本锁定:使用requirements.txt固定版本
code复制torch==2.2.0 torchvision==0.16.0 numpy==1.26.0 -
显存管理:对于全景图像训练,显存需求较大,可尝试:
- 减小batch size
- 使用
--resolution 1参数降低初始分辨率 - 启用
--fp16混合精度训练
5. 全景图像训练特别说明
ODGS项目针对全景图像(如Insta360)进行了优化,相比原始3DGS有一些特殊处理:
- 球面投影:将全景图像映射到球面坐标系
- 视点采样:在球面上均匀采样相机位置
- 密度调整:根据球面距离调整高斯分布密度
训练命令示例:
bash复制python train.py -s /path/to/insta360_data --eval -m output
--data_device cuda
--resolution 2
--white_background
--sh_degree 3
关键参数说明:
--resolution 2:控制初始图像分辨率(1-4)--white_background:假设背景为纯白色--sh_degree 3:球谐函数阶数,影响光照效果
我在实际测试中发现,全景图像训练对初始参数敏感,建议:
- 先使用低分辨率(--resolution 1)快速测试
- 逐步提高分辨率进行精细训练
- 适当增加迭代次数(默认30k次可能不足)