当前位置：首页 > news >正文

Horizon-GS 部署全攻略：从数据集下载到三维重建实战

news 2026/6/14 22:57:31

Horizon-GS 部署全攻略：从数据集下载到三维重建实战

手把手教你搭建大规模航拍-地面联合三维重建环境，跑通 Horizon-GS 完整流程

写在前面

在数字孪生、自动驾驶、VR/AR 等领域，能够同时融合航拍视角（俯视大范围）与地面街景视角（近景细节）的三维重建技术一直是个挑战。现有的 3D Gaussian Splatting（3D-GS）方法大多只针对单一视角，跨视角融合时容易出现视角差异大、数据不均衡、梯度冲突等问题。

Horizon-GS 正是为了解决这一痛点而生的。它通过创新的两阶段训练策略（粗阶段 + 精阶段）和分块合并机制，实现了对超大城市级场景的统一高质量重建，并且支持实时渲染。

本文将为你提供一份从零开始、精确到每条命令的部署指南，涵盖环境配置、数据集下载（重点解决国内网络和磁盘空间问题）、预处理、训练（小场景 & 大场景）、评估及常见问题排错。跟着做，你一定能跑通。

一、准备工作：检查你的硬件与系统

在敲任何命令前，请先确认你的服务器满足以下最低要求：

项目	推荐配置
操作系统	Ubuntu 20.04 / 22.04 (Windows/WSL2 也可，但更复杂)
GPU	NVIDIA RTX 3090 / 4090 / A5000 或同等算力
显存	24GB 以上（小场景可降至 12GB，需调低 batch_size）
磁盘空间	至少50GB（用于代码、数据集、训练输出）
CUDA 版本	11.6 或更高（使用`nvidia-smi`查看）
Python 版本	3.11（项目环境文件已锁定）

⚠️重要：如果你的/data分区已满（比如只剩 0% 可用），请提前规划好数据存放路径（例如/home分区）。后面会详细教你怎么处理。

二、一键配置环境（Conda + 依赖）

2.1 克隆项目代码（含子模块）

# 克隆主仓库，--recursive 会同时拉取依赖的子模块（如 gsplat 变体）gitclone https://github.com/city-super/Horizon-GS.git--recursivecdHorizon-GS

2.2 创建 Conda 环境

项目根目录下已经提供了environment.yml文件，它会自动安装 Python 3.11、PyTorch、CUDA 工具包以及专用的gsplat库。

condaenvcreate--fileenvironment.yml conda activate horizon_gs

如果下载依赖缓慢，可以给 conda 换国内源（如清华源），但environment.yml中也可能包含 pip 包，请耐心等待。

2.3 验证环境

python-c"import torch; print(torch.cuda.is_available())"# 应输出 Truepython-c"import gsplat; print(gsplat.__version__)"# 应输出版本号（如 1.2.0）

如果以上命令报错，说明环境没装好，请重新执行conda env create或手动补装缺失包。

三、下载 HorizonGS 数据集（核心难点）

Horizon-GS 官方提供了三个数据集：HorizonGS、UCGS、MatrixCity。本文以最核心的HorizonGS为例，讲解完整的下载与组织方法。

3.1 选择国内镜像源（解决下载慢/连不上）

Hugging Face 官方源在国内访问极不稳定，我们使用镜像站hf-mirror.com。

3.2 方法一：使用`hf`命令行工具（推荐）

# 安装 huggingface_hub 并启用 hf 命令pipinstall-U"huggingface_hub[hf]"# 设置镜像源exportHF_ENDPOINT=https://hf-mirror.com# 创建数据目录（假设存放在 /home/admin/HorizonGS，因为 /data 可能没空间）mkdir-p/home/admin/HorizonGScd/home/admin# 开始下载（支持断点续传）hf download BoDai/HorizonGS\--repo-type dataset\--local-dir ./HorizonGS\--resume

参数解释：

--repo-type dataset：告诉工具下载的是数据集（而不是模型）
--local-dir：本地保存路径
--resume：如果中断，下次执行会继续

预期结果：你会看到进度条，最终在/home/admin/HorizonGS下得到完整的数据集文件。

3.3 方法二：使用`wget`递归下载（备用方案）

如果你不想安装huggingface_hub，或者担心其缓存占用双倍空间，可以用wget直接拉取：

cd/home/adminmkdir-pHorizonGS&&cdHorizonGSwget-r-np-nH--cut-dirs=4-R"index.html*"-erobots=off\https://hf-mirror.com/datasets/BoDai/HorizonGS/resolve/main/

该命令会递归下载所有文件，并剔除index.html等无用文件。

3.4 处理磁盘空间不足（经典问题）

如果你在执行hf download时遇到OSError: [Errno 28] No space left on device，说明目标分区已满。解决方案：

检查各分区剩余空间：
```
df-h
```
找到可用空间大的分区，例如/home有 212GB，/有 796GB。

更改下载目录到有空间的分区：

cd/home/admin# 或 cd /root# 然后执行上面的下载命令

软链接到项目的数据目录（让项目能找到数据）：
假设你的项目代码在/home/admin/Horizon-GS，数据集实际在/home/admin/HorizonGS：
```
cd/home/admin/Horizon-GSmkdir-pdataln-s/home/admin/HorizonGS data/HorizonGS
```
这样项目就能通过data/HorizonGS访问数据了，无需移动实际文件。

3.5 验证数据集结构

下载完成后，数据目录应大致如下（具体以官方提供的为准）：

HorizonGS/ ├── aerial/ │ ├── images/ # 航拍原始图片 │ └── sparse/0/ # COLMAP 输出的相机参数与点云 ├── street/ │ ├── images/ # 街景图片 │ └── sparse/0/ └── config.yaml # 数据集全局配置（可能不存在，需预处理生成）

注意：原始下载的文件夹可能不叫HorizonGS，请根据实际名称调整软链接。

四、数据预处理：生成训练配置

在正式训练前，必须运行预处理脚本，它会解析相机参数、划分训练/验证集、生成后续训练所需的cameras.json等文件。

cd/home/admin/Horizon-GS# 进入项目根目录# 执行预处理（以 HorizonGS 为例）python preprocess/data_preprocess.py--configconfig/HorizonGS/config.yaml

如果项目提供的config/HorizonGS/config.yaml不存在，你可以参考其他数据集的配置文件手动创建一个，或者直接修改路径。核心内容如下：

# config/HorizonGS/config.yaml 示例（需根据实际调整）data:root_dir:"data/HorizonGS"# 数据集根目录aerial_dir:"aerial"# 航拍子文件夹street_dir:"street"# 街景子文件夹output_dir:"processed"# 预处理输出目录

预处理完成后，会在data/HorizonGS/processed下生成cameras.json、points3D.ply等文件，并输出类似下面的日志：

Preprocessing finished. Total aerial images: 1200, street images: 3400. Saved cameras to data/HorizonGS/processed/cameras.json.

五、模型训练（粗→细两阶段）

Horizon-GS 的核心创新就是两阶段训练。你必须先执行 coarse 阶段，再执行 fine 阶段，不能跳过。

5.1 小场景训练（如 Block_small）

粗阶段 (Coarse)

该阶段主要依赖航拍图像学习全局几何骨架。

python train.py--configconfig/HorizonGS/coarse.yaml

配置文件coarse.yaml中，max_iters默认 30000，aerial_sample_weight通常设为 2～5（比地面权重高）。
训练过程中会定期保存模型到output/HorizonGS/coarse/point_cloud/iteration_xxxxx/。
可以在另一个终端运行tensorboard --logdir output/来监控 loss 曲线。

精阶段 (Fine)

粗阶段完成后，加载粗阶段最后的模型，启用地面图像的精细化训练。

python train.py--configconfig/HorizonGS/fine.yaml

fine.yaml中会指定load_from = "output/HorizonGS/coarse/point_cloud/iteration_30000"这类路径。
此阶段会冻结航拍高斯的空间属性（位置、协方差），只优化颜色和不透明度；同时地面高斯全参数优化并启用密度控制。

5.2 大场景训练（如 Block_A）

对于超过 1 平方公里的城市级场景，需要使用分块训练避免显存爆炸。

步骤概览：预处理 → 对各块分别执行 coarse → 对各块分别执行 fine → 合并所有块。

# 1. 预处理（生成分块信息）python preprocess/data_preprocess.py--configconfig/Block_A/config.yaml# 2. 训练每个块的 coarse（假设分成了 16 块，项目脚本会自动循环或手动指定）python train.py--configconfig/Block_A/coarse_chunk0.yaml python train.py--configconfig/Block_A/coarse_chunk1.yaml# ... 依次执行# 3. 训练每个块的 finepython train.py--configconfig/Block_A/fine_chunk0.yaml# ...# 4. 合并所有块的最终模型python merge.py-moutput/Block_A--configconfig/Block_A/config.yaml

具体 chunk 的数量和名称在预处理时自动生成，你可以在config/Block_A/下看到多个 yaml 文件。

六、评估与渲染

训练完成后，使用以下命令生成渲染结果并计算指标。

# 渲染测试集的所有视角图片python render.py-moutput/HorizonGS/fine/point_cloud/iteration_30000# 计算 PSNR, SSIM, LPIPSpython metrics.py-moutput/HorizonGS/fine/point_cloud/iteration_30000# 导出为 mesh 文件（.ply 或 .obj）python export_mesh.py-moutput/HorizonGS/fine/point_cloud/iteration_30000

渲染的图片会保存在<model_path>/renders下，指标会打印在终端并保存到results.json。

七、常见问题与解决方案（FAQ）

错误现象	可能原因	解决方法
`hf: command not found`	没有安装 huggingface_hub 或未启用 hf 命令	`pip install -U "huggingface_hub[hf]"`
`No space left on device`	磁盘分区已满	使用`df -h`查看，换到`/home`等有空间的分区下载；或清理旧数据（如`sudo rm -rf /data/mengjun`释放 3.8T）
`Permission denied`读取子目录	文件夹权限不够	用`sudo du -sh`查看，或用`sudo chown -R $USER:$USER /path`修改所有者
`ModuleNotFoundError: No module named 'gsplat'`	gsplat 没装好	`pip install gsplat`，或重新执行`conda env create`
CUDA 报错`invalid device function`	PyTorch CUDA 版本与驱动不匹配	检查`nvcc --version`和`python -c "import torch; print(torch.version.cuda)"`，不一致则重新安装 PyTorch
训练 loss 一直不下降	预处理错误或配置文件路径不对	检查`coarse.yaml`中的`source_path`是否指向`processed`目录；确认航拍和地面图像都能被正确加载
合并后出现明显接缝	分块重叠区域太小或融合权重不合适	增大预处理时的`overlap`参数（如 20→30 米），或修改`merge.py`中的加权平滑半径