<img src="https://img.shields.io/badge/Trainer-就绪-green"/> <img src="https://img.shields.io/badge/Renderer-就绪-green"/> <img src="https://img.shields.io/badge/Framework-就绪-green"/> <img src="https://img.shields.io/badge/Documentation-预览-purple"/> <img src="https://img.shields.io/badge/License-MIT-orange"/> <picture> <img src="https://yellow-cdn.veclightyear.com/835a84d5/bc3375c9-876a-4251-8987-3e1ddcd46c7f.svg" width="350"> </picture> <picture> <img src="https://yellow-cdn.veclightyear.com/835a84d5/5bc3305a-7dd8-42c4-8e6a-e065d9810672.png?raw=true" width="650"> </picture> 🌏随心所欲地用NeRF重建全球 <picture> <img src="https://yellow-cdn.veclightyear.com/835a84d5/97b1c433-9616-43c0-b431-dd3d24bfbcc7.gif?raw=true" width="300"> </picture> <picture> <img src="https://yellow-cdn.veclightyear.com/835a84d5/82d7aff7-b761-4eaf-9b92-d35da965af43.gif?raw=true" width="300"> </picture> <picture> <img src="https://yellow-cdn.veclightyear.com/835a84d5/7abb0ebb-827b-4b24-bb59-03afefb685b3.gif?raw=true" width="300"> </picture> <picture> <img src="https://yellow-cdn.veclightyear.com/835a84d5/38a49dfa-d1fb-4021-850b-86195ab02c94.gif?raw=true" width="300"> </picture> <a href="https://landmark.intern-ai.org.cn/"> 🏠主页 </a> | <a href="https://internlandmark.github.io/LandMark_Documentation/"> 📑文档站点 </a> | <a href="https://city-super.github.io/gridnerf/"> ✍️论文页面 </a> | <a href="https://city-super.github.io/matrixcity/"> 🏬MatrixCity </a>

💻 关于

这个代码库包含了LandMark项目的源代码，这是一个开创性的大规模3D真实世界城市场景建模和渲染系统。该项目是基于GridNeRF（CVPR23）构建的。更多详细信息请参考论文和项目页面。

在GridNeRF的基础上，LandMark通过并行化、优化算子和内核，以及改进算法，大幅提高了训练和渲染效率。主要包括：

大规模、高质量的新视角渲染：
- 首次实现了在超过100平方公里的城市数据上高效训练3D神经场景；渲染分辨率达到了4K。我们使用超过2000亿个可学习参数来建模场景。
多项功能扩展：
- 除了渲染，我们还展示了布局调整（如移除或添加建筑物）和场景风格化（如改变光照和季节）等功能。
集成训练和渲染系统：
- 我们提供了一个涵盖算法、算子和计算系统的完整系统，为现实世界3D大模型的训练、渲染和应用奠定了坚实基础。
分布式渲染系统：
- 用于大规模GridNeRF模型的实时渲染。

现在，您可以训练和渲染自己的LandMark模型，尽情发挥创意。

您的点赞和对社区的贡献正是我们所需要的！

🎨 支持的功能

LandMark目前支持以下功能：

GridNeRF顺序模型训练
GridNeRF并行模型训练
- 分支并行
- 平面并行
- 通道并行
GridNeRF混合并行训练（模型并行和DDP训练）
GridNeRF顺序模型渲染
训练和渲染都支持Pytorch DDP
支持MatrixCity数据集
实时分布式渲染系统
支持动态获取的参数加载器，可支持无限区域

强烈建议阅读文档，了解我们并行加速和动态获取策略的实现细节。

🚀 快速开始

先决条件

您必须拥有一张NVIDIA GPU卡，并在系统上安装了CUDA。这个库已经在单个和多个A100 GPU上进行了测试。

安装LandMark

LandMark代码库包含配置文件，帮助您创建合适的环境

git clone https://github.com/InternLandMark/LandMark.git
cd ./LandMark
export PYTHONPATH=$YOUR_PREFIX_PATH/LandMark/:$PYTHONPATH

创建环境

我们建议使用Conda来管理复杂的依赖关系：

cd LandMark
conda create --name landmark -y python=3.9.16
conda activate landmark
python -m pip install --upgrade pip

这个库已经在Python版本3.9.16上进行了测试。

Pytorch & CUDA

使用以下命令一次性安装带CUDA的pytorch：

pip install torch==1.13.1+cu116 torchvision==0.14.1+cu116 --extra-index-url https://download.pytorch.org/whl/cu116

这个库已经在CUDA版本11.6上进行了测试。

依赖项

我们提供了requirements.txt文件，方便您轻松设置环境。

pip install -r requirements.txt

准备数据集

出于保密要求，我们使用的原生数据集（如上所示）不会公开。为了理想地复现结果，强烈推荐使用MatrixCity数据集。关于如何复现的更多细节，请参考以下章节：MatrixCity数据集。我们已经为MatrixCity数据集准备了调优后的配置文件和专用的数据加载器。

从真实世界捕获的大规模场景最适合我们的方法。我们建议使用一栋建筑物、一个知名地标甚至一个小镇的数据集。准备大约250~300张重建目标的图像。确保有足够的重叠。

按照以下结构重新组织您的数据集：

your_dataset/
- images/
  - image_0.png
  - image_1.png
  - image_2.png
  - ...
- transforms_train.json
- transforms_test.json

images/文件夹包含训练集和测试集的所有图像。 transforms_xxx.json中支持多焦距和单焦距格式的相机姿态。

### 单焦距示例 ###
{
    "camera_model": "SIMPLE_PINHOLE",
    "fl_x": 427,
    "fl_y": 427,
    "w": 547,
    "h": 365,
    "frames": [
        {
            "file_path": "./images/image_0.png",
            "transform_matrix": []
        }
    ]
}

### 多焦距示例 ###
{
    "camera_model": "SIMPLE_PINHOLE",
    "frames": [
        {
            "fl_x": 1116,
            "fl_y": 1116,
            "w": 1420,
            "h": 1065,
            "file_path": "./images/image_0.png",
            "transform_matrix": []
        }
    ]
}

像其他NeRF方法一样，使用COLMAP提取姿态和sparse点云模型。然后使用以下命令转换姿态数据：

python app/tools/colmap2nerf.py --recon_dir data/your_dataset/sparse/0 --output_dir data/your_dataset

在your_dataset/文件夹中将生成支持单焦距的transforms_train.json和transforms_test.json文件。 参考app/tools/config_parser.py和app/tools/dataloader/city_dataset.py获取帮助。

设置参数

我们提供了一个配置文件confs/city.txt作为示例，帮助您初始化实验。 有许多参数可供自定义。为了更好地理解，我们将它们分为四种类型。 这里展示了一些重要的参数。在继续之前，别忘了指定与路径相关的参数。

experiment
- dataroot - 数据集的基础路径。使用LandMark/datasets来管理所有数据集
- datadir - 您的数据集路径。这是相对于数据集基础路径的相对路径
- dataset_name - 设置数据加载器的类型，而不是数据集。建议使用"city"
- basedir - 保存训练检查点的位置。默认使用LandMark/log
train
- start_iters - 训练中的起始迭代次数
- n_iters - 训练中的总迭代次数
- batch_size - 训练批量大小
- add_nerf - 在哪个迭代开始使用nerf分支
render
- sampling_opt - 渲染时是否使用采样优化
model
- resMode - 多分辨率模型中的分辨率模式

关于参数的更多详细信息，请参考LandMark/app/config_parser.py 调整--ub和--lb参数以在实验中获得理想结果。

训练模型

现在是时候训练您自己的LandMark模型了：

python app/trainer.py --config confs/city.txt

训练检查点和图像默认将保存在LandMark/log/your_expname中。

渲染图像

训练过程完成后，可以进行独立的渲染测试：

python app/renderer.py --config confs/city.txt --ckpt=log/your_expname/your_expname.th

渲染结果默认将保存在LandMark/log/your_expname/imgs_test_all中。

📖了解更多

目录结构

app/
- models/ - 包含GridNeRF模型的顺序、并行和动态获取实现
- tools/ - 包含数据加载器、训练/渲染工具
- tests/ - 包含完整性测试脚本
- trainer.py - 管理训练过程
- renderer.py - 管理渲染过程
confs/ - 包含实验的配置文件
dist_renders - 关于分布式渲染系统的代码、介绍和脚本
requirements.txt - pip的环境配置文件

Pytorch分布式数据并行支持

训练器和渲染器都支持pytorch DDP。 要使用DDP进行训练，请使用以下命令：

python -m torch.distributed.launch --nproc_per_node=GPU数量 app/trainer.py --config confs/city.txt

要使用DDP进行渲染，请使用以下命令：

python -m torch.distributed.launch --nproc_per_node=GPU数量 app/renderer.py --config confs/city.txt --ckpt=log/your_expname/your_expname.th

可能需要正确设置一些与多GPU环境相关的参数。根据您的实际环境指定GPU数量。

例如：

如果使用N个GPU训练顺序gridnerf模型，将启用N倍DDP训练
如果使用分支并行和平面划分[2,2]配置训练gridnerf模型，并且使用的GPU总数为N，将启用N/(2x2)倍DDP训练。

使用LandMark模型并行方法进行训练

目前支持三种类型的模型并行策略进行训练：

通道并行
平面并行
分支并行

值得指出的是，所有这些策略都适用于超过2000张图像和几英亩面积的大规模场景重建。要在实验中包含这些并行特性，只需使用像 confs/city_multi_branch_parallel.txt 这样的配置文件。在配置文件中设置好路径参数后，就可以训练即插即用的分支并行模型了：

python -m torch.distributed.launch --nproc_per_node=GPU数量 app/trainer.py --config confs/city_multi_branch_parallel.txt

使用DDP训练分支并行模型和顺序模型在使用上几乎没有区别，但训练效率得到了极大提升。尤其是在大规模场景的重建任务中，我们的并行策略在加速整个训练过程方面表现出稳定的适应能力。

训练后要用并行模型进行渲染，使用与顺序模型相同的命令

python app/renderer.py --config confs/city_multi_branch_parallel.txt --ckpt=log/你的实验名称/你的实验名称.th

数据集准备

完全支持出色的MatrixCity数据集。confs/matrixcity 中为 block_1 和 block_2 提供了专门的文件。 建议从 OpenXLab 或百度网盘（密码：hqnn）下载数据集。 需要下载以下文件并按原目录结构组织：

MatrixCity/small_city/aerial/train/block_1.tar
MatrixCity/small_city/aerial/train/block_2.tar
MatrixCity/small_city/aerial/test/block_1_test.tar
MatrixCity/small_city/aerial/test/block_2_test.tar
MatrixCity/small_city/aerial/pose/block_A/

下载后，需要使用 tar -xf [tar文件名] 解压tar文件

最后，需要在配置文件中正确设置 dataroot、datadir 和 dataset_name，如下所示：

dataroot = 你的MATRIXCITY文件夹路径/small_city/aerial/pose
datadir = block_A
dataset_name = matrixcity

使用MatrixCity数据集进行测试

对于单GPU训练和渲染，只需使用：

# 训练
python app/trainer.py --config confs/matrixcity/matrixcity_2block_multi.txt

# 渲染
python app/renderer.py --config confs/matrixcity/matrixcity_2block_multi.txt --ckpt log/matrix_city_block_1+2_multi/matrix_city_block_1+2_multi.th

对于多GPU DDP训练和渲染：

# 训练
python -m torch.distributed.launch --nproc_per_node=GPU数量 app/trainer.py --config confs/matrixcity/matrixcity_2block_multi.txt

# 单GPU渲染
python app/renderer.py --config confs/matrixcity/matrixcity_2block_multi.txt --ckpt log/matrix_city_block_1+2_multi/matrix_city_block_1+2_multi.th

# 多GPU渲染
python -m torch.distributed.launch --nproc_per_node=GPU数量  app/renderer.py --config confs/matrixcity/matrixcity_2block_multi.txt --ckpt log/matrix_city_block_1+2_multi/matrix_city_block_1+2_multi.th

其他训练并行方法也可用：

python -m torch.distributed.launch --nproc_per_node=GPU数量 app/trainer.py --config confs/matrixcity_2block_multi_branch_parallel.txt

为了让用户快速上手，我们提供了两个检查点，它们基于以下两个命令训练：

# matrix_city_block_1+2_multi.th
python app/trainer.py --config confs/matrixcity/matrixcity_2block_multi.txt

# matrix_city_block_1+2_multi_lowquality.th
python app/trainer.py --config confs/matrixcity/matrixcity_2block_lowquality.txt

如果你想跳过训练阶段，可以直接下载它们并使用以下命令进行渲染。

# matrix_city_block_1+2_multi.th
python app/renderer.py --config confs/matrixcity/matrixcity_2block_multi.txt --ckpt 你的目录/matrix_city_block_1+2_multi.th

# matrix_city_block_1+2_multi_lowquality.th
python app/renderer.py --config confs/matrixcity/matrixcity_2block_lowquality.txt --ckpt 你的目录/matrix_city_block_1+2_multi_lowquality.th