Horizon-GS 部署全攻略从数据集下载到三维重建实战手把手教你搭建大规模航拍-地面联合三维重建环境跑通 Horizon-GS 完整流程写在前面在数字孪生、自动驾驶、VR/AR 等领域能够同时融合航拍视角俯视大范围与地面街景视角近景细节的三维重建技术一直是个挑战。现有的 3D Gaussian Splatting3D-GS方法大多只针对单一视角跨视角融合时容易出现视角差异大、数据不均衡、梯度冲突等问题。Horizon-GS 正是为了解决这一痛点而生的。它通过创新的两阶段训练策略粗阶段 精阶段和分块合并机制实现了对超大城市级场景的统一高质量重建并且支持实时渲染。本文将为你提供一份从零开始、精确到每条命令的部署指南涵盖环境配置、数据集下载重点解决国内网络和磁盘空间问题、预处理、训练小场景 大场景、评估及常见问题排错。跟着做你一定能跑通。一、准备工作检查你的硬件与系统在敲任何命令前请先确认你的服务器满足以下最低要求项目推荐配置操作系统Ubuntu 20.04 / 22.04 (Windows/WSL2 也可但更复杂)GPUNVIDIA 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-GS2.2 创建 Conda 环境项目根目录下已经提供了environment.yml文件它会自动安装 Python 3.11、PyTorch、CUDA 工具包以及专用的gsplat库。condaenvcreate--fileenvironment.yml conda activate horizon_gs如果下载依赖缓慢可以给 conda 换国内源如清华源但environment.yml中也可能包含 pip 包请耐心等待。2.3 验证环境python-cimport torch; print(torch.cuda.is_available())# 应输出 Truepython-cimport 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-Uhuggingface_hub[hf]# 设置镜像源exportHF_ENDPOINThttps://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-pHorizonGScdHorizonGSwget-r-np-nH--cut-dirs4-Rindex.html*-erobotsoff\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/HorizonGScd/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默认 30000aerial_sample_weight通常设为 25比地面权重高。训练过程中会定期保存模型到output/HorizonGS/coarse/point_cloud/iteration_xxxxx/。可以在另一个终端运行tensorboard --logdir output/来监控 loss 曲线。精阶段 (Fine)粗阶段完成后加载粗阶段最后的模型启用地面图像的精细化训练。python train.py--configconfig/HorizonGS/fine.yamlfine.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 或 .objpython 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.8TPermission denied读取子目录文件夹权限不够用sudo du -sh查看或用sudo chown -R $USER:$USER /path修改所有者ModuleNotFoundError: No module named gsplatgsplat 没装好pip install gsplat或重新执行conda env createCUDA 报错invalid device functionPyTorch CUDA 版本与驱动不匹配检查nvcc --version和python -c import torch; print(torch.version.cuda)不一致则重新安装 PyTorch训练 loss 一直不下降预处理错误或配置文件路径不对检查coarse.yaml中的source_path是否指向processed目录确认航拍和地面图像都能被正确加载合并后出现明显接缝分块重叠区域太小或融合权重不合适增大预处理时的overlap参数如 20→30 米或修改merge.py中的加权平滑半径八、写在最后你的下一步现在你已经成功将 Horizon-GS 跑通了你可以在自己的数据上尝试只需将自己的航拍和街景图像用 COLMAP 重建出相机位姿然后模仿data/HorizonGS的结构组织文件夹再运行预处理和训练即可。如果你在部署过程中遇到其他奇怪的问题欢迎在评论区留言记得附上完整的错误日志。希望这篇博文能帮你节省大量踩坑时间让你专注于三维重建本身的研究与应用。Happy Reconstructing! 参考链接Horizon-GS 官方项目页论文 PDFHugging Face 镜像站 hf-mirror.com
Horizon-GS 部署全攻略：从数据集下载到三维重建实战
发布时间：2026/6/14 22:57:34
Horizon-GS 部署全攻略从数据集下载到三维重建实战手把手教你搭建大规模航拍-地面联合三维重建环境跑通 Horizon-GS 完整流程写在前面在数字孪生、自动驾驶、VR/AR 等领域能够同时融合航拍视角俯视大范围与地面街景视角近景细节的三维重建技术一直是个挑战。现有的 3D Gaussian Splatting3D-GS方法大多只针对单一视角跨视角融合时容易出现视角差异大、数据不均衡、梯度冲突等问题。Horizon-GS 正是为了解决这一痛点而生的。它通过创新的两阶段训练策略粗阶段 精阶段和分块合并机制实现了对超大城市级场景的统一高质量重建并且支持实时渲染。本文将为你提供一份从零开始、精确到每条命令的部署指南涵盖环境配置、数据集下载重点解决国内网络和磁盘空间问题、预处理、训练小场景 大场景、评估及常见问题排错。跟着做你一定能跑通。一、准备工作检查你的硬件与系统在敲任何命令前请先确认你的服务器满足以下最低要求项目推荐配置操作系统Ubuntu 20.04 / 22.04 (Windows/WSL2 也可但更复杂)GPUNVIDIA 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-GS2.2 创建 Conda 环境项目根目录下已经提供了environment.yml文件它会自动安装 Python 3.11、PyTorch、CUDA 工具包以及专用的gsplat库。condaenvcreate--fileenvironment.yml conda activate horizon_gs如果下载依赖缓慢可以给 conda 换国内源如清华源但environment.yml中也可能包含 pip 包请耐心等待。2.3 验证环境python-cimport torch; print(torch.cuda.is_available())# 应输出 Truepython-cimport 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-Uhuggingface_hub[hf]# 设置镜像源exportHF_ENDPOINThttps://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-pHorizonGScdHorizonGSwget-r-np-nH--cut-dirs4-Rindex.html*-erobotsoff\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/HorizonGScd/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默认 30000aerial_sample_weight通常设为 25比地面权重高。训练过程中会定期保存模型到output/HorizonGS/coarse/point_cloud/iteration_xxxxx/。可以在另一个终端运行tensorboard --logdir output/来监控 loss 曲线。精阶段 (Fine)粗阶段完成后加载粗阶段最后的模型启用地面图像的精细化训练。python train.py--configconfig/HorizonGS/fine.yamlfine.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 或 .objpython 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.8TPermission denied读取子目录文件夹权限不够用sudo du -sh查看或用sudo chown -R $USER:$USER /path修改所有者ModuleNotFoundError: No module named gsplatgsplat 没装好pip install gsplat或重新执行conda env createCUDA 报错invalid device functionPyTorch CUDA 版本与驱动不匹配检查nvcc --version和python -c import torch; print(torch.version.cuda)不一致则重新安装 PyTorch训练 loss 一直不下降预处理错误或配置文件路径不对检查coarse.yaml中的source_path是否指向processed目录确认航拍和地面图像都能被正确加载合并后出现明显接缝分块重叠区域太小或融合权重不合适增大预处理时的overlap参数如 20→30 米或修改merge.py中的加权平滑半径八、写在最后你的下一步现在你已经成功将 Horizon-GS 跑通了你可以在自己的数据上尝试只需将自己的航拍和街景图像用 COLMAP 重建出相机位姿然后模仿data/HorizonGS的结构组织文件夹再运行预处理和训练即可。如果你在部署过程中遇到其他奇怪的问题欢迎在评论区留言记得附上完整的错误日志。希望这篇博文能帮你节省大量踩坑时间让你专注于三维重建本身的研究与应用。Happy Reconstructing! 参考链接Horizon-GS 官方项目页论文 PDFHugging Face 镜像站 hf-mirror.com
![[智能体-404]：应用 - Make平台搭建智能体与AI原生的低代码智能体平台的比较](http://pic.xiahunao.cn/yaotu/[智能体-404]：应用 - Make平台搭建智能体与AI原生的低代码智能体平台的比较)
