Habitat-API

Habitat-API is a modular high-level library for end-to-end development in embodied AI -- defining embodied AI tasks (e.g. navigation, instruction following, question answering), configuring embodied agents (physical form, sensors, capabilities), training these agents (via imitation or reinforcement learning, or no learning at all as in classical SLAM), and benchmarking their performance on the defined tasks using standard metrics.

Habitat-API currently uses Habitat-Sim as the core simulator, but is designed with a modular abstraction for the simulator backend to maintain compatibility over multiple simulators.

Motivation
Citing Habitat
Installation
Example
Docker Setup
Details
Data
Baselines
Acknowledgments
License
References

Motivation

While there has been significant progress in the vision and language communities thanks to recent advances in deep representations, we believe there is a growing disconnect between ‘internet AI’ and embodied AI. The focus of the former is pattern recognition in images, videos, and text on datasets typically curated from the internet. The focus of the latter is to enable action by an embodied agent in an environment (e.g. a robot). This brings to the forefront issues of active perception, long-term planning, learning from interaction, and holding a dialog grounded in an environment.

To this end, we aim to standardize the entire ‘software stack’ for training embodied agents – scanning the world and creating highly photorealistic 3D assets, developing the next generation of highly efficient and parallelizable simulators, specifying embodied AI tasks that enable us to benchmark scientific progress, and releasing modular high-level libraries to train and deploy embodied agents.

Citing Habitat

If you use the Habitat platform in your research, please cite the following technical report:

@article{habitat19arxiv,
  title =   {Habitat: {A} {P}latform for {E}mbodied {AI} {R}esearch},
  author =  {{Manolis Savva*} and {Abhishek Kadian*} and {Oleksandr Maksymets*} and Yili Zhao and Erik Wijmans and Bhavana Jain and Julian Straub and Jia Liu and Vladlen Koltun and Jitendra Malik and Devi Parikh and Dhruv Batra},
  journal = {arXiv preprint arXiv:1904.01201},
  year =    {2019}
}

Installation

Clone the github repository and install habitat-api using the commands below. Note that python>=3.6 is required for working with habitat-api. All the development and testing was done using python3.6. Please use 3.6 to avoid possible issues.
```
cd habitat-api
pip install -e .
```
The command above will install only habitat core API. To include habitat_baselines along with all additional requirements, use the command below instead:
```
cd habitat-api
pip install -r requirements.txt
python setup.py develop --all # install habitat and habitat_baselines
```
Install habitat-sim from github repo.
Download the test scenes data and extract data folder in zip to habitat-api/data/ where habitat-api/ is the github repository folder.
Run the example script python examples/example.py which in the end should print out number of steps agent took inside an environment (eg: Episode finished after 2 steps.). To verify that tests pass run python setup.py test which should print out a log about passed, skipped and failed tests.
Run python examples/benchmark.py to evaluate a forward only agent in a test environment downloaded in step-3.

Example

Example code-snippet which uses tasks/pointnav.yaml for configuration of task and agent.

import habitat

# Load embodied AI task (PointNav) and a pre-specified virtual robot
env = habitat.Env(
    config=habitat.get_config("configs/tasks/pointnav.yaml")
)

observations = env.reset()

# Step through environment with random actions
while not env.episode_over:
    observations = env.step(env.action_space.sample())

See examples/register_new_sensors_and_measures.py for an example of how to extend habitat-api from outside the source code

Docker Setup

We also provide a docker setup for habitat. This works on machines with an NVIDIA GPU and requires users to install nvidia-docker. The following Dockerfile was used to build the habitat docker. To setup the habitat stack using docker follow the below steps:

Pull the habitat docker image: docker pull fairembodied/habitat:latest
Start an interactive bash session inside the habitat docker: docker run --runtime=nvidia -it fairhabitat/habitat:v1
Activate the habitat conda environment: source activate habitat
Benchmark a forward only agent on the test scenes data: cd habitat-api; python examples/benchmark.py. This should print out an output like:

2019-02-25 02:39:48,680 initializing sim Sim-v0
2019-02-25 02:39:49,655 initializing task Nav-v0
spl: 0.000

Details

An important objective of Habitat-API is to make it easy for users to set up a variety of embodied agent tasks in 3D environments. The process of setting up a task involves using environment information provided by the simulator, connecting the information with a dataset (e.g. PointGoal targets, or question and answer pairs for Embodied QA) and providing observations which can be used by the agents. Keeping this primary objective in mind the core API defines the following key concepts as abstractions that can be extended:

Env: the fundamental environment concept for Habitat. All the information needed for working on embodied tasks with a simulator is abstracted inside an Env. This class acts as a base for other derived environment classes. Env consists of three major components: a Simulator, a Dataset (containing Episodes), and a Task, and it serves to connects all these three components together.
Dataset: contains a list of task-specific episodes from a particular data split and additional dataset-wide information. Handles loading and saving of a dataset to disk, getting a list of scenes, and getting a list of episodes for a particular scene.
Episode: a class for episode specification that includes the initial position and orientation of an Agent, a scene id, a goal position and optionally shortest paths to the goal. An episode is a description of one task instance for the agent.

Architecture of Habitat-API

Task: this class builds on top of the simulator and dataset. The criteria of episode termination and measures of success are provided by the Task.
Sensor: a generalization of the physical Sensor concept provided by a Simulator, with the capability to provide Task-specific Observation data in a specified format.
Observation: data representing an observation from a Sensor. This can correspond to physical sensors on an Agent (e.g. RGB, depth, semantic segmentation masks, collision sensors) or more abstract sensors such as the current agent state.

Note that the core functionality defines fundamental building blocks such as the API for interacting with the simulator backend, and receiving observations through Sensors. Concrete simulation backends, 3D datasets, and embodied agent baselines are implemented on top of the core API.

Data

To make things easier we expect data folder of particular structure or symlink presented in habitat-api working directory.

Scenes datasets

Scenes models	Extract path	Archive size
Gibson	`data/scene_datasets/gibson/{scene}.glb`	1.5 GB
MatterPort3D	`data/scene_datasets/mp3d/{scene}/{scene}.glb`	15 GB

Matterport3D

The full Matterport3D (MP3D) dataset for use with Habitat can be downloaded using the official Matterport3D download script as follows: python download_mp.py --task habitat -o data/scene_datasets/mp3d/. You only need the habitat zip archive and not the entire Matterport3D dataset. Note that this download script requires python 2.7 to run. Extract the matterport data to data/scene_datasets/mp3d.

Gibson

Download the Habitat related Gibson dataset following the instructions here. After downloading extract the dataset to folder habitat-api/data/scene_datasets/gibson/ folder (this folder should contain the .glb files from Gibson).

Task datasets

Task	Scenes	Link	Extract path	Config to use	Archive size
Point goal navigtaion	Gibson	pointnav_gibson_v1.zip	`data/datasets/pointnav/gibson/v1/`	`datasets/pointnav/gibson.yaml`	385 MB
Point goal navigtaion	MatterPort3D	pointnav_mp3d_v1.zip	`data/datasets/pointnav/mp3d/v1/`	`datasets/pointnav/mp3d.yaml`	400 MB

To use an episode dataset provide related config to the Env in the example or use the config for RL agent training.

Baselines

Habitat-API includes reinforcement learning (via PPO) and classical SLAM based baselines. For running PPO training on sample data and more details refer habitat_baselines/README.md.

Acknowledgments

The Habitat project would not have been possible without the support and contributions of many individuals. We would like to thank Dmytro Mishkin, Xinlei Chen, Georgia Gkioxari, Daniel Gordon, Leonidas Guibas, Saurabh Gupta, Or Litany, Marcus Rohrbach, Amanpreet Singh, Devendra Singh Chaplot, Yuandong Tian, and Yuxin Wu for many helpful conversations and guidance on the design and development of the Habitat platform.

License

Habitat-API is MIT licensed. See the LICENSE file for details.

References

Habitat: A Platform for Embodied AI Research. Manolis Savva, Abhishek Kadian, Oleksandr Maksymets, Yili Zhao, Erik Wijmans, Bhavana Jain, Julian Straub, Jia Liu, Vladlen Koltun, Jitendra Malik, Devi Parikh, Dhruv Batra. Tech report, arXiv:1904.01201, 2019.

grahamannett/habitat-api