Habitat-Sim

一款高性能、支持物理引擎的3D模拟器，具备以下功能：

• 室内外空间的3D扫描数据（内置对HM3D、HSSD、MatterPort3D、Gibson、Replica等数据集的支持）
• 空间及分段刚性物体的CAD模型（例如ReplicaCAD、YCB、Google Scanned Objects等）
• 可配置传感器（RGB-D相机、自运动感知设备）
• 通过URDF描述的机器人（移动机械臂如Fetch、固定基座机械臂如Franka、四足机器人如AlienGo等）
• 刚体物理动力学（通过Bullet实现）。

Habitat的设计理念是优先考虑仿真速度，而非仿真功能的广度。在渲染Matterport3D数据集中的场景时，Habitat-Sim在单线程下可达到每秒数千帧（FPS），而在单GPU上使用多进程时则可超过1万FPS。Habitat-Sim还能以每秒8000步（SPS）的速度模拟Fetch机器人与ReplicaCAD场景的交互，其中每一步都包括渲染1张RGBD观测图像（128×128像素）以及持续1/30秒的刚体动力学计算。

Habitat-Sim通常与Habitat-Lab一起使用，后者是一个用于具身AI端到端实验的模块化高级库——可用于定义具身AI任务（如导航、指令遵循、问答）、训练智能体（通过模仿学习或强化学习，或在经典的SensePlanAct流程中不进行学习），并使用标准指标评估其在这些任务上的表现。

有问题或意见？欢迎加入AI Habitat社区讨论区。


https://user-images.githubusercontent.com/2941091/126080914-36dc8045-01d4-4a68-8c2e-74d0bca1b9b8.mp4

---

目录

1. 引用Habitat
2. 安装
3. 测试
4. 文档
5. 数据集
6. 外部贡献
7. 许可证

引用Habitat

如果您在研究中使用了Habitat平台，请引用以下论文：Habitat 1.0、Habitat 2.0和Habitat 3.0：

@misc{puig2023habitat3,
      title  = {Habitat 3.0: 人类、虚拟化身与机器人的共栖环境},
      author = {Xavi Puig、Eric Undersander、Andrew Szot、Mikael Dallaire Cote、Ruslan Partsey、Jimmy Yang、Ruta Desai、Alexander William Clegg、Michal Hlavac、Tiffany Min、Theo Gervet、Vladimír Vondruš、Vincent-Pierre Berges、John Turner、Oleksandr Maksymets、Zsolt Kira、Mrinal Kalakrishnan、Jitendra Malik、Devendra Singh Chaplot、Unnat Jain、Dhruv Batra、Akshara Rai、Roozbeh Mottaghi},
      year={2023},
      archivePrefix={arXiv},
}

@inproceedings{szot2021habitat,
  title     =     {Habitat 2.0: 训练家庭助手重新整理居住环境},
  author    =     {Andrew Szot、Alex Clegg、Eric Undersander、Erik Wijmans、Yili Zhao、John Turner、Noah Maestre、Mustafa Mukadam、Devendra Chaplot、Oleksandr Maksymets、Aaron Gokaslan、Vladimir Vondrus、Sameer Dharur、Franziska Meier、Wojciech Galuba、Angel Chang、Zsolt Kira、Vladlen Koltun、Jitendra Malik、Manolis Savva、Dhruv Batra},
  booktitle =     {神经信息处理系统进展会议（NeurIPS）},
  year      =     {2021}
}

@inproceedings{habitat19iccv,
  title     =     {Habitat：一个用于具身AI研究的平台},
  author    =     {Manolis Savva、Abhishek Kadian、Oleksandr Maksymets、Yili Zhao、Erik Wijmans、Bhavana Jain、Julian Straub、Jia Liu、Vladlen Koltun、Jitendra Malik、Devi Parikh、Dhruv Batra},
  booktitle =     {IEEE/CVF国际计算机视觉会议（ICCV） proceedings},
  year      =     {2019}
}

Habitat-Sim还基于他人的工作成果。如果您使用了他人贡献的方法或模型，请记得引用他们的工作。有关外部贡献及其对应的工作和引用，请参阅外部贡献部分。

安装

Habitat-Sim可以通过四种方式安装：

1. 通过Conda——推荐大多数用户使用的方式。提供稳定版和夜间构建版本。
2. 通过PIP——运行pip install . --no-build-isolation即可从源码编译。请阅读从源码构建指南及常见问题。
3. 通过Docker——大约每年更新一次，用于Habitat挑战赛。请阅读habitat-docker-setup。
4. 从源码安装——适用于积极开发的用户。请阅读从源码构建指南及常见问题。

[推荐] Conda 软件包

Habitat 处于积极开发中，我们建议用户仅使用稳定版本。自 v0.1.4 版本起，我们为每个发布版本提供了Conda 软件包。

1. 准备 Conda 环境

   假设您已安装 Conda，让我们来创建一个 Conda 环境：

   # 我们需要 Python>=3.9 和 CMake>=3.22
   conda create -n habitat python=3.12 cmake=3.27
   conda activate habitat
   

2. 使用 Conda 安装 habitat-sim

   根据您的系统和需求，选择以下选项之一：

   • 在带有显示设备的机器上安装：

     conda install habitat-sim -c conda-forge -c aihabitat
     

   • 在无头机器（即没有连接显示设备的机器，例如集群）以及多 GPU 机器上安装（此参数依赖 EGL，因此在 macOS 上无效）：

     conda install habitat-sim headless -c conda-forge -c aihabitat
     

   • 【最常见场景】安装带 Bullet 物理引擎的 habitat-sim：

     conda install habitat-sim withbullet -c conda-forge -c aihabitat
     

   • 注意：构建参数可以串联使用。例如，在无头机器上安装带物理引擎的 habitat-sim：

     conda install habitat-sim withbullet headless -c conda-forge -c aihabitat
     

   对于旧版本的软件包，可以通过显式指定版本号来安装，例如 conda install habitat-sim=0.1.6 -c conda-forge -c aihabitat。

   我们还提供了主分支的每日夜间构建 Conda 包。不过，只有在您需要最新发布版本中尚未包含的特定功能时，才应使用该包。要获取最新主分支的夜间构建版本，只需将 -c aihabitat 替换为 -c aihabitat-nightly 即可。

测试

1. 让我们使用我们的 Python 数据下载工具下载一些 3D 资源：

   • 下载（测试）3D 场景

     python -m habitat_sim.utils.datasets_download --uids habitat_test_scenes --data-path /path/to/data/
     

     请注意，这些测试场景不提供语义标注。 如果您想通过 example.py 测试语义传感器，请使用 Matterport3D 数据集中的数据（参见 数据集）。

   • 下载示例对象

     python -m habitat_sim.utils.datasets_download --uids habitat_example_objects --data-path /path/to/data/
     

2. 交互式测试：使用 Habitat-Sim 自带的 C++ 或 Python 交互式查看器：

   #C++
   # 在执行 'pip install .' 后，查看器位于 PATH 中：
   viewer /path/to/data/scene_datasets/habitat-test-scenes/skokloster-castle.glb
   # 对于可编辑/开发版本，会创建一个便捷的符号链接：
   ./build/viewer /path/to/data/scene_datasets/habitat-test-scenes/skokloster-castle.glb
   
   #Python
   python examples/viewer.py --scene /path/to/data/scene_datasets/habitat-test-scenes/skokloster-castle.glb
   

   您应该能够在该测试场景中控制智能体。使用 W/A/S/D 键进行前后左右移动，使用方向键或鼠标左键来控制视线方向（上下左右）。试着找到那幅被花环环绕的女子画像吧！祝您玩得开心！

3. 物理交互：Habitat-sim 通过与 Bullet 物理引擎 集成，提供了刚体和关节动力学仿真功能。现在就通过我们的 C++ 或 Python 交互式查看器来体验一下吧。

   首先，下载我们完全可交互的 ReplicaCAD 公寓数据集（140 MB）：

   #注意：默认情况下，数据将被下载到 habitat-sim/data/ 目录下。您也可以通过添加 `--data-path /path/to/data/` 来指定数据路径。
   # 使用 conda 安装
   python -m habitat_sim.utils.datasets_download --uids replica_cad_dataset
   
   # 使用源代码（从 habitat_sim/ 目录内）
   python src_python/habitat_sim/utils/datasets_download.py --uids replica_cad_dataset
   

   • 或者，您也可以选择下载带有预烘焙光照的 105 种场景变体，使用 --uids replica_cad_baked_lighting（480 MB）。

   然后，在启用物理模拟的查看器应用中加载一个 ReplicaCAD 场景。如果您在上面修改了数据路径，也请在下面的查看器调用中相应地修改。

   #C++
   viewer --enable-physics --dataset data/replica_cad/replicaCAD.scene_dataset_config.json -- apt_1
   
   #python
   python examples/viewer.py --dataset data/replica_cad/replicaCAD.scene_dataset_config.json --scene apt_1
   

   • 如果您使用的是带有预烘焙光照的场景，请使用以下命令：

     python examples/viewer.py --dataset data/replica_cad_baked_lighting/replicaCAD_baked.scene_dataset_config.json --scene Baked_sc1_staging_00
     

   查看器应用程序会在运行时将完整的键盘和鼠标操作选项输出到控制台。

   快速入门示例：

   • 使用 WASD 键移动
   • 左键单击并拖动鼠标来环视四周
   • 按下空格键切换物理模拟的开启与关闭状态（默认为开启）
   • 按下 'm' 键切换到“抓取”鼠标模式
   • 此时，左键或右键单击并拖动即可移动物体、开关门或抽屉，并松开鼠标以放下物体。
   • 当抓住某个物体时，滚动鼠标滚轮可以实现：
     • （默认）将其拉近或推远
     • （按住 ALT 键）绕固定约束框架旋转（偏航角）
     • （按住 CTRL 键）绕固定约束框架旋转（俯仰角）
     • （同时按住 ALT 和 CTRL 键）绕固定约束框架旋转（翻滚角）

4. 非交互式测试（例如用于无头系统）：运行示例脚本：

   python /path/to/habitat-sim/examples/example.py --scene /path/to/data/scene_datasets/habitat-test-scenes/skokloster-castle.glb
   

   智能体会沿着特定路径行进，最后您将看到性能统计信息，例如： 640 x 480, 总时间：3.208 秒。FPS：311.7。

   若要复现 Habitat ICCV'19 中的基准测试表格，请运行：

   python examples/benchmark.py --scene /path/to/mp3d_example/17DRP5sb8fy/17DRP5sb8fy.glb
   

   example.py 还提供了其他参数，用于更改传感器配置、打印场景中的语义标注统计信息、计算动作空间中最短路径轨迹以及设置其他实用功能。有关详细信息，请参阅 example.py 和 demo_runner.py 的源代码。

   加载特定的 MP3D 或 Gibson 房屋：examples/example.py --scene path/to/mp3d/house_id.glb。

   我们还提供了一个 示例演示，供参考。

   若要在 Python 中运行物理示例（在编译时启用了 Bullet 物理模拟）：

   python examples/example.py --scene /path/to/data/scene_datasets/habitat-test-scenes/skokloster-castle.glb --enable_physics
   

   请注意，在此模式下，智能体会被冻结，并面向生成的物理物体。此外，还可以使用 --save_png 将物理场景中智能体的视觉观测帧输出到当前目录。

常见测试问题

• 如果您在远程机器上运行，并在初始化模拟器时遇到显示错误，例如：

   X11: DISPLAY 环境变量缺失
   无法初始化 GLFW
  

  请确保您的环境中未定义 DISPLAY 变量（运行 unset DISPLAY 来取消定义该变量）。

• 如果您看到类似 libGL 的错误：

   X11: DISPLAY 环境变量缺失
   无法初始化 GLFW
  

  这可能是因为您的 libGL 库位于非标准位置。请参阅例如 这个问题。

文档

浏览在线 Habitat-Sim 文档。

查看我们的 ECCV 教程系列 ，获得动手实践的快速入门体验。

如果找不到您问题的答案，请尝试在我们的 讨论论坛 上向开发者和社区提问。

数据集

如何使用 Habitat-Sim 支持的常见数据集。

外部贡献

• 如果您使用 PyRobot 中的噪声模型，请引用他们的技术报告。

  具体来说，该噪声模型用于名为 pyrobot_* 的有噪控制函数，并定义在 src_python/habitat_sim/agent/controls/pyrobot_noisy_controls.py 文件中。

• 如果您使用 Redwood 深度噪声模型，请引用他们的论文。

  具体而言，该噪声模型定义在 src_python/habitat_sim/sensors/noise_models/redwood_depth_noise_model.py 和 src/esp/sensor/RedwoodNoiseModel.* 文件中。

许可证

Habitat-Sim 采用 MIT 许可证。详情请参阅 LICENSE 文件。

演示脚本使用了：

• The King’s Hall，由 Skokloster Castle (Skoklosters slott) 创作，采用 知识共享署名 4.0 国际许可协议。
• Van Gogh Room，由 ruslans3d 创作，采用 知识共享署名 4.0 国际许可协议。

Habitat-Sim 快速上手指南

Habitat-Sim 是一个高性能的、支持物理引擎的 3D 模拟器，专为具身人工智能（Embodied AI）研究设计。它支持多种室内/室外场景数据集、可配置传感器以及基于 URDF 的机器人模型，并以极高的渲染速度著称。

1. 环境准备

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

• 操作系统: Linux (推荐 Ubuntu) 或 macOS。
  • 注意：无头模式（Headless，即无显示器环境）依赖 EGL，不支持 macOS。
• Python 版本: 3.9 或更高 (推荐 3.12)。
• 包管理器: Conda (强烈推荐)。
• 硬件:
  • 单线程即可运行，但多进程配合单个 GPU 可发挥最大性能（>10,000 FPS）。
  • 若需物理模拟，需支持 Bullet Physics。

2. 安装步骤

推荐使用 Conda 进行安装，这是最稳定且配置最简单的方法。

第一步：创建 Conda 环境

打开终端，执行以下命令创建名为 habitat 的环境（包含 Python 3.12 和 CMake）：

conda create -n habitat python=3.12 cmake=3.27
conda activate habitat

第二步：安装 Habitat-Sim

根据您的使用场景选择以下任一命令：

• 场景 A：通用安装（带物理引擎支持，最常用） 适用于大多数开发和研究场景，包含 Bullet 物理引擎支持。

  conda install habitat-sim withbullet -c conda-forge -c aihabitat
  

• 场景 B：无头服务器安装（集群/无显示器） 适用于没有连接显示器的服务器或多 GPU 环境（仅限 Linux）。

  conda install habitat-sim headless -c conda-forge -c aihabitat
  

• 场景 C：带物理引擎的无头安装 结合了上述两种需求。

  conda install habitat-sim withbullet headless -c conda-forge -c aihabitat
  

• 场景 D：普通桌面安装（有显示器，无需物理引擎）

  conda install habitat-sim -c conda-forge -c aihabitat
  

提示：如果下载速度较慢，可尝试配置 Conda 国内镜像源（如清华源或中科大源），但核心包仍需从 aihabitat 频道拉取。

3. 基本使用

安装完成后，您可以下载测试数据并启动交互式查看器来验证安装。

第一步：下载测试场景

使用内置工具下载简单的测试场景数据：

python -m habitat_sim.utils.datasets_download --uids habitat_test_scenes --data-path ./data

第二步：运行交互式查看器 (Python)

运行以下命令启动查看器，加载刚才下载的城堡场景：

python examples/viewer.py --scene ./data/scene_datasets/habitat-test-scenes/skokloster-castle.glb

第三步：操作指南

启动后，您将看到一个 3D 场景，可以通过以下按键控制智能体：

• 移动: W (前), A (左), S (后), D (右)
• 视角: 鼠标左键拖动 或 方向键
• 任务: 尝试在场景中寻找一幅“被花环包围的女性画像”。

进阶：体验物理交互 (可选)

若要体验刚体动力学和物理交互，需下载 ReplicaCAD 数据集并启用物理引擎：

1. 下载数据:

   python -m habitat_sim.utils.datasets_download --uids replica_cad_dataset --data-path ./data
   

2. 启动带物理引擎的查看器:

   python examples/viewer.py --dataset ./data/replica_cad/replicaCAD.scene_dataset_config.json --scene apt_1
   

   • 按 SPACE 键开启/关闭物理模拟。
   • 按 m 键抓取/放置物体（具体操作请参考控制台输出的帮助信息）。