Neuralangelo

这是 Neuralangelo: 高保真神经表面重建 的官方实现。

Zhaoshuo Li, Thomas Müller, Alex Evans, Russell H. Taylor, Mathias Unberath, Ming-Yu Liu, Chen-Hsuan Lin
2023年IEEE计算机视觉与模式识别会议（CVPR）

项目页面 | 论文 | Colab笔记本

该代码基于NVIDIA深度想象力研究组的Imaginaire库构建。
如有商业咨询，请提交NVIDIA研究许可表格。

安装

我们提供两种环境设置方式：

我们提供预构建的Docker镜像，其中
- docker.io/chenhsuanlin/colmap:3.8用于运行COLMAP和数据预处理脚本。这包括预构建的COLMAP库（支持CUDA）。
- docker.io/chenhsuanlin/neuralangelo:23.04-py3用于运行主要的Neuralangelo流程。
相应的Dockerfile可以在docker目录中找到。
Neuralangelo的conda环境。安装依赖项并激活neuralangelo环境：
```
conda env create --file neuralangelo.yaml
conda activate neuralangelo
```

对于COLMAP，COLMAP网站上还提供了其他安装选项。

数据准备

请参阅数据准备获取详细说明。
我们假设已知视频中每一帧提取的相机姿态。代码使用与Instant NGP相同的json格式。

运行Neuralangelo！

EXPERIMENT=toy_example
GROUP=example_group
NAME=example_name
CONFIG=projects/neuralangelo/configs/custom/${EXPERIMENT}.yaml
GPUS=1  # 使用>1进行多GPU训练！
torchrun --nproc_per_node=${GPUS} train.py \
    --logdir=logs/${GROUP}/${NAME} \
    --config=${CONFIG} \
    --show_pbar

一些有用的注意事项：

此代码库支持使用Weights & Biases进行日志记录。您应该拥有W&B账户才能使用此功能。
- 添加--wandb命令行参数以启用W&B日志记录。
- 添加--wandb_name以指定W&B项目名称。
- 更详细的控制可以在imaginaire/trainers/base.py的init_wandb()函数中找到。
可以通过命令行覆盖配置（例如--optim.params.lr=1e-2）。
设置--checkpoint={CHECKPOINT_PATH}以使用特定的检查点初始化；设置--resume以恢复训练。
如果启用了外观嵌入，请确保将data.num_images设置为训练图像的数量。

等值面提取

使用以下命令运行等值面网格提取：

CHECKPOINT=logs/${GROUP}/${NAME}/xxx.pt
OUTPUT_MESH=xxx.ply
CONFIG=logs/${GROUP}/${NAME}/config.yaml
RESOLUTION=2048
BLOCK_RES=128
GPUS=1  # 使用>1进行多GPU网格提取
torchrun --nproc_per_node=${GPUS} projects/neuralangelo/scripts/extract_mesh.py \
    --config=${CONFIG} \
    --checkpoint=${CHECKPOINT} \
    --output_file=${OUTPUT_MESH} \
    --resolution=${RESOLUTION} \
    --block_res=${BLOCK_RES}

一些有用的注意事项：

添加--textured以提取带纹理的网格。
添加--keep_lcc以去除噪声。可能也会去除细小结构。
降低BLOCK_RES以减少GPU内存使用。
降低RESOLUTION以减小网格大小。

常见问题（FAQ）

问： CUDA内存不足。如何减少内存占用？
答： Neuralangelo在默认配置下至少需要24GB GPU内存。如果内存不足，请考虑调整model.object.sdf.encoding.hashgrid下的以下超参数（建议值）：

GPU显存超参数
8GB dict_size=20, dim=4
12GB dict_size=21, dim=4
16GB dict_size=21, dim=8

请注意，上述超参数调整可能会牺牲重建质量。

如果Neuralangelo在训练期间运行正常，但在评估期间出现CUDA内存不足，请考虑调整data.val下的评估参数，包括设置较小的image_size（例如，最大分辨率200x200），并设置batch_size=1，subset=1。
问：我的自定义数据集重建效果不佳。我该怎么办？
答：值得关注以下几点：
- COLMAP恢复的相机姿态可能不准确。我们已实现工具（使用Blender或Jupyter笔记本）来检查COLMAP结果。
- 计算的边界区域可能不准确和/或太小/太大。请参阅数据预处理了解如何手动调整边界区域。
- 视频捕捉序列可能包含严重的运动模糊或失焦帧。更高的快门速度（减少运动模糊）和更小的光圈（增加焦点范围）非常有帮助。

GPU显存	超参数
8GB	`dict_size=20`, `dim=4`
12GB	`dict_size=21`, `dim=4`
16GB	`dict_size=21`, `dim=8`

引用

如果您发现我们的代码对您的研究有用，请引用

@inproceedings{li2023neuralangelo,
  title={Neuralangelo: High-Fidelity Neural Surface Reconstruction},
  author={Li, Zhaoshuo and M\"uller, Thomas and Evans, Alex and Taylor, Russell H and Unberath, Mathias and Liu, Ming-Yu and Lin, Chen-Hsuan},
  booktitle={IEEE Conference on Computer Vision and Pattern Recognition ({CVPR})},
  year={2023}
}