Matterport3D 模拟器

基于真实全景图像的强化学习人工智能研究平台。

Matterport3D 模拟器使开发者能够构建利用视觉信息（RGB-D 图像）与真实 3D 环境交互的人工智能智能体。它主要用于深度强化学习领域的研究，该领域横跨计算机视觉、自然语言处理和机器人技术。

访问主网站观看演示。

新增：2019年2月 我们发布了多项更新。现在模拟器已容器化，支持批量智能体而不仅限于单个智能体，并且效率（速度）比之前大幅提升。此外，它现在不仅能输出 RGB 图像，还能输出深度图。因此，原始 API 发生了一些变化（主要是所有输入和输出都改为批量处理）。为了区分首次发布版本，我们为那些暂不升级到新版本的用户标记了 v0.1 版本。

功能特性

• 数据集包含 90 种以室内为主的环境；
• 输出 RGB 和深度图像；
• 所有图像和深度图均为真实采集，而非合成数据（提供更丰富的视觉复杂度）；
• 提供 C++ 和 Python 的 API；
• 可自定义图像分辨率、相机参数等；
• 支持离屏渲染（基于 GPU 和 CPU）；
• 高速渲染（使用 Titan X GPU，在 640x480 分辨率下可实现约 1000 fps 的 RGB-D 离屏渲染）；
• 包含渲染管线和智能体运动等的单元测试；
• 未来版本可能支持类别级和实例级目标分割。

参考文献

Matterport3D 模拟器和 Room-to-Room (R2R) 导航数据集在以下论文中有所介绍：

• 视觉与语言导航：在真实环境中理解基于视觉的导航指令。

如果您使用该模拟器或我们的数据集，请引用我们的论文（CVPR 2018 Spotlight Oral）：

Bibtex 格式：

@inproceedings{mattersim,
  title={{Vision-and-Language Navigation}: Interpreting visually-grounded navigation instructions in real environments},
  author={Peter Anderson and Qi Wu and Damien Teney and Jake Bruce and Mark Johnson and Niko S{\"u}nderhauf and Ian Reid and Stephen Gould and Anton van den Hengel},
  booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
  year={2018}
}

模拟器数据

Matterport3D 模拟器基于来自 Matterport3D 数据集 的密集采样的 360 度室内 RGB-D 图像。该数据集包含 90 种不同的室内场景，涵盖住宅、办公室、教堂和酒店等。每个场景包含从 8 到 349 个视角采集的完整 360 度 RGB-D 扫描数据，这些视角平均间隔 2.25 米，覆盖整个可行走的平面布局。

行动选项

在每个视角位置，智能体可以平移和俯仰相机，也可以选择在不同视角之间移动。智能体的具体观测和行动细节将在下方及论文中详细说明。

Room-to-Room (R2R) 导航任务

该模拟器包含了 Room-to-Room (R2R) 导航任务的训练数据和评估指标。此任务要求自主智能体根据自然语言导航指令，前往一个此前未见过的建筑中的目标位置。请参阅具体说明，以设置并运行此任务。EvalAI 上设有测试服务器和排行榜，地址为 EvalAI。

安装/构建说明

我们建议使用我们的 Dockerfile 来安装模拟器。当然，您也可以不使用 Docker 进行构建，但满足项目依赖可能会更加困难。

先决条件

• NVIDIA GPU，驱动程序版本 ≥ 396.37；
• 安装 Docker；
• 安装 NVIDIA Docker 2.0；
• 注意：无需单独安装 CUDA/CuDNN 工具包，这些工具将由 Docker 镜像提供。

克隆代码库

克隆 Matterport3DSimulator 仓库：

# 请务必使用 --recursive 选项进行克隆
git clone --recursive https://github.com/peteanderson80/Matterport3DSimulator.git
cd Matterport3DSimulator

如果您未使用 --recursive 选项克隆，则需要手动从顶级目录克隆 pybind 子模块：

git submodule update --init --recursive
``。

### 下载数据集

要使用该模拟器，您首先需要下载 [Matterport3D 数据集](https://niessner.github.io/Matterport/)。申请访问权限后即可下载，下载脚本支持选择性下载特定类型的数据。至少需要下载 `matterport_skybox_images`。如果希望使用深度输出，还需下载 `undistorted_depth_images` 和 `undistorted_camera_parameters`。

设置一个环境变量指向解压后的数据集路径，其中 `<PATH>` 是包含各个 Matterport 扫描目录（17DRP5sb8fy、2t7WUuJeko7 等）的完整绝对路径（不是相对路径或符号链接）：

export MATTERPORT_DATA_DIR=

请注意，如果 `<PATH>` 是远程的 sshfs 挂载点，您需要使用 `-o allow_root` 选项挂载，否则 Docker 容器将无法访问该目录。

### 使用 Docker 构建

构建 Docker 镜像：

docker build -t mattersim:9.2-devel-ubuntu18.04 .

运行 Docker 容器，并同时挂载 Git 仓库和数据集：

nvidia-docker run -it --mount type=bind,source=$MATTERPORT_DATA_DIR,target=/root/mount/Matterport3DSimulator/data/v1/scans --volume pwd:/root/mount/Matterport3DSimulator mattersim:9.2-devel-ubuntu18.04

现在（在 Docker 容器内），构建模拟器代码：

cd /root/mount/Matterport3DSimulator mkdir build && cd build cmake -DEGL_RENDERING=ON .. make cd ../

#### 渲染选项（GPU、CPU、离屏）

请注意，共有三种渲染方式，可通过构建过程中的 [CMake](https://cmake.org/) 选项进行选择（只需调整上述构建命令中的第 3 行）：
- 基于 OpenGL 的 GPU 渲染（需要 X 服务器）：`cmake ..`（默认）；
- 基于 [EGL](https://www.khronos.org/egl/) 的离屏 GPU 渲染：`cmake -DEGL_RENDERING=ON ..`；
- 基于 [OSMesa](https://www.mesa3d.org/osmesa.html) 的离屏 CPU 渲染：`cmake -DOSMESA_RENDERING=ON ..`。

对于智能体训练，推荐采用高速的离屏 GPU 渲染（EGL）。

### 数据集预处理

为了加快数据加载速度并减少内存使用，我们通过缩小尺寸并将所有立方体面合并为一张图像来预处理 `matterport_skybox_images`。在 Docker 容器内运行以下脚本：

./scripts/downsize_skybox.py

这将花费一些时间，具体取决于使用的进程数量（该设置可在脚本中调整）。

完成之后，数据集中的 `matterport_skybox_images` 子目录将包含文件名为 `<PANO_ID>_skybox_small.jpg` 的图像文件。默认情况下，图像会被缩小 50%，并使用 20 个进程。

#### 深度输出

如果您需要同时获取深度和 RGB 图像（通过调用 `sim.setDepthEnabled(True)`），请运行以下脚本以预计算匹配的深度天空盒图像：

./scripts/depth_to_skybox.py

深度天空盒是基于 `undistorted_depth_images` 使用简单的混合方法生成的。由于深度图像中存在大量缺失值（对应于数据集中常见的反光、明亮、透明以及远处的表面），我们应用了一种基于 [NYUv2](https://cs.nyu.edu/~silberman/datasets/nyu_depth_v2.html) 代码的简单交叉双边滤波器，以填充除最大孔洞之外的所有区域。需要注意的是：
- 我们假设 `undistorted depth images` 已经与 `matterport_skybox_images` 对齐，但实际上这种对齐并不完美。对于某些需要更高对齐精度的应用场景（例如生成 RGB 点云），可能需要将 `matterport_skybox_images` 替换为拼接后的 `undistorted_color_images`（这些图像与 `undistorted_depth_images` 完全对齐）。
- 在生成的深度天空盒中，深度值表示的是从相机中心到目标点的欧几里得距离，而不是 z 方向上的距离。这一点会在模拟器中进行校正（见下文的模拟器 API）。

### 运行测试

现在（仍然在 Docker 容器内），运行单元测试：

./build/tests ~Timing

如果所有测试都通过，`sim_imgs` 目录中将包含由模拟器渲染的一些测试图像。您也可以测试渲染帧率。以下命令会尝试将所有 Matterport 环境加载到内存中（大约需要 50 GB 内存），然后在标准输出中打印出关于渲染帧率的信息（分辨率为 640x480，仅输出 RGB）：

./build/tests Timing

为了获得准确的结果，必须单独运行计时测试，而不能与其他测试同时进行。请注意，如果内存不足，计时测试将会失败。只要其他所有测试都通过（即 `./build/tests ~Timing`），则说明安装成功。有关单元测试配置选项，请参阅 [Catch](https://github.com/philsquared/Catch) 文档。

现在退出 Docker 容器：

exit

## 交互式演示

要运行交互式演示，在完成上述安装和构建步骤后，启动 Docker 容器，并将主机的 X 服务器和 DISPLAY 环境变量共享给容器：

xhost + nvidia-docker run -it -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --mount type=bind,source=$MATTERPORT_DATA_DIR,target=/root/mount/Matterport3DSimulator/data/v1/scans,readonly --volume pwd:/root/mount/Matterport3DSimulator mattersim:9.2-devel-ubuntu18.04 cd /root/mount/Matterport3DSimulator

如果您遇到类似 `Error: BadShmSeg (invalid shared segment parameter) 128` 的错误，可能还需要在上述 docker run 命令中添加 `-e="QT_X11_NO_MITSHM=1"`。

下面提供了运行 Python 和 C++ 演示的命令。这些是非常简单的演示，旨在展示如何在 Python 和 C++ 中使用模拟器。默认情况下，*这些演示未启用深度渲染*。如果您已经预处理了深度输出并希望查看深度信息，请检查代码并将其打开（参见上文的深度输出部分）。无论构建模拟器时使用了哪种渲染选项，这些演示都应该能够正常运行。

Python 演示：

python3 src/driver/driver.py

C++ 演示：

build/mattersim_main

`web` 目录中的 JavaScript 代码也可以用作交互式演示，或者用于从模拟器中以第一人称视角生成视频，亦或作为 Amazon Mechanical Turk 上的界面来收集自然语言指令数据。


### 不使用 Docker 构建

模拟器可以在不使用 Docker 容器的情况下，通过上述的 CMake 构建命令进行构建。然而，这不是推荐的做法，因为所有依赖项都需要在本地安装，且可能会与现有库发生冲突。主要要求如下：
- Ubuntu >= 14.04
- 已安装 CUDA 的 Nvidia 驱动程序
- 支持 C++11 的 C++ 编译器
- [CMake](https://cmake.org/) >= 3.10
- [OpenCV](http://opencv.org/) >= 2.4，包括 3.x 版本
- [OpenGL](https://www.opengl.org/)
- [GLM](https://glm.g-truc.net/0.9.8/index.html)
- [Numpy](http://www.numpy.org/)

可选依赖项（取决于 CMake 的渲染选项）：
- [OSMesa](https://www.mesa3d.org/osmesa.html) 用于支持 OSMesa 后端
- [epoxy](https://github.com/anholt/libepoxy) 用于支持 EGL 后端

提供的 [Dockerfile](Dockerfile) 包含了大多数这些库的安装命令。例如，要安装 OpenGL 及相关库：

sudo apt-get install libjsoncpp-dev libepoxy-dev libglm-dev libosmesa6 libosmesa6-dev libglew-dev

### 模拟器 API

模拟器的 [Python API](src/lib_python/MatterSimPython.cpp) 与详细注释的 [MatterSim.hpp](include/MatterSim.hpp) C++ 头文件完全一致，只是用 Python 列表代替了 C++ std::vector 等数据结构。通常，以 `set` 开头的函数用于设置智能体和模拟器的配置，例如批量大小、渲染参数、是否启用深度输出等。对于训练智能体，我们建议设置 `setPreloadingEnabled(True)`、`setBatchSize(X)` 和 `setCacheSize(2X)`，其中 X 是所需的批量大小，例如：

import MatterSim sim = MatterSim.Simulator() sim.setCameraResolution(640, 480) sim.setPreloadingEnabled(True) sim.setDepthEnabled(True) sim.setBatchSize(100) sim.setCacheSize(200) # cacheSize 200 会占用约 1.2GB 的 GPU 内存来缓存全景纹理

当启用预加载时，所有全景图像将在开始之前被加载到内存中。预加载需要几分钟时间，并且对于 RGB 输出大约需要 50GB 的内存（如果启用深度输出，则需要约 80GB），但这样可以显著提高渲染速度。

要启动模拟器，先调用 `initialize`，然后调用 `newEpisode` 函数，该函数接受扫描 ID 列表、视点 ID 列表、方向角列表（以弧度为单位）以及相机高度角列表（以弧度为单位）作为参数，例如：

sim.initialize()

假设批次大小为 1

sim.newEpisode(['2t7WUuJeko7'], ['1e6b606b44df4a6086c0f97e826d4d15'], [0], [0])

航向是从 y 轴定义的，z 轴朝上（向右转为正）。相机俯仰角是从由 x-y 平面定义的地平线开始测量的（向上为正）。还有一个 `newRandomEpisode` 函数，它只需要一个扫描 ID 列表，并随机确定一个视点和航向（相机俯仰角为零）。

与模拟器的交互通过 `makeAction` 函数进行，该函数接受可导航位置索引列表、航向变化列表（以弧度为单位）和俯仰角变化列表（以弧度为单位）作为参数。可导航位置索引用于选择智能体应移动到的附近相机视点。*默认情况下，只有位于智能体当前视野范围内的相机视点才被视为可导航，除非禁用了受限导航*（例如，智能体不能后退）。对于智能体 `n`，可导航位置由 `getState()[n].navigableLocations` 给出。索引 0 始终包含当前视点（即智能体始终可以选择停留在原地）。由于导航图是不规则的，其余视点按其与图像中心的角距离排序，因此索引 1（如果可用）将近似于直接向前移动。例如，要在不移动的情况下左转 30 度（保持相机俯仰角不变）：

sim.makeAction([0], [-0.523599], [0])

在任何时候，都可以通过调用 `getState` 来获取模拟器状态。返回的状态包含一个对象列表（每个批次中的每个智能体对应一个对象），其属性如下例所示：
```javascript
[
  {
    "scanId" : "2t7WUuJeko7"  // 智能体所在的建筑物
    "step" : 5,               // 自上次 newEpisode() 调用以来的帧数
    "rgb" : <image>,          // 8 位图像（BGR 通道顺序），可通过 np.array(rgb, copy=False) 访问
    "depth" : <image>,        // 16 位单通道图像，包含像素在 z 方向相对于相机中心的距离 
                              // （不是相对于相机中心的欧几里得距离），每 0.25 毫米对应一个值（除以 4000 即可得到米）。 
                              // 零值表示“无读数”。可通过 np.array(depth, copy=False) 访问
    "location" : {            // 智能体当前的 3D 位置
        "viewpointId" : "1e6b606b44df4a6086c0f97e826d4d15",  // 视点标识符
        "ix" : 5,                                            // 视点索引，由模拟器使用
        "x" : 3.59775996208,                                 // 世界坐标系中的 3D 位置
        "y" : -0.837355971336,
        "z" : 1.68884003162,
        "rel_heading" : 0,                                   // 相对于该位置的机器人相对坐标
        "rel_elevation" : 0,
        "rel_distance" : 0
    }
    "heading" : 3.141592,     // 智能体当前的相机航向，以弧度为单位
    "elevation" : 0,          // 智能体当前的相机俯仰角，以弧度为单位
    "viewIndex" : 0,          // 智能体当前视角的索引 [0-35]（仅在视角离散化时有效）
                              // [0-11] 表示低头，[12-23] 表示平视，[24-35] 表示抬头
    "navigableLocations": [   // 可移动到的视点列表。索引 0 始终是当前视点，即不动。
        {                     // 其余有效视点按其与图像中心的角距离排序。
            "viewpointId" : "1e6b606b44df4a6086c0f97e826d4d15",  // 视点标识符
            "ix" : 5,                                            // 视点索引，由模拟器使用
            "x" : 3.59775996208,                                 // 世界坐标系中的 3D 位置
            "y" : -0.837355971336,
            "z" : 1.68884003162,
            "rel_heading" : 0,                                   // 相对于该位置的机器人相对坐标
            "rel_elevation" : 0,
            "rel_distance" : 0
        },
        {
            "viewpointId" : "1e3a672fa1d24d668866455162e5b58a",  // 视点标识符
            "ix" : 14,                                           // 视点索引，由模拟器使用
            "x" : 4.03619003296,                                 // 世界坐标系中的 3D 位置
            "y" : 1.11550998688,
            "z" : 1.65892004967,
            "rel_heading" : 0.220844170027,                      // 相对于该位置的机器人相对坐标
            "rel_elevation" : -0.0149478448723,
            "rel_distance" : 2.00169944763
        },
        {...}
    ]
  }
]

有关示例用法，请参阅 src/driver/driver.py。要为 doxygen 目录中的 C++ 类生成 HTML 文档，请运行以下命令，并在浏览器中导航至 doxygen/html/index.html：

doxygen

预计算 ResNet 图像特征

在我们最初使用此模拟器的工作中，我们将航向和俯仰角离散化为 30 度的增量，并为每个视角预先计算了图像特征。现在模拟器的速度已经快得多，这已不再必要，但为了完整性，我们仍将在下面列出该设置的详细信息。

我们使用 Caffe 生成图像特征。要复制我们的方法，首先下载一些 Caffe ResNet-152 的权重并将其保存到 models 目录中。我们尝试了在 ImageNet 数据集上预训练的权重，以及在 Places365 数据集上微调后的权重。然后可以使用脚本 scripts/precompute_features.py 来预先计算 ResNet-152 的特征。特征将以 tsv 格式保存在 img_features 目录中。

或者，您可以跳过生成步骤，直接下载并解压我们的 tsv 文件到 img_features 目录：

• ResNet-152-ImageNet 特征 [38 万/2.9 GB]
• ResNet-152-Places365 特征 [38 万/2.9 GB]

目录结构

• connectivity: JSON 格式的导航图。
• webgl_imgs: 包含使用 JavaScript 渲染的数据集视图（用于测试比较）。
• sim_imgs: 将存放运行测试后模拟器渲染的图像。
• models: 用于预先计算 ResNet 图像特征的 Caffe 模型。
• img_features: 存储预先计算的图像特征。
• data: Matterport3D 数据集。
• tasks: 目前仅包含 Room-to-Room (R2R) 导航任务。
• web: 用于可视化轨迹并使用 Amazon Mechanical Turk (AMT) 收集标注的 JavaScript 代码。

其他目录大多不言自明。

许可证

Matterport3D 数据集及其衍生数据根据 Matterport3D 使用条款发布。我们的代码采用 MIT 许可证发布。

致谢

我们谨向 Matterport 表示感谢，感谢其允许学术界使用 Matterport3D 数据集。本项目得到了 Facebook ParlAI 研究奖以及 澳大利亚机器人视觉中心 的支持。

贡献

我们欢迎社区的贡献。所有提交的内容均需经过评审，在大多数情况下还需要通过测试。

Matterport3D Simulator 快速上手指南

Matterport3D Simulator 是一个用于强化学习研究的 AI 平台，支持智能体在真实的 3D 室内环境中通过视觉信息（RGB-D 图像）进行交互。它广泛应用于计算机视觉、自然语言处理和机器人领域的深度强化学习研究。

环境准备

系统要求

• 操作系统: Ubuntu >= 14.04 (推荐使用 Ubuntu 18.04)
• GPU: Nvidia GPU，驱动程序版本 >= 396.37
• 内存: 运行完整数据集测试建议预留 50GB+ 内存

前置依赖

推荐使用 Docker 部署以避免复杂的本地依赖冲突。需安装以下工具：

• Docker
• nvidia-docker2.0

注意: 无需手动安装 CUDA 或 CuDNN，Docker 镜像中已包含。

安装步骤

1. 克隆代码仓库

确保使用 --recursive 参数克隆，以获取必要的子模块：

git clone --recursive https://github.com/peteanderson80/Matterport3DSimulator.git
cd Matterport3DSimulator

如果忘记加参数，可手动初始化子模块：

git submodule update --init --recursive

2. 下载数据集

访问 Matterport3D 官网 申请权限并下载数据。

• 必需: matterport_skybox_images
• 可选 (如需深度图): undistorted_depth_images 和 undistorted_camera_parameters

解压后，设置环境变量指向数据集根目录（必须是绝对路径）：

export MATTERPORT_DATA_DIR=<PATH>

> 注：若路径为远程 sshfs 挂载，请使用 -o allow_root 选项挂载。

3. 构建 Docker 镜像

在项目根目录下构建镜像：

docker build -t mattersim:9.2-devel-ubuntu18.04 .

4. 启动容器并编译

运行容器，挂载代码库和数据集目录：

nvidia-docker run -it --mount type=bind,source=$MATTERPORT_DATA_DIR,target=/root/mount/Matterport3DSimulator/data/v1/scans --volume `pwd`:/root/mount/Matterport3DSimulator mattersim:9.2-devel-ubuntu18.04

进入容器后，创建构建目录并编译（推荐使用 EGL 进行离屏 GPU 渲染以提升速度）：

cd /root/mount/Matterport3DSimulator
mkdir build && cd build
cmake -DEGL_RENDERING=ON ..
make
cd ../

5. 数据预处理

为加速加载并减少内存占用，需对天空盒图像进行下采样处理：

./scripts/downsize_skybox.py

如需使用深度图输出，还需运行：

./scripts/depth_to_skybox.py

基本使用

编译完成后，可直接在容器内运行示例程序。默认示例仅开启 RGB 渲染，如需深度图请在代码中启用 sim.setDepthEnabled(True) 并确保已完成深度数据预处理。

Python 示例

运行简单的 Python 驱动演示：

python3 src/driver/driver.py

C++ 示例

运行 C++ 主程序演示：

build/mattersim_main

验证安装

运行单元测试（不含耗时测速测试）以确认安装成功：

./build/tests ~Timing

若测试通过，sim_imgs 目录中将生成渲染出的测试图像。