robosuite.utils package

Submodules

robosuite.utils.binding_utils module

Useful classes for supporting DeepMind MuJoCo binding.

class robosuite.utils.binding_utils.MjData(model)

Bases: object

Wrapper class for a MuJoCo ‘mjData’ instance. MjData contains all of the dynamic variables and intermediate results produced by the simulation. These are expected to change on each simulation timestep. The properties without docstrings are defined in mujoco source code from deepmind/mujoco.

property B_colind

property B_rowadr

property B_rownnz

property C_colind

property C_rowadr

property C_rownnz

property D_colind

property D_rowadr

property D_rownnz

property act

property act_dot

property actuator

property actuator_force

property actuator_length

property actuator_moment

property actuator_velocity

property bind

property body

property body_xmat

mujoco-py used to support sim.data.body_xmat but DM mujoco bindings requires sim.data.xmax, so we explicitly expose this as a property

Type:

Note

property body_xpos

mujoco-py used to support sim.data.body_xpos but DM mujoco bindings requires sim.data.xpos, so we explicitly expose this as a property

Type:

Note

property body_xquat

mujoco-py used to support sim.data.body_xquat but DM mujoco bindings requires sim.data.xquat, so we explicitly expose this as a property

Type:

Note

property bvh_aabb_dyn

property bvh_active

property cacc

property cam

property cam_xmat

property cam_xpos

property camera

property cdof

property cdof_dot

property cfrc_ext

property cfrc_int

property cinert

property contact

property crb

property ctrl

property cvel

property dof_island

property dof_islandind

property efc_AR

property efc_AR_colind

property efc_AR_rowadr

property efc_AR_rownnz

property efc_D

property efc_J

property efc_JT

property efc_JT_colind

property efc_JT_rowadr

property efc_JT_rownnz

property efc_JT_rowsuper

property efc_J_colind

property efc_J_rowadr

property efc_J_rownnz

property efc_J_rowsuper

property efc_KBIP

property efc_R

property efc_aref

property efc_b

property efc_diagApprox

property efc_force

property efc_frictionloss

property efc_id

property efc_island

property efc_margin

property efc_pos

property efc_state

property efc_type

property efc_vel

property energy

property eq_active

property flexedge_J

property flexedge_J_colind

property flexedge_J_rowadr

property flexedge_J_rownnz

property flexedge_length

property flexedge_velocity

property flexelem_aabb

property flexvert_xpos

property geom

property geom_xmat

property geom_xpos

get_body_jacp(name)

Query the position jacobian of a mujoco body using a name string.

Parameters:

name (str) – The name of a mujoco body

Returns:

The jacp value of the mujoco body

Return type:

jacp (np.ndarray)

get_body_jacr(name)

Query the rotation jacobian of a mujoco body using a name string.

Parameters:

name (str) – The name of a mujoco body

Returns:

The jacr value of the mujoco body

Return type:

jacr (np.ndarray)

get_body_xmat(name)

Query the rotation of a mujoco body in a rotation matrix using a name string.

Parameters:

name (str) – The name of a mujoco body

Returns:

The xmat value of the mujoco body

Return type:

xmat (np.ndarray)

get_body_xpos(name)

Query cartesian position of a mujoco body using a name string.

Parameters:

name (str) – The name of a mujoco body

Returns:

The xpos value of the mujoco body

Return type:

xpos (np.ndarray)

get_body_xquat(name)

Query the rotation of a mujoco body in quaternion (in wxyz convention) using a name string.

Parameters:

name (str) – The name of a mujoco body

Returns:

The xquat value of the mujoco body

Return type:

xquat (np.ndarray)

get_body_xvelp(name)

Query the translational velocity of a mujoco body using a name string.

Parameters:

name (str) – The name of a mujoco body

Returns:

The translational velocity of the mujoco body.

Return type:

xvelp (np.ndarray)

get_body_xvelr(name)

Query the rotational velocity of a mujoco body using a name string.

Parameters:

name (str) – The name of a mujoco body

Returns:

The rotational velocity of the mujoco body.

Return type:

xvelr (np.ndarray)

get_camera_xmat(name)

Get the rotation of a camera in a rotation matrix using name

Parameters:

name (str) – The name of a camera

Returns:

The 3x3 rotation matrix of a camera

Return type:

cam_xmat (np.ndarray)

get_camera_xpos(name)

Get the cartesian position of a camera using name

Parameters:

name (str) – The name of a camera

Returns:

The cartesian position of a camera

Return type:

cam_xpos (np.ndarray)

get_geom_jacp(name)

Query the position jacobian of a mujoco geom using a name string.

Parameters:

name (str) – The name of a mujoco geom

Returns:

The jacp value of the mujoco geom

Return type:

jacp (np.ndarray)

get_geom_jacr(name)

Query the rotation jacobian of a mujoco geom using a name string.

Parameters:

name (str) – The name of a mujoco geom

Returns:

The jacr value of the mujoco geom

Return type:

jacr (np.ndarray)

get_geom_xmat(name)

Query the rotation of a mujoco geom in a rotation matrix using a name string.

Parameters:

name (str) – The name of a mujoco geom

Returns:

The 3x3 rotation matrix of the mujoco geom.

Return type:

geom_xmat (np.ndarray)

get_geom_xpos(name)

Query the cartesian position of a mujoco geom using a name string.

Parameters:

name (str) – The name of a mujoco geom

Returns:

The cartesian position of the mujoco body.

Return type:

geom_xpos (np.ndarray)

get_geom_xvelp(name)

Query the translational velocity of a mujoco geom using a name string.

Parameters:

name (str) – The name of a mujoco geom

Returns:

The translational velocity of the mujoco geom

Return type:

xvelp (np.ndarray)

get_geom_xvelr(name)

Query the rotational velocity of a mujoco geom using a name string.

Parameters:

name (str) – The name of a mujoco geom

Returns:

The rotational velocity of the mujoco geom

Return type:

xvelr (np.ndarray)

get_joint_qpos(name)

Get the position of a joint using name.

Parameters:

name (str) – The name of a joint

Returns:

The current position of a joint.

Return type:

qpos (np.ndarray)

get_joint_qvel(name)

Get the velocity of a joint using name.

Parameters:

name (str) – The name of a joint

Returns:

The current velocity of a joint.

Return type:

qvel (np.ndarray)

get_light_xdir(name)

Get the direction of a light source using name

Parameters:

name (str) – The name of a light

Returns:

The direction vector of the lightsource

Return type:

light_xdir (np.ndarray)

get_light_xpos(name)

Get cartesian position of a light source

Parameters:

name (str) – The name of a lighting source

Returns:

The cartesian position of the light source

Return type:

light_xpos (np.ndarray)

get_mocap_pos(name)

Get the position of a mocap body using name.

Parameters:

name (str) – The name of a joint

Returns:

The current position of a mocap body.

Return type:

mocap_pos (np.ndarray)

get_mocap_quat(name)

Get the quaternion of a mocap body using name.

Parameters:

name (str) – The name of a joint

Returns:

The current quaternion of a mocap body.

Return type:

mocap_quat (np.ndarray)

get_sensor(name)

Get the data of a sensor using name

Parameters:

name (str) – The name of a sensor

Returns:

The sensor data vector

Return type:

sensordata (np.ndarray)

get_site_jacp(name)

Query the position jacobian of a mujoco site using a name string.

Parameters:

name (str) – The name of a mujoco site

Returns:

The jacp value of the mujoco site

Return type:

jacp (np.ndarray)

get_site_jacr(name)

Query the rotation jacobian of a mujoco site using a name string.

Parameters:

name (str) – The name of a mujoco site

Returns:

The jacr value of the mujoco site

Return type:

jacr (np.ndarray)

get_site_xmat(name)

Query the rotation of a mujoco site in a rotation matrix using a name string.

Parameters:

name (str) – The name of a mujoco site

Returns:

The 3x3 rotation matrix of the mujoco site.

Return type:

site_xmat (np.ndarray)

get_site_xpos(name)

Query the cartesian position of a mujoco site using a name string.

Parameters:

name (str) – The name of a mujoco site

Returns:

The carteisan position of the mujoco site

Return type:

site_xpos (np.ndarray)

get_site_xvelp(name)

Query the translational velocity of a mujoco site using a name string.

Parameters:

name (str) – The name of a mujoco site

Returns:

The translational velocity of the mujoco site

Return type:

xvelp (np.ndarray)

get_site_xvelr(name)

Query the rotational velocity of a mujoco site using a name string.

Parameters:

name (str) – The name of a mujoco site

Returns:

The rotational velocity of the mujoco site

Return type:

xvelr (np.ndarray)

property island_dofadr

property island_dofind

property island_dofnum

property island_efcadr

property island_efcind

property island_efcnum

property jnt

property joint

property light

property light_xdir

property light_xpos

property mapD2M

property mapM2C

property mapM2D

property maxuse_arena

property maxuse_con

property maxuse_efc

property maxuse_stack

property maxuse_threadstack

property mocap_pos

property mocap_quat

property model

The parent MjModel for this MjData instance.

property moment_colind

property moment_rowadr

property moment_rownnz

property nJ

property narena

property nbuffer

property ncon

property ne

property nefc

property nf

property nisland

property nl

property nplugin

property parena

property pbase

property plugin

property plugin_data

property plugin_state

property pstack

property qDeriv

property qH

property qHDiagInv

property qLD

property qLDiagInv

property qLDiagSqrtInv

property qLU

property qM

property qacc

property qacc_smooth

property qacc_warmstart

property qfrc_actuator

property qfrc_applied

property qfrc_bias

property qfrc_constraint

property qfrc_damper

property qfrc_fluid

property qfrc_gravcomp

property qfrc_inverse

property qfrc_passive

property qfrc_smooth

property qfrc_spring

property qpos

property qvel

property sensor

property sensordata

set_joint_qpos(name, value)

Set the position of a joint using name.

Parameters:

• name (str) – The name of a joint

• value (float) – The desired joint velocity of a joint.

set_joint_qvel(name, value)

Set the velocities of a joint using name.

Parameters:

• name (str) – The name of a joint

• value (float) – The desired joint velocity of a joint.

set_mocap_pos(name, value)

Set the quaternion of a mocap body using name.

Parameters:

• name (str) – The name of a joint

• value (float) – The desired joint position of a mocap body.

set_mocap_quat(name, value)

Set the quaternion of a mocap body using name.

Parameters:

• name (str) – The name of a joint

• value (float) – The desired joint quaternion of a mocap body.

property site

property site_xmat

property site_xpos

property solver

property solver_fwdinv

property solver_nisland

property solver_niter

property solver_nnz

property subtree_angmom

property subtree_com

property subtree_linvel

property ten

property ten_J

property ten_J_colind

property ten_J_rowadr

property ten_J_rownnz

property ten_length

property ten_velocity

property ten_wrapadr

property ten_wrapnum

property tendon

property tendon_efcadr

property threadpool

property time

property timer

property userdata

property warning

property wrap_obj

property wrap_xpos

property xanchor

property xaxis

property xfrc_applied

property ximat

property xipos

property xmat

property xpos

property xquat

class robosuite.utils.binding_utils.MjModel(model_ptr)

Bases: object

Wrapper class for a MuJoCo ‘mjModel’ instance. MjModel encapsulates features of the model that are expected to remain constant. It also contains simulation and visualization options which may be changed occasionally, although this is done explicitly by the user.

property actuator

property actuator_acc0

property actuator_actadr

property actuator_actearly

property actuator_actlimited

property actuator_actnum

property actuator_actrange

property actuator_biasprm

property actuator_biastype

property actuator_cranklength

property actuator_ctrllimited

property actuator_ctrlrange

property actuator_dynprm

property actuator_dyntype

property actuator_forcelimited

property actuator_forcerange

property actuator_gainprm

property actuator_gaintype

property actuator_gear

property actuator_group

actuator_id2name(id)

Get actuator name from actuator id.

property actuator_length0

property actuator_lengthrange

actuator_name2id(name)

Get actuator id from actuator name.

property actuator_plugin

property actuator_trnid

property actuator_trntype

property actuator_user

property bind

property body

property body_bvhadr

property body_bvhnum

property body_conaffinity

property body_contype

property body_dofadr

property body_dofnum

property body_geomadr

property body_geomnum

property body_gravcomp

body_id2name(id)

Get body name from mujoco body id.

property body_inertia

property body_invweight0

property body_ipos

property body_iquat

property body_jntadr

property body_jntnum

property body_margin

property body_mass

property body_mocapid

body_name2id(name)

Get body id from mujoco body name.

property body_parentid

property body_plugin

property body_pos

property body_quat

property body_rootid

property body_sameframe

property body_simple

property body_subtreemass

property body_treeid

property body_user

property body_weldid

property bvh_aabb

property bvh_child

property bvh_depth

property bvh_nodeid

property cam

property cam_bodyid

property cam_fovy

property cam_intrinsic

property cam_ipd

property cam_mat0

property cam_mode

property cam_orthographic

property cam_pos

property cam_pos0

property cam_poscom0

property cam_quat

property cam_resolution

property cam_sensorsize

property cam_targetbodyid

property cam_user

property camera

camera_id2name(id)

Get camera name from camera id.

camera_name2id(name)

Get camera id from camera name.

property dof_M0

property dof_Madr

property dof_armature

property dof_bodyid

property dof_damping

property dof_frictionloss

property dof_invweight0

property dof_jntid

property dof_parentid

property dof_simplenum

property dof_solimp

property dof_solref

property dof_treeid

property eq

property eq_active0

property eq_data

property eq_obj1id

property eq_obj2id

property eq_objtype

property eq_solimp

property eq_solref

property eq_type

property equality

property exclude

property exclude_signature

property flex_activelayers

property flex_bvhadr

property flex_bvhnum

property flex_centered

property flex_conaffinity

property flex_condim

property flex_contype

property flex_damping

property flex_dim

property flex_edge

property flex_edgeadr

property flex_edgedamping

property flex_edgeequality

property flex_edgenum

property flex_edgestiffness

property flex_elem

property flex_elemadr

property flex_elemdataadr

property flex_elemedge

property flex_elemedgeadr

property flex_elemlayer

property flex_elemnum

property flex_evpair

property flex_evpairadr

property flex_evpairnum

property flex_flatskin

property flex_friction

property flex_gap

property flex_group

property flex_internal

property flex_margin

property flex_matid

property flex_priority

property flex_radius

property flex_rgba

property flex_rigid

property flex_selfcollide

property flex_shell

property flex_shelldataadr

property flex_shellnum

property flex_solimp

property flex_solmix

property flex_solref

property flex_stiffness

property flex_texcoord

property flex_texcoordadr

property flex_vert

property flex_vert0

property flex_vertadr

property flex_vertbodyid

property flex_vertnum

property flexedge_invweight0

property flexedge_length0

property flexedge_rigid

property from_binary_path

property from_xml_path

property from_xml_string

property geom

property geom_aabb

property geom_bodyid

property geom_conaffinity

property geom_condim

property geom_contype

property geom_dataid

property geom_fluid

property geom_friction

property geom_gap

property geom_group

geom_id2name(id)

Get geom name from geom id.

property geom_margin

property geom_matid

geom_name2id(name)

Get geom id from geom name.

property geom_plugin

property geom_pos

property geom_priority

property geom_quat

property geom_rbound

property geom_rgba

property geom_sameframe

property geom_size

property geom_solimp

property geom_solmix

property geom_solref

property geom_type

property geom_user

get_joint_qpos_addr(name)

See openai/mujoco-py

Returns the qpos address for given joint. Returns: - address (int, tuple): returns int address if 1-dim joint, otherwise

returns the a (start, end) tuple for pos[start:end] access.

get_joint_qvel_addr(name)

See openai/mujoco-py

Returns the qvel address for given joint. Returns: - address (int, tuple): returns int address if 1-dim joint, otherwise

returns the a (start, end) tuple for vel[start:end] access.

get_xml()

property hfield

property hfield_adr

property hfield_data

property hfield_ncol

property hfield_nrow

property hfield_pathadr

property hfield_size

property jnt

property jnt_actfrclimited

property jnt_actfrcrange

property jnt_actgravcomp

property jnt_axis

property jnt_bodyid

property jnt_dofadr

property jnt_group

property jnt_limited

property jnt_margin

property jnt_pos

property jnt_qposadr

property jnt_range

property jnt_solimp

property jnt_solref

property jnt_stiffness

property jnt_type

property jnt_user

property joint

joint_id2name(id)

Get joint name from mujoco joint id.

joint_name2id(name)

Get joint id from joint name.

property key

property key_act

property key_ctrl

property key_mpos

property key_mquat

property key_qpos

property key_qvel

property key_time

property keyframe

property light

property light_active

property light_ambient

property light_attenuation

property light_bodyid

property light_bulbradius

property light_castshadow

property light_cutoff

property light_diffuse

property light_dir

property light_dir0

property light_directional

property light_exponent

light_id2name(id)

Get light name from light id.

property light_mode

light_name2id(name)

Get light id from light name.

property light_pos

property light_pos0

property light_poscom0

property light_specular

property light_targetbodyid

make_mappings()

Make some useful internal mappings that mujoco-py supported.

property mat

property mat_emission

property mat_metallic

property mat_reflectance

property mat_rgba

property mat_roughness

property mat_shininess

property mat_specular

property mat_texid

property mat_texrepeat

property mat_texuniform

property material

property mesh

property mesh_bvhadr

property mesh_bvhnum

property mesh_face

property mesh_faceadr

property mesh_facenormal

property mesh_facenum

property mesh_facetexcoord

property mesh_graph

property mesh_graphadr

mesh_id2name(id)

Get mesh name from mesh id.

mesh_name2id(name)

Get mesh id from mesh name.

property mesh_normal

property mesh_normaladr

property mesh_normalnum

property mesh_pathadr

property mesh_pos

property mesh_quat

property mesh_scale

property mesh_texcoord

property mesh_texcoordadr

property mesh_texcoordnum

property mesh_vert

property mesh_vertadr

property mesh_vertnum

property nB

property nC

property nD

property nJmom

property nM

property na

property name_actuatoradr

property name_bodyadr

property name_camadr

property name_eqadr

property name_excludeadr

property name_flexadr

property name_geomadr

property name_hfieldadr

property name_jntadr

property name_keyadr

property name_lightadr

property name_matadr

property name_meshadr

property name_numericadr

property name_pairadr

property name_pluginadr

property name_sensoradr

property name_siteadr

property name_skinadr

property name_tendonadr

property name_texadr

property name_textadr

property name_tupleadr

property names

property names_map

property narena

property nbody

property nbuffer

property nbvh

property nbvhdynamic

property nbvhstatic

property ncam

property nconmax

property nemax

property neq

property nexclude

property nflex

property nflexedge

property nflexelem

property nflexelemdata

property nflexelemedge

property nflexevpair

property nflexshelldata

property nflextexcoord

property nflexvert

property ngeom

property ngravcomp

property nhfield

property nhfielddata

property njmax

property njnt

property nkey

property nlight

property nmat

property nmesh

property nmeshface

property nmeshgraph

property nmeshnormal

property nmeshtexcoord

property nmeshvert

property nmocap

property nnames

property nnames_map

property nnumeric

property nnumericdata

property npair

property npaths

property nplugin

property npluginattr

property npluginstate

property nq

property nsensor

property nsensordata

property nsite

property nskin

property nskinbone

property nskinbonevert

property nskinface

property nskintexvert

property nskinvert

property ntendon

property ntex

property ntexdata

property ntext

property ntextdata

property ntree

property ntuple

property ntupledata

property nu

property numeric

property numeric_adr

property numeric_data

property numeric_size

property nuser_actuator

property nuser_body

property nuser_cam

property nuser_geom

property nuser_jnt

property nuser_sensor

property nuser_site

property nuser_tendon

property nuserdata

property nv

property nwrap

property opt

property pair

property pair_dim

property pair_friction

property pair_gap

property pair_geom1

property pair_geom2

property pair_margin

property pair_signature

property pair_solimp

property pair_solref

property pair_solreffriction

property paths

property plugin

property plugin_attr

property plugin_attradr

property plugin_stateadr

property plugin_statenum

property qpos0

property qpos_spring

property sensor

property sensor_adr

property sensor_cutoff

property sensor_datatype

property sensor_dim

sensor_id2name(id)

Get sensor name from sensor id.

sensor_name2id(name)

Get sensor id from sensor name.

property sensor_needstage

property sensor_noise

property sensor_objid

property sensor_objtype

property sensor_plugin

property sensor_refid

property sensor_reftype

property sensor_type

property sensor_user

property site

property site_bodyid

property site_group

site_id2name(id)

Get site name from site id.

property site_matid

site_name2id(name)

Get site id from site name.

property site_pos

property site_quat

property site_rgba

property site_sameframe

property site_size

property site_type

property site_user

property skin

property skin_boneadr

property skin_bonebindpos

property skin_bonebindquat

property skin_bonebodyid

property skin_bonenum

property skin_bonevertadr

property skin_bonevertid

property skin_bonevertnum

property skin_bonevertweight

property skin_face

property skin_faceadr

property skin_facenum

property skin_group

property skin_inflate

property skin_matid

property skin_pathadr

property skin_rgba

property skin_texcoord

property skin_texcoordadr

property skin_vert

property skin_vertadr

property skin_vertnum

property stat

property tendon

property tendon_adr

property tendon_damping

property tendon_frictionloss

property tendon_group

tendon_id2name(id)

Get tendon name from tendon id.

property tendon_invweight0

property tendon_length0

property tendon_lengthspring

property tendon_limited

property tendon_margin

property tendon_matid

tendon_name2id(name)

Get tendon id from tendon name.

property tendon_num

property tendon_range

property tendon_rgba

property tendon_solimp_fri

property tendon_solimp_lim

property tendon_solref_fri

property tendon_solref_lim

property tendon_stiffness

property tendon_user

property tendon_width

property tex

property tex_adr

property tex_data

property tex_height

property tex_nchannel

property tex_pathadr

property tex_type

property tex_width

property text_adr

property text_data

property text_size

property texture

property tuple

property tuple_adr

property tuple_objid

property tuple_objprm

property tuple_objtype

property tuple_size

property vis

property wrap_objid

property wrap_prm

property wrap_type

class robosuite.utils.binding_utils.MjRenderContext(sim, offscreen=True, device_id=-1, max_width=640, max_height=480)

Bases: object

Class that encapsulates rendering functionality for a MuJoCo simulation.

See openai/mujoco-py

read_pixels(width, height, depth=False, segmentation=False)

render(width, height, camera_id=None, segmentation=False)

update_offscreen_size(width, height)

upload_texture(tex_id)

Uploads given texture to the GPU.

class robosuite.utils.binding_utils.MjRenderContextOffscreen(sim, device_id, max_width=640, max_height=480)

Bases: MjRenderContext

class robosuite.utils.binding_utils.MjSim(model)

Bases: object

Meant to somewhat replicate functionality in mujoco-py’s MjSim object (see openai/mujoco-py).

add_render_context(render_context)

forward()

Forward call to synchronize derived quantities.

free()

classmethod from_xml_file(xml_file)

classmethod from_xml_string(xml)

get_state()

Return MjSimState instance for current state.

render(width=None, height=None, *, camera_name=None, depth=False, mode='offscreen', device_id=-1, segmentation=False)

Renders view from a camera and returns image as an numpy.ndarray. Args: - width (int): desired image width. - height (int): desired image height. - camera_name (str): name of camera in model. If None, the free

camera will be used.

• depth (bool): if True, also return depth buffer

• device (int): device to use for rendering (only for GPU-backed

  rendering).

Returns: - rgb (uint8 array): image buffer from camera - depth (float array): depth buffer from camera (only returned

if depth=True)

reset()

Reset simulation.

set_state(value)

Set internal state from MjSimState instance. Should call @forward afterwards to synchronize derived quantities.

set_state_from_flattened(value)

Set internal mujoco state using flat mjstate array. Should call @forward afterwards to synchronize derived quantities.

See openai/mujoco-py

step(with_udd=True)

Step simulation.

step1()

Step1 (before actions are set).

step2()

Step2 (after actions are set).

class robosuite.utils.binding_utils.MjSimState(time, qpos, qvel)

Bases: object

A mujoco simulation state.

flatten()

classmethod from_flattened(array, sim)

Takes flat mjstate array and MjSim instance and returns MjSimState.

robosuite.utils.buffers module

Collection of Buffer objects with general functionality

class robosuite.utils.buffers.Buffer

Bases: object

Abstract class for different kinds of data buffers. Minimum API should have a “push” and “clear” method

clear()

push(value)

Pushes a new @value to the buffer

Parameters:

value – Value to push to the buffer

class robosuite.utils.buffers.DelayBuffer(dim, length)

Bases: RingBuffer

Modified RingBuffer that returns delayed values when polled

get_delayed_value(delay)

Returns value @delay increments behind most recent value.

Parameters:

delay (int) – How many steps backwards from most recent value to grab value. Note that this should not be greater than the buffer’s length

Returns:

delayed value

Return type:

np.array

class robosuite.utils.buffers.DeltaBuffer(dim, init_value=None)

Bases: Buffer

Simple 2-length buffer object to streamline grabbing delta values between “current” and “last” values

Constructs delta object.

Parameters:

• dim (int) – Size of numerical arrays being inputted

• init_value (None or Iterable) – Initial value to fill “last” value with initially. If None (default), last array will be filled with zeros

property average

Returns the average between the current and last value

Returns:

Averaged value of all elements in buffer

Return type:

float or np.array

clear()

Clears last and current value

property delta

Returns the delta between last value and current value. If abs_value is set to True, then returns the absolute value between the values

Parameters:

abs_value (bool) – Whether to return absolute value or not

Returns:

difference between current and last value

Return type:

float or np.array

push(value)

Pushes a new value into the buffer; current becomes last and @value becomes current

Parameters:

value (int or float or array) – Value(s) to push into the array (taken as a single new element)

class robosuite.utils.buffers.RingBuffer(dim, length)

Bases: Buffer

Simple RingBuffer object to hold values to average (useful for, e.g.: filtering D component in PID control)

Note that the buffer object is a 2D numpy array, where each row corresponds to individual entries into the buffer

Parameters:

• dim (int) – Size of entries being added. This is, e.g.: the size of a state vector that is to be stored

• length (int) – Size of the ring buffer

property average

Gets the average of components in buffer

Returns:

Averaged value of all elements in buffer

Return type:

float or np.array

clear()

Clears buffer and reset pointer

property current

Gets the most recent value pushed to the buffer

Returns:

Most recent value in buffer

Return type:

float or np.array

push(value)

Pushes a new value into the buffer

Parameters:

value (int or float or array) – Value(s) to push into the array (taken as a single new element)

robosuite.utils.camera_utils module

robosuite.utils.control_utils module

robosuite.utils.control_utils.nullspace_torques(mass_matrix, nullspace_matrix, initial_joint, joint_pos, joint_vel, joint_kp=10)

For a robot with redundant DOF(s), a nullspace exists which is orthogonal to the remainder of the controllable subspace of the robot’s joints. Therefore, an additional secondary objective that does not impact the original controller objective may attempt to be maintained using these nullspace torques.

This utility function specifically calculates nullspace torques that attempt to maintain a given robot joint positions @initial_joint with zero velocity using proportinal gain @joint_kp

Note:

@mass_matrix, @nullspace_matrix, @joint_pos, and @joint_vel should reflect the robot’s state at the current

timestep

Parameters:

• mass_matrix (np.array) – 2d array representing the mass matrix of the robot

• nullspace_matrix (np.array) – 2d array representing the nullspace matrix of the robot

• initial_joint (np.array) – Joint configuration to be used for calculating nullspace torques

• joint_pos (np.array) – Current joint positions

• joint_vel (np.array) – Current joint velocities

• joint_kp (float) – Proportional control gain when calculating nullspace torques

Returns:

nullspace torques

Return type:

np.array

robosuite.utils.control_utils.opspace_matrices(mass_matrix, J_full, J_pos, J_ori)

Calculates the relevant matrices used in the operational space control algorithm

Parameters:

• mass_matrix (np.array) – 2d array representing the mass matrix of the robot

• J_full (np.array) – 2d array representing the full Jacobian matrix of the robot

• J_pos (np.array) – 2d array representing the position components of the Jacobian matrix of the robot

• J_ori (np.array) – 2d array representing the orientation components of the Jacobian matrix of the robot

Returns:

• (np.array): full lambda matrix (as 2d array)

• (np.array): position components of lambda matrix (as 2d array)

• (np.array): orientation components of lambda matrix (as 2d array)

• (np.array): nullspace matrix (as 2d array)

Return type:

4-tuple

robosuite.utils.control_utils.orientation_error(desired, current)

This function calculates a 3-dimensional orientation error vector for use in the impedance controller. It does this by computing the delta rotation between the inputs and converting that rotation to exponential coordinates (axis-angle representation, where the 3d vector is axis * angle). See https://en.wikipedia.org/wiki/Axis%E2%80%93angle_representation for more information. Optimized function to determine orientation error from matrices

Parameters:

• desired (np.array) – 2d array representing target orientation matrix

• current (np.array) – 2d array representing current orientation matrix

Returns:

2d array representing orientation error as a matrix

Return type:

np.array

robosuite.utils.control_utils.set_goal_orientation(delta, current_orientation, orientation_limit=None, set_ori=None)

Calculates and returns the desired goal orientation, clipping the result accordingly to @orientation_limits. @delta and @current_orientation must be specified if a relative goal is requested, else @set_ori must be an orientation matrix specified to define a global orientation

Parameters:

• delta (np.array) – Desired relative change in orientation, in axis-angle form [ax, ay, az]

• current_orientation (np.array) – Current orientation, in rotation matrix form

• orientation_limit (None or np.array) – 2d array defining the (min, max) limits of permissible orientation goal commands

• set_ori (None or np.array) – If set, will ignore @delta and set the goal orientation to this value

Returns:

calculated goal orientation in absolute coordinates

Return type:

np.array

Raises:

ValueError – [Invalid orientation_limit shape]

robosuite.utils.control_utils.set_goal_position(delta, current_position, position_limit=None, set_pos=None)

Calculates and returns the desired goal position, clipping the result accordingly to @position_limits. @delta and @current_position must be specified if a relative goal is requested, else @set_pos must be specified to define a global goal position

Parameters:

• delta (np.array) – Desired relative change in position

• current_position (np.array) – Current position

• position_limit (None or np.array) – 2d array defining the (min, max) limits of permissible position goal commands

• set_pos (None or np.array) – If set, will ignore @delta and set the goal position to this value

Returns:

calculated goal position in absolute coordinates

Return type:

np.array

Raises:

ValueError – [Invalid position_limit shape]

robosuite.utils.errors module

exception robosuite.utils.errors.RandomizationError

Bases: robosuiteError

Exception raised for really really bad RNG.

exception robosuite.utils.errors.SimulationError

Bases: robosuiteError

Exception raised for errors during runtime.

exception robosuite.utils.errors.XMLError

Bases: robosuiteError

Exception raised for errors related to xml.

exception robosuite.utils.errors.robosuiteError

Bases: Exception

Base class for exceptions in robosuite.

robosuite.utils.input_utils module

robosuite.utils.log_utils module

This file contains utility classes and functions for logging to stdout and stderr Adapted from robomimic: ARISE-Initiative/robomimic

class robosuite.utils.log_utils.ConsoleFormatter(fmt=None, datefmt=None, style='%', validate=True)

Bases: Formatter

Formatter class of logging for console logging.

FORMATS = {10: '[robosuite %(levelname)s] %(message)s (%(filename)s:%(lineno)d)', 20: '[robosuite %(levelname)s] %(message)s (%(filename)s:%(lineno)d)', 30: '[robosuite %(levelname)s] %(message)s (%(filename)s:%(lineno)d)', 40: '[robosuite %(levelname)s] %(message)s (%(filename)s:%(lineno)d)', 50: '[robosuite %(levelname)s] %(message)s (%(filename)s:%(lineno)d)'}

format(record)

Apply custom fomatting on LogRecord object record.

class robosuite.utils.log_utils.DefaultLogger(logger_name='robosuite_logs', console_logging_level='INFO', file_logging_level=None)

Bases: object

Default logger class in robosuite codebase.

get_logger()

_summary_

Returns:

The retrieved logger whose name equals self.logger_name

Return type:

DefaultLogger

class robosuite.utils.log_utils.FileFormatter(fmt=None, datefmt=None, style='%', validate=True)

Bases: Formatter

Formatter class of logging for file logging.

FORMATS = {10: '[robosuite %(levelname)s - %(asctime)s] %(message)s (%(filename)s:%(lineno)d)', 20: '[robosuite %(levelname)s - %(asctime)s] %(message)s (%(filename)s:%(lineno)d)', 30: '[robosuite %(levelname)s - %(asctime)s] %(message)s (%(filename)s:%(lineno)d)', 40: '[robosuite %(levelname)s - %(asctime)s] %(message)s (%(filename)s:%(lineno)d)', 50: '[robosuite %(levelname)s - %(asctime)s] %(message)s (%(filename)s:%(lineno)d)'}

format(record)

Apply custom fomatting on LogRecord object record.

robosuite.utils.mjcf_utils module

class robosuite.utils.mjcf_utils.CustomMaterial(texture, tex_name, mat_name, tex_attrib=None, mat_attrib=None, shared=False)

Bases: object

Simple class to instantiate the necessary parameters to define an appropriate texture / material combo

Instantiates a nested dict holding necessary components for procedurally generating a texture / material combo

Please see http://www.mujoco.org/book/XMLreference.html#asset for specific details on

attributes expected for Mujoco texture / material tags, respectively

Note that the values in @tex_attrib and @mat_attrib can be in string or array / numerical form.

Parameters:

• texture (None or str or 4-array) – Name of texture file to be imported. If a string, should be part of ALL_TEXTURES. If texture is a 4-array, then this argument will be interpreted as an rgba tuple value and a template png will be procedurally generated during object instantiation, with any additional texture / material attributes specified. If None, no file will be linked and no rgba value will be set Note, if specified, the RGBA values are expected to be floats between 0 and 1

• tex_name (str) – Name to reference the imported texture

• mat_name (str) – Name to reference the imported material

• tex_attrib (dict) – Any other optional mujoco texture specifications.

• mat_attrib (dict) – Any other optional mujoco material specifications.

• shared (bool) – If True, this material should not have any naming prefixes added to all names

Raises:

AssertionError – [Invalid texture]

robosuite.utils.mjcf_utils.add_material(root, naming_prefix='', custom_material=None)

Iterates through all element(s) in @root recursively and adds a material / texture to all visual geoms that don’t already have a material specified.

Parameters:

• root (ET.Element) – Root of the xml element tree to start recursively searching through.

• naming_prefix (str) – Adds this prefix to all material and texture names

• custom_material (None or CustomMaterial) – If specified, will add this material to all visual geoms. Else, will add a default “no-change” material.

Returns:

(ET.Element, ET.Element, CustomMaterial, bool) (tex_element, mat_element, material, used)

corresponding to the added material and whether the material was actually used or not.

Return type:

4-tuple

robosuite.utils.mjcf_utils.add_prefix(root, prefix, tags='default', attribs='default', exclude=None)

Find all element(s) matching the requested @tag, and appends @prefix to all @attributes if they exist.

Parameters:

• root (ET.Element) – Root of the xml element tree to start recursively searching through.

• prefix (str) – Prefix to add to all specified attributes

• tags (str or list of str or set) – Tag(s) to search for in this ElementTree. “Default” corresponds to all tags

• attribs (str or list of str or set) – Element attribute(s) to append prefix to. “Default” corresponds to all attributes that reference names

• exclude (None or function) – Filtering function that should take in an ET.Element or a string (attribute) and return True if we should exclude the given element / attribute from having any prefixes added

robosuite.utils.mjcf_utils.add_to_dict(dic, fill_in_defaults=True, default_value=None, **kwargs)

Helper function to add key-values to dictionary @dic where each entry is its own array (list). :param dic: Dictionary to which new key / value pairs will be added. If the key already exists,

will append the value to that key entry

Parameters:

• fill_in_defaults (bool) – If True, will automatically add @default_value to all dictionary entries that are not explicitly specified in @kwargs

• default_value (any) – Default value to fill (None by default)

Returns:

Modified dictionary

Return type:

dict

robosuite.utils.mjcf_utils.array_to_string(array)

Converts a numeric array into the string format in mujoco.

Examples

[0, 1, 2] => “0 1 2”

Parameters:

array (n-array) – Array to convert to a string

Returns:

String equivalent of @array

Return type:

str

robosuite.utils.mjcf_utils.convert_to_string(inp)

Converts any type of {bool, int, float, list, tuple, array, string, np.str_} into an mujoco-xml compatible string.

Note that an input string / np.str_ results in a no-op action.

Parameters:

inp – Input to convert to string

Returns:

String equivalent of @inp

Return type:

str

robosuite.utils.mjcf_utils.find_elements(root, tags, attribs=None, return_first=True)

Find all element(s) matching the requested @tag and @attributes. If @return_first is True, then will return the first element found matching the criteria specified. Otherwise, will return a list of elements that match the criteria.

Parameters:

• root (ET.Element) – Root of the xml element tree to start recursively searching through.

• tags (str or list of str or set) – Tag(s) to search for in this ElementTree.

• attribs (None or dict of str) – Element attribute(s) to check against for a filtered element. A match is considered found only if all attributes match. Each attribute key should have a corresponding value with which to compare against.

• return_first (bool) – Whether to immediately return once the first matching element is found.

Returns:

Matching element(s) found. Returns None if there was no match.

Return type:

None or ET.Element or list of ET.Element

robosuite.utils.mjcf_utils.find_elements_by_substring(root, tags, substrings, attribs=None, return_first=False)

Find all element(s) matching the requested @substrings and @attributes. If @return_first is True, then will return the first element found matching the criteria specified. Otherwise, will return a list of elements that match the criteria.

Parameters:

• root (ET.Element) – Root of the xml element tree to start recursively searching through.

• tags (str or list of str or set) – Tag(s) to search for in this ElementTree.

• substrings (str or list of str or set) – Substring(s) to search for in this ElementTree.

• attribs (None or dict of str) – Element attribute(s) to check against for a filtered element. A match is considered found only if all attributes match. Each attribute key should have a corresponding value with which to compare against.

• return_first (bool) – Whether to immediately return once the first matching element is found.

Returns:

Matching element(s) found. Returns None if there was no match.

Return type:

None or ET.Element or list of ET.Element

robosuite.utils.mjcf_utils.find_parent(element, target)

Find the parent element of the target.

robosuite.utils.mjcf_utils.get_ids(sim, elements, element_type='geom', inplace=False)

Grabs the mujoco IDs for each element in @elements, corresponding to the specified @element_type.

Parameters:

• sim (MjSim) – Active mujoco simulation object

• elements (str or list or dict) – Element(s) to convert into IDs. Note that the return type corresponds to @elements type, where each element name is replaced with the ID

• element_type (str) – The type of element to grab ID for. Options are {geom, body, site}

• inplace (bool) – If False, will create a copy of @elements to prevent overwriting the original data structure

Returns:

IDs corresponding to @elements.

Return type:

str or list or dict

robosuite.utils.mjcf_utils.get_size(size, size_max, size_min, default_max, default_min)

Helper method for providing a size, or a range to randomize from

Parameters:

• size (n-array) – Array of numbers that explicitly define the size

• size_max (n-array) – Array of numbers that define the custom max size from which to randomly sample

• size_min (n-array) – Array of numbers that define the custom min size from which to randomly sample

• default_max (n-array) – Array of numbers that define the default max size from which to randomly sample

• default_min (n-array) – Array of numbers that define the default min size from which to randomly sample

Returns:

size generated

Return type:

np.array

Raises:

ValueError – [Inconsistent array sizes]

robosuite.utils.mjcf_utils.new_actuator(name, joint, act_type='actuator', **kwargs)

Creates an actuator tag with attributes specified by @**kwargs.

Parameters:

• name (str) – Name for this actuator

• joint (str) – type of actuator transmission. see all types here: http://mujoco.org/book/modeling.html#actuator

• act_type (str) – actuator type. Defaults to “actuator”

• **kwargs – Any additional specified attributes for the new joint

Returns:

new actuator xml element

Return type:

ET.Element

robosuite.utils.mjcf_utils.new_body(name, pos=(0, 0, 0), **kwargs)

Creates a body element with attributes specified by @**kwargs.

Parameters:

• name (str) – Name for this body

• pos (3-array) – (x,y,z) 3d position of the body frame.

• **kwargs – Any additional specified attributes for the new body

Returns:

new body xml element

Return type:

ET.Element

robosuite.utils.mjcf_utils.new_element(tag, name, **kwargs)

Creates a new @tag element with attributes specified by @**kwargs.

Parameters:

• tag (str) – Type of element to create

• name (None or str) – Name for this element. Should only be None for elements that do not have an explicit name attribute (e.g.: inertial elements)

• **kwargs – Specified attributes for the new joint

Returns:

new specified xml element

Return type:

ET.Element

robosuite.utils.mjcf_utils.new_geom(name, type, size, pos=(0, 0, 0), group=0, **kwargs)

Creates a geom element with attributes specified by @**kwargs.

NOTE: With the exception of @geom_type, @size, and @pos, if any arg is set to

None, the value will automatically be popped before passing the values to create the appropriate XML

Parameters:

• name (str) – Name for this geom

• type (str) – type of the geom. see all types here: http://mujoco.org/book/modeling.html#geom

• size (n-array of float) – geom size parameters.

• pos (3-array) – (x,y,z) 3d position of the site.

• group (int) – the integrer group that the geom belongs to. useful for separating visual and physical elements.

• **kwargs – Any additional specified attributes for the new geom

Returns:

new geom xml element

Return type:

ET.Element

robosuite.utils.mjcf_utils.new_inertial(pos=(0, 0, 0), mass=None, **kwargs)

Creates a inertial element with attributes specified by @**kwargs.

Parameters:

• pos (3-array) – (x,y,z) 3d position of the inertial frame.

• mass (float) – The mass of inertial

• **kwargs – Any additional specified attributes for the new inertial element

Returns:

new inertial xml element

Return type:

ET.Element

robosuite.utils.mjcf_utils.new_joint(name, **kwargs)

Creates a joint tag with attributes specified by @**kwargs.

Parameters:

• name (str) – Name for this joint

• **kwargs – Specified attributes for the new joint

Returns:

new joint xml element

Return type:

ET.Element

robosuite.utils.mjcf_utils.new_site(name, rgba=[1, 0, 0, 1], pos=(0, 0, 0), size=(0.005,), **kwargs)

Creates a site element with attributes specified by @**kwargs.

NOTE: With the exception of @name, @pos, and @size, if any arg is set to

None, the value will automatically be popped before passing the values to create the appropriate XML

Parameters:

• name (str) – Name for this site

• rgba (4-array) – (r,g,b,a) color and transparency. Defaults to solid red.

• pos (3-array) – (x,y,z) 3d position of the site.

• size (n-array of float) – site size (sites are spherical by default).

• **kwargs – Any additional specified attributes for the new site

Returns:

new site xml element

Return type:

ET.Element

robosuite.utils.mjcf_utils.recolor_collision_geoms(root, rgba, exclude=None)

Iteratively searches through all elements starting with @root to find all geoms belonging to group 0 and set the corresponding rgba value to the specified @rgba argument. Note: also removes any material values for these elements.

Parameters:

• root (ET.Element) – Root of the xml element tree to start recursively searching through

• rgba (4-array) – (R, G, B, A) values to assign to all geoms with this group.

• exclude (None or function) – Filtering function that should take in an ET.Element and return True if we should exclude the given element / attribute from having its collision geom impacted.

robosuite.utils.mjcf_utils.save_sim_model(sim, fname)

Saves the current model xml from @sim at file location @fname.

Parameters:

• sim (MjSim) – XML file to save, in string form

• fname (str) – Absolute filepath to the location to save the file

robosuite.utils.mjcf_utils.set_alpha(node, alpha=0.1)

Sets all a(lpha) field of the rgba attribute to be @alpha for @node and all subnodes used for managing display

Parameters:

• node (ET.Element) – Specific node element within XML tree

• alpha (float) – Value to set alpha value of rgba tuple

robosuite.utils.mjcf_utils.sort_elements(root, parent=None, element_filter=None, _elements_dict=None)

Utility method to iteratively sort all elements based on @tags. This XML ElementTree will be parsed such that all elements with the same key as returned by @element_filter will be grouped as a list entry in the returned dictionary.

Parameters:

• root (ET.Element) – Root of the xml element tree to start recursively searching through

• parent (ET.Element) – Parent of the root node. Default is None (no parent node initially)

• element_filter (None or function) – Function used to filter the incoming elements. Should take in two ET.Elements (current_element, parent_element) and return a string filter_key if the element should be added to the list of values sorted by filter_key, and return None if no value should be added. If no element_filter is specified, defaults to self._element_filter.

• _elements_dict (dict) – Dictionary that gets passed to recursive calls. Should not be modified externally by top-level call.

Returns:

Filtered key-specific lists of the corresponding elements

Return type:

dict

robosuite.utils.mjcf_utils.string_to_array(string)

Converts a array string in mujoco xml to np.array.

Examples

“0 1 2” => [0, 1, 2]

Parameters:

string (str) – String to convert to an array

Returns:

Numerical array equivalent of @string

Return type:

np.array

robosuite.utils.mjcf_utils.xml_path_completion(xml_path, root=None)

Takes in a local xml path and returns a full path.

if @xml_path is absolute, do nothing if @xml_path is not absolute, load xml that is shipped by the package

Parameters:

• xml_path (str) – local xml path

• root (str) – root folder for xml path. If not specified defaults to robosuite.models.assets_root

Returns:

Full (absolute) xml path

Return type:

str

robosuite.utils.mjmod module

Modder classes used for domain randomization. Largely based off of the mujoco-py implementation below.

openai/mujoco-py

class robosuite.utils.mjmod.BaseModder(sim, random_state=None)

Bases: object

Base class meant to modify simulation attributes mid-sim.

Using @random_state ensures that sampling here won’t be affected by sampling that happens outside of the modders.

Parameters:

• sim (MjSim) – simulation object

• random_state (RandomState) – instance of np.random.RandomState, specific seed used to randomize these modifications without impacting other numpy seeds / randomizations

property model

Returns: MjModel: Mujoco sim model

update_sim(sim)

Setter function to update internal sim variable

Parameters:

sim (MjSim) – MjSim object

class robosuite.utils.mjmod.CameraModder(sim, random_state=None, camera_names=None, randomize_position=True, randomize_rotation=True, randomize_fovy=True, position_perturbation_size=0.01, rotation_perturbation_size=0.087, fovy_perturbation_size=5.0)

Bases: BaseModder

Modder for modifying camera attributes in mujoco sim

Parameters:

• sim (MjSim) – MjSim object

• random_state (None or RandomState) – instance of np.random.RandomState

• camera_names (None or list of str) – list of camera names to use for randomization. If not provided, all cameras are used for randomization.

• randomize_position (bool) – if True, randomize camera position

• randomize_rotation (bool) – if True, randomize camera rotation

• randomize_fovy (bool) – if True, randomize camera fovy

• position_perturbation_size (float) – size of camera position perturbations to each dimension

• rotation_perturbation_size (float) – magnitude of camera rotation perturbations in axis-angle. Default corresponds to around 5 degrees.

• fovy_perturbation_size (float) – magnitude of camera fovy perturbations (corresponds to focusing)

Raises:

AssertionError – [No randomization selected]

get_camid(name)

Grabs unique id number of a specific camera

Parameters:

name (str) – Name of the camera

Returns:

id of camera. -1 if not found

Return type:

int

get_fovy(name)

Grabs fovy of a specific camera

Parameters:

name (str) – Name of the camera

Returns:

vertical field of view of the camera, expressed in degrees

Return type:

float

Raises:

AssertionError – Invalid camera name

get_pos(name)

Grabs position of a specific camera

Parameters:

name (str) – Name of the camera

Returns:

(x,y,z) position of the camera

Return type:

np.array

Raises:

AssertionError – Invalid camera name

get_quat(name)

Grabs orientation of a specific camera

Parameters:

name (str) – Name of the camera

Returns:

(w,x,y,z) orientation of the camera, expressed in quaternions

Return type:

np.array

Raises:

AssertionError – Invalid camera name

randomize()

Randomizes all requested camera values within the sim

restore_defaults()

Reloads the saved parameter values.

save_defaults()

Uses the current MjSim state and model to save default parameter values.

set_fovy(name, value)

Sets fovy of a specific camera

Parameters:

• name (str) – Name of the camera

• value (float) – vertical field of view of the camera, expressed in degrees

Raises:

• AssertionError – Invalid camera name

• AssertionError – Invalid value

set_pos(name, value)

Sets position of a specific camera

Parameters:

• name (str) – Name of the camera

• value (np.array) – (x,y,z) position of the camera

Raises:

• AssertionError – Invalid camera name

• AssertionError – Invalid value

set_quat(name, value)

Sets orientation of a specific camera

Parameters:

• name (str) – Name of the camera

• value (np.array) – (w,x,y,z) orientation of the camera, expressed in quaternions

Raises:

• AssertionError – Invalid camera name

• AssertionError – Invalid value

class robosuite.utils.mjmod.DynamicsModder(sim, random_state=None, randomize_density=True, randomize_viscosity=True, density_perturbation_ratio=0.1, viscosity_perturbation_ratio=0.1, body_names=None, randomize_position=True, randomize_quaternion=True, randomize_inertia=True, randomize_mass=True, position_perturbation_size=0.02, quaternion_perturbation_size=0.02, inertia_perturbation_ratio=0.02, mass_perturbation_ratio=0.02, geom_names=None, randomize_friction=True, randomize_solref=True, randomize_solimp=True, friction_perturbation_ratio=0.1, solref_perturbation_ratio=0.1, solimp_perturbation_ratio=0.1, joint_names=None, randomize_stiffness=True, randomize_frictionloss=True, randomize_damping=True, randomize_armature=True, stiffness_perturbation_ratio=0.1, frictionloss_perturbation_size=0.05, damping_perturbation_size=0.01, armature_perturbation_size=0.01)

Bases: BaseModder

Modder for various dynamics properties of the mujoco model, such as friction, damping, etc. This can be used to modify parameters stored in MjModel (ie friction, damping, etc.) as well as optimizer parameters stored in PyMjOption (i.e.: medium density, viscosity, etc.) To modify a parameter, use the parameter to be changed as a keyword argument to self.mod and the new value as the value for that argument. Supports arbitrary many modifications in a single step. Example use:

sim = MjSim(…) modder = DynamicsModder(sim) modder.mod(“element1_name”, “attr1”, new_value1) modder.mod(“element2_name”, “attr2”, new_value2) … modder.update()

NOTE: It is necessary to perform modder.update() after performing all modifications to make sure

the changes are propagated

NOTE: A full list of supported randomizable parameters can be seen by calling modder.dynamics_parameters

NOTE: When modifying parameters belonging to MjModel.opt (e.g.: density, viscosity), no name should

be specified (set it as None in mod(…)). This is because opt does not have a name attribute associated with it

Parameters:

• sim (MjSim) – Mujoco sim instance

• random_state (RandomState) – instance of np.random.RandomState

• randomize_density (bool) – If True, randomizes global medium density

• randomize_viscosity (bool) – If True, randomizes global medium viscosity

• density_perturbation_ratio (float) – Relative (fraction) magnitude of default density randomization

• viscosity_perturbation_ratio – Relative (fraction) magnitude of default viscosity randomization

• body_names (None or list of str) – list of bodies to use for randomization. If not provided, all bodies in the model are randomized.

• randomize_position (bool) – If True, randomizes body positions

• randomize_quaternion (bool) – If True, randomizes body quaternions

• randomize_inertia (bool) – If True, randomizes body inertias (only applicable for non-zero mass bodies)

• randomize_mass (bool) – If True, randomizes body masses (only applicable for non-zero mass bodies)

• position_perturbation_size (float) – Magnitude of body position randomization

• quaternion_perturbation_size (float) – Magnitude of body quaternion randomization (angle in radians)

• inertia_perturbation_ratio (float) – Relative (fraction) magnitude of body inertia randomization

• mass_perturbation_ratio (float) – Relative (fraction) magnitude of body mass randomization

• geom_names (None or list of str) – list of geoms to use for randomization. If not provided, all geoms in the model are randomized.

• randomize_friction (bool) – If True, randomizes geom frictions

• randomize_solref (bool) – If True, randomizes geom solrefs

• randomize_solimp (bool) – If True, randomizes geom solimps

• friction_perturbation_ratio (float) – Relative (fraction) magnitude of geom friction randomization

• solref_perturbation_ratio (float) – Relative (fraction) magnitude of geom solref randomization

• solimp_perturbation_ratio (float) – Relative (fraction) magnitude of geom solimp randomization

• joint_names (None or list of str) – list of joints to use for randomization. If not provided, all joints in the model are randomized.

• randomize_stiffness (bool) – If True, randomizes joint stiffnesses

• randomize_frictionloss (bool) – If True, randomizes joint frictionlosses

• randomize_damping (bool) – If True, randomizes joint dampings

• randomize_armature (bool) – If True, randomizes joint armatures

• stiffness_perturbation_ratio (float) – Relative (fraction) magnitude of joint stiffness randomization

• frictionloss_perturbation_size (float) – Magnitude of joint frictionloss randomization

• damping_perturbation_size (float) – Magnitude of joint damping randomization

• armature_perturbation_size (float) – Magnitude of joint armature randomization

property dynamics_parameters

Returns: set: All dynamics parameters that can be randomized using this modder.

mod(name, attr, val)

General method to modify dynamics parameter @attr to be new value @val, associated with element @name.

Parameters:

• name (str) – Name of element to modify parameter. This can be a body, geom, or joint name. If modifying an opt parameter, this should be set to None

• attr (str) – Name of the dynamics parameter to modify. Valid options are self.dynamics_parameters

• val (int or float or n-array) – New value(s) to set for the given dynamics parameter. The type of this argument should match the expected type for the given parameter.

mod_armature(name, val)

Modifies the @name’s joint armature within the simulation. See http://www.mujoco.org/book/XMLreference.html#joint for more details.

Parameters:

• name (str) – Name for this element.

• val (float) – New armature.

mod_damping(name, val)

Modifies the @name’s joint damping within the simulation. See http://www.mujoco.org/book/XMLreference.html#joint for more details.

NOTE: If the requested joint is a free joint, it will be ignored since it does not

make physical sense to have damping associated with this joint (air drag / damping is already captured implicitly by the medium density / viscosity values)

Parameters:

• name (str) – Name for this element.

• val (float) – New damping.

mod_density(name=None, val=0.0)

Modifies the global medium density of the simulation. See http://www.mujoco.org/book/XMLreference.html#option for more details.

Parameters:

• name (str) – Name for this element. Should be left as None (opt has no name attribute)

• val (float) – New density value.

mod_friction(name, val)

Modifies the @name’s geom friction within the simulation. See http://www.mujoco.org/book/XMLreference.html#geom for more details.

Parameters:

• name (str) – Name for this element.

• val (3-array) – New (sliding, torsional, rolling) friction values.

mod_frictionloss(name, val)

Modifies the @name’s joint frictionloss within the simulation. See http://www.mujoco.org/book/XMLreference.html#joint for more details.

NOTE: If the requested joint is a free joint, it will be ignored since it does not

make physical sense to have friction loss associated with this joint (air drag / damping is already captured implicitly by the medium density / viscosity values)

Parameters:

• name (str) – Name for this element.

• val (float) – New friction loss.

mod_inertia(name, val)

Modifies the @name’s relative body inertia within the simulation. See http://www.mujoco.org/book/XMLreference.html#body for more details.

Parameters:

• name (str) – Name for this element.

• val (3-array) – New (ixx, iyy, izz) diagonal values in the inertia matrix.

mod_mass(name, val)

Modifies the @name’s mass within the simulation. See http://www.mujoco.org/book/XMLreference.html#body for more details.

Parameters:

• name (str) – Name for this element.

• val (float) – New mass.

mod_position(name, val=(0, 0, 0))

Modifies the @name’s relative body position within the simulation. See http://www.mujoco.org/book/XMLreference.html#body for more details.

Parameters:

• name (str) – Name for this element.

• val (3-array) – New (x, y, z) relative position.

mod_quaternion(name, val=(1, 0, 0, 0))

Modifies the @name’s relative body orientation (quaternion) within the simulation. See http://www.mujoco.org/book/XMLreference.html#body for more details.

Note: This method automatically normalizes the inputted value.

Parameters:

• name (str) – Name for this element.

• val (4-array) – New (w, x, y, z) relative quaternion.

mod_solimp(name, val)

Modifies the @name’s geom contact solver impedance parameters within the simulation. See http://www.mujoco.org/book/modeling.html#CSolver for more details.

Parameters:

• name (str) – Name for this element.

• val (5-array) – New (dmin, dmax, width, midpoint, power) solimp values.

mod_solref(name, val)

Modifies the @name’s geom contact solver parameters within the simulation. See http://www.mujoco.org/book/modeling.html#CSolver for more details.

Parameters:

• name (str) – Name for this element.

• val (2-array) – New (timeconst, dampratio) solref values.

mod_stiffness(name, val)

Modifies the @name’s joint stiffness within the simulation. See http://www.mujoco.org/book/XMLreference.html#joint for more details.

NOTE: If the stiffness is already at 0, we IGNORE this value since a non-stiff joint (i.e.: free-turning)

joint is fundamentally different than a stiffened joint)

Parameters:

• name (str) – Name for this element.

• val (float) – New stiffness.

mod_viscosity(name=None, val=0.0)

Modifies the global medium viscosity of the simulation. See http://www.mujoco.org/book/XMLreference.html#option for more details.

Parameters:

• name (str) – Name for this element. Should be left as None (opt has no name attribute)

• val (float) – New viscosity value.

property opt

Returns: PyMjOption: MjModel sim options

randomize()

Randomizes all enabled dynamics parameters in the simulation

restore_defaults()

Restores the default values curently saved in this modder

save_defaults()

Grabs the current values for all parameters in sim and stores them as default values

update()

Propagates the changes made up to this point through the simulation

update_sim(sim)

In addition to super method, update internal default values to match the current values from (the presumably new) @sim.

Parameters:

sim (MjSim) – MjSim object

class robosuite.utils.mjmod.LightingModder(sim, random_state=None, light_names=None, randomize_position=True, randomize_direction=True, randomize_specular=True, randomize_ambient=True, randomize_diffuse=True, randomize_active=True, position_perturbation_size=0.1, direction_perturbation_size=0.35, specular_perturbation_size=0.1, ambient_perturbation_size=0.1, diffuse_perturbation_size=0.1)

Bases: BaseModder

Modder to modify lighting within a Mujoco simulation.

Parameters:

• sim (MjSim) – MjSim object

• random_state (RandomState) – instance of np.random.RandomState

• light_names (None or list of str) – list of lights to use for randomization. If not provided, all lights in the model are randomized.

• randomize_position (bool) – If True, randomizes position of lighting

• randomize_direction (bool) – If True, randomizes direction of lighting

• randomize_specular (bool) – If True, randomizes specular attribute of lighting

• randomize_ambient (bool) – If True, randomizes ambient attribute of lighting

• randomize_diffuse (bool) – If True, randomizes diffuse attribute of lighting

• randomize_active (bool) – If True, randomizes active nature of lighting

• position_perturbation_size (float) – Magnitude of position randomization

• direction_perturbation_size (float) – Magnitude of direction randomization

• specular_perturbation_size (float) – Magnitude of specular attribute randomization

• ambient_perturbation_size (float) – Magnitude of ambient attribute randomization

• diffuse_perturbation_size (float) – Magnitude of diffuse attribute randomization

get_active(name)

Grabs active nature of a specific light source

Parameters:

name (str) – Name of the lighting source

Returns:

Whether light source is active (1) or not (0)

Return type:

int

Raises:

AssertionError – Invalid light name

get_ambient(name)

Grabs ambient attribute of a specific light source

Parameters:

name (str) – Name of the lighting source

Returns:

(r,g,b) ambient color of lighting source

Return type:

np.array

Raises:

AssertionError – Invalid light name

get_diffuse(name)

Grabs diffuse attribute of a specific light source

Parameters:

name (str) – Name of the lighting source

Returns:

(r,g,b) diffuse color of lighting source

Return type:

np.array

Raises:

AssertionError – Invalid light name

get_dir(name)

Grabs direction of a specific light source

Parameters:

name (str) – Name of the lighting source

Returns:

(x,y,z) direction of lighting source

Return type:

np.array

Raises:

AssertionError – Invalid light name

get_lightid(name)

Grabs unique id number of a specific light source

Parameters:

name (str) – Name of the lighting source

Returns:

id of lighting source. -1 if not found

Return type:

int

get_pos(name)

Grabs position of a specific light source

Parameters:

name (str) – Name of the lighting source

Returns:

(x,y,z) position of lighting source

Return type:

np.array

Raises:

AssertionError – Invalid light name

get_specular(name)

Grabs specular attribute of a specific light source

Parameters:

name (str) – Name of the lighting source

Returns:

(r,g,b) specular color of lighting source

Return type:

np.array

Raises:

AssertionError – Invalid light name

randomize()

Randomizes all requested lighting values within the sim

restore_defaults()

Reloads the saved parameter values.

save_defaults()

Uses the current MjSim state and model to save default parameter values.

set_active(name, value)

Sets active nature of a specific light source

Parameters:

• name (str) – Name of the lighting source

• value (int) – Whether light source is active (1) or not (0)

Raises:

AssertionError – Invalid light name

set_ambient(name, value)

Sets ambient attribute of a specific light source

Parameters:

• name (str) – Name of the lighting source

• value (np.array) – (r,g,b) ambient color to set lighting source to

Raises:

• AssertionError – Invalid light name

• AssertionError – Invalid @value

set_diffuse(name, value)

Sets diffuse attribute of a specific light source

Parameters:

• name (str) – Name of the lighting source

• value (np.array) – (r,g,b) diffuse color to set lighting source to

Raises:

• AssertionError – Invalid light name

• AssertionError – Invalid @value

set_dir(name, value)

Sets direction of a specific light source

Parameters:

• name (str) – Name of the lighting source

• value (np.array) – (ax,ay,az) direction to set lighting source to

Raises:

• AssertionError – Invalid light name

• AssertionError – Invalid @value

set_pos(name, value)

Sets position of a specific light source

Parameters:

• name (str) – Name of the lighting source

• value (np.array) – (x,y,z) position to set lighting source to

Raises:

• AssertionError – Invalid light name

• AssertionError – Invalid @value

set_specular(name, value)

Sets specular attribute of a specific light source

Parameters:

• name (str) – Name of the lighting source

• value (np.array) – (r,g,b) specular color to set lighting source to

Raises:

• AssertionError – Invalid light name

• AssertionError – Invalid @value

class robosuite.utils.mjmod.Texture(model, tex_id)

Bases: object

Helper class for operating on the MuJoCo textures.

Parameters:

• model (MjModel) – Mujoco sim model

• tex_id (int) – id of specific texture in mujoco sim

property bitmap

Grabs color bitmap associated with this texture from the mujoco sim.

Returns:

3d-array representing the rgb texture bitmap

Return type:

np.array

height

id

tex_adr

tex_rgb

type

width

class robosuite.utils.mjmod.TextureModder(sim, random_state=None, geom_names=None, randomize_local=False, randomize_material=False, local_rgb_interpolation=0.1, local_material_interpolation=0.2, texture_variations=('rgb', 'checker', 'noise', 'gradient'), randomize_skybox=True)

Bases: BaseModder

Modify textures in model. Example use:

sim = MjSim(…) modder = TextureModder(sim) modder.whiten_materials() # ensures materials won’t impact colors modder.set_checker(‘some_geom’, (255, 0, 0), (0, 0, 0)) modder.rand_all(‘another_geom’)

Note: in order for the textures to take full effect, you’ll need to set the rgba values for all materials to [1, 1, 1, 1], otherwise the texture colors will be modulated by the material colors. Call the whiten_materials helper method to set all material colors to white.

Parameters:

• sim (MjSim) – MjSim object

• random_state (RandomState) – instance of np.random.RandomState

• geom_names ([string]) – list of geom names to use for randomization. If not provided, all geoms are used for randomization.

• randomize_local (bool) – if True, constrain RGB color variations to be close to the original RGB colors per geom and texture. Otherwise, RGB color values will be sampled uniformly at random.

• randomize_material (bool) – if True, randomizes material properties associated with a given texture (reflectance, shininess, specular)

• local_rgb_interpolation (float) – determines the size of color variations from the base geom colors when @randomize_local is True.

• local_material_interpolation (float) – determines the size of material variations from the base material when @randomize_local and @randomize_material are both True.

• texture_variations (list of str) – a list of texture variation strings. Each string must be either ‘rgb’, ‘checker’, ‘noise’, or ‘gradient’ and corresponds to a specific kind of texture randomization. For each geom that has a material and texture, a random variation from this list is sampled and applied.

• randomize_skybox (bool) – if True, apply texture variations to the skybox as well.

get_checker_matrices(name)

Grabs checker pattern matrix associated with @name.

Parameters:

name (str) – Name of geom

Returns:

3d-array representing rgb checker pattern

Return type:

np.array

get_geom_rgb(name)

Grabs rgb color of a specific geom

Parameters:

name (str) – Name of the geom

Returns:

(r,g,b) geom colors

Return type:

np.array

get_material(name)

Grabs material of a specific geom

Parameters:

name (str) – Name of the geom

Returns:

(reflectance, shininess, specular) material properties associated with the geom

Return type:

np.array

get_rand_rgb(n=1)

Grabs a batch of random rgb tuple combos

Parameters:

n (int) – How many sets of rgb tuples to randomly generate

Returns:

if n > 1, each tuple entry is a rgb tuple. else, single (r,g,b) array

Return type:

np.array or n-tuple

get_texture(name)

Grabs texture of a specific geom

Parameters:

name (str) – Name of the geom

Returns:

texture associated with the geom

Return type:

Texture

rand_checker(name)

Generates a random checker pattern for a specific geom

Parameters:

name (str) – Name of the geom to randomize for

rand_gradient(name)

Generates a random gradient pattern for a specific geom

Parameters:

name (str) – Name of the geom to randomize for

rand_noise(name)

Generates a random RGB noise pattern for a specific geom

Parameters:

name (str) – Name of the geom to randomize for

rand_rgb(name)

Generates a random RGB color for a specific geom

Parameters:

name (str) – Name of the geom to randomize for

randomize()

Overrides mujoco-py implementation to also randomize color for geoms that have no material.

restore_defaults()

Reloads the saved parameter values.

save_defaults()

Uses the current MjSim state and model to save default parameter values.

set_checker(name, rgb1, rgb2, perturb=False)

Use the two checker matrices to create a checker pattern from the two colors, and set it as the texture for geom @name.

Parameters:

• name (str) – Name of geom

• rgb1 (3-array) – (r,g,b) value for one half of checker pattern

• rgb2 (3-array) – (r,g,b) value for other half of checker pattern

• perturb (bool) – Whether to perturb the resulting checker pattern or not

set_geom_rgb(name, rgb)

Sets rgb color of a specific geom

Parameters:

• name (str) – Name of the geom

• rgb (np.array) – (r,g,b) geom colors

set_gradient(name, rgb1, rgb2, vertical=True, perturb=False)

Creates a linear gradient from rgb1 to rgb2.

Parameters:

• name (str) – Name of geom

• rgb1 (3-array) – start color

• rgb2 (3- array) – end color

• vertical (bool) – if True, the gradient in the positive y-direction, if False it’s in the positive x-direction.

• perturb (bool) – Whether to perturb the resulting gradient pattern or not

set_material(name, material, perturb=False)

Sets the material that corresponds to geom @name.

If @perturb is True, then use the computed material to perturb the default material slightly, instead of replacing it.

Parameters:

• name (str) – Name of the geom

• material (np.array) – (reflectance, shininess, specular) material properties associated with the geom

• perturb (bool) – Whether to perturb the inputted material properties or not

set_noise(name, rgb1, rgb2, fraction=0.9, perturb=False)

Sets the texture bitmap for geom @name to a noise pattern

Parameters:

• name (str) – name of geom

• rgb1 (3-array) – background color

• rgb2 (3-array) – color of random noise foreground color

• fraction (float) – fraction of pixels with foreground color

• perturb (bool) – Whether to perturb the resulting color pattern or not

set_rgb(name, rgb, perturb=False)

Just set the texture bitmap for geom @name to a constant rgb value.

Parameters:

• name (str) – Name of geom

• rgb (3-array) – desired (r,g,b) color

• perturb (bool) – Whether to perturb the resulting color pattern or not

set_texture(name, bitmap, perturb=False)

Sets the bitmap for the texture that corresponds to geom @name.

If @perturb is True, then use the computed bitmap to perturb the default bitmap slightly, instead of replacing it.

Parameters:

• name (str) – Name of the geom

• bitmap (np.array) – 3d-array representing rgb pixel-wise values

• perturb (bool) – Whether to perturb the inputted bitmap or not

upload_texture(name, device_id=0)

Uploads the texture to the GPU so it’s available in the rendering.

Parameters:

name (str) – name of geom

whiten_materials()

Extends modder.TextureModder to also whiten geom_rgba

Helper method for setting all material colors to white, otherwise the texture modifications won’t take full effect.

robosuite.utils.numba module

Numba utils.

robosuite.utils.numba.jit_decorator(func)

robosuite.utils.observables module

robosuite.utils.observables.NO_CORRUPTION(inp)

robosuite.utils.observables.NO_DELAY()

robosuite.utils.observables.NO_FILTER(inp)

class robosuite.utils.observables.Observable(name, sensor, corrupter=None, filter=None, delayer=None, sampling_rate=20, enabled=True, active=True)

Bases: object

Base class for all observables – defines interface for interacting with sensors

Parameters:

• name (str) – Name for this observable

• sensor (function with sensor decorator) – Method to grab raw sensor data for this observable. Should take in a single dict argument (observation cache if a pre-computed value is required) and return the raw sensor data for the current timestep. Must handle case if inputted argument is empty ({}), and should have sensor decorator when defined

• corrupter (None or function) – Method to corrupt the raw sensor data for this observable. Should take in the output of @sensor and return the same type (corrupted data). If None, results in default no corruption

• filter (None or function) – Method to filter the outputted reading for this observable. Should take in the output of @corrupter and return the same type (filtered data). If None, results in default no filter. Note that this function can also double as an observer, where sampled data is recorded by this function.

• delayer (None or function) – Method to delay the raw sensor data when polling this observable. Should take in no arguments and return a float, for the number of seconds to delay the measurement by. If None, results in default no delayer

• sampling_rate (float) – Sampling rate for this observable (Hz)

• enabled (bool) – Whether this sensor is enabled or not. If enabled, this observable’s values are continually computed / updated every time update() is called.

• active (bool) – Whether this sensor is active or not. If active, this observable’s current observed value is returned from self.obs, otherwise self.obs returns None.

is_active()

Determines whether observable is active or not. This observable is considered active if its current observation value is being returned in self.obs.

Returns:

True if this observable is active

Return type:

bool

is_enabled()

Determines whether observable is enabled or not. This observable is considered enabled if its values are being continually computed / updated during each update() call.

Returns:

True if this observable is enabled

Return type:

bool

property modality

Modality of this sensor

Returns:

Modality name for this observable

Return type:

str

property obs

Current observation from this observable

Returns:

If active, current observed value from this observable. Otherwise, None

Return type:

None or float or np.array

reset()

Resets this observable’s internal values (but does not reset its sensor, corrupter, delayer, or filter)

set_active(active)

Sets whether this observable is active or not. If active, this observable’s current observed value is returned from self.obs, otherwise self.obs returns None.

Parameters:

active (bool) – True if this observable should be active

set_corrupter(corrupter)

Sets the corrupter for this observable.

Parameters:

corrupter (None or function) – Method to corrupt the raw sensor data for this observable. Should take in the output of self.sensor and return the same type (corrupted data). If None, results in default no corruption

set_delayer(delayer)

Sets the delayer for this observable.

Parameters:

delayer (None or function) – Method to delay the raw sensor data when polling this observable. Should take in no arguments and return a float, for the number of seconds to delay the measurement by. If None, results in default no filter

set_enabled(enabled)

Sets whether this observable is enabled or not. If enabled, this observable’s values are continually computed / updated every time update() is called.

Parameters:

enabled (bool) – True if this observable should be enabled

set_filter(filter)

Sets the filter for this observable. Note that this function can also double as an observer, where sampled data is recorded by this function.

Parameters:

filter (None or function) – Method to filter the outputted reading for this observable. Should take in the output of @corrupter and return the same type (filtered data). If None, results in default no filter

set_sampling_rate(rate)

Sets the sampling rate for this observable.

Parameters:

rate (int) – New sampling rate for this observable (Hz)

set_sensor(sensor)

Sets the sensor for this observable.

Parameters:

sensor (function with sensor decorator) – Method to grab raw sensor data for this observable. Should take in a single dict argument (observation cache if a pre-computed value is required) and return the raw sensor data for the current timestep. Must handle case if inputted argument is empty ({}), and should have sensor decorator when defined

update(timestep, obs_cache, force=False)

Updates internal values for this observable, if enabled.

Parameters:

• timestep (float) – Amount of simulation time (in sec) that has passed since last call.

• obs_cache (dict) – Observation cache mapping observable names to pre-computed values to pass to sensor. This will be updated in-place during this call.

• force (bool) – If True, will force the observable to update its internal value to the newest value.

robosuite.utils.observables.create_deterministic_corrupter(corruption, low=-inf, high=inf)

Creates a deterministic corrupter that applies the same corrupted value to all sensor values

Parameters:

• corruption (float) – Corruption to apply

• low (float) – Minimum value for output for clipping

• high (float) – Maximum value for output for clipping

Returns:

corrupter

Return type:

function

robosuite.utils.observables.create_deterministic_delayer(delay)

Create a deterministic delayer that always returns the same delay value

Parameters:

delay (float) – Delay value to return

Returns:

delayer

Return type:

function

robosuite.utils.observables.create_gaussian_noise_corrupter(mean, std, low=-inf, high=inf)

Creates a corrupter that applies gaussian noise to a given input with mean @mean and std dev @std

Parameters:

• mean (float) – Mean of the noise to apply

• std (float) – Standard deviation of the noise to apply

• low (float) – Minimum value for output for clipping

• high (float) – Maxmimum value for output for clipping

Returns:

corrupter

Return type:

function

robosuite.utils.observables.create_gaussian_sampled_delayer(mean, std)

Creates a gaussian sampled delayer, with average delay @mean which varies by standard deviation @std

Parameters:

• mean (float) – Average delay

• std (float) – Standard deviation of the delay variation

Returns:

delayer

Return type:

function

robosuite.utils.observables.create_uniform_noise_corrupter(min_noise, max_noise, low=-inf, high=inf)

Creates a corrupter that applies uniform noise to a given input within range @low to @high

Parameters:

• min_noise (float) – Minimum noise to apply

• max_noise (float) – Maximum noise to apply

• low (float) – Minimum value for output for clipping

• high (float) – Maxmimum value for output for clipping

Returns:

corrupter

Return type:

function

robosuite.utils.observables.create_uniform_sampled_delayer(min_delay, max_delay)

Creates uniformly sampled delayer, with minimum delay @low and maximum delay @high, both inclusive

Parameters:

• min_delay (float) – Minimum possible delay

• max_delay (float) – Maxmimum possible delay

Returns:

delayer

Return type:

function

robosuite.utils.observables.sensor(modality)

Decorator that should be added to any sensors that will be an observable.

Decorated functions should have signature:

any = func(obs_cache)

Where @obs_cache is a dictionary mapping observable keys to pre-computed values, and @any is either a scalar or array. This function should also handle the case if obs_cache is either None or an empty dict.

An example use case is shown below:

>>> @sensor(modality="proprio")
>>> def joint_pos(obs_cache):
        # Always handle case if obs_cache is empty
        if not obs_cache:
            return np.zeros(7)
        # Otherwise, run necessary calculations and return output
        ...
        out = ...
        return out

Parameters:

modality (str) – Modality for this sensor

Returns:

decorator function

Return type:

function

robosuite.utils.opencv_renderer module

opencv renderer class.

class robosuite.utils.opencv_renderer.OpenCVRenderer(sim)

Bases: object

add_keypress_callback(keypress_callback)

close()

Any cleanup to close renderer.

render()

set_camera(camera_id)

Set the camera view to the specified camera ID. :param camera_id: id of the camera to set the current viewer to :type camera_id: int

robosuite.utils.placement_samplers module

class robosuite.utils.placement_samplers.ObjectPositionSampler(name, mujoco_objects=None, ensure_object_boundary_in_range=True, ensure_valid_placement=True, reference_pos=(0, 0, 0), z_offset=0.0)

Bases: object

Base class of object placement sampler.

Parameters:

• name (str) – Name of this sampler.

• mujoco_objects (None or MujocoObject or list of MujocoObject) – single model or list of MJCF object models

• ensure_object_boundary_in_range (bool) – If True, will ensure that the object is enclosed within a given boundary (should be implemented by subclass)

• ensure_valid_placement (bool) – If True, will check for correct (valid) object placements

• reference_pos (3-array) – global (x,y,z) position relative to which sampling will occur

• z_offset (float) – Add a small z-offset to placements. This is useful for fixed objects that do not move (i.e. no free joint) to place them above the table.

add_objects(mujoco_objects)

Add additional objects to this sampler. Checks to make sure there’s no identical objects already stored.

Parameters:

mujoco_objects (MujocoObject or list of MujocoObject) – single model or list of MJCF object models

reset()

Resets this sampler. Removes all mujoco objects from this sampler.

sample(fixtures=None, reference=None, on_top=True)

Uniformly sample on a surface (not necessarily table surface).

Parameters:

• fixtures (dict) – dictionary of current object placements in the scene as well as any other relevant obstacles that should not be in contact with newly sampled objects. Used to make sure newly generated placements are valid. Should be object names mapped to (pos, quat, MujocoObject)

• reference (str or 3-tuple or None) – if provided, sample relative placement. Can either be a string, which corresponds to an existing object found in @fixtures, or a direct (x,y,z) value. If None, will sample relative to this sampler’s ‘reference_pos’ value.

• on_top (bool) – if True, sample placement on top of the reference object.

Returns:

dictionary of all object placements, mapping object_names to (pos, quat, obj), including the

placements specified in @fixtures. Note quat is in (w,x,y,z) form

Return type:

dict

class robosuite.utils.placement_samplers.SequentialCompositeSampler(name)

Bases: ObjectPositionSampler

Samples position for each object sequentially. Allows chaining multiple placement initializers together - so that object locations can be sampled on top of other objects or relative to other object placements.

Parameters:

name (str) – Name of this sampler.

add_objects(mujoco_objects)

Override super method to make sure user doesn’t call this (all objects should implicitly belong to sub-samplers)

add_objects_to_sampler(sampler_name, mujoco_objects)

Adds specified @mujoco_objects to sub-sampler with specified @sampler_name.

Parameters:

• sampler_name (str) – Existing sub-sampler name

• mujoco_objects (MujocoObject or list of MujocoObject) – Object(s) to add

append_sampler(sampler, sample_args=None)

Adds a new placement initializer with corresponding @sampler and arguments

Parameters:

• sampler (ObjectPositionSampler) – sampler to add

• sample_args (None or dict) – If specified, should be additional arguments to pass to @sampler’s sample() call. Should map corresponding sampler’s arguments to values (excluding @fixtures argument)

Raises:

AssertionError – [Object name in samplers]

hide(mujoco_objects)

Helper method to remove an object from the workspace.

Parameters:

mujoco_objects (MujocoObject or list of MujocoObject) – Object(s) to hide

reset()

Resets this sampler. In addition to base method, iterates over all sub-samplers and resets them

sample(fixtures=None, reference=None, on_top=True)

Sample from each placement initializer sequentially, in the order that they were appended.

Parameters:

• fixtures (dict) – dictionary of current object placements in the scene as well as any other relevant obstacles that should not be in contact with newly sampled objects. Used to make sure newly generated placements are valid. Should be object names mapped to (pos, quat, MujocoObject)

• reference (str or 3-tuple or None) – if provided, sample relative placement. This will override each sampler’s @reference argument if not already specified. Can either be a string, which corresponds to an existing object found in @fixtures, or a direct (x,y,z) value. If None, will sample relative to this sampler’s ‘reference_pos’ value.

• on_top (bool) – if True, sample placement on top of the reference object. This will override each sampler’s @on_top argument if not already specified. This corresponds to a sampled z-offset of the current sampled object’s bottom_offset + the reference object’s top_offset (if specified)

Returns:

dictionary of all object placements, mapping object_names to (pos, quat, obj), including the

placements specified in @fixtures. Note quat is in (w,x,y,z) form

Return type:

dict

Raises:

RandomizationError – [Cannot place all objects]

class robosuite.utils.placement_samplers.UniformRandomSampler(name, mujoco_objects=None, x_range=(0, 0), y_range=(0, 0), rotation=None, rotation_axis='z', ensure_object_boundary_in_range=True, ensure_valid_placement=True, reference_pos=(0, 0, 0), z_offset=0.0)

Bases: ObjectPositionSampler

Places all objects within the table uniformly random.

Parameters:

• name (str) – Name of this sampler.

• mujoco_objects (None or MujocoObject or list of MujocoObject) – single model or list of MJCF object models

• x_range (2-array of float) – Specify the (min, max) relative x_range used to uniformly place objects

• y_range (2-array of float) – Specify the (min, max) relative y_range used to uniformly place objects

• rotation (None or float or Iterable) –

  None:

  Add uniform random random rotation

  Iterable (a,b):

  Uniformly randomize rotation angle between a and b (in radians)

  value:

  Add fixed angle rotation

• rotation_axis (str) – Can be ‘x’, ‘y’, or ‘z’. Axis about which to apply the requested rotation

• ensure_object_boundary_in_range (bool) –

  True:

  The center of object is at position: [uniform(min x_range + radius, max x_range - radius)], [uniform(min x_range + radius, max x_range - radius)]

  False:

  [uniform(min x_range, max x_range)], [uniform(min x_range, max x_range)]

• ensure_valid_placement (bool) – If True, will check for correct (valid) object placements

• reference_pos (3-array) – global (x,y,z) position relative to which sampling will occur

• z_offset (float) – Add a small z-offset to placements. This is useful for fixed objects that do not move (i.e. no free joint) to place them above the table.

sample(fixtures=None, reference=None, on_top=True)

Uniformly sample relative to this sampler’s reference_pos or @reference (if specified).

Parameters:

• fixtures (dict) – dictionary of current object placements in the scene as well as any other relevant obstacles that should not be in contact with newly sampled objects. Used to make sure newly generated placements are valid. Should be object names mapped to (pos, quat, MujocoObject)

• reference (str or 3-tuple or None) – if provided, sample relative placement. Can either be a string, which corresponds to an existing object found in @fixtures, or a direct (x,y,z) value. If None, will sample relative to this sampler’s ‘reference_pos’ value.

• on_top (bool) – if True, sample placement on top of the reference object. This corresponds to a sampled z-offset of the current sampled object’s bottom_offset + the reference object’s top_offset (if specified)

Returns:

dictionary of all object placements, mapping object_names to (pos, quat, obj), including the

placements specified in @fixtures. Note quat is in (w,x,y,z) form

Return type:

dict

Raises:

• RandomizationError – [Cannot place all objects]

• AssertionError – [Reference object name does not exist, invalid inputs]

robosuite.utils.robot_utils module

robosuite.utils.robot_utils.check_bimanual(robot_name)

Utility function that returns whether the inputted robot_name is a bimanual robot or not

Parameters:

robot_name (str) – Name of the robot to check

Returns:

True if the inputted robot is a bimanual robot

Return type:

bool

robosuite.utils.transform_utils module

Utility functions of matrix and vector transformations.

NOTE: convention for quaternions is (x, y, z, w)

robosuite.utils.transform_utils.axisangle2quat(vec)

Converts scaled axis-angle to quat.

Parameters:

vec (np.array) – (ax,ay,az) axis-angle exponential coordinates

Returns:

(x,y,z,w) vec4 float angles

Return type:

np.array

robosuite.utils.transform_utils.clip_rotation(quat, limit)

Limits a (delta) rotation to a specified limit

Converts rotation to axis-angle, clips, then re-converts back into quaternion

Parameters:

• quat (np.array) – (x,y,z,w) rotation being clipped

• limit (float) – Value to limit rotation by – magnitude (scalar, in radians)

Returns:

• (np.array) Clipped rotation quaternion (x, y, z, w)

• (bool) whether the value was clipped or not

Return type:

2-tuple

robosuite.utils.transform_utils.clip_translation(dpos, limit)

Limits a translation (delta position) to a specified limit

Scales down the norm of the dpos to ‘limit’ if norm(dpos) > limit, else returns immediately

Parameters:

• dpos (n-array) – n-dim Translation being clipped (e,g.: (x, y, z)) – numpy array

• limit (float) – Value to limit translation by – magnitude (scalar, in same units as input)

Returns:

• (np.array) Clipped translation (same dimension as inputs)

• (bool) whether the value was clipped or not

Return type:

2-tuple

robosuite.utils.transform_utils.convert_quat(q, to='xyzw')

Converts quaternion from one convention to another. The convention to convert TO is specified as an optional argument. If to == ‘xyzw’, then the input is in ‘wxyz’ format, and vice-versa.

Parameters:

• q (np.array) – a 4-dim array corresponding to a quaternion

• to (str) – either ‘xyzw’ or ‘wxyz’, determining which convention to convert to.

robosuite.utils.transform_utils.euler2mat(euler)

Converts euler angles into rotation matrix form

Parameters:

euler (np.array) – (r,p,y) angles

Returns:

3x3 rotation matrix

Return type:

np.array

Raises:

AssertionError – [Invalid input shape]

robosuite.utils.transform_utils.force_in_A_to_force_in_B(force_A, torque_A, pose_A_in_B)

Converts linear and rotational force at a point in frame A to the equivalent in frame B.

Parameters:

• force_A (np.array) – (fx,fy,fz) linear force in A

• torque_A (np.array) – (tx,ty,tz) rotational force (moment) in A

• pose_A_in_B (np.array) – 4x4 matrix corresponding to the pose of A in frame B

Returns:

• (np.array) (fx,fy,fz) linear forces in frame B

• (np.array) (tx,ty,tz) moments in frame B

Return type:

2-tuple

robosuite.utils.transform_utils.get_orientation_error(target_orn, current_orn)

Returns the difference between two quaternion orientations as a 3 DOF numpy array. For use in an impedance controller / task-space PD controller.

Parameters:

• target_orn (np.array) – (x, y, z, w) desired quaternion orientation

• current_orn (np.array) – (x, y, z, w) current quaternion orientation

Returns:

(ax,ay,az) current orientation error, corresponds to

(target_orn - current_orn)

Return type:

orn_error (np.array)

robosuite.utils.transform_utils.get_pose_error(target_pose, current_pose)

Computes the error corresponding to target pose - current pose as a 6-dim vector. The first 3 components correspond to translational error while the last 3 components correspond to the rotational error.

Parameters:

• target_pose (np.array) – a 4x4 homogenous matrix for the target pose

• current_pose (np.array) – a 4x4 homogenous matrix for the current pose

Returns:

6-dim pose error.

Return type:

np.array

robosuite.utils.transform_utils.make_pose(translation, rotation)

Makes a homogeneous pose matrix from a translation vector and a rotation matrix.

Parameters:

• translation (np.array) – (x,y,z) translation value

• rotation (np.array) – a 3x3 matrix representing rotation

Returns:

a 4x4 homogeneous matrix

Return type:

pose (np.array)

robosuite.utils.transform_utils.mat2euler(rmat, axes='sxyz')

Converts given rotation matrix to euler angles in radian.

Parameters:

• rmat (np.array) – 3x3 rotation matrix

• axes (str) – One of 24 axis sequences as string or encoded tuple (see top of this module)

Returns:

(r,p,y) converted euler angles in radian vec3 float

Return type:

np.array

robosuite.utils.transform_utils.mat2pose(hmat)

Converts a homogeneous 4x4 matrix into pose.

Parameters:

hmat (np.array) – a 4x4 homogeneous matrix

Returns:

• (np.array) (x,y,z) position array in cartesian coordinates

• (np.array) (x,y,z,w) orientation array in quaternion form

Return type:

2-tuple

robosuite.utils.transform_utils.mat2quat(rmat)

Converts given rotation matrix to quaternion.

Parameters:

rmat (np.array) – 3x3 rotation matrix

Returns:

(x,y,z,w) float quaternion angles

Return type:

np.array

robosuite.utils.transform_utils.mat4(array)

Converts an array to 4x4 matrix.

Parameters:

array (n-array) – the array in form of vec, list, or tuple

Returns:

a 4x4 numpy matrix

Return type:

np.array

robosuite.utils.transform_utils.matrix_inverse(matrix)

Helper function to have an efficient matrix inversion function.

Parameters:

matrix (np.array) – 2d-array representing a matrix

Returns:

2d-array representing the matrix inverse

Return type:

np.array

robosuite.utils.transform_utils.pose2mat(pose)

Converts pose to homogeneous matrix.

Parameters:

pose (2-tuple) – a (pos, orn) tuple where pos is vec3 float cartesian, and orn is vec4 float quaternion.

Returns:

4x4 homogeneous matrix

Return type:

np.array

robosuite.utils.transform_utils.pose_in_A_to_pose_in_B(pose_A, pose_A_in_B)

Converts a homogenous matrix corresponding to a point C in frame A to a homogenous matrix corresponding to the same point C in frame B.

Parameters:

• pose_A (np.array) – 4x4 matrix corresponding to the pose of C in frame A

• pose_A_in_B (np.array) – 4x4 matrix corresponding to the pose of A in frame B

Returns:

4x4 matrix corresponding to the pose of C in frame B

Return type:

np.array

robosuite.utils.transform_utils.pose_inv(pose)

Computes the inverse of a homogeneous matrix corresponding to the pose of some frame B in frame A. The inverse is the pose of frame A in frame B.

Parameters:

pose (np.array) – 4x4 matrix for the pose to inverse

Returns:

4x4 matrix for the inverse pose

Return type:

np.array

robosuite.utils.transform_utils.quat2axisangle(quat)

Converts quaternion to axis-angle format. Returns a unit vector direction scaled by its angle in radians.

Parameters:

quat (np.array) – (x,y,z,w) vec4 float angles

Returns:

(ax,ay,az) axis-angle exponential coordinates

Return type:

np.array

robosuite.utils.transform_utils.quat2mat(quaternion)

Converts given quaternion to matrix.

Parameters:

quaternion (np.array) – (x,y,z,w) vec4 float angles

Returns:

3x3 rotation matrix

Return type:

np.array

robosuite.utils.transform_utils.quat_conjugate(quaternion)

Return conjugate of quaternion.

E.g.: >>> q0 = random_quaternion() >>> q1 = quat_conjugate(q0) >>> q1[3] == q0[3] and all(q1[:3] == -q0[:3]) True

Parameters:

quaternion (np.array) – (x,y,z,w) quaternion

Returns:

(x,y,z,w) quaternion conjugate

Return type:

np.array

robosuite.utils.transform_utils.quat_distance(quaternion1, quaternion0)

Returns distance between two quaternions, such that distance * quaternion0 = quaternion1

Parameters:

• quaternion1 (np.array) – (x,y,z,w) quaternion

• quaternion0 (np.array) – (x,y,z,w) quaternion

Returns:

(x,y,z,w) quaternion distance

Return type:

np.array

robosuite.utils.transform_utils.quat_inverse(quaternion)

Return inverse of quaternion.

E.g.: >>> q0 = random_quaternion() >>> q1 = quat_inverse(q0) >>> np.allclose(quat_multiply(q0, q1), [0, 0, 0, 1]) True

Parameters:

quaternion (np.array) – (x,y,z,w) quaternion

Returns:

(x,y,z,w) quaternion inverse

Return type:

np.array

robosuite.utils.transform_utils.quat_multiply(quaternion1, quaternion0)

Return multiplication of two quaternions (q1 * q0).

E.g.: >>> q = quat_multiply([1, -2, 3, 4], [-5, 6, 7, 8]) >>> np.allclose(q, [-44, -14, 48, 28]) True

Parameters:

• quaternion1 (np.array) – (x,y,z,w) quaternion

• quaternion0 (np.array) – (x,y,z,w) quaternion

Returns:

(x,y,z,w) multiplied quaternion

Return type:

np.array

robosuite.utils.transform_utils.quat_slerp(quat0, quat1, fraction, shortestpath=True)

Return spherical linear interpolation between two quaternions.

E.g.: >>> q0 = random_quat() >>> q1 = random_quat() >>> q = quat_slerp(q0, q1, 0.0) >>> np.allclose(q, q0) True

>>> q = quat_slerp(q0, q1, 1.0)
>>> np.allclose(q, q1)
True

>>> q = quat_slerp(q0, q1, 0.5)
>>> angle = math.acos(np.dot(q0, q))
>>> np.allclose(2.0, math.acos(np.dot(q0, q1)) / angle) or         np.allclose(2.0, math.acos(-np.dot(q0, q1)) / angle)
True

Parameters:

• quat0 (np.array) – (x,y,z,w) quaternion startpoint

• quat1 (np.array) – (x,y,z,w) quaternion endpoint

• fraction (float) – fraction of interpolation to calculate

• shortestpath (bool) – If True, will calculate the shortest path

Returns:

(x,y,z,w) quaternion distance

Return type:

np.array

robosuite.utils.transform_utils.random_axis_angle(angle_limit=None, random_state=None)

Samples an axis-angle rotation by first sampling a random axis and then sampling an angle. If @angle_limit is provided, the size of the rotation angle is constrained.

If @random_state is provided (instance of np.random.RandomState), it will be used to generate random numbers.

Parameters:

• angle_limit (None or float) – If set, determines magnitude limit of angles to generate

• random_state (None or RandomState) – RNG to use if specified

Raises:

AssertionError – [Invalid RNG]

robosuite.utils.transform_utils.random_quat(rand=None)

Return uniform random unit quaternion.

E.g.: >>> q = random_quat() >>> np.allclose(1.0, vector_norm(q)) True >>> q = random_quat(np.random.random(3)) >>> q.shape (4,)

Parameters:

rand (3-array or None) – If specified, must be three independent random variables that are uniformly distributed between 0 and 1.

Returns:

(x,y,z,w) random quaternion

Return type:

np.array

robosuite.utils.transform_utils.rotate_2d_point(input, rot)

rotate a 2d vector counterclockwise

Parameters:

• input (np.array) – 1d-array representing 2d vector

• rot (float) – rotation value

Returns:

rotated 1d-array

Return type:

np.array

robosuite.utils.transform_utils.rotation_matrix(angle, direction, point=None)

Returns matrix to rotate about axis defined by point and direction.

E.g.:

>>> angle = (random.random() - 0.5) * (2*math.pi)
>>> direc = numpy.random.random(3) - 0.5
>>> point = numpy.random.random(3) - 0.5
>>> R0 = rotation_matrix(angle, direc, point)
>>> R1 = rotation_matrix(angle-2*math.pi, direc, point)
>>> is_same_transform(R0, R1)
True

>>> R0 = rotation_matrix(angle, direc, point)
>>> R1 = rotation_matrix(-angle, -direc, point)
>>> is_same_transform(R0, R1)
True

>>> I = numpy.identity(4, numpy.float32)
>>> numpy.allclose(I, rotation_matrix(math.pi*2, direc))
True

>>> numpy.allclose(2., numpy.trace(rotation_matrix(math.pi/2,
...                                                direc, point)))
True

Parameters:

• angle (float) – Magnitude of rotation

• direction (np.array) – (ax,ay,az) axis about which to rotate

• point (None or np.array) – If specified, is the (x,y,z) point about which the rotation will occur

Returns:

4x4 homogeneous matrix that includes the desired rotation

Return type:

np.array

robosuite.utils.transform_utils.unit_vector(data, axis=None, out=None)

Returns ndarray normalized by length, i.e. eucledian norm, along axis.

E.g.:

>>> v0 = numpy.random.random(3)
>>> v1 = unit_vector(v0)
>>> numpy.allclose(v1, v0 / numpy.linalg.norm(v0))
True

>>> v0 = numpy.random.rand(5, 4, 3)
>>> v1 = unit_vector(v0, axis=-1)
>>> v2 = v0 / numpy.expand_dims(numpy.sqrt(numpy.sum(v0*v0, axis=2)), 2)
>>> numpy.allclose(v1, v2)
True

>>> v1 = unit_vector(v0, axis=1)
>>> v2 = v0 / numpy.expand_dims(numpy.sqrt(numpy.sum(v0*v0, axis=1)), 1)
>>> numpy.allclose(v1, v2)
True

>>> v1 = numpy.empty((5, 4, 3), dtype=numpy.float32)
>>> unit_vector(v0, axis=1, out=v1)
>>> numpy.allclose(v1, v2)
True

>>> list(unit_vector([]))
[]

>>> list(unit_vector([1.0]))
[1.0]

Parameters:

• data (np.array) – data to normalize

• axis (None or int) – If specified, determines specific axis along data to normalize

• out (None or np.array) – If specified, will store computation in this variable

Returns:

If @out is not specified, will return normalized vector. Otherwise, stores the output in @out

Return type:

None or np.array

robosuite.utils.transform_utils.vec(values)

Converts value tuple into a numpy vector.

Parameters:

values (n-array) – a tuple of numbers

Returns:

vector of given values

Return type:

np.array

robosuite.utils.transform_utils.vel_in_A_to_vel_in_B(vel_A, ang_vel_A, pose_A_in_B)

Converts linear and angular velocity of a point in frame A to the equivalent in frame B.

Parameters:

• vel_A (np.array) – (vx,vy,vz) linear velocity in A

• ang_vel_A (np.array) – (wx,wy,wz) angular velocity in A

• pose_A_in_B (np.array) – 4x4 matrix corresponding to the pose of A in frame B

Returns:

• (np.array) (vx,vy,vz) linear velocities in frame B

• (np.array) (wx,wy,wz) angular velocities in frame B

Return type:

2-tuple

Module contents