# EmerNeRF

**Repository Path**: Fj1225815367/EmerNeRF

## Basic Information

- **Project Name**: EmerNeRF
- **Description**: PyTorch Implementation of EmerNeRF: Emergent Spatial-Temporal Scene Decomposition via Self-Supervision
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2024-01-01
- **Last Updated**: 2024-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EmerNeRF

PyTorch 实现：
> [**EmerNeRF: 通过自监督实现的紧急时空场景分解**](https://arxiv.org/abs/2311.02077),  
> [Jiawei Yang](https://jiawei-yang.github.io), [Boris Ivanovic](https://www.borisivanovic.com/), [Or Litany](https://orlitany.github.io/), [Xinshuo Weng](https://www.xinshuoweng.com/), [Seung Wook Kim](https://seung-kim.github.io/seungkim/), [Boyi Li](https://sites.google.com/site/boyilics/home), [Tong Che](), [Danfei Xu](https://faculty.cc.gatech.edu/~danfei/), [Sanja Fidler](https://www.cs.utoronto.ca/~fidler/), [Marco Pavone](https://web.stanford.edu/~pavone/), [Yue Wang](https://yuewang.xyz/)

#### [项目页面](https://emernerf.github.io) | [论文](https://arxiv.org/abs/2311.02077)

<p align="center">
  <img src="assets/overview.png" alt="EmerNeRF overview">
</p>

## 新闻

- [2023/11/05] 我们发布了 EmerNeRF 的初始版本，支持从 Waymo Open Dataset 获取的 NeRF On-The-Road (NOTR) 数据集。同时也支持 NuScenes。
## 目录

- [引言](#introduction)
- [安装](#installation)
- [数据集准备](#dataset-preparation)
- [运行代码](#run-the-code)
  - [配置](#configs)
  - [训练](#training)
  - [体素检查](#voxel-inspection)
- [预训练模型](#pretrained-models)
- [引用](#citation)
- [常见问题解答](docs/FAQ.md)

## 引言

我们介绍了 EmerNeRF，这是一种利用神经场进行时空分解、运动估计和基础特征提取的自监督方法。EmerNeRF 能够以自监督的方式将场景分解为动态对象和静态背景，并估计它们的运动。通过在 4D 时空中提取和“去噪”2D 特征，EmerNeRF 为场景理解揭示了新的潜力。此外，我们发布了 NeRF On-The-Road（NOTR）数据集分割，以支持未来的研究。
## 安装

我们的代码是在 Ubuntu 22.04 上使用 Python 3.9 和 PyTorch 2.0 开发的。请注意，该代码仅在这些指定的版本上进行了测试。我们建议使用 conda 安装依赖项。安装过程可能需要超过 30 分钟。
1. 创建 `emernerf` conda 环境并安装所有依赖项：

```shell
conda create -n emernerf python=3.9 -y
conda activate emernerf
# 这将需要一些时间：超过10分钟。
pip install -r requirements.txt
```

2. 手动安装`nerfacc`和`tiny-cuda-nn`：

```shell
pip install git+https://github.com/KAIR-BAIR/nerfacc.git
pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch
```

**故障排除**:

<details>
  <summary><strong>nvcc fatal : Unsupported gpu architecture 'compute_89` </strong></summary>

如果遇到错误 `nvcc fatal : Unsupported gpu architecture 'compute_89`，请尝试以下命令：

```
TCNN_CUDA_ARCHITECTURES=86 pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch
```

</details>

<details>
  <summary><strong>error: parameter packs not expanded with ‘...’</strong></summary>

如果你遇到这个错误：

 ```
 error: parameter packs not expanded with ‘...’
 ```

在GitHub上参考[这个解决方案](<https://github.com/NVlabs/instant-ngp/issues/119#issuecomment-1034701258>)。

</details>

## 数据准备

- **NOTR (Waymo) 数据集**: 查看 [NOTR 数据集准备](docs/NOTR.md) 以获取有关准备 NOTR 数据集的详细说明。
  
- **NuScenes 数据集**: 有关准备NuScenes数据集以及查看示例样本结果的详细说明，请参阅[NuScenes数据集准备](docs/NUSCENES.md)。

如果您有兴趣设置自定义数据集，请使用这两个数据集作为模板。同时，请查看`datasets/base`目录，以熟悉我们代码库中的数据集准备流程。  

## 运行代码

### 配置

我们在 `configs/default_config.yaml` 文件中为每个配置提供了详细的注释。在发布的代码中，您还会找到这些详细的注释。

### 训练

样本训练脚本可以在 `sample_scripts/` 目录中找到。

1. **数据检查**. 在开始训练之前，您可能希望检查数据。我们已经包含了一个用于可视化数据的脚本。要可视化 NOTR 数据集，请执行以下操作：

```shell
# 根据需要调整超参数。
python train_emernerf.py \
    --config_file configs/default_config.yaml \
    --output_root $output_root \
    --project $project \
    --run_name ${scene_idx} \
    --render_data_video_only \  # 这将渲染数据的视频。
    data.scene_idx=$scene_idx \
    data.pixel_source.load_size=[160,240] \ # 进行下采样以增强激光雷达点的可见性。
    data.pixel_source.num_cams=3 \ # Opt for 1, 3, or 5
    data.start_timestep=0 \
    data.end_timestep=-1 

```

此脚本会生成一个视频，类似于下面的视频，展示 LiDAR 点根据其范围值着色以及 3D 场景流和它们的特征映射（如果`load_features=True`）：

<p align="center">
  <img src="assets/notr_data.jpg">
</p>

<p align="center">
  <img src="assets/nuscenes_data.jpg">
</p>

2. **训练**. 对于最全面的 EmerNeRF 训练（包括动态编码器、流编码器和特征提取），请使用：

```shell
  python train_emernerf.py \
    --config_file configs/default_flow.yaml \
    --output_root $output_root \
    --project $project \
    --run_name ${scene_idx}_flow \
    data.scene_idx=$scene_idx \
    data.start_timestep=$start_timestep \
    data.end_timestep=$end_timestep \
    data.pixel_source.load_features=True \
    data.pixel_source.feature_model_type=dinov2_vitb14 \
    nerf.model.head.enable_feature_head=True \
    nerf.model.head.enable_learnable_pe=True \
    logging.saveckpt_freq=$num_iters \
    optim.num_iters=$num_iters
```

要获取更多示例，请参考`sample_scripts/`文件夹。

3. **体素检查**. 我们提供了可视化代码，用于显示空间-时间特征，就像我们的主页上展示的那样。要可视化体素特征，只需添加`--visualize_voxel`并指定`resume_from=$YOUR_PRETRAINED_MODEL`。这将生成一个HTML文件，您可以在浏览器中打开以进行体素特征可视化：

<p align="center">
  <img src="assets/sample_voxel.jpg" alt="Example Voxel Visualization">
</p>

## 预训练模型

- [ ] 我们将很快发布所有预训练模型。请注意，预训练模型的发布将遵循Waymo的数据共享政策。因此，我们将只会根据注册用户的请求发布预训练模型。更多细节即将提供。

## 引用

如果您发现本代码或我们的论文对您的研究有用，请考虑引用我们的论文。

```bibtex
@article{yang2023emernerf,
    title={EmerNeRF: Emergent Spatial-Temporal Scene Decomposition via Self-Supervision},
    author={Jiawei Yang and Boris Ivanovic and Or Litany and Xinshuo Weng and Seung Wook Kim and Boyi Li and Tong Che and Danfei Xu and Sanja Fidler and Marco Pavone and Yue Wang},
    journal={arXiv preprint arXiv:2311.02077},
    year={2023}
}
```