---

最新动态

VirtualHome 2.3 已发布！以下是最新更新：

• 增加了程序化生成能力，使智能体能够探索无限种独特的环境！
• 我们新增了更多自定义设计的环境。
• 加强了环境中的物理模拟效果。
• 引入了同步昼夜变化的时间管理系统。
• 新增户外地形，具备精确的阳光和阴影效果。
• 改进了室内实时光照效果。
• 房间更加逼真。
• 性能显著提升，资源优化，稳定性增强。
• 更新了文档。
• 修复了现有环境中的一些常见问题。

往期更新

• [2020年8月] 添加了强化学习环境演示，并提供了将环境与 Ray 结合使用的示例。
• [2020年4月] 我们新增了文档！请访问 http://virtual-home.org/documentation 查看。
• 我们提供了类似 OpenAI Gym 的环境，用于在 VirtualHome 上训练强化学习智能体。请查看 unity_environment.py 类。
• 提供了在场景中添加角色和固定摄像机的 API，并支持从这些摄像机录制视频。

目前开发中

• 程序化生成能力的进一步优化。
• 更高的写实性功能。
• 更多动作和物体交互。
• 人类交互功能。

---

目录

1. 概述
2. 设置
3. 生成视频/关键帧
4. VirtualHome 强化学习环境
5. 数据集
6. 自定义 VirtualHome
7. 引用
8. 贡献者

---

概述

VirtualHome 中的活动由两个部分组成：程序表示构成活动的一系列动作顺序，而 图 则代表活动发生环境的定义。给定一个程序和一张图，模拟器会执行该程序，生成活动的视频，或者生成一系列图，展示活动进行过程中环境的变化情况。为此，VirtualHome 包含两种模拟器：Unity 模拟器 和 演化图模拟器。您可以在 http://virtual-home.org/documentation 找到更完整的文档，其中包含示例和不同的可执行文件。

Unity 模拟器

该模拟器基于 Unity 构建，可用于生成活动视频。要使用此模拟器，您需要下载相应的可执行文件，并通过 Python API 运行它。您可以在 demo/unity_demo.ipynb 中查看该模拟器的演示。

演化图模拟器

该模拟器完全在 Python 中运行，可在执行程序时生成一系列图。您可以在 simulation/evolving_graph 中运行它。请注意，此模拟器中的某些对象和动作目前尚未在 Unity 模拟器中支持。

---

设置

安装

$ pip install virtualhome

我们还提供了一个带有演示和起始代码的 Jupyter 笔记本。如果您想运行演示，请 安装 Jupyter 并在您的主机上运行。如果您是 Jupyter 新手，请参阅 运行 Jupyter Notebook 以了解如何使用此工具。

下载 Unity 模拟器

下载 VirtualHome UnitySimulator 可执行文件，并将其移动到 simulation/unity_simulator 目录下。

• 下载 Linux x86-64 版本。
• 下载 Mac OS X 版本。
• 下载 Windows 版本。

测试模拟器

要在本地机器上测试模拟器，双击可执行文件，或通过终端运行。通过终端运行时，建议设置窗口模式（这样模拟器就不会占据整个屏幕），命令如下：

./path_to_exec -screen-fullscreen 0 -screen-quality 4 

模拟器启动后，在 demo/unity_demo.ipynb 中运行演示。

如果您没有显示器，或者希望远程测试模拟器，可以使用 Docker 或 X 服务器（安装说明请参见 这篇 Medium 文章）。使用 X 服务器运行可执行文件时，请使用 -batchmode 参数。对于 Linux 系统，操作步骤如下：

首先在终端中启动 X 服务器。您需要指定要使用的显示编号以及对应的 GPU。默认情况下，它会使用所有可用的 GPU：

sudo python helper_scripts/startx.py $display_num

然后在另一个终端中启动可执行文件：

DISPLAY=:display_num ./{path_sim}/{exec_file}.x86_64 -batchmode

对于 Linux 系统，您还可以通过 UnityCommunication 指定可执行文件来启动模拟器。这将直接在指定的屏幕上打开可执行文件。具体操作如下：

在启动 X 服务器后，运行：

from simulation.unity_simulator import comm_unity
comm = comm_unity.UnityCommunication(file_name=file_name, port={your_port}, x_display={your_display})

这将打开一个可执行文件，并创建一个通信对象，用于渲染脚本或模拟活动。您可以同时打开多个可执行文件，以多进程方式训练模型或生成数据。

Docker

您也可以使用 Docker 运行 Unity 模拟器。设置方法请参见 这里。

---

生成视频和快照

VirtualHome Unity 模拟器 允许生成与家庭活动相对应的视频。此外，还可以使用 Evolving Graph 模拟器获取每一步执行时的环境，并利用 UnitySimulator 为每一步生成环境快照。

生成视频

打开模拟器并运行：

cd demo/
python generate_video.py

生成快照

打开模拟器并运行：

cd demo/
python generate_snapshots.py

系统将为给定的脚本生成一组快照，并保存到 demo/snapshot_test.png。

---

VirtualHome 强化学习环境

VirtualHome 可用作强化学习的环境。我们在 simulation/environment/unity_environment.py 中提供了一个基类 UnityEnvironment。您可以通过运行以下代码来测试该类的功能：

cd demo
python test_unity_environment.py

提供的环境可以与 Ray 结合使用，以并行运行多个环境，从而扩展您的强化学习算法。您可以通过运行以下代码来测试并行环境：

cd demo
python test_unity_environment_mp.py

---

数据集

我们收集了一组程序，并使用 Evolving Graph 模拟器为其添加了图结构。您可以从 这里 下载这些数据。下载并解压后，将程序移动到 dataset 文件夹中。您也可以通过执行以下脚本完成此操作：

./helper_scripts/download_dataset.sh

数据集应遵循以下结构：

dataset
└── programs_processed_precond_nograb_morepreconds
	|── initstate
	├── withoutconds
	├── executable_programs
	|   ├── TrimmedTestScene7_graph
	|	└── ...
	└── state_list
		├── TrimmedTestScene7_graph
	   	└── ...	

其中，withoutconds 和 initstate 文件夹包含原始程序及先决条件。

当脚本在环境中执行时，脚本会根据环境中的实例调整原始对象的位置。您可以在 executable_programs/{environment}/{script_name}.txt 中查看最终生成的脚本。

要查看环境的图结构及其在程序执行过程中的变化，请检查 state_list/{environment}/{script_name}.json。

有关程序和环境图的更多详细信息，请参阅 dataset/README.md。

脚本增强

在论文《通过活动草图合成环境感知型活动》中，我们使用两个知识库对脚本进行了增强：KB-RealEnv 和 KB-ExceptionHandler。您可以从 KB-RealEnv 和 KB-ExceptionHandler 下载增强后的脚本。

以下是用于增强脚本的代码：

使用 KB-RealEnv 增强

cd dataset_utils
python augment_dataset_locations.py

使用 KB-ExceptionHandler 增强

cd dataset_utils
python augment_dataset_exceptions.py

原始收集及脚本化程序

我们最初收集了一组基于语言描述预测的程序，并通过脚本语言生成了更多的程序。这些程序在 这里 被描述为 VirtualHome 活动（收集的程序）和 ActivityPrograms（脚本化的程序）。您可以从以下链接下载：

• 下载 VirtualHome 活动。
• 下载 ActivityPrograms。

资源

为了进行上述生成和增强操作，我们使用了一些有价值的资源文件来设置物体的属性、 affordance 等。更多详情请参阅 resources/README.md。

---

文档

如需了解更多关于 VirtualHome 的信息，请访问 VirtualHome 文档。

---

修改 VirtualHome

如果您希望为 VirtualHome 做出贡献，或根据自己的研究需求修改模拟器，请查看包含 Unity 源代码 的仓库。您需要下载 Unity 编辑器，并在完成更新后构建自己的可执行文件。

---

引用

VirtualHome 已被用于以下研究：

• VirtualHome：通过程序模拟家庭活动。PDF
  X. Puig*, K. Ra*, M. Boben*, J. Li, T. Wang, S. Fidler, A. Torralba。
  CVPR2018。

• 通过活动草图合成环境感知型活动。
  A. Liao*, X. Puig*, M. Boben, A. Torralba, S. Fidler。
  CVPR2019。

• 观看与协助：社会感知与人机协作的挑战。
  X. Puig, T. Shu, S. Li, Z. Wang, J. Tenenbaum, S. Fidler, A. Torralba。
  ICLR2021，亮点论文。
  NeurIPS 合作人工智能研讨会 2020 年度最佳论文奖。

• 用于交互式决策的预训练语言模型。项目 | PDF
  S. Li, X. Puig, C. Paxton, Y. Du, C. Wang, L. Fan, T. Chen, D. Huang, E. Akyürek, A. Anandkumar, J. Andreas, I. Mordatch, A. Torralba, Y. Zhu。
  NeurIPS 2022，口头报告。

如果您计划使用该模拟器，请引用以下两篇论文（第一篇介绍了 v1.0 版本，第二篇介绍了 v2.0 版本，即 VirtualHome-Social）：

@inproceedings{puig2018virtualhome,
  title={Virtualhome: Simulating household activities via programs},
  author={Puig, Xavier and Ra, Kevin and Boben, Marko and Li, Jiaman and Wang, Tingwu and Fidler, Sanja and Torralba, Antonio},
  booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition},
  pages={8494--8502},
  year={2018}
}

@misc{puig2020watchandhelp,
      title={Watch-And-Help: A Challenge for Social Perception and Human-AI Collaboration}, 
      author={Xavier Puig and Tianmin Shu and Shuang Li and Zilin Wang and Joshua B. Tenenbaum and Sanja Fidler and Antonio Torralba},
      year={2020},
      eprint={2010.09890},
      archivePrefix={arXiv},
      primaryClass={cs.AI}
}

---

贡献者

VirtualHome API 和代码由以下人员开发：

• Xavier Puig
• Marko Boben
• Kabir Swain
• Jordan Ren
• Kevin Ra
• Zilin Wang
• Shuang Li
• Tianmin Shu
• Andrew Liao

---

VirtualHome 快速上手指南

VirtualHome 是一个交互式平台，旨在通过程序模拟复杂的家庭活动。它支持智能体与环境进行复杂交互（如抓取物体、开关电器等），并提供 Python API 以便将活动指令序列渲染为视频或环境状态图。该平台适用于具身人工智能（Embodied AI）任务的研究与训练。

1. 环境准备

系统要求

• 操作系统: Linux (x86-64), macOS, 或 Windows。
  • 注：若需在无显示器的服务器（Headless）上运行 Unity 模拟器，推荐使用 Linux 并配置 X Server 或使用 Docker。
• Python: 建议 Python 3.6+
• 硬件: 需要支持 OpenGL 的 GPU（用于运行 Unity 模拟器）。

前置依赖

• Jupyter Notebook (可选，用于运行官方演示):

  pip install jupyter
  

• Ray (可选，用于强化学习并行环境):

  pip install ray
  

2. 安装步骤

第一步：安装 Python 包

使用 pip 安装核心库：

pip install virtualhome

国内加速提示：如果下载速度慢，可使用清华源或阿里源： pip install virtualhome -i https://pypi.tuna.tsinghua.edu.cn/simple

第二步：下载 Unity 模拟器

VirtualHome 的核心渲染功能依赖 Unity 可执行文件。请根据你的操作系统下载对应版本，并将其解压移动到项目目录下的 simulation/unity_simulator 文件夹中。

• Linux: 下载链接
• macOS: 下载链接
• Windows: 下载链接

(注：目前官方未提供中国镜像源，若下载受阻建议使用代理或离线传输)

第三步：验证安装

在终端启动模拟器（以 Linux 为例，设置为窗口模式以防占满全屏）：

./path_to_exec -screen-fullscreen 0 -screen-quality 4

看到模拟器窗口启动即表示环境就绪。

3. 基本使用

VirtualHome 主要通过编写“程序脚本”来驱动智能体行动。以下是最简单的视频生成示例。

示例：生成活动视频

确保 Unity 模拟器已在后台运行，然后执行以下 Python 脚本生成视频：

cd demo/
python generate_video.py

该脚本会读取默认的活动指令序列，控制智能体在场景中执行动作，并输出渲染后的视频文件。

进阶：生成环境快照 (Snapshots)

如果你只需要关键帧图像而非完整视频，可以运行：

cd demo/
python generate_snapshots.py

生成的网格快照将保存为 demo/snapshot_test.png。

代码调用示例 (Python API)

你也可以直接在 Python 代码中调用模拟器：

from simulation.unity_simulator import comm_unity

# 初始化通信对象 (需确保模拟器已启动)
comm = comm_unity.UnityCommunication(port='8080')

# 重置场景
comm.reset()

# 定义简单的活动脚本 (例如：智能体走到沙发前坐下)
# 格式通常为：<AGENT> <ACTION> <OBJECT>
script = [
    '<char0> walk <sofa1>',
    '<char0> sit <sofa1>'
]

# 执行脚本并生成视频
comm.exec_script(script)

---

更多详细文档、自定义环境修改及强化学习接口请参考 VirtualHome 官方文档。