.. _my-kbenvs: ************ Environments ************ VirtualHome is composed of 50 custom designed environmenta where activities can be executed. Each environment is encoded as a dictionary, containing a node for every object and edges between them representing relationships. Each environment can be updated by modifying the corresponding dictionary. We call this dictionary :ref:`EnvironmentGraph`. You can load each environment using :meth:`unity_simulator.UnityCommunication.reset` function, specifying the matching environment id. You can retrieve the information of an environment using :meth:`unity_simulator.UnityCommunication.environment_graph`. After loading an environment, you can modify it using :meth:`unity_simulator.UnityCommunication.expand_scene`. ============ Environments ============ Below are a few samples of the environments included in VirtualHome. .. list-table:: :widths: 20 100 :header-rows: 1 * - Environment ID - Apartment View * - 0 - .. image:: ../../images/doc/apartments/scene1rot.png :width: 50% * - 1 - .. image:: ../../images/doc/apartments/scene2rot.png :width: 50% * - 2 - .. image:: ../../images/doc/apartments/scene3rot.png :width: 50% * - 3 - .. image:: ../../images/doc/apartments/scene4rot.png :width: 50% * - 4 - .. image:: ../../images/doc/apartments/scene5rot.png :width: 50% * - 5 - .. image:: ../../images/doc/apartments/scene6rot.png :width: 50% * - 6 - .. image:: ../../images/doc/apartments/scene7rot.png :width: 50% ================= Environment Graph ================= The Environment Graph is the way to represent a environment in VirtualHome. It is represented as a dictionary of node, corresponding to objects, and edges, corresponding to relationships. Here is an example: .. code-block:: json { "nodes":[ { "id":1, "class_name":"character", "states":[ ], "properties":[ ], "category":"Person" }, { "id":2, "class_name":"kitchen", "states":[ ], "properties":[ ], "category":"Room" } ], "edges":[ { "from_id":1, "to_id":2, "relation_type":"INSIDE" } ] } The structure of the Graph is documented below. Environment Graph ***************** .. json:object:: EnvironmentGraph :property nodes: list of objects :proptype nodes: list(:json:object:`Nodes`) :property edges: list of relationships between objects :proptype edges: list(:json:object:`Edges`) .. json:object:: Nodes :property int id: id of object :property str class_name: class_name of the object :property str category: cateogry of the object :property str prefab_name: name of the Unity game object used :property list(str) states: states of the objects :property list(str) properties: properties of the objects :property bounding_box: bounding box of the given object :proptype bounding_box: list(:json:object:`BoundingBox`) :property obj_transform: 3D information of the given object :proptype obj_transform: :json:object:`ObjTransform` .. json:object:: BoundingBox :property list(float) center: center of the bounding box, in x,y,z :property list(float) size: size of the bounding box, in x,y,z. The size is axis aligned .. json:object:: ObjTransform :property list(float) position: x,y,z position of the game object. Does not necessarily match with BoundingBox center. :property list(float) rotation: x,y,z,w representation a quaternion of the object rotation https://docs.unity3d.com/ScriptReference/Quaternion.html .. json:object:: Edges :property int from_id: id of Node in the from relationship :property int to_id: id of Node in the to relationship :property str relation_type: relationship between the 2 objects. States ****** Objects can have the following states .. list-table:: :widths: 20 100 :header-rows: 1 * - State - Meaning * - `OPEN` - Indicates whether a container is open. * - `CLOSED` - Indicates whether a container is closed. * - `ON` - Indicates whether a light, electronic device is ON. * - `OFF` - Indicates whether a light, electronic device is OFF. Properties ********** Objects can have the following properties. Some have effect on the Uniy Simulator and some are just used to categorize the objects. We only indicate meaning for the former. .. list-table:: :widths: 20 100 :header-rows: 1 * - Property - Meaning * - `CAN_OPEN` - Whether the object can be opened * - `CLOTHES` - * - `CONTAINERS` - * - COVER_OBJECT - * - `CREAM` - * - `CUTTABLE` - * - `DRINKABLE` - * - `EATABLE` - * - `GRABBABLE` - Whether the object can be grabbed * - `HANGABLE` - * - `HAS_PAPER` - * - `HAS_PLUG` - * - `HAS_SWITCH` - Whether the object can be turned on or off * - `LIEABLE` - * - `LOOKABLE` - * - `MOVABLE` - * - `POURABLE` - * - `READABLE` - * - `RECIPIENT` - * - `SITTABLE` - Whether the agent can sit in this object * - `SURFACE` - Whether the agent can place things on this object Relationships ************* Objects can have different relationships between each other, we describe here their meaning .. list-table:: :widths: 20 100 :header-rows: 1 * - Relation Type - Meaning * - `ON` - Object `from_id` is on top of object `to_id`. * - `INSIDE` - Object `from_id` is inside of object `to_id`. * - `BETWEEN` - Used for doors. Door connects with room `to_id`. * - `CLOSE` - Object `from_id` is close to object `to_id` (< 1.5 metres). * - `FACING` - Object `to_id` is visible from objects `from_id` and distance is < 5 metres. If object1 is a sofa or a chair it should also be turned towards object2. * - `HOLDS_RH` - Character `from_id` holds object `to_id` with the right hand. * - `HOLDS_LH` - Character `from_id` holds object `to_id` with the left hand. * - `SITTING` - Character `from_id` is sitting in object `to_id`. ========================== Environmental Manipulation ========================== VirtualHome also supports environmental manipulation. The current supported features are to set the time to a pre defined state which accurate day/night lighting, and physics where objects in the environment experience gravity with semi-accurate collisions. To set the time you can call the :meth:`comm.set_time()` function and to activate gravity in the environment the :meth:`comm.activate_physics()` function can be called. Set Time ******** The following example shows how to set the time in the environment: .. code-block:: python # Set the time of the environment using hours, minutes and seconds comm.set_time(hours=0, minutes=0, seconds=0, scaler=1) set_time -------- The time of the environment will be set to accurately display lightning and corresponding actions which can be simulated depending on the time. :Arguments: ``hours``, ``minutes``, ``seconds`` :Modifier: :Preconditions: - Environment has to be in a active state :Postconditions: - The time will be set for the environment and outside lighting will be affected by the time. :Example: - ``comm.set_time(hours=6, minutes=30, seconds=0)`` Activate Physics **************** The following example shows how to activate physics: .. code-block:: python # Activate physics (gravity) comm.activate_physics() activate_physics ---------------- All interactble objects can be influenced by gravity and collisions. :Arguments: ``gravity`` :Modifier: :Preconditions: - Environment has to be in a active state :Postconditions: - All interactble objects expereince gravatational force and can represent semi-acccurate collisions :Example: - ``comm.activate_physics(gravity=-10)`` Remove Terrain **************** The following example shows how to remove the outdoor terrain: .. code-block:: python # Remove terrain comm.remove_terrain() remove_terrain -------------- All outdoor objects will be removed. :Arguments: ``none`` :Modifier: :Preconditions: - Environment has to be in a active state :Postconditions: - Outdoor terrain is removed :Example: - ``comm.remove_terrain()``