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 Toggleable Objects by Object Type

Enables setting the toggle state of an entire object type. This example shows setting all DeskLamp objects in a scene to the off state. Not that this initialization function only works with object types that have the On/Off actionable property. To check if a specific Sim Object can be set with this function, check if it has the toggleable = true object metadata attribute.

controller.reset('FloorPlan319')
controller.step(dict(action='SetObjectToggles', objectToggles=[{'objectType': 'DeskLamp', 'isOn': False}]))
Parameter Type Description Default
objectToggles list List of toggleable object types and the bool value to set each type to 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.