This documentation reflects AI2-THOR version 2.1.0. For the latest AI2-THOR documentation, visit ai2thor.allenai.org.

Initialization

Prior to running any additional commands, it is assumed you have run the following::

import ai2thor.controller
controller = ai2thor.controller.Controller()
controller.start()
# can be any one of the scenes FloorPlan###
controller.reset('FloorPlan28')
controller.step(dict(action='Initialize', gridSize=0.25))

Initialize

Initialize must be called after resetting a scene to set fields such as gridSize.

controller.step(dict(action='Initialize', gridSize=0.25))

Parameter	Type	Description	Default
gridSize	float	Size of the grid that the agent navigates in. This determines the step size that the agent takes when the actions MoveAhead, MoveBack, MoveRight, MoveLeft are taken.	0.25
renderDepthImage	bool	When enabled a depth image is sent and made available on the returned Event as the attribute `depth_frame`.	False
renderClassImage	bool	When enabled a class segmentation image is sent and made available on the returned Event as the attribute `class_segmentation_frame`.	False
renderObjectImage	bool	When enabled an object segmentation image is sent and made available on the returned Event as the attribute `instance_segmentation_frame`.	False
visibilityDistance	float	Distance in meters from the agent’s camera (positioned near the top of the agent) that an object should be considered visibile.	1.5
cameraY	float	Height of the camera attached to the agent.	0.675
fieldOfView	float	Field of view for the agent’s camera. Corresponds to the value Camera.fieldOfView	60.0

Object Position Randomization

After initializing the scene, pickupable objects can have their default positions randomized to any valid receptacle they could be placed in within the scene. Objects are not guaranteed to move from their default position, as sometimes there is not enough free space in the scene for an object to move.

controller.reset('FloorPlan28')
controller.step(dict(action='Initialize', gridSize=0.25))
controller.step(dict(action = 'InitialRandomSpawn', randomSeed = 0, forceVisible = false, numPlacementAttempts = 5,
numRepeats = [{'objectType': 'Statue', 'count': 20}, {'objectType': 'Bowl', 'count': 20}], minFreePerReceptacleType = [{'objectType': 'Sink', 'count': 1000}]))

Remember to reset and initiialize the scene before using the Position Randomizer, otherwise seeded values will be innacurate.

Parameter	Type	Description	Default
randomSeed	int	Used to seed the randomization for duplicatable scene states. Because this seed depends on the current state of the scene, remember to reset the scene with controller.reset() before running InitialRandomSpawn(), otherwise the seeded randomization will not be accurate	0
forceVisible	bool	When enabled, the scene will attempt to randomize all moveable objects outside of receptacles in plain view. Use this if you want to avoid objects spawning inside closed drawers, cabinets, etc.	False
numPlacementAttempts	int	how many times each object in the scene attempts to randomly spawn. Setting this value higher will lead to fewer spawn failures at the cost of performance	5
numRepeats	list	Used to specify how many objects of a certain type will spawn somewhere in the scene. It does not guarantee this number of spawned objects, only the number of attempted spawned objects, so this is the max it will be. This will only spawn copies of objects already in the scene, so if you request an object which is not in the scene upon reset, it will not work.	None
minFreePerReceptacleType	list	Used to specify if a given type should be left empty (or partially empty). Only Receptacles that have `count` number of free positions will be valid receptacles for objects to be moved into. This can be used to enforce certain receptacle types to be left empty or have more free space to put objects in upon initialization. Set count to a high value (ie:1000000) for a given `objectType` and that Receptacle will have more free space.	None

Restore Object Positions

This is useful for setting a scene to the exact state of a previous initialization without relying on the Object Position Randomization’s random seed. Use a previous metadata dump of SimObjects to get position/rotation data for each SimObject. Sets up a scene according to the provided objects and poses. Objects which are specified twice will be copied. Objects which are not specified but are in the original scene will be removed.

controller.reset('FloorPlan319')
object_poses = [{"objectName":"Alarm_Clock_19","rotation":{"y":270,"x":0,"z":0},"position":{"y":0.8197357,"x":2.45610785,"z":0.054755792}},{"objectName":"Book_19","rotation":{"y":0,"x":0,"z":0},"position":{"y":0.7308113,"x":0.3694262,"z":1.497829}},{"objectName":"pillow_19","rotation":{"y":0,"x":0,"z":0},"position":{"y":0.809355736,"x":-0.5954236,"z":0.17262423}},{"objectName":"Alarm_Clock_19","rotation":{"y":270,"x":0,"z":0},"position":{"y":0.8197357,"x":2.64169645,"z":-0.134690791}}]
controller.step(dict(action='SetObjectPoses', objectPoses=object_poses,))

Parameter	Type	Description	Default
objectPoses	list	List of object names and their poses. This information can be dumped from the metadata of a prior episode.	None

Set Object States by Object Type

Enables setting the toggle state of an entire object type to a specified value. This example shows setting all DeskLamp objects in a scene to the off state. Refer to the Object Attributes section on the Metadata page for a detailed breakdown of which objectTypes have what actionable properties.

controller.reset('FloorPlan319')
controller.step(dict(action='SetObjectToggles', objectToggles=[{'objectType': 'DeskLamp', 'isOn': False}]))

Parameter	Type	Description	Default
objectToggles	list	List of object types and the value to set. Object Types and their possible states can be referenced from the ObjectMetadata.	None

Randomize All Object States by Random Seed

After initializing the scene, all objects with State changes can have their initial states randomized. This will randomly set or toggle all potential states that every sim object has (ie: a Cup might randomly be filled with water, dirty, broken, etc.). Use this after randomizing object positions with InitialRandomSpawn as many state changes are one-way and destructive, so objects cannot be guaranteed to be repositioned if states have already be randomized.

controller.reset('FloorPlan28')
controller.step(dict(action='Initialize', gridSize=0.25))
controller.step(dict(action = 'RandomToggleStateOfAllObjects', randomSeed = 0))

Parameter	Type	Description	Default
randomSeed	int	Used to seed the randomization for duplicatable scene states. Because this seed depends on the current state of the scene, always reset the scene with controller.reset() before performing additional Random state toggles.	0

Randomize Only Objects With a Specific State by Random Seed

After initializing the scene, this will randomly set or toggle the state of all sim objects in the scene that have the state specified by StateChange (ie: Randomly break all objects in the scene that CanBreak). Use this after randomizing object positions with InitialRandomSpawn as many state changes are one-way and destructive, so objects cannot be guaranteed to be repositioned if states have already be randomized.

controller.reset('FloorPlan28')
controller.step(dict(action='Initialize', gridSize=0.25))
controller.step(dict(action = 'RandomToggleSpecificState', randomSeed = 0, StateChange = "CanOpen");

Parameter	Type	Description	Default
randomSeed	int	Used to seed the randomization for duplicatable scene states. Because this seed depends on the current state of the scene, always reset the scene with controller.reset() before performing additional Random state toggles.	0
StateChange	string	Used to specify which state to randomly toggle for all objects that have the state. Valid states are: CanOpen, CanToggleOnOff, CanBeFilled, CanBeSliced, CanBeCooked, CanBreak, CanBeDirty, CanBeUsedUp	CanOpen

Unbreakable Objects

Objects with the Breakable property break by default if enough force is applied to them. This means dropping these objects from a high enough distance will cause automatic state changes. You can use this helper initialization function to set all objects of a given Type to unbreakable, preving this automatic interaction. This example sets all Eggs in the scene to be unbreakable unless explicitly using the BreakObject action.

controller.reset('FloorPlan28')
controller.step(dict(action='Initialize', gridSize=0.25))
controller.step(dict(action = 'MakeObjectsOfTypeUnbreakable', objectType = "Egg");

Parameter	Type	Description	Default
objectType	string	Specify an object type to be set as unbreakable except by explicit use of the BreakObject action	None

Next Steps

Continue on to the Agent Navigation documentation for information on how to manipulate and move the Agent within the environment.