# Environment¶

The MujocoEnv class defines a top-level simulation object encapsulating a MjSim object. Robosuite uses class extensions of this base class, namely, RobotEnv which additionally encompasses Robot objects and the top-level task environments which capture specific ManipulationTask instances and additional objects.

## Base Environment¶

class robosuite.environments.base.MujocoEnv(has_renderer=False, has_offscreen_renderer=True, render_camera='frontview', render_collision_mesh=False, render_visual_mesh=True, control_freq=10, horizon=1000, ignore_done=False, hard_reset=True)

Initializes a Mujoco Environment.

Parameters
• has_renderer (bool) – If true, render the simulation state in a viewer instead of headless mode.

• has_offscreen_renderer (bool) – True if using off-screen rendering.

• render_camera (str) – Name of camera to render if has_renderer is True. Setting this value to ‘None’ will result in the default angle being applied, which is useful as it can be dragged / panned by the user using the mouse

• render_collision_mesh (bool) – True if rendering collision meshes in camera. False otherwise.

• render_visual_mesh (bool) – True if rendering visual meshes in camera. False otherwise.

• control_freq (float) – how many control signals to receive in every simulated second. This sets the amount of simulation time that passes between every action input.

• horizon (int) – Every episode lasts for exactly @horizon timesteps.

• ignore_done (bool) – True if never terminating the environment (ignore @horizon).

• hard_reset (bool) – If True, re-loads model, sim, and render object upon a reset call, else, only calls sim.reset and resets all robosuite-internal variables

Raises

ValueError – [Invalid renderer selection]

initialize_time(control_freq)

Initializes the time constants used for simulation.

Parameters

control_freq (float) – Hz rate to run control loop at within the simulation

reset()

Resets simulation.

Returns

Environment observation space after reset occurs

Return type

OrderedDict

step(action)

Takes a step in simulation with control command @action.

Parameters

action (np.array) – Action to execute within the environment

Returns

• (OrderedDict) observations from the environment

• (float) reward from the environment

• (bool) whether the current episode is completed or not

• (dict) misc information

Return type

4-tuple

Raises

ValueError – [Steps past episode termination]

reward(action)

Reward should be a function of state and action

Parameters

action (np.array) – Action to execute within the environment

Returns

Reward from environment

Return type

float

render()

Renders to an on-screen window.

observation_spec()

Returns an observation as observation specification.

An alternative design is to return an OrderedDict where the keys are the observation names and the values are the shapes of observations. We leave this alternative implementation commented out, as we find the current design is easier to use in practice.

Returns

Observations from the environment

Return type

OrderedDict

property action_spec

Action specification should be implemented in subclasses.

Action space is represented by a tuple of (low, high), which are two numpy vectors that specify the min/max action limits per dimension.

property action_dim

Size of the action space :returns: Action space dimension :rtype: int

reset_from_xml_string(xml_string)

Reloads the environment from an XML description of the environment.

Parameters

xml_string (str) – Filepath to the xml file that will be loaded directly into the sim

find_contacts(geoms_1, geoms_2)

Finds contact between two geom groups.

Parameters
• geoms_1 (list of str) – a list of geom names

• geoms_2 (list of str) – another list of geom names

Returns

iterator of all contacts between @geoms_1 and @geoms_2

Return type

generator

close()

Do any cleanup necessary here.

## Robot Environment¶

class robosuite.environments.robot_env.RobotEnv(robots, controller_configs=None, gripper_types='default', gripper_visualizations=False, initialization_noise=None, use_camera_obs=True, use_indicator_object=False, has_renderer=False, has_offscreen_renderer=True, render_camera='frontview', render_collision_mesh=False, render_visual_mesh=True, control_freq=10, horizon=1000, ignore_done=False, hard_reset=True, camera_names='agentview', camera_heights=256, camera_widths=256, camera_depths=False)

Initializes a robot environment in Mujoco.

Parameters
• robots – Specification for specific robot arm(s) to be instantiated within this env (e.g: “Sawyer” would generate one arm; [“Panda”, “Panda”, “Sawyer”] would generate three robot arms)

• controller_configs (str or list of dict) – If set, contains relevant controller parameters for creating a custom controller. Else, uses the default controller for this specific task. Should either be single dict if same controller is to be used for all robots or else it should be a list of the same length as “robots” param

• gripper_types (None or str or list of str) – type of gripper, used to instantiate gripper models from gripper factory. Default is “default”, which is the default grippers(s) associated with the robot(s) the ‘robots’ specification. None removes the gripper, and any other (valid) model overrides the default gripper. Should either be single str if same gripper type is to be used for all robots or else it should be a list of the same length as “robots” param

• gripper_visualizations (bool or list of bool) – True if using gripper visualization. Useful for teleoperation. Should either be single bool if gripper visualization is to be used for all robots or else it should be a list of the same length as “robots” param

• initialization_noise (dict or list of dict) –

Dict containing the initialization noise parameters. The expected keys and corresponding value types are specified below:

’magnitude’

The scale factor of uni-variate random noise applied to each of a robot’s given initial joint positions. Setting this value to None or 0.0 results in no noise being applied. If “gaussian” type of noise is applied then this magnitude scales the standard deviation applied, If “uniform” type of noise is applied then this magnitude sets the bounds of the sampling range

’type’

Type of noise to apply. Can either specify “gaussian” or “uniform”

Should either be single dict if same noise value is to be used for all robots or else it should be a list of the same length as “robots” param

Note

Specifying “default” will automatically use the default noise settings. Specifying None will automatically create the required dict with “magnitude” set to 0.0.

• use_camera_obs (bool) – if True, every observation includes rendered image(s)

• use_indicator_object (bool) – if True, sets up an indicator object that is useful for debugging.

• has_renderer (bool) – If true, render the simulation state in a viewer instead of headless mode.

• has_offscreen_renderer (bool) – True if using off-screen rendering

• render_camera (str) – Name of camera to render if has_renderer is True. Setting this value to ‘None’ will result in the default angle being applied, which is useful as it can be dragged / panned by the user using the mouse

• render_collision_mesh (bool) – True if rendering collision meshes in camera. False otherwise.

• render_visual_mesh (bool) – True if rendering visual meshes in camera. False otherwise.

• control_freq (float) – how many control signals to receive in every second. This sets the amount of simulation time that passes between every action input.

• horizon (int) – Every episode lasts for exactly @horizon timesteps.

• ignore_done (bool) – True if never terminating the environment (ignore @horizon).

• hard_reset (bool) – If True, re-loads model, sim, and render object upon a reset call, else, only calls sim.reset and resets all robosuite-internal variables

• camera_names (str or list of str) –

name of camera to be rendered. Should either be single str if same name is to be used for all cameras’ rendering or else it should be a list of cameras to render.

Note

At least one camera must be specified if @use_camera_obs is True.

Note

To render all robots’ cameras of a certain type (e.g.: “robotview” or “eye_in_hand”), use the convention “all-{name}” (e.g.: “all-robotview”) to automatically render all camera images from each robot’s camera list).

• camera_heights (int or list of int) – height of camera frame. Should either be single int if same height is to be used for all cameras’ frames or else it should be a list of the same length as “camera names” param.

• camera_widths (int or list of int) – width of camera frame. Should either be single int if same width is to be used for all cameras’ frames or else it should be a list of the same length as “camera names” param.

• camera_depths (bool or list of bool) – True if rendering RGB-D, and RGB otherwise. Should either be single bool if same depth setting is to be used for all cameras or else it should be a list of the same length as “camera names” param.

Raises
• ValueError – [Camera obs require offscreen renderer]

• ValueError – [Camera name must be specified to use camera obs]

move_indicator(pos)

Sets 3d position of indicator object to @pos.

Parameters

pos (3-tuple) – (x,y,z) values to place the indicator within the env

_pre_action(action, policy_step=False)

Overrides the superclass method to control the robot(s) within this enviornment using their respective controllers using the passed actions and gripper control.

Parameters
• action (np.array) – The control to apply to the robot(s). Note that this should be a flat 1D array that encompasses all actions to be distributed to each robot if there are multiple. For each section of the action space assigned to a single robot, the first @self.robots[i].controller.control_dim dimensions should be the desired controller actions and if the robot has a gripper, the next @self.robots[i].gripper.dof dimensions should be actuation controls for the gripper.

• policy_step (bool) – Whether a new policy step (action) is being taken

Raises

AssertionError – [Invalid action dimension]

_post_action(action)

Run any necessary visualization after running the action

Parameters

action (np.array) – Action being passed during this timestep

Returns

• (float) reward from the environment

• (bool) whether the current episode is completed or not

• (dict) empty dict to be filled with information by subclassed method

Return type

3-tuple

_get_observation()

Returns an OrderedDict containing observations [(name_string, np.array), …].

Important keys:

‘robot-state’: contains robot-centric information.

‘image’: requires @self.use_camera_obs to be True. Contains a rendered frame from the simulation.

‘depth’: requires @self.use_camera_obs and @self.camera_depth to be True. Contains a rendered depth map from the simulation

Returns

Observations from the environment

Return type

OrderedDict

_check_gripper_contact()

Checks whether each gripper is in contact with an object.

Returns

True if the specific gripper is in contact with an object

Return type

list of bool

_check_arm_contact()

Checks whether each robot arm is in contact with an object.

Returns

True if the specific gripper is in contact with an object

Return type

list of bool

_check_q_limits()

Check if each robot arm is either very close or at the joint limits

Returns

True if the specific arm is near its joint limits

Return type

list of bool

_visualization()

Do any needed visualization here

_load_robots()

Instantiates robots and stores them within the self.robots attribute

_check_robot_configuration(robots)

Sanity check to make sure inputted robots and the corresponding requested task/configuration combo is legal. Should be implemented in every specific task module

Parameters

robots (str or list of str) – Inputted requested robots at the task-level environment