MonoScene: 单目3D语义场景补全

MonoScene: 单目3D语义场景补全
Anh-Quan Cao, Raoul de Charette
法国巴黎Inria研究所。
CVPR 2022

如果您觉得这项工作或代码有用，请引用我们的论文并为本仓库点个赞(star)：

@inproceedings{cao2022monoscene,
    title={MonoScene: Monocular 3D Semantic Scene Completion}, 
    author={Anh-Quan Cao and Raoul de Charette},
    booktitle={CVPR},
    year={2022}
}

预告片

SemanticKITTI	KITTI-360 (在SemanticKITTI上训练)

NYUv2

目录

• 新闻
• 准备MonoScene
  • 安装
  • 数据集
  • 预训练模型
• 运行MonoScene
  • 训练
  • 评估
• 推理与可视化
  • 推理
  • 可视化
• 相关仅基于相机的3D占用预测项目
• 许可证

新闻

• 25/03/2026：朝着通用统一的占用预测迈进了一步，推出了OccAny：通用无约束城市3D占用预测（CVPR'26）
• 05/12/2023：请查看我们最近的工作PaSCo：具有不确定性感知的城市3D全景场景补全 :rotating_light:
• 20/04/2023：请查看其他仅基于相机的3D占用预测项目
• 28/06/2022：我们在Hugging Face上添加了MonoScene演示
• 13/06/2022：我们添加了一个关于如何在mayavi中以编程方式定义视点的教程
• 12/06/2022：我们添加了一篇关于如何安装mayavi的指南
• 09/06/2022：我们修复了GitHub仓库中提到的安装错误（见https://github.com/astra-vision/MonoScene/issues/18）

准备MonoScene

安装

1. 创建conda环境：

$ conda create -y -n monoscene python=3.7
$ conda activate monoscene

2. 本代码使用Python 3.7、PyTorch 1.7.1和CUDA 10.2实现。请安装PyTorch：

$ conda install pytorch==1.7.1 torchvision==0.8.2 torchaudio==0.7.2 cudatoolkit=10.2 -c pytorch

3. 安装其他依赖项：

$ cd MonoScene/
$ pip install -r requirements.txt

4. 安装tbb：

$ conda install -c bioconda tbb=2020.2

5. 将torchmetrics降级到0.6.0版本：

$ pip install torchmetrics==0.6.0

6. 最后，安装MonoScene：

$ pip install -e ./

数据集

SemanticKITTI

1. 您需要下载

   • 语义场景补全数据集v1.1（SemanticKITTI体素数据，700 MB）来自SemanticKITTI官网
   • KITTI Odometry Benchmark校准数据（下载里程计数据集，包含校准文件，1 MB）以及RGB图像（下载里程计数据集，彩色图像，65 GB）来自KITTI Odometry官网。
   • 数据集文件夹位于**/path/to/semantic_kitti**，应具有以下结构：

   └── /path/to/semantic_kitti/
     └── dataset
       ├── poses
       └── sequences
   

2. 创建一个文件夹来存储SemanticKITTI预处理数据，路径为/path/to/kitti/preprocess/folder。

3. 将路径存储在环境变量中以便快速访问（注意：dataset文件夹位于/path/to/semantic_kitti）：

$ export KITTI_PREPROCESS=/path/to/kitti/preprocess/folder
$ export KITTI_ROOT=/path/to/semantic_kitti 

4. 对数据进行预处理，生成低分辨率标签，用于计算真实值关系矩阵：

$ cd MonoScene/
$ python monoscene/data/semantic_kitti/preprocess.py kitti_root=$KITTI_ROOT kitti_preprocess_root=$KITTI_PREPROCESS

NYUv2

1. 下载NYUv2数据集。

2. 创建一个文件夹来存储NYUv2预处理数据，路径为/path/to/NYU/preprocess/folder。

3. 将路径存储在环境变量中以便快速访问：

$ export NYU_PREPROCESS=/path/to/NYU/preprocess/folder
$ export NYU_ROOT=/path/to/NYU/depthbin 

4. 对数据进行预处理，生成低分辨率标签，用于计算真实值关系矩阵：

$ cd MonoScene/
$ python monoscene/data/NYU/preprocess.py NYU_root=$NYU_ROOT NYU_preprocess_root=$NYU_PREPROCESS

KITTI-360

1. 我们仅对KITTI-360进行推理。您可以从http://www.cvlibs.net/datasets/kitti-360/download.php下载用于训练和验证的透视图像（128G）或用于测试的透视图像（1.5G）。

2. 创建一个文件夹来存储KITTI-360数据，路径为/path/to/KITTI-360/folder。

3. 将路径存储在环境变量中以便快速访问：

$ export KITTI_360_ROOT=/path/to/KITTI-360

预训练模型

下载MonoScene在SemanticKITTI上的预训练模型链接以及在NYUv2上的预训练模型链接，然后将其放入文件夹/path/to/MonoScene/trained_models。

运行MonoScene

训练

要在SemanticKITTI上训练MonoScene，请输入以下命令：

SemanticKITTI

1. 创建文件夹来存储训练日志，路径为**/path/to/kitti/logdir**。

2. 将其存储在环境变量中：

$ export KITTI_LOG=/path/to/kitti/logdir

3. 使用4块GPU，每块GPU处理1个样本，以batch_size为4，在Semantic KITTI上训练MonoScene：

$ cd MonoScene/
$ python monoscene/scripts/train_monoscene.py \
    dataset=kitti \
    enable_log=true \
    kitti_root=$KITTI_ROOT \
    kitti_preprocess_root=$KITTI_PREPROCESS\
    kitti_logdir=$KITTI_LOG \
    n_gpus=4 batch_size=4    

NYUv2

1. 在 /path/to/NYU/logdir 创建用于存储训练日志的文件夹。

2. 将路径存储到环境变量中：

$ export NYU_LOG=/path/to/NYU/logdir

3. 使用 2 张 GPU、每张 GPU 处理 2 个样本（即 batch_size=4）在 NYUv2 数据集上训练 MonoScene：

$ cd MonoScene/
$ python monoscene/scripts/train_monoscene.py \
    dataset=NYU \
    NYU_root=$NYU_ROOT \
    NYU_preprocess_root=$NYU_PREPROCESS \
    logdir=$NYU_LOG \
    n_gpus=2 batch_size=4

评估

SemanticKITTI

要在 SemanticKITTI 验证集上评估 MonoScene，请执行以下命令：

$ cd MonoScene/
$ python monoscene/scripts/eval_monoscene.py \
    dataset=kitti \
    kitti_root=$KITTI_ROOT \
    kitti_preprocess_root=$KITTI_PREPROCESS \
    n_gpus=1 batch_size=1

NYUv2

要在 NYUv2 测试集上评估 MonoScene，请执行以下命令：

$ cd MonoScene/
$ python monoscene/scripts/eval_monoscene.py \
    dataset=NYU \
    NYU_root=$NYU_ROOT\
    NYU_preprocess_root=$NYU_PREPROCESS \
    n_gpus=1 batch_size=1

推理与可视化

推理

请创建文件夹 /path/to/monoscene/output 以存储 MonoScene 的输出，并将其路径存储到环境变量中：

export MONOSCENE_OUTPUT=/path/to/monoscene/output

NYUv2

要在 NYUv2 测试集上生成预测结果，请执行以下命令：

$ cd MonoScene/
$ python monoscene/scripts/generate_output.py \
    +output_path=$MONOSCENE_OUTPUT \
    dataset=NYU \
    NYU_root=$NYU_ROOT \
    NYU_preprocess_root=$NYU_PREPROCESS \
    n_gpus=1 batch_size=1

Semantic KITTI

要在 Semantic KITTI 验证集上生成预测结果，请执行以下命令：

$ cd MonoScene/
$ python monoscene/scripts/generate_output.py \
    +output_path=$MONOSCENE_OUTPUT \
    dataset=kitti \
    kitti_root=$KITTI_ROOT \
    kitti_preprocess_root=$KITTI_PREPROCESS \
    n_gpus=1 batch_size=1

KITTI-360

这里我们使用序列 2013_05_28_drive_0009_sync，您也可以使用其他序列。要在 KITTI-360 上生成预测结果，请执行以下命令：

$ cd MonoScene/
$ python monoscene/scripts/generate_output.py \
    +output_path=$MONOSCENE_OUTPUT \
    dataset=kitti_360 \
    +kitti_360_root=$KITTI_360_ROOT \
    +kitti_360_sequence=2013_05_28_drive_0009_sync  \
    n_gpus=1 batch_size=1

可视化

注意： 如果您在使用 mayavi 时遇到困难，可以使用替代的 基于 Open3D 的可视化代码。

我们使用 mayavi 来可视化预测结果。请按照 官方安装说明 安装 mayavi。然后，使用以下命令分别对各个数据集的输出进行可视化。

如果您在 安装 mayavi 时遇到困难，可以查看我们的 mayavi 安装指南。

如果您在 调整 mayavi 视角时遇到困难，可以查看我们的 教程。

您还需要使用以下命令安装可视化脚本所需的软件包：

pip install tqdm
pip install omegaconf
pip install hydra-core

NYUv2

$ cd MonoScene/
$ python monoscene/scripts/visualization/NYU_vis_pred.py +file=/path/to/output/file.pkl

Semantic KITTI

$ cd MonoScene/
$ python monoscene/scripts/visualization/kitti_vis_pred.py +file=/path/to/output/file.pkl +dataset=kitt

KITTI-360

$ cd MonoScene/ 
$ python monoscene/scripts/visualization/kitti_vis_pred.py +file=/path/to/output/file.pkl +dataset=kitti_360

相关的仅基于相机的 3D 占用预测项目

• NDC-Scene: 在归一化设备坐标空间中提升单目 3D 语义场景补全，ICCV 2023。
• OG: 为视觉占用预测配备实例分割和视觉定位能力，arXiv 2023。
• FB-OCC: 基于前后视图变换的 3D 占用预测，CVPRW 2023。
• 通过上下文实例查询统一 3D 语义场景补全，arXiv 2023。
• OVO: 开放词汇占用预测，arXiv 2023。
• OccNet: 场景即占用，ICCV 2023。
• SceneRF: 基于辐射场的自监督单目 3D 场景重建，ICCV 2023。
• 幕后：用于单视图重建的密度场，CVPR 2023。
• VoxFormer: 基于稀疏体素的 Transformer 用于基于相机的 3D 语义场景补全，CVPR 2023。
• OccDepth: 一种深度感知的 3D 语义占用网络方法，arXiv 2023。
• StereoScene: BEV 辅助立体匹配赋能 3D 语义场景补全，arXiv 2023。
• 三视角用于基于视觉的 3D 语义占用预测，CVPR 2023。
• 自动驾驶中 3D 占用估计的简单尝试，arXiv 2023。
• OccFormer: 双路径 Transformer 用于基于视觉的 3D 语义占用预测，ICCV 2023。
• SurroundOcc: 多摄像头 3D 占用预测用于自动驾驶，ICCV 2023。
• PanoOcc: 统一的占用表示用于基于相机的 3D 全景分割，arXiv 2023。
• PointOcc: 基于柱状三视角的点云 3D 语义占用预测，arXiv 2023。
• RenderOcc: 以视觉为中心的 3D 占用预测，辅以 2D 渲染监督，arXiv 2023。

数据集/基准测试

• PointSSC: 用于语义场景补全的车路协同点云基准测试，arXiv 2023。
• OpenOccupancy: 用于周围语义占用感知的大规模基准测试，ICCV 2023。
• nuScenes 的占用数据集，Github 2023
• Occ3D: 用于自动驾驶的大规模 3D 占用预测基准测试，arXiv 2023。
• OccNet: 场景即占用，ICCV 2023。
• SSCBench: 用于自动驾驶的大规模 3D 语义场景补全基准测试，arXiv 2023。

许可证

MonoScene 根据 Apache 2.0 许可证 发布。

MonoScene 快速上手指南

MonoScene 是一个基于单目图像的 3D 语义场景补全工具，支持 SemanticKITTI、NYUv2 和 KITTI-360 数据集。本指南将帮助你快速完成环境配置、安装及基础推理。

1. 环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04)
• Python: 3.7 (项目严格依赖此版本)
• CUDA: 10.2
• PyTorch: 1.7.1
• GPU: 建议具备至少 8GB 显存用于训练，推理可根据模型大小调整

注意：由于项目依赖较旧版本的 PyTorch 和 Python，强烈建议使用 conda 创建独立的虚拟环境以避免冲突。

2. 安装步骤

2.1 创建 Conda 环境并安装 PyTorch

# 创建名为 monoscene 的 Python 3.7 环境
conda create -y -n monoscene python=3.7
conda activate monoscene

# 安装指定版本的 PyTorch (CUDA 10.2)
# 如果下载速度慢，可尝试添加清华源：-c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/
conda install pytorch==1.7.1 torchvision==0.8.2 torchaudio==0.7.2 cudatoolkit=10.2 -c pytorch

2.2 安装项目依赖

克隆代码库并安装所需依赖：

# 假设你已经 git clone 了仓库并进入目录
cd MonoScene/

# 安装 requirements.txt 中的依赖
pip install -r requirements.txt

# 安装 tbb 库
conda install -c bioconda tbb=2020.2

# 强制降级 torchmetrics 到 0.6.0 (关键步骤，版本不匹配会报错)
pip install torchmetrics==0.6.0

# 以编辑模式安装 MonoScene
pip install -e ./

2.3 安装可视化工具 (可选)

如果需要运行官方可视化脚本，需安装 mayavi。若安装困难，可使用 Open3D 替代方案（见原文注）。

# 安装 mayavi 及其依赖
pip install tqdm omegaconf hydra-core
# mayavi 安装较为复杂，建议参考作者提供的专门教程或使用 conda 安装
conda install -c conda-forge mayavi

3. 基本使用

以下演示如何使用预训练模型在 NYUv2 数据集上进行最简单的推理与结果生成。

3.1 准备数据与模型

1. 下载数据集：下载 NYUv2 数据集并解压。
2. 下载预训练模型：下载 NYUv2 预训练权重，并将其放入项目根目录下的 trained_models 文件夹中。
3. 配置环境变量：

# 替换为你的实际路径
export NYU_ROOT=/path/to/NYU/depthbin 
export NYU_PREPROCESS=/path/to/NYU/preprocess/folder
export MONOSCENE_OUTPUT=/path/to/monoscene/output

# 执行数据预处理 (生成低分辨率标签)
python monoscene/data/NYU/preprocess.py NYU_root=$NYU_ROOT NYU_preprocess_root=$NYU_PREPROCESS

3.2 执行推理

运行以下命令生成预测结果（.pkl 文件）：

cd MonoScene/
python monoscene/scripts/generate_output.py \
    +output_path=$MONOSCENE_OUTPUT \
    dataset=NYU \
    NYU_root=$NYU_ROOT \
    NYU_preprocess_root=$NYU_PREPROCESS \
    n_gpus=1 batch_size=1

3.3 可视化结果 (可选)

如果你已成功安装 mayavi，可以使用以下命令查看生成的 3D 场景：

# 将 /path/to/output/file.pkl 替换为上一步生成的实际文件路径
python monoscene/scripts/visualization/NYU_vis_pred.py +file=/path/to/output/file.pkl

提示：对于 SemanticKITTI 或 KITTI-360 数据集，只需更改 dataset 参数及对应的根路径环境变量（KITTI_ROOT, KITTI_360_ROOT 等），命令格式与上述类似。