Skip to content

Latest commit

 

History

History
236 lines (167 loc) · 8.48 KB

README_CN.md

File metadata and controls

236 lines (167 loc) · 8.48 KB
Raw

XRNeRF

actions LICENSE

简介

简体中文 | English

本文档提供 XRNeRF 相关用法的基本教程。对于安装说明，请参阅 安装指南。

基准

更多细节可查看 benchmark.md.

支持的场景类神经渲染方法如下：

(click to collapse)

支持的人体类神经渲染方法如下：

(click to collapse)

如果期望在XRNeRF中看到新的NeRF方法，可以张贴在愿望清单，我们会根据社区投票意见来安排下一步的计划。

数据集

我们推荐把数据集放在项目目录/data下面，否则可能需要修改config中的内容

xrnerf
├── xrnerf
├── docs
├── configs
├── test
├── extensions
├── data
│   ├── nerf_llff_data
│   ├── nerf_synthetic
│   ├── multiscale
│   ├── multiscale_google
│   ├── ...

请参阅 数据集准备 获取数据集准备的相关信息。

安装

安装方法详见教程, 我们还提供了docker镜像文件作为另一种环境安装方式。

创建模型

基本概念

在XRNeRF中，模型被分为4个部分

  • embedder: 输入点的位置和视角，输出embedded特征数据，embedder可能是纯函数型的，或者带有可学习参数的
  • mlp: 使用embedder的输出作为输入，输出原始的点数据（采样点的rgb值和密度值）送给render, 一般由多层感知机组成
  • render: 获取mlp的输出数据，沿着射线上的点进行积分等操作，输出图像上一个像素点的rgb值
  • network: 将以上三个部分组织起来，同时也是与mmcv的runner进行交互的部分，控制了训练时的loss计算和验证时的指标计算

对于上述所有模型而言，输入都是一个字典类型的data。模型使用字典data中的内容来创建新的键值对，并加入data。以origin nerf为例，最开始的data应该包含pts(尺寸为 n_rays, n_pts, 3) and viewdirs(尺寸为 n_rays, n_pts, 3).

自定义一个新模型

如果要自定义一个network，需要继承BaseNerfNetwork，其中定义了两个抽象方法

  • train_step(): training 模式下的推理和计算loss的函数.
  • val_step(): testing 模式下的推理函数.

NerfNetwork 是一个很好的例子

具体而言，如果想要实现一个具有新feature的nerf方法，有以下几步需要做

  1. 创建一个新文件如 xrnerf/models/networks/my_networks.py.

    from ..builder import NETWORKS
from .nerf import NerfNetwork

@NETWORKS.register_module()
class MyNerfNetwork(NerfNetwork):

    def __init__(self, cfg, mlp=None, mlp_fine=None, render=None):
        super().__init__(cfg, mlp, mlp_fine, render)

    def forward(self, data):
        ....

    def train_step(self, data, optimizer, **kwargs):
        ....

    def val_step(self, data, optimizer=None, **kwargs):
        ....

  2. 修改 xrnerf/models/networks/__init__.py 文件

    from .my_networks import MyNerfNetwork

  3. 修改配置文件config file 原来

    model = dict(
    type='NerfNetwork',
    ....

    现在

    model = dict(
    type='MyNerfNetwork',
    ....

同样的，要实现embedder/mlp/render的新功能，步骤与上述类似

  • 要定义一个新的embedder, 需要继承nn.Module 或者 BaseEmbedder, 并定义 forward 方法. BaseEmbedder 是个很好的例子
  • 要定义一个新的mlp, 需要继承 nn.Module 或者 BaseMLP, 并定义 forward 方法. NerfMLP 可供参考
  • 要定义一个新的render, 需要继承 nn.Module 或者 BaseRender, 并定义 forward 方法. NerfRender 可供参考

训练

迭代次数控制

XRnerf 使用 mmcv.runner.IterBasedRunner 来控制训练, 并用 mmcv.runner.EpochBasedRunner 来测试.

训练时, 配置文件的 max_iters 表示最多训练多少次. 测试时, max_iters 被强制改为1, 表示进行一次完整的epoch.

训练命令

python run_nerf.py --config configs/nerf/nerf_blender_base01.py --dataname lego

参数为:

  • --config: 配置文件位置
  • --dataname: 使用数据集下的哪个数据来训练

测试

python run_nerf.py --config configs/nerf/nerf_blender_base01.py --dataname lego --test_only --load_from iter_200000.pth

参数为:

  • --config: 配置文件位置
  • --dataname: 使用数据集下的哪个数据
  • --test_only: 切换为测试模式
  • --load_from: 重载覆盖掉原来配置文件里的 load_from， 在某些情况下为了方便而使用

详细教程

目前, XRNeRF 提供以下几种更详细的教程

除此以外，文档还包括以下内容

引用

@misc{xrnerf,
    title={OpenXRLab Neural Radiance Field Toolbox and Benchmark},
    author={XRNeRF Contributors},
    howpublished = {\url{https://github.com/openxrlab/xrnerf}},
    year={2022}
}

参与贡献

我们非常欢迎用户对于 XRNeRF 做出的任何贡献，可以参考 贡献指南 文件了解更多细节

致谢

XRNeRF 是一款由不同学校和公司共同贡献的开源项目。我们感谢所有为项目提供算法复现和新功能支持的贡献者，以及提供宝贵反馈的用户。 我们希望该工具箱和基准测试可以为社区提供灵活的代码工具，供用户复现现有算法并开发自己的新模型，从而不断为开源社区提供贡献。

OpenXRLab中的其他项目

  • XRPrimer: OpenXRLab foundational library for XR-related algorithms.
  • XRSLAM: OpenXRLab Visual-inertial SLAM Toolbox and Benchmark.
  • XRSfM: OpenXRLab Structure-from-Motion Toolbox and Benchmark.
  • XRLocalization: OpenXRLab Visual Localization Toolbox and Server.
  • XRMoCap: OpenXRLab Multi-view Motion Capture Toolbox and Benchmark.
  • XRMoGen: OpenXRLab Human Motion Generation Toolbox and Benchmark.
  • XRNeRF: OpenXRLab Neural Radiance Field (NeRF) Toolbox and Benchmark.