CityGaussian系列：基于高斯的高质量大规模场景重建

中国科学院自动化研究所；中国科学院大学

本仓库包含我们使用高斯泼溅进行大规模场景重建的一系列工作的官方实现，如果你喜欢它，请给我们点个赞吧！

• CityGaussianV2：高效且几何精确的大规模场景重建（ICLR 2025）
• CityGaussian：基于高斯的实时高质量大规模场景渲染（ECCV 2024）

以上链接指向相关论文。当前主分支已基于Gaussian Lightning v0.10.1进行了重基。如需访问原始V1代码，请切换至V1-Original分支。若需支持VGGT-X，请参阅此处的指导文档[vggt_x.md]。欢迎探索本仓库！

👏 特性

• CityGaussian风格的多GPU重建，内存消耗可控，GPU数量无限制
• 模型划分与数据分配分析
• 2DGS风格的网格提取及大规模场景几何性能评估
• 轨迹对齐渲染与去除浮动物的网格视频生成
• 针对COLMAP结果不完善的情况（如来自3D基础模型的结果），进行姿态与3DGS联合优化
• 包含Gaussian Lightning的功能，包括Web查看器、MipSplatting、AbsGS、StopThePop等。

表格结果与检查点

场景	SSIM↑	PSNR↑	LPIPS↓	精确率↑	召回率↑	F1分数↑	#GS(M)
LFLS	0.744	23.44	0.246	0.556	0.400	0.466	8.19
SMBU	0.794	24.00	0.185	0.559	0.523	0.541	5.33
上校区	0.779	25.78	0.186	0.654	0.394	0.491	7.87
MatrixCity航拍	0.859	27.26	0.175	0.432	0.790	0.559	8.57
MatrixCity街景	0.791	22.32	0.344	0.325	0.797	0.461	7.40

请注意，对于街景数据，F1分数低于论文中报告的数值，因为我们牺牲了精确率以提高召回率，从而获得更完整的路面覆盖。如果需要连续的路面，可以将depth_ratio调整为0.0，但表面重建效果会较差。CityGSV2的检查点可在以下地址找到：

• 百度网盘：https://pan.baidu.com/s/1tRKiJzMLk2-zoyvoa9bkqA?pwd=1b4r
• Hugging Face：https://huggingface.co/TeslaYang123/CityGaussianV2

📰 新闻

[2025.10.18] 增加对VGGT-X的姿态与3DGS联合优化的支持与指导！

[2025.04.04] 现已开通Discord频道。欢迎加入，进行更深入、更即时的城市重建交流！

[2025.03.26] 本仓库现归属于研究机构Linketic。

[2025.01.31] CityGaussian V2的检查点已发布！

[2025.01.22] CityGaussian V2已被ICLR 2025接收！

[2025.01.22] CityGaussian V2的代码现已发布。欢迎大家试用！

[2024.11.04] 宣布我们的CityGaussianV2！

[2024.10.12] 主要数据集上V1版本的检查点已发布！

[2024.08.05] CityGaussian V1的代码现已可用！

🛠 使用指南

• 安装
• 数据准备
• 运行与评估
• GS与网格上的视频渲染
• VGGT-X

📝 待办事项清单

• [ ] 正式实现外观嵌入。
• [ ] 支持V1风格的LoD。
• [x] 支持VGGT-X。
• [x] 发布CityGaussian V2的检查点。
• [x] 发布CityGaussian V2。
• [x] 发布CityGaussian的代码和检查点。
• [x] 发布主要数据集的ColMap结果。

星标历史

📄 许可证

本作品采用知识共享署名-非商业性使用-相同方式共享4.0国际许可协议。

🤗 引用

如果您觉得本仓库有用，请使用以下BibTeX条目进行引用。

@inproceedings{
    liu2024citygaussianv2,
    title={CityGaussianV2：高效且几何精确的大规模场景重建},
    author={刘洋、罗传臣、毛仲凯、彭俊然、张兆翔},
    booktitle={第十三届国际学习表征会议},
    year={2025},
    url={https://openreview.net/forum?id=a3ptUbuzbW}
}

@inproceedings{liu2025citygaussian,
  title={CityGaussian：基于高斯的实时高质量大规模场景渲染},
  author={刘洋、罗传臣、范璐、王乃燕、彭俊然、张兆翔},
  booktitle={欧洲计算机视觉大会},
  pages={265--282},
  year={2025},
  organization={施普林格}
}

👏 致谢

本仓库受益于 3DGS、2DGS、TrimGS、LightGaussian、Gaussian Lightning。感谢他们的杰出工作！

❓ 常见问题解答

• 训练时出现显存不足。 为了在有限显存下完成训练，可以尝试对图像进行降采样，或者调整 train_large.py 中的 max_cache_num 参数（我们使用了较大的 1024）。此外，还可以在并行调优中增加 prune_ratio，以进一步降低显存消耗。

• COLMAP 结果的生成。 我们直接使用数据集提供的真实位姿，并分别对训练集和测试集进行匹配。这种方式比从零开始匹配更快、更稳定。不过，即便如此，仍然需要花费较多时间。

• 大多数块未被训练。 主要原因是分配给大多数块的数据量过少（少于 50 张），为防止过拟合，这些块不会参与训练。这通常归因于不合理的 AABB 设置，请尝试调整它，看看是否能解决问题。

CityGaussian 快速上手指南

CityGaussian 系列工具专为基于高斯泼溅（Gaussian Splatting）的大规模场景高质量重建而设计，支持多 GPU 并行训练、几何精度优化及实时渲染。本指南基于最新 V2 版本（ICLR 2025），帮助您快速部署并运行。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04/22.04)
• GPU: NVIDIA 显卡，显存建议 16GB 以上（大规模场景推荐 24GB+），支持 CUDA 11.8 或 12.x
• Python: 3.8 - 3.10
• 前置依赖:
  • git
  • cmake
  • build-essential
  • ffmpeg (用于视频生成)

系统依赖安装命令：

sudo apt-get update
sudo apt-get install -y git cmake build-essential ffmpeg libgl1-mesa-glx libglib2.0-0

安装步骤

本项目已重构基于 Gaussian Lightning，推荐使用 Conda 进行环境管理。

1. 克隆仓库

git clone https://github.com/Linketic/CityGaussian.git
cd CityGaussian

2. 创建并激活虚拟环境

conda create -n citygs python=3.9 -y
conda activate citygs

3. 安装 PyTorch 与 CUDA 支持

请根据您的 CUDA 版本选择对应的安装命令（以下为 CUDA 11.8 示例，国内用户可使用清华源加速）：

# 使用清华源加速安装 PyTorch
pip install torch torchvision torchaudio --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 或者官方命令 (CUDA 11.8)
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

4. 安装项目依赖

安装核心依赖库及 Gaussian Lightning 相关组件：

pip install -r requirements.txt
pip install submodules/diff-gaussian-rasterization
pip install submodules/simple-knn

注意：如果编译 diff-gaussian-rasterization 失败，请确保已正确安装 cuda-toolkit 且 nvcc 在环境变量中。

基本使用

以下是基于 CityGaussianV2 进行大规模场景重建的最简流程。

1. 数据准备

您需要准备经过 COLMAP 处理的数据集（包含 images, sparse/0, dense 等文件夹）。 假设您的数据集位于 data/my_scene 目录下，结构如下：

data/my_scene/
├── images/
├── sparse/
│   └── 0/
│       ├── cameras.bin
│       ├── images.bin
│       └── points3D.bin
└── poses_bounds.npy (可选，若使用特定格式)

2. 启动训练

使用 train_large.py 脚本启动多块区域并行训练。以下命令展示了基础用法，自动划分场景块并进行优化：

python train_large.py -s data/my_scene --model_path output/my_scene_result --iteration 30000

关键参数说明：

• -s: 输入数据路径。
• --model_path: 模型输出及检查点保存路径。
• --iteration: 总训练迭代次数（大规模场景建议 30000+）。
• --max_cache_num: 控制内存占用，显存不足时可调小此值（默认较大，如 1024）。
• --prune_ratio: 剪枝比例，调大可进一步降低显存需求。

多 GPU 自动并行示例： CityGaussian 支持自动检测 GPU 数量并进行任务分配，无需额外配置即可利用所有可用显卡：

# 自动利用所有可见 GPU 进行分布式训练
python train_large.py -s data/my_scene --model_path output/multi_gpu_result

3. 渲染与评估

训练完成后，可使用以下命令生成渲染视频或评估指标：

生成轨迹对齐的渲染视频：

python render_video.py --model_path output/my_scene_result --trajectory_path data/my_scene/trajectory.json

评估重建质量：

python metrics.py --model_path output/my_scene_result --source_path data/my_scene

4. 网格提取 (可选)

若需获取几何网格模型（基于 2DGS 风格提取）：

python extract_mesh.py --model_path output/my_scene_result --output_mesh output/mesh.ply

---

提示：对于超大规模城市级数据，建议参考 doc/data_preparation.md 调整 AABB 边界设置以避免部分区块因数据过少而被跳过训练。