robosuite.utils package

Contents

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 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 narena#
property nbuffer#
property ncon#
property ne#
property nefc#
property nf#
property nisland#
property nl#
property nnzJ#
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 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_vertadr#
property flex_vertbodyid#
property flex_vertnum#
property flex_xvert0#
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 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#

This module includes:

  • Utility classes for modifying sim cameras

  • Utility functions for performing common camera operations such as retrieving

camera matrices and transforming from world to camera frame or vice-versa.

class robosuite.utils.camera_utils.CameraMover(env, camera='frontview', init_camera_pos=None, init_camera_quat=None)#

Bases: object

A class for manipulating a camera.

WARNING: This class will initially RE-INITIALIZE the environment.

Parameters:

  • env (MujocoEnv) – Mujoco environment to modify camera

  • camera (str) – Which camera to mobilize during playback, e.g.: frontview, agentview, etc.

  • init_camera_pos (None or 3-array) – If specified, should be the (x,y,z) global cartesian pos to initialize camera to

  • init_camera_quat (None or 4-array) – If specified, should be the (x,y,z,w) global quaternion orientation to initialize camera to

get_camera_pose()#

Grab the current camera pose, which optionally includes position and / or quaternion

Returns:

  • 3-array: (x,y,z) camera global cartesian pos

  • 4-array: (x,y,z,w) camera global quaternion orientation

Return type:

2-tuple

modify_xml_for_camera_movement(xml, camera_name)#

Cameras in mujoco are ‘fixed’, so they can’t be moved by default. Although it’s possible to hack position movement, rotation movement does not work. An alternative is to attach a camera to a mocap body, and move the mocap body.

This function modifies the camera with name @camera_name in the xml by attaching it to a mocap body that can move around freely. In this way, we can move the camera by moving the mocap body.

See http://www.mujoco.org/forum/index.php?threads/move-camera.2201/ for further details.

Parameters:

  • xml (str) – Mujoco sim XML file as a string

  • camera_name (str) – Name of camera to tune

move_camera(direction, scale)#

Move the camera view along a direction (in the camera frame).

Parameters:

  • direction (3-array) – direction vector for where to move camera in camera frame

  • scale (float) – how much to move along that direction

rotate_camera(point, axis, angle)#

Rotate the camera view about a direction (in the camera frame).

Parameters:

  • point (None or 3-array) – (x,y,z) cartesian coordinates about which to rotate camera in camera frame. If None, assumes the point is the current location of the camera

  • axis (3-array) – (ax,ay,az) axis about which to rotate camera in camera frame

  • angle (float) – how much to rotate about that direction

Returns:

pos: (x,y,z) updated camera position quat: (x,y,z,w) updated camera quaternion orientation

Return type:

2-tuple

set_camera_pose(pos=None, quat=None)#

Sets the camera pose, which optionally includes position and / or quaternion

Parameters:

  • pos (None or 3-array) – If specified, should be the (x,y,z) global cartesian pos to set camera to

  • quat (None or 4-array) – If specified, should be the (x,y,z,w) global quaternion orientation to set camera to

class robosuite.utils.camera_utils.DemoPlaybackCameraMover(demo, env_config=None, replay_from_actions=False, visualize_sites=False, camera='frontview', init_camera_pos=None, init_camera_quat=None, use_dr=False, dr_args=None)#

Bases: CameraMover

A class for playing back demonstrations and recording the resulting frames with the flexibility of a mobile camera that can be set manually or panned automatically frame-by-frame

Note: domain randomization is also supported for playback!

Parameters:

  • demo (str) – absolute fpath to .hdf5 demo

  • env_config (None or dict) – (optional) values to override inferred environment information from demonstration. (e.g.: camera h / w, depths, segmentations, etc…) Any value not specified will be inferred from the extracted demonstration metadata Note that there are some specific arguments that MUST be set a certain way, if any of these values are specified with @env_config, an error will be raised

  • replay_from_actions (bool) – If True, will replay demonstration’s actions. Otherwise, replays will be hardcoded from the demonstration states

  • visualize_sites (bool) – If True, will visualize sites during playback. Note that this CANNOT be paired simultaneously with camera segmentations

  • camera (str) – Which camera to mobilize during playback, e.g.: frontview, agentview, etc.

  • init_camera_pos (None or 3-array) – If specified, should be the (x,y,z) global cartesian pos to initialize camera to

  • init_camera_quat (None or 4-array) – If specified, should be the (x,y,z,w) global quaternion orientation to initialize camera to

  • use_dr (bool) – If True, will use domain randomization during playback

  • dr_args (None or dict) – If specified, will set the domain randomization wrapper arguments if using dr

grab_episode_frames(demo_num, pan_point=(0, 0, 0.8), pan_axis=(0, 0, 1), pan_rate=0.01)#
Playback entire episode @demo_num, while optionally rotating the camera about point @pan_point and

axis @pan_axis if @pan_rate > 0

Parameters:

  • demo_num (int) – Demonstration episode number to load for playback

  • pan_point (3-array) – (x,y,z) cartesian coordinates about which to rotate camera in camera frame

  • pan_direction (3-array) – (ax,ay,az) axis about which to rotate camera in camera frame

  • pan_rate (float) – how quickly to pan camera if not 0

Returns:

Keyword-mapped stacked np.arrays from the demonstration sequence, corresponding to all image

modalities used in the playback environment (e.g.: “image”, “depth”, “segmentation_instance”)

Return type:

dict

grab_next_frame()#

Grabs the next frame in the demo sequence by stepping the simulation and returning the resulting value(s)

Returns:

Keyword-mapped np.arrays from the demonstration sequence, corresponding to all image modalities used

in the playback environment (e.g.: “image”, “depth”, “segmentation_instance”)

Return type:

dict

load_episode_xml(demo_num)#

Loads demo episode with specified @demo_num into the simulator.

Parameters:

demo_num (int) – Demonstration number to load

robosuite.utils.camera_utils.bilinear_interpolate(im, x, y)#

Bilinear sampling for pixel coordinates x and y from source image im. Taken from https://stackoverflow.com/questions/12729228/simple-efficient-bilinear-interpolation-of-images-in-numpy-and-python

robosuite.utils.camera_utils.get_camera_extrinsic_matrix(sim, camera_name)#

Returns a 4x4 homogenous matrix corresponding to the camera pose in the world frame. MuJoCo has a weird convention for how it sets up the camera body axis, so we also apply a correction so that the x and y axis are along the camera view and the z axis points along the viewpoint. Normal camera convention: https://docs.opencv.org/2.4/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html

Parameters:

  • sim (MjSim) – simulator instance

  • camera_name (str) – name of camera

Returns:

4x4 camera extrinsic matrix

Return type:

R (np.array)

robosuite.utils.camera_utils.get_camera_intrinsic_matrix(sim, camera_name, camera_height, camera_width)#

Obtains camera intrinsic matrix.

Parameters:

  • sim (MjSim) – simulator instance

  • camera_name (str) – name of camera

  • camera_height (int) – height of camera images in pixels

  • camera_width (int) – width of camera images in pixels

Returns:

3x3 camera matrix

Return type:

K (np.array)

robosuite.utils.camera_utils.get_camera_segmentation(sim, camera_name, camera_height, camera_width)#

Obtains camera segmentation matrix.

Parameters:

  • sim (MjSim) – simulator instance

  • camera_name (str) – name of camera

  • camera_height (int) – height of camera images in pixels

  • camera_width (int) – width of camera images in pixels

Returns:

2-channel segmented image where the first contains the

geom types and the second contains the geom IDs

Return type:

im (np.array)

robosuite.utils.camera_utils.get_camera_transform_matrix(sim, camera_name, camera_height, camera_width)#

Camera transform matrix to project from world coordinates to pixel coordinates.

Parameters:

  • sim (MjSim) – simulator instance

  • camera_name (str) – name of camera

  • camera_height (int) – height of camera images in pixels

  • camera_width (int) – width of camera images in pixels

Returns:

4x4 camera matrix to project from world coordinates to pixel coordinates

Return type:

K (np.array)

robosuite.utils.camera_utils.get_real_depth_map(sim, depth_map)#

By default, MuJoCo will return a depth map that is normalized in [0, 1]. This helper function converts the map so that the entries correspond to actual distances.

(see deepmind/dm_control)

Parameters:

  • sim (MjSim) – simulator instance

  • depth_map (np.array) – depth map with values normalized in [0, 1] (default depth map returned by MuJoCo)

Returns:

depth map that corresponds to actual distances

Return type:

depth_map (np.array)

robosuite.utils.camera_utils.project_points_from_world_to_camera(points, world_to_camera_transform, camera_height, camera_width)#

Helper function to project a batch of points in the world frame into camera pixels using the world to camera transformation.

Parameters:

  • points (np.array) – 3D points in world frame to project onto camera pixel locations. Should be shape […, 3].

  • world_to_camera_transform (np.array) – 4x4 Tensor to go from robot coordinates to pixel coordinates.

  • camera_height (int) – height of the camera image

  • camera_width (int) – width of the camera image

Returns:

projected pixel indices of shape […, 2]

Return type:

pixels (np.array)

robosuite.utils.camera_utils.transform_from_pixels_to_world(pixels, depth_map, camera_to_world_transform)#

Helper function to take a batch of pixel locations and the corresponding depth image and transform these points from the camera frame to the world frame.

Parameters:

  • pixels (np.array) – pixel coordinates of shape […, 2]

  • depth_map (np.array) – depth images of shape […, H, W, 1]

  • camera_to_world_transform (np.array) – 4x4 Tensor to go from pixel coordinates to world coordinates.

Returns:

3D points in robot frame of shape […, 3]

Return type:

points (np.array)

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#

Utility functions for grabbing user inputs

robosuite.utils.input_utils.choose_controller()#

Prints out controller options, and returns the requested controller name

Returns:

Chosen controller name

Return type:

str

robosuite.utils.input_utils.choose_environment()#

Prints out environment options, and returns the selected env_name choice

Returns:

Chosen environment name

Return type:

str

robosuite.utils.input_utils.choose_multi_arm_config()#

Prints out multi-arm environment configuration options, and returns the requested config name

Returns:

Requested multi-arm configuration name

Return type:

str

robosuite.utils.input_utils.choose_robots(exclude_bimanual=False, use_humanoids=False)#

Prints out robot options, and returns the requested robot. Restricts options to single-armed robots if @exclude_bimanual is set to True (False by default). Restrict options to humanoids if @use_humanoids is set to True (Flase by default).

Parameters:

  • exclude_bimanual (bool) – If set, excludes bimanual robots from the robot options

  • use_humanoids (bool) – If set, use humanoid robots

Returns:

Requested robot name

Return type:

str

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: '\x1b[1m\x1b[32m[robosuite %(levelname)s] \x1b[0m%(message)s (%(filename)s:%(lineno)d)', 30: '\x1b[1m\x1b[33m[robosuite %(levelname)s] \x1b[0m%(message)s (%(filename)s:%(lineno)d)', 40: '\x1b[1m\x1b[31m[robosuite %(levelname)s] \x1b[0m%(message)s (%(filename)s:%(lineno)d)', 50: '\x1b[7m\x1b[1m\x1b[31m[robosuite %(levelname)s] \x1b[0m%(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: '\x1b[1m\x1b[32m[robosuite %(levelname)s - %(asctime)s] \x1b[0m%(message)s (%(filename)s:%(lineno)d)', 20: '\x1b[1m\x1b[32m[robosuite %(levelname)s - %(asctime)s] \x1b[0m%(message)s (%(filename)s:%(lineno)d)', 30: '\x1b[1m\x1b[33m[robosuite %(levelname)s - %(asctime)s] \x1b[0m%(message)s (%(filename)s:%(lineno)d)', 40: '\x1b[1m\x1b[31m[robosuite %(levelname)s - %(asctime)s] \x1b[0m%(message)s (%(filename)s:%(lineno)d)', 50: '\x1b[1m\x1b[31m[robosuite %(levelname)s - %(asctime)s] \x1b[0m%(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#

Contents