embodichain.lab.sim.objects

Classes

Light	Light represents a batch of lights in the simulation.
LightCfg	Configuration for a light asset in the simulation.
RigidObject	RigidObject represents a batch of rigid body in the simulation.
RigidBodyData	Data manager for rigid body with body type of dynamic or kinematic.
RigidObjectCfg	Configuration for a rigid body asset in the simulation.
RigidObjectGroup	RigidObjectGroup represents a batch of rigid bodies in the simulation.
RigidBodyGroupData	Data manager for rigid body group with body type of dynamic or kinematic.
RigidObjectGroupCfg	Configuration for a rigid object group asset in the simulation.
Articulation	Articulation represents a batch of articulations in the simulation.
ArticulationData	GPU data manager for articulation.
ArticulationCfg	Configuration for an articulation asset in the simulation.
SoftObject	SoftObject represents a batch of soft body in the simulation.
SoftBodyData	Data manager for soft body
SoftObjectCfg	Configuration for a soft body asset in the simulation.
ClothObject	ClothObject represents a batch of cloth body in the simulation.
ClothBodyData	Data manager for cloth.
ClothObjectCfg	Configuration for a cloth body asset in the simulation.
Robot	A class representing a batch of robots in the simulation environment.
RobotCfg	RobotCfg(uid: 'str | None' = <factory>, init_pos: 'tuple[float, float, float]' = <factory>, init_rot: 'tuple[float, float, float]' = <factory>, init_local_pose: 'np.ndarray | None' = <factory>, fpath: 'str' = <factory>, drive_pros: 'JointDrivePropertiesCfg' = <factory>, body_scale: 'tuple | list' = <factory>, attrs: 'RigidBodyAttributesCfg' = <factory>, link_attrs: 'dict[str, LinkPhysicsOverrideCfg] | None' = <factory>, fix_base: 'bool' = <factory>, disable_self_collision: 'bool' = <factory>, init_qpos: 'torch.Tensor | np.ndarray | Sequence[float]' = <factory>, qpos_limits: 'torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None' = <factory>, sleep_threshold: 'float' = <factory>, min_position_iters: 'int' = <factory>, min_velocity_iters: 'int' = <factory>, build_pk_chain: 'bool' = <factory>, compute_uv: 'bool' = <factory>, use_usd_properties: 'bool' = <factory>, control_parts: 'Dict[str, List[str]] | None' = <factory>, urdf_cfg: 'URDFCfg | None' = <factory>, solver_cfg: 'SolverCfg | Dict[str, SolverCfg] | None' = <factory>)

Light

class embodichain.lab.sim.objects.Light

Bases: BatchEntity

Light represents a batch of lights in the simulation.

Each light supports the following properties:

• Color (3 floats)

• Intensity (1 float)

• Falloff (1 float)

• Location (3 floats)

Methods:

__init__(cfg[, entities, device])
destroy()	Destroy all entities managed by this batch entity.
enable_shadow(flags[, env_ids])	Enable or disable shadow casting.
get_local_pose([to_matrix])	Get local pose of each light, either as full matrix or translation vector.
reset([env_ids])	Reset the light to its initial configuration state.
set_color(colors[, env_ids])	Set color for one or more lights.
set_direction(directions[, env_ids])	Set direction for directional-type lights.
set_falloff(falloffs[, env_ids])	Set falloff (radius) for one or more lights.
set_intensity(intensities[, env_ids])	Set intensity for one or more lights.
set_local_pose(pose[, env_ids, to_matrix])	Set local pose (translation) for one or more lights.
set_mesh(mesh[, env_ids])	Set the mesh for mesh-type lights.
set_rect_wh(widths, heights[, env_ids])	Set width and height for rectangular area lights.
set_spot_angle(inner_angles, outer_angles[, ...])	Set inner and outer cone angles for spot lights.

Attributes:

is_global

Whether this light is a global scene light (single instance).

__init__(cfg, entities=None, device=device(type='cpu'))

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

enable_shadow(flags, env_ids=None)

Enable or disable shadow casting.

Applies to all light types.

Parameters:

• flags (torch.Tensor) – Boolean tensor of shape () (0-dim), (1,), or (M,). Non-zero values enable shadows; zero disables.

• env_ids (Sequence[int] | None) – Indices of instances to set.

Return type:

None

get_local_pose(to_matrix=False)

Get local pose of each light, either as full matrix or translation vector.

Parameters:

to_matrix (bool, optional) – If True, return poses as 4×4 matrices. If False, return translations only as (x, y, z). Defaults to False.

Returns:

• If to_matrix=True: Tensor of shape (N, 4, 4), where N == num_instances.

• If to_matrix=False: Tensor of shape (N, 3), containing translations.

On error or empty instances, returns an empty tensor with shape (0, 4, 4) or (0, 3) respectively, and logs via logger.log_error.

Return type:

torch.Tensor

property is_global: bool

Whether this light is a global scene light (single instance).

Global lights ("sun", "direction") are infinite-distance light sources that illuminate the entire scene. They are never batched per environment.

Returns:

True if the light is a global scene light.

Return type:

bool

reset(env_ids=None)

Reset the light to its initial configuration state.

Applies only the properties relevant to self.cfg.light_type.

Attention

When this light has only one instance (global lights such as "sun" and "direction", or any light in a single-environment scene), env_ids is normalized to None because there is only one instance to update. Passing per-environment indices is silently ignored.

Parameters:

env_ids (Sequence[int] | None) – The environment IDs to reset. If None, resets all environments.

Return type:

None

set_color(colors, env_ids=None)

Set color for one or more lights.

Parameters:

• colors (torch.Tensor) – Tensor of shape (M, 3) or (3,), representing RGB values. - If shape is (3,), the same color is applied to all targeted instances. - If shape is (M, 3), M must match the number of targeted instances.

• env_ids (Sequence[int] | None) – Indices of instances to set. If None: - For colors.shape == (3,), applies to all instances. - For colors.shape == (M, 3), M must equal num_instances, applies per-instance.

Return type:

None

set_direction(directions, env_ids=None)

Set direction for directional-type lights.

Only applies to sun, direction, spot, rect, and mesh light types. Logs a warning and no-ops for other types.

Parameters:

• directions (torch.Tensor) – Tensor of shape (3,) or (M, 3), representing (x, y, z) direction vectors.

• env_ids (Sequence[int] | None) – Indices of instances to set. If None: - For shape (3,), applies to all instances. - For shape (M, 3), M must equal num_instances, applies per-instance.

Return type:

None

set_falloff(falloffs, env_ids=None)

Set falloff (radius) for one or more lights.

Parameters:

• falloffs (torch.Tensor) – Tensor of shape (M,), (1,), or scalar (0-dim). - If scalar or shape (1,), the same falloff is applied to all targeted instances. - If shape (M,), M must match the number of targeted instances.

• env_ids (Sequence[int] | None) – Indices of instances to set. If None: - For scalar/shape (1,), applies to all instances. - For shape (M,), M must equal num_instances, applies per-instance.

Return type:

None

set_intensity(intensities, env_ids=None)

Set intensity for one or more lights.

Parameters:

• intensities (torch.Tensor) – Tensor of shape (M,), (1,), or scalar (0-dim). - If scalar or shape (1,), the same intensity is applied to all targeted instances. - If shape (M,), M must match the number of targeted instances.

• env_ids (Sequence[int] | None) – Indices of instances to set. If None: - For scalar/shape (1,), applies to all instances. - For shape (M,), M must equal num_instances, applies per-instance.

Return type:

None

set_local_pose(pose, env_ids=None, to_matrix=False)

Set local pose (translation) for one or more lights.

Parameters:

• pose (torch.Tensor) –

  • If to_matrix=False: shape (3,) or (M, 3), representing (x, y, z).

  • If to_matrix=True: shape (4, 4) or (M, 4, 4); translation extracted automatically.

• env_ids (Sequence[int] | None) – Indices to set. If None: - For vector input (3,) broadcast to all, or (M,3) with M == num_instances. - For matrix input (4,4) broadcast to all, or (M,4,4) with M == num_instances.

• to_matrix (bool) – Interpret pose as full 4x4 matrix if True, else as vector(s).

Return type:

None

set_mesh(mesh, env_ids=None)

Set the mesh for mesh-type lights.

Only applies to mesh light type. Logs a warning and no-ops for other types. This is NOT tensor-batched — the same MeshObject is assigned to all targeted instances.

Parameters:

• mesh (MeshObject) – The mesh object to assign to the light.

• env_ids (Sequence[int] | None) – Indices of instances to set. If None, applies to all instances.

Return type:

None

set_rect_wh(widths, heights, env_ids=None)

Set width and height for rectangular area lights.

Only applies to rect light type. Logs a warning and no-ops for other types.

Parameters:

• widths (torch.Tensor) – Tensor of shape () (0-dim), (1,), or (M,) representing width of the rectangular light.

• heights (torch.Tensor) – Tensor of shape () (0-dim), (1,), or (M,) representing height of the rectangular light.

• env_ids (Sequence[int] | None) – Indices of instances to set.

Return type:

None

set_spot_angle(inner_angles, outer_angles, env_ids=None)

Set inner and outer cone angles for spot lights.

Only applies to spot light type. Logs a warning and no-ops for other types.

Parameters:

• inner_angles (torch.Tensor) – Tensor of shape () (0-dim), (1,), or (M,) representing inner cone angle in degrees.

• outer_angles (torch.Tensor) – Tensor of shape () (0-dim), (1,), or (M,) representing outer cone angle in degrees.

• env_ids (Sequence[int] | None) – Indices of instances to set.

Return type:

None

class embodichain.lab.sim.objects.LightCfg

Bases: ObjectBaseCfg

Configuration for a light asset in the simulation.

Supports six light types matching the dexsim rendering backend:

• "point": Per-environment omnidirectional point light with position and falloff radius. Created as a batched light (one per environment).

• "sun": Global directional sun light (infinite distance). Created as a single scene-level instance. Uses direction only; position is ignored. Sun-specific fields (angular_radius, halo_size, halo_falloff) are reserved for future backend support.

• "direction": Global pure directional light at infinite distance. Created as a single scene-level instance. Direction only; no position.

• "spot": Per-environment spotlight with position, direction, and inner/outer cone angles. Created as a batched light.

• "rect": Per-environment rectangular area light with position, direction, width, and height. Created as a batched light.

• "mesh": Per-environment mesh-based emissive light. Requires a MeshObject via embodichain.lab.sim.objects.light.Light.set_mesh() (not tensor-batched). Created as a batched light.

Attention

The angular_radius, halo_size, and halo_falloff fields are reserved for future use. The dexsim Python bindings do not yet expose setters for these sun-specific properties.

Attributes:

angular_radius	Angular radius of the sun disc in degrees.
color	RGB color of the light source.
direction	Direction vector for directional, spot, rect, and mesh lights.
enable_shadow	Whether the light casts shadows.
halo_falloff	Halo falloff for sun light.
halo_size	Halo size for sun light.
init_local_pose	4x4 transformation matrix of the root in local frame.
init_pos	Position of the root in simulation world frame.
init_rot	Euler angles (in degree) of the root in simulation world frame.
intensity	Intensity of the light source in watts/m^2.
light_type	"point", "sun", "direction", "spot", "rect", "mesh".
mesh_path	Asset path for mesh-based emissive lights.
radius	Falloff radius for point lights.
rect_height	Height of the rectangular area light.
rect_width	Width of the rectangular area light.
spot_angle_inner	Inner cone angle of the spotlight in degrees.
spot_angle_outer	Outer cone angle of the spotlight in degrees.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

angular_radius: float

Angular radius of the sun disc in degrees. Reserved for future use.

color: tuple[float, float, float]

RGB color of the light source. Defaults to white (1.0, 1.0, 1.0).

direction: tuple[float, float, float]

Direction vector for directional, spot, rect, and mesh lights. Defaults to (0.0, 0.0, -1.0) (pointing down along -Z).

enable_shadow: bool

Whether the light casts shadows. Defaults to True.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

ObjectBaseCfg

halo_falloff: float

Halo falloff for sun light. Reserved for future use.

halo_size: float

Halo size for sun light. Reserved for future use.

init_local_pose: ndarray | None

4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]

Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]

Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

intensity: float

Intensity of the light source in watts/m^2. Defaults to 30.0.

light_type: Literal['point', 'sun', 'direction', 'spot', 'rect', 'mesh']

"point", "sun", "direction", "spot", "rect", "mesh".

Type:

Light type. Supported

mesh_path: str

Asset path for mesh-based emissive lights. Only used when light_type="mesh". The actual mesh assignment is done via embodichain.lab.sim.objects.light.Light.set_mesh() which accepts a dexsim.models.MeshObject. This field stores the path for reference.

radius: float

Falloff radius for point lights. Only used when light_type="point". Defaults to 10.0.

rect_height: float

Height of the rectangular area light. Only used when light_type="rect". Defaults to 1.0.

rect_width: float

Width of the rectangular area light. Only used when light_type="rect". Defaults to 1.0.

spot_angle_inner: float

Inner cone angle of the spotlight in degrees. Only used when light_type="spot". Defaults to 30.0.

spot_angle_outer: float

Outer cone angle of the spotlight in degrees. Only used when light_type="spot". Defaults to 45.0.

Rigid Object

class embodichain.lab.sim.objects.RigidObject

Bases: BatchEntity

RigidObject represents a batch of rigid body in the simulation.

There are three types of rigid body:

• Static: Actors that do not move and are used as the environment.

• Dynamic: Actors that can move and are affected by physics.

• Kinematic: Actors that can move but are not affected by physics.

Methods:

__init__(cfg[, entities, device])
add_force_torque([force, torque, pos, env_ids])	Add force and/or torque to the rigid object.
apply_render_material_inst(env_idx, mat_inst)	Swap a dexsim MaterialInst onto a render-body segment for the given env.
clear_dynamics([env_ids])	Clear the dynamics of the rigid bodies by resetting velocities and applying zero forces and torques.
destroy()	Destroy all entities managed by this batch entity.
enable_collision(enable[, env_ids])	Enable or disable collision for the rigid bodies.
get_body_scale([env_ids])	Retrieve the body scale for specified environment instances.
get_damping([env_ids])	Get linear and angular damping for the rigid object.
get_existing_visual_material([env_ids, shared])	Build reuse state from the material dexsim parsed onto each env's render body.
get_friction([env_ids])	Get friction for the rigid object.
get_inertia([env_ids])	Get inertia tensor for the rigid object.
get_local_pose([to_matrix])	Get local pose of the rigid object.
get_mass([env_ids])	Get mass for the rigid object.
get_triangles([env_ids])	Retrieve the triangle indices of the rigid objects.
get_user_ids([env_ids])	Get the user ids of the rigid bodies.
get_vertices([env_ids, scale])	Retrieve the vertices of the rigid objects.
get_visual_material_inst([env_ids])	Get material instances for the rigid object.
reset([env_ids])	Reset the entity to its initial state.
restore_visual_material([env_ids])	Restore the visual materials captured when the rigid object was created.
set_attrs(attrs[, env_ids])	Set physical attributes for the rigid object.
set_body_scale(scale[, env_ids])	Set the scale of the rigid body.
set_body_type(body_type)	Set the body type of the rigid object.
set_collision_filter(filter_data[, env_ids])	set collision filter data for the rigid object.
set_com_pose(com_pose[, env_ids])	Set the center of mass pose of the rigid body.
set_damping(damping[, env_ids])	Set linear and angular damping for the rigid object.
set_friction(friction[, env_ids])	Set friction for the rigid object.
set_inertia(inertia[, env_ids])	Set inertia tensor for the rigid object.
set_local_pose(pose[, env_ids])	Set local pose of the rigid object.
set_mass(mass[, env_ids])	Set mass for the rigid object.
set_physical_visible([visible, rgba])	set collion render visibility
set_velocity([lin_vel, ang_vel, env_ids])	Set linear and/or angular velocity for the rigid object.
set_visible([visible])	Set the visibility of the rigid object.
set_visual_material(mat[, env_ids, shared])	Set visual material for the rigid object.
share_visual_material_inst(mat_insts)	Share material instances for the rigid object.

Attributes:

body_data	Get the rigid body data manager for this rigid object.
body_state	Get the body state of the rigid object.
is_non_dynamic	Check if the rigid object is non-dynamic (static or kinematic).
is_static	Check if the rigid object is static.
user_ids	Get the user ids of the rigid object.

__init__(cfg, entities=None, device=device(type='cpu'))

add_force_torque(force=None, torque=None, pos=None, env_ids=None)

Add force and/or torque to the rigid object.

TODO: Currently, apply force at position pos is not supported.

Note: there are a few different ways to apply force and torque:

• If pos is specified, the force is applied at that position.

• if not pos is specified, the force and torque are applied at the center of mass of the rigid body.

Parameters:

• force (torch.Tensor | None = None) – The force to add with shape (N, 3). Defaults to None.

• torque (torch.Tensor | None, optional) – The torque to add with shape (N, 3). Defaults to None.

• pos (torch.Tensor | None, optional) – The position to apply the force at with shape (N, 3). Defaults to None.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

apply_render_material_inst(env_idx, mat_inst, mesh_id=0)

Swap a dexsim MaterialInst onto a render-body segment for the given env.

Parameters:

• env_idx (int) – Environment index.

• mat_inst (MaterialInst) – dexsim MaterialInst to attach.

• mesh_id (int) – Render-body segment index.

Return type:

None

property body_data: RigidBodyData | None

Get the rigid body data manager for this rigid object.

Returns:

The rigid body data manager.

Return type:

RigidBodyData

property body_state: Tensor

Get the body state of the rigid object.

The body state of a rigid object is represented as a tensor with the following format: [x, y, z, qw, qx, qy, qz, lin_x, lin_y, lin_z, ang_x, ang_y, ang_z]

If the rigid object is static, linear and angular velocities will be zero.

Returns:

The body state of the rigid object with shape (N, 13), where N is the number of instances.

Return type:

torch.Tensor

clear_dynamics(env_ids=None)

Clear the dynamics of the rigid bodies by resetting velocities and applying zero forces and torques.

Parameters:

env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Return type:

None

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

enable_collision(enable, env_ids=None)

Enable or disable collision for the rigid bodies.

Parameters:

• enable (torch.Tensor) – A tensor of shape (N,) representing whether to enable collision for each rigid body.

• env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Return type:

None

get_body_scale(env_ids=None)

Retrieve the body scale for specified environment instances.

Parameters:

env_ids (Sequence[int] | None) – A sequence of environment instance IDs. If None, retrieves the body scale for all instances.

Returns:

A tensor containing the body scales of the specified instances, with shape (N, 3) dtype int32 and located on the specified device.

Return type:

torch.Tensor

get_damping(env_ids=None)

Get linear and angular damping for the rigid object.

Parameters:

env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Returns:

The damping of the rigid object with shape (N, 2), where the first column is linear damping and the second column is angular damping.

Return type:

torch.Tensor

get_existing_visual_material(env_ids=None, shared=False)

Build reuse state from the material dexsim parsed onto each env’s render body.

For each env (first only if shared), every render-body segment’s existing MaterialInst is captured as an immutable original. One working instance is shared by all segments so randomized updates have constant material-update cost.

Parameters:

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are used.

• shared (bool) – If True, build state for the first env only (caller applies it to all).

Return type:

List[List[ReuseSegmentState]]

Returns:

Per-env list of per-segment ReuseSegmentState (length 1 if shared).

Raises:

ValueError – If a segment has no material or no retrievable template.

get_friction(env_ids=None)

Get friction for the rigid object.

Parameters:

env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Returns:

The friction of the rigid object with shape (N,).

Return type:

torch.Tensor

get_inertia(env_ids=None)

Get inertia tensor for the rigid object.

Parameters:

env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Returns:

The inertia tensor of the rigid object with shape (N, 3), where each row is the diagonal of the inertia tensor.

Return type:

torch.Tensor

get_local_pose(to_matrix=False)

Get local pose of the rigid object.

Parameters:

to_matrix (bool, optional) – If True, return the pose as a 4x4 matrix. If False, return as (x, y, z, qw, qx, qy, qz). Defaults to False.

Returns:

The local pose of the rigid object with shape (N, 7) or (N, 4, 4) depending on to_matrix.

Return type:

torch.Tensor

get_mass(env_ids=None)

Get mass for the rigid object.

Parameters:

env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Returns:

The mass of the rigid object with shape (N,).

Return type:

torch.Tensor

get_triangles(env_ids=None)

Retrieve the triangle indices of the rigid objects.

Parameters:

env_ids (Sequence[int] | None) – A sequence of environment IDs for which to retrieve triangle indices. If None, retrieves triangle indices for all instances.

Returns:

A tensor containing the triangle indices of the specified rigid objects with shape (N, num_tris, 3).

Return type:

torch.Tensor

get_user_ids(env_ids=None)

Get the user ids of the rigid bodies.

Parameters:

env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Returns:

A tensor of shape (num_envs,) representing the user ids of the rigid bodies.

Return type:

torch.Tensor

get_vertices(env_ids=None, scale=False)

Retrieve the vertices of the rigid objects.

Parameters:

• env_ids (Sequence[int] | None) – A sequence of environment IDs for which to retrieve vertices. If None, retrieves vertices for all instances.

• scale (bool) – Whether to multiply the vertices by the body scale. Defaults to False.

Returns:

A tensor containing the user IDs of the specified rigid objects with shape (N, num_verts, 3).

Return type:

torch.Tensor

get_visual_material_inst(env_ids=None)

Get material instances for the rigid object.

Parameters:

env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Returns:

List of material instances.

Return type:

List[MaterialInst]

property is_non_dynamic: bool

Check if the rigid object is non-dynamic (static or kinematic).

Returns:

True if the rigid object is non-dynamic, False otherwise.

Return type:

bool

property is_static: bool

Check if the rigid object is static.

Returns:

True if the rigid object is static, False otherwise.

Return type:

bool

reset(env_ids=None)

Reset the entity to its initial state.

Parameters:

env_ids (Sequence[int] | None) – The environment IDs to reset. If None, reset all environments.

Return type:

None

restore_visual_material(env_ids=None)

Restore the visual materials captured when the rigid object was created.

Parameters:

env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are restored.

Return type:

None

set_attrs(attrs, env_ids=None)

Set physical attributes for the rigid object.

Parameters:

• attrs (Union[RigidBodyAttributesCfg, List[RigidBodyAttributesCfg]]) – The physical attributes to set.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_body_scale(scale, env_ids=None)

Set the scale of the rigid body.

Parameters:

• scale (torch.Tensor) – The scale to set with shape (N, 3).

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_body_type(body_type)

Set the body type of the rigid object.

Note

Only ‘dynamic’ and ‘kinematic’ body types are supported and can be changed at runtime.

Parameters:

body_type (str) – The body type to set. Must be one of ‘dynamic’, or ‘kinematic’.

Return type:

None

set_collision_filter(filter_data, env_ids=None)

set collision filter data for the rigid object.

Parameters:

• filter_data (torch.Tensor) – [N, 4] of int. First element of each object is arena id. If 2nd element is 0, the object will collision with all other objects in world. 3rd and 4th elements are not used currently.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used. Defaults to None.

Return type:

None

set_com_pose(com_pose, env_ids=None)

Set the center of mass pose of the rigid body. The pose format is (x, y, z, qw, qx, qy, qz).

Parameters:

• com_pose (torch.Tensor) – The center of mass pose to set with shape (N, 7).

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_damping(damping, env_ids=None)

Set linear and angular damping for the rigid object.

Parameters:

• damping (torch.Tensor) – The damping to set with shape (N, 2), where the first column is linear damping and the second column is angular damping.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_friction(friction, env_ids=None)

Set friction for the rigid object.

Parameters:

• friction (torch.Tensor) – The friction to set with shape (N,).

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_inertia(inertia, env_ids=None)

Set inertia tensor for the rigid object.

Parameters:

• inertia (torch.Tensor) – The inertia tensor to set with shape (N, 3), where each row is the diagonal of the inertia tensor.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_local_pose(pose, env_ids=None)

Set local pose of the rigid object.

Parameters:

• pose (torch.Tensor) – The local pose of the rigid object with shape (N, 7) or (N, 4, 4).

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_mass(mass, env_ids=None)

Set mass for the rigid object.

Parameters:

• mass (torch.Tensor) – The mass to set with shape (N,).

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_physical_visible(visible=True, rgba=None)

set collion render visibility

Parameters:

• visible (bool, optional) – is collision body visible. Defaults to True.

• rgba (Sequence[float] | None, optional) – collision body visible rgba. It will be defined at the first time the function is called. Defaults to None.

set_velocity(lin_vel=None, ang_vel=None, env_ids=None)

Set linear and/or angular velocity for the rigid object.

Parameters:

• lin_vel (torch.Tensor | None, optional) – The linear velocity to set with shape (N, 3). Defaults to None.

• ang_vel (torch.Tensor | None, optional) – The angular velocity to set with shape (N, 3). Defaults to None.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_visible(visible=True)

Set the visibility of the rigid object.

Parameters:

visible (bool, optional) – Whether the rigid object is visible. Defaults to True.

Return type:

None

set_visual_material(mat, env_ids=None, shared=False)

Set visual material for the rigid object.

Note

If shared is True, the same material instance will be used for all specified environment indices. If shared is False, a unique material instance will be created for each specified environment index.

Parameters:

• mat (VisualMaterial) – The material to set.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

• shared (bool, optional) – Whether to share the material instance among all specified environment indices. Defaults to False.

Return type:

None

share_visual_material_inst(mat_insts)

Share material instances for the rigid object.

Parameters:

mat_insts (List[VisualMaterialInst]) – List of material instances to share.

Return type:

None

property user_ids: Tensor

Get the user ids of the rigid object.

Returns:

The user ids of the rigid object with shape (N,).

Return type:

torch.Tensor

class embodichain.lab.sim.objects.RigidBodyData

Bases: object

Data manager for rigid body with body type of dynamic or kinematic.

Note

1. The pose data managed by dexsim is in the format of (qx, qy, qz, qw, x, y, z), but in SimulationManager, we use (x, y, z, qw, qx, qy, qz) format.

Methods:

__init__(entities, ps, device)

Initialize the RigidBodyData.

Attributes:

acc	Get the linear and angular accelerations of the rigid bodies.
com_pose	Get the center of mass pose of the rigid bodies.
vel	Get the linear and angular velocities of the rigid bodies.

__init__(entities, ps, device)

Initialize the RigidBodyData.

Parameters:

• entities (List[MeshObject]) – List of MeshObjects representing the rigid bodies.

• ps (PhysicsScene) – The physics scene.

• device (torch.device) – The device to use for the rigid body data.

property acc: Tensor

Get the linear and angular accelerations of the rigid bodies.

Returns:

The linear and angular accelerations concatenated, with shape (N, 6).

Return type:

torch.Tensor

property com_pose: Tensor

Get the center of mass pose of the rigid bodies.

Returns:

The center of mass pose with shape (N, 7).

Return type:

torch.Tensor

property vel: Tensor

Get the linear and angular velocities of the rigid bodies.

Returns:

The linear and angular velocities concatenated, with shape (N, 6).

Return type:

torch.Tensor

class embodichain.lab.sim.objects.RigidObjectCfg

Bases: ObjectBaseCfg

Configuration for a rigid body asset in the simulation.

This class extends the base asset configuration to include specific properties for rigid bodies, such as physical attributes and collision group.

Attributes:

acd_method	The method used for approximate convex decomposition (ACD) of the mesh.
body_scale	Scale of the rigid body in the simulation world frame.
init_local_pose	4x4 transformation matrix of the root in local frame.
init_pos	Position of the root in simulation world frame.
init_rot	Euler angles (in degree) of the root in simulation world frame.
max_convex_hull_num	The maximum number of convex hulls that will be created for the rigid body.
sdf_resolution	Resolution for the signed distance field (SDF) of the rigid body.
shape	Shape configuration for the rigid body.
use_usd_properties	Whether to use physical properties from USD file instead of config.

Methods:

from_dict(init_dict)	Initialize the configuration from a dictionary.
to_dexsim_body_type()	Convert the body type to dexsim ActorType.

acd_method: str

The method used for approximate convex decomposition (ACD) of the mesh.

Deprecated since version Use: MeshCfg.acd_method instead. This field is kept for backward compatibility and overrides the shape-level value when explicitly set.

Currently, "coacd" and "vhacd" are supported. Only used when max_convex_hull_num is set to larger than 1.

body_scale: tuple | list

Scale of the rigid body in the simulation world frame.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

ObjectBaseCfg

init_local_pose: ndarray | None

4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]

Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]

Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

max_convex_hull_num: int

The maximum number of convex hulls that will be created for the rigid body.

Deprecated since version Use: MeshCfg.max_convex_hull_num instead. This field is kept for backward compatibility and overrides the shape-level value when explicitly set.

If set to larger than 1, the rigid body will be decomposed into multiple convex hulls using the approximate convex decomposition method specified by acd_method. Reference: SarahWeiii/CoACD

sdf_resolution: int

Resolution for the signed distance field (SDF) of the rigid body.

Deprecated since version Use: MeshCfg.sdf_resolution instead. This field is kept for backward compatibility and overrides the shape-level value when explicitly set.

The spacing of the uniformly sampled SDF is equal to the largest AABB extent of the mesh, divided by the resolution. If sdf_resolution is set to larger than 0, an SDF will be generated for collision detection. SDF will increase the accuracy of collision, but also takes more time to initialize and simulate.

shape: ShapeCfg

Shape configuration for the rigid body.

to_dexsim_body_type()

Convert the body type to dexsim ActorType.

Return type:

ActorType

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values. Only effective for USD files.

Rigid Object Group

class embodichain.lab.sim.objects.RigidObjectGroup

Bases: BatchEntity

RigidObjectGroup represents a batch of rigid bodies in the simulation.

Methods:

__init__(cfg[, entities, device])
clear_dynamics([env_ids])	Clear the dynamics of the rigid bodies by resetting velocities and applying zero forces and torques.
destroy()	Destroy all entities managed by this batch entity.
get_local_pose([to_matrix])	Get local pose of the rigid object group.
get_user_ids()	Get the user ids of the rigid body group.
reset([env_ids])	Reset the entity to its initial state.
set_collision_filter(filter_data[, env_ids])	set collision filter data for the rigid object group.
set_local_pose(pose[, env_ids, obj_ids])	Set local pose of the rigid object group.
set_physical_visible([visible, rgba])	set collion render visibility
set_visible([visible])	Set the visibility of the rigid object group.
set_visual_material(mat[, env_ids])	Set visual material for the rigid object group.

Attributes:

body_data	Get the rigid body data manager for this rigid object.
body_state	Get the body state of the rigid object.
is_non_dynamic	Check if the rigid object is non-dynamic (static or kinematic).
num_objects	Get the number of objects in each rigid body instance.

__init__(cfg, entities=None, device=device(type='cpu'))

property body_data: RigidBodyGroupData

Get the rigid body data manager for this rigid object.

Returns:

The rigid body data manager.

Return type:

RigidBodyGroupData

property body_state: Tensor

Get the body state of the rigid object.

The body state of a rigid object is represented as a tensor with the following format: [x, y, z, qw, qx, qy, qz, lin_x, lin_y, lin_z, ang_x, ang_y, ang_z]

If the rigid object is static, linear and angular velocities will be zero.

Returns:

The body state of the rigid object with shape (num_instances, num_objects, 13),

where N is the number of instances.

Return type:

torch.Tensor

clear_dynamics(env_ids=None)

Clear the dynamics of the rigid bodies by resetting velocities and applying zero forces and torques.

Parameters:

env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Return type:

None

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

get_local_pose(to_matrix=False)

Get local pose of the rigid object group.

Parameters:

to_matrix (bool, optional) – If True, return the pose as a 4x4 matrix. If False, return as (x, y, z, qw, qx, qy, qz). Defaults to False.

Returns:

The local pose of the rigid object with shape (num_instances, num_objects, 7) or (num_instances, num_objects, 4, 4) depending on to_matrix.

Return type:

torch.Tensor

get_user_ids()

Get the user ids of the rigid body group.

Returns:

A tensor of shape (num_envs, num_objects) representing the user ids of the rigid body group.

Return type:

torch.Tensor

property is_non_dynamic: bool

Check if the rigid object is non-dynamic (static or kinematic).

Returns:

True if the rigid object is non-dynamic, False otherwise.

Return type:

bool

property num_objects: int

Get the number of objects in each rigid body instance.

Returns:

The number of objects in each rigid body instance.

Return type:

int

reset(env_ids=None)

Reset the entity to its initial state.

Parameters:

env_ids (Sequence[int] | None) – The environment IDs to reset. If None, reset all environments.

Return type:

None

set_collision_filter(filter_data, env_ids=None)

set collision filter data for the rigid object group.

Parameters:

• filter_data (torch.Tensor) – [N, 4] of int. First element of each object is arena id. If 2nd element is 0, the object will collision with all other objects in world. 3rd and 4th elements are not used currently.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used. Defaults to None.

Return type:

None

set_local_pose(pose, env_ids=None, obj_ids=None)

Set local pose of the rigid object group.

Parameters:

• pose (torch.Tensor) – The local pose of the rigid object group with shape (num_instances, num_objects, 7) or (num_instances, num_objects, 4, 4).

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

• obj_ids (Sequence[int] | None, optional) – Object indices within the group. If None, all objects are set. Defaults to None.

Return type:

None

set_physical_visible(visible=True, rgba=None)

set collion render visibility

Parameters:

• visible (bool, optional) – is collision body visible. Defaults to True.

• rgba (Sequence[float] | None, optional) – collision body visible rgba. It will be defined at the first time the function is called. Defaults to None.

set_visible(visible=True)

Set the visibility of the rigid object group.

Parameters:

visible (bool, optional) – Whether the rigid object group is visible. Defaults to True.

Return type:

None

set_visual_material(mat, env_ids=None)

Set visual material for the rigid object group.

Note

For each entity in the rigid object group, a unique material instance will be created and shared among all objects in that entity.

Parameters:

• mat (VisualMaterial) – The material to set.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

class embodichain.lab.sim.objects.RigidBodyGroupData

Bases: object

Data manager for rigid body group with body type of dynamic or kinematic.

Methods:

__init__(entities, ps, device)

Initialize the RigidBodyGroupData.

Attributes:

vel	Get the linear and angular velocities of the rigid bodies.

__init__(entities, ps, device)

Initialize the RigidBodyGroupData.

Parameters:

• entities (List[List[MeshObject]]) – List of List MeshObjects representing the rigid body group.

• ps (PhysicsScene) – The physics scene.

• device (torch.device) – The device to use for the rigid body group data.

property vel: Tensor

Get the linear and angular velocities of the rigid bodies.

Returns:

The linear and angular velocities concatenated, with shape (num_instances, num_objects, 6).

Return type:

torch.Tensor

class embodichain.lab.sim.objects.RigidObjectGroupCfg

Bases: object

Configuration for a rigid object group asset in the simulation.

Rigid object groups can be initialized from multiple rigid object configurations specified in a folder. If folder_path is specified, user should provide a RigidObjectCfg in rigid_objects as a template configuration for all objects in the group.

For example: ```python rigid_object_group: RigidObjectGroupCfg(

folder_path=”path/to/folder”, max_num=5, rigid_objects={

“template_obj”: RigidObjectCfg(

shape=MeshCfg(

fpath=””, # fpath will be ignored when folder_path is specified

), body_type=”dynamic”,

)

}

)

Attributes:

body_type	Body type for all rigid objects in the group.
ext	File extension for the rigid object assets.
folder_path	Path to the folder containing the rigid object assets.
max_num	Maximum number of rigid objects to initialize from the folder.
rigid_objects	Configuration for the rigid objects in the group.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

body_type: Literal['dynamic', 'kinematic']

Body type for all rigid objects in the group.

ext: str

File extension for the rigid object assets.

This is only used when folder_path is specified.

folder_path: str | None

Path to the folder containing the rigid object assets.

This is used to initialize multiple rigid object configurations from a folder.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

RigidObjectGroupCfg

max_num: int

Maximum number of rigid objects to initialize from the folder.

This is only used when folder_path is specified.

rigid_objects: Dict[str, RigidObjectCfg]

Configuration for the rigid objects in the group.

Articulation

class embodichain.lab.sim.objects.Articulation

Bases: BatchEntity

Articulation represents a batch of articulations in the simulation.

An articulation is a collection of rigid bodies connected by joints. The joints can be either fixed or actuated. The joints can be of different types, such as revolute or prismatic.

For fixed-base articulation, it can be a robot arm, door, etc. For floating-base articulation, it can be a humanoid, drawer, etc.

Parameters:

• cfg (ArticulationCfg) – Configuration for the articulation.

• entities (List[_Articulation], optional) – List of articulation entities.

• device (torch.device, optional) – Device to use (CPU or CUDA).

Methods:

__init__(cfg[, entities, device])
apply_render_material_inst(env_idx, ...[, ...])	Swap a dexsim MaterialInst onto a link's render-body segment for the given env.
clear_dynamics([env_ids])	Clear the dynamics of the articulation.
compute_fk(qpos[, link_names, ...])	Compute the forward kinematics (FK) for the given joint positions.
compute_jacobian(qpos[, end_link_name, ...])	Compute the Jacobian matrix for the given joint positions using the pk_serial_chain.
destroy()	Destroy all entities managed by this batch entity.
get_existing_visual_material([env_ids, ...])	Build reuse state from materials dexsim parsed onto each link's render body.
get_joint_drive([joint_ids, env_ids])	Get the drive properties for the articulation.
get_link_physical_attr([link_names, env_ids])	Get physical attributes for articulation links.
get_link_pose(link_name[, env_ids, to_matrix])	Get the pose of a specific link in the articulation.
get_link_vert_face(link_name)	Get the vertices and faces of a specific link in the articulation.
get_local_pose([to_matrix])	Get local pose (root link pose) of the articulation.
get_mass([link_names, env_ids])	Get the mass of specific links in the articulation.
get_qf_limits([joint_ids, env_ids])	Get joint effort limits for selected environments and joints.
get_qpos([target])	Get the current positions (qpos) or target positions (target_qpos) of the articulation.
get_qpos_limits([joint_ids, env_ids])	Get joint position limits for selected environments and joints.
get_qvel([target])	Get the current velocities (qvel) or target velocities (target_qvel) of the articulation.
get_qvel_limits([joint_ids, env_ids])	Get joint velocity limits for selected environments and joints.
get_user_ids([link_name, env_ids])	Get the user ids of the articulation.
get_visual_material_inst([env_ids, link_names])	Get visual material instances for the rigid object.
reallocate_body_data()	Reallocate body data tensors to match the current articulation state in the GPU physics scene.
reset([env_ids])	Reset the entity to its initial state.
restore_visual_material([env_ids, link_names])	Restore visual materials captured when the articulation was created.
set_collision_filter(filter_data[, env_ids])	set collision filter data for the rigid object.
set_fix_base([fix, env_ids])	Set whether the base of the articulation is fixed.
set_joint_drive([stiffness, damping, ...])	Set the drive properties for the articulation.
set_link_physical_attr(attrs[, link_names, ...])	Set physical attributes for selected articulation links.
set_local_pose(pose[, env_ids])	Set local pose of the articulation.
set_mass(mass, link_names[, env_ids])	Set the mass of specific links in the articulation.
set_physical_visible([visible, link_names, rgba])	set collision
set_qf(qf[, joint_ids, env_ids])	Set the generalized efforts (qf) of the articulation.
set_qf_limits(qf_limits[, joint_ids, env_ids])	Set joint effort limits for selected environments and joints.
set_qpos(qpos[, joint_ids, env_ids, target])	Set the joint positions (qpos) or target positions for the articulation.
set_qpos_limits(qpos_limits[, joint_ids, ...])	Set joint position limits for selected environments and joints.
set_qvel(qvel[, joint_ids, env_ids, target])	Set the velocities (qvel) or target velocities of the articulation.
set_qvel_limits(qvel_limits[, joint_ids, ...])	Set joint velocity limits for selected environments and joints.
set_self_collision([enable, env_ids])	Set whether self-collision is enabled for the articulation.
set_visual_material(mat[, env_ids, ...])	Set visual material for the rigid object.

Attributes:

active_dof	Get the number of active degrees of freedom of the articulation.
active_joint_names	Get the names of the active joints in the articulation.
all_joint_names	Get the names of the joints in the articulation.
body_data	Get the rigid body data manager for this rigid object.
body_state	Get the body state of the articulation.
dof	Get the degree of freedom of the articulation.
joint_names	Get the names of the joints in the articulation.
link_names	Get the names of the links in the articulation.
mimic_ids	Get the mimic joint ids for the articulation.
mimic_multipliers	Get the mimic joint multipliers for the articulation.
mimic_offsets	Get the mimic joint offsets for the articulation.
mimic_parents	Get the mimic joint parent ids for the articulation.
num_links	Get the number of links in the articulation.
root_link_name	Get the name of the root link of the articulation.
root_state	Get the root state of the articulation.
user_ids	Get the user-defined IDs of the articulation.

__init__(cfg, entities=None, device=device(type='cpu'))

property active_dof: int

Get the number of active degrees of freedom of the articulation.

Returns:

The number of active degrees of freedom of the articulation.

Return type:

int

property active_joint_names: List[str]

Get the names of the active joints in the articulation.

Returns:

The names of the active joints in the articulation.

Return type:

List[str]

property all_joint_names: List[str]

Get the names of the joints in the articulation.

Returns:

The names of the joints in the articulation.

Return type:

List[str]

apply_render_material_inst(env_idx, mat_inst, link_name, mesh_id=0)

Swap a dexsim MaterialInst onto a link’s render-body segment for the given env.

Parameters:

• env_idx (int) – Environment index.

• mat_inst (MaterialInst) – dexsim MaterialInst to attach.

• link_name (str) – Link whose render body receives the material.

• mesh_id (int) – Render-body segment index.

Return type:

None

property body_data: ArticulationData

Get the rigid body data manager for this rigid object.

Returns:

The rigid body data manager.

Return type:

RigidBodyData

property body_state: Tensor

Get the body state of the articulation.

Returns:

The body state of the articulation with shape (N, num_links, 13).

Return type:

torch.Tensor

clear_dynamics(env_ids=None)

Clear the dynamics of the articulation.

Parameters:

env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Return type:

None

compute_fk(qpos, link_names=None, end_link_name=None, root_link_name=None, to_dict=False, **kwargs)

Compute the forward kinematics (FK) for the given joint positions.

Parameters:

• qpos (torch.Tensor) – Joint positions. Shape can be (dof,) for a single configuration or (batch_size, dof) for batched configurations.

• link_names (Union[str, list[str], tuple[str]], optional) – Names of the links for which FK is computed. If None, all links are considered.

• end_link_name (str, optional) – Name of the end link for which FK is computed. If None, all links are considered.

• root_link_name (str, optional) – Name of the root link for which FK is computed. Defaults to None.

• to_dict (bool, optional) – If True, returns the FK result as a dictionary of Transform3d objects. Defaults to False.

• **kwargs – Additional keyword arguments for customization.

Raises:

• RuntimeError – If the pk_chain is not initialized.

• TypeError – If an invalid type is provided for link_names.

• ValueError – If the shape of the resulting matrices is unexpected.

Returns:

The homogeneous transformation matrix/matrices for the specified links.

Shape is (batch_size, 4, 4) for batched input or (4, 4) for single input. If to_dict is True, returns a dictionary of Transform3d objects instead.

Return type:

torch.Tensor

compute_jacobian(qpos, end_link_name=None, root_link_name=None, locations=None, jac_type='full')

Compute the Jacobian matrix for the given joint positions using the pk_serial_chain.

Parameters:

• qpos (torch.Tensor) – The joint positions. Shape can be (dof,) for a single configuration or (batch_size, dof) for batched configurations.

• end_link_name (str, optional) – The name of the end link for which the Jacobian is computed. Defaults to the last link in the chain.

• root_link_name (str, optional) – The name of the root link for which the Jacobian is computed. Defaults to the first link in the chain.

• locations (torch.Tensor | np.ndarray, optional) – Offset points relative to the end-effector frame for which the Jacobian is computed. Shape can be (batch_size, 3) or (3,) for a single offset. Defaults to None (origin of the end-effector frame).

• jac_type (str, optional) – Specifies the part of the Jacobian to return: - ‘full’: Returns the full Jacobian (6, dof) or (batch_size, 6, dof). - ‘trans’: Returns only the translational part (3, dof) or (batch_size, 3, dof). - ‘rot’: Returns only the rotational part (3, dof) or (batch_size, 3, dof). Defaults to ‘full’.

Raises:

• RuntimeError – If the pk_chain is not initialized.

• ValueError – If an invalid jac_type is provided.

Returns:

The Jacobian matrix. Shape depends on the input:

• For a single link: (6, dof) or (batch_size, 6, dof).

• For multiple links: (num_links, 6, dof) or (num_links, batch_size, 6, dof).

The shape also depends on the jac_type parameter.

Return type:

torch.Tensor

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

property dof: int

Get the degree of freedom of the articulation.

Returns:

The degree of freedom of the articulation.

Return type:

int

get_existing_visual_material(env_ids=None, link_names=None, shared=False)

Build reuse state from materials dexsim parsed onto each link’s render body.

Each segment keeps its original material for restoration. Segments on the same link share one working material so randomized property updates happen once per link instead of once per mesh segment.

Parameters:

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are used.

• link_names (Optional[List[str]]) – Links to include. If None, all links are used.

• shared (bool) – If True, build state for the first env only.

Return type:

List[Dict[str, List[ReuseSegmentState]]]

Returns:

Per-env dict mapping link name to per-segment ReuseSegmentState.

Raises:

ValueError – If a link/segment has no material or no retrievable template.

get_joint_drive(joint_ids=None, env_ids=None)

Get the drive properties for the articulation.

Parameters:

• joint_ids (Sequence[int] | None, optional) – The joint indices to get the drive properties for. If None, gets for all joints. Defaults to None.

• env_ids (Sequence[int] | None, optional) – The environment indices to get the drive properties for. If None, gets for all environments. Defaults to None.

Returns:

A tuple containing the stiffness, damping, max_effort,

max_velocity, friction, and armature tensors with shape (N, len(joint_ids)) for the specified environments.

Return type:

Tuple[torch.Tensor, …]

get_link_physical_attr(link_names=None, env_ids=None)

Get physical attributes for articulation links.

Parameters:

• link_names (Union[str, Sequence[str], None]) – Link names or regex patterns. If None, all links are returned.

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, only env 0 is queried.

Return type:

list[PhysicalAttr]

Returns:

List of PhysicalAttr, one per (env, link) pair in row-major order (env-major).

get_link_pose(link_name, env_ids=None, to_matrix=False)

Get the pose of a specific link in the articulation.

Parameters:

• link_name (str) – The name of the link.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

• to_matrix (bool, optional) – If True, return the pose as a 4x4 matrix. If False, return as (x, y, z, qw, qx, qy, qz). Defaults to False.

Returns:

The pose of the specified link with shape (N, 7) or (N, 4, 4) depending on to_matrix.

Return type:

torch.Tensor

get_link_vert_face(link_name)

Get the vertices and faces of a specific link in the articulation.

Parameters:

link_name (str) – The name of the link.

Returns:

• vertices (torch.Tensor): The vertices of the specified link with shape (V, 3).

• faces (torch.Tensor): The faces of the specified link with shape (F, 3).

Return type:

Tuple[torch.Tensor, torch.Tensor]

get_local_pose(to_matrix=False)

Get local pose (root link pose) of the articulation.

Parameters:

to_matrix (bool, optional) – If True, return the pose as a 4x4 matrix. If False, return as (x, y, z, qw, qx, qy, qz). Defaults to False.

Returns:

The local pose of the articulation with shape (N, 7) or (N, 4, 4) depending on to_matrix.

Return type:

torch.Tensor

get_mass(link_names=None, env_ids=None)

Get the mass of specific links in the articulation.

Parameters:

• link_names (Sequence[str] | None, optional) – The names of the links to get the mass for. If None, gets mass for all links. Defaults to None.

• env_ids (Sequence[int] | None, optional) – Environment indices to get the mass from. If None, gets from all environments. Defaults to None.

Returns:

The mass of the specified links with shape (N, len(link_names)).

Return type:

torch.Tensor

get_qf_limits(joint_ids=None, env_ids=None)

Get joint effort limits for selected environments and joints.

Parameters:

• joint_ids (Union[Sequence[int], Tensor, None]) – Joint indices to query. If None, all joints are queried.

• env_ids (Union[Sequence[int], Tensor, None]) – Environment indices to query. If None, all environments are queried.

Returns:

Joint effort limits with shape (num_envs, num_joints).

Return type:

torch.Tensor

get_qpos(target=False)

Get the current positions (qpos) or target positions (target_qpos) of the articulation.

Parameters:

target (bool) – If True, gets target positions for simulation. If False, gets current positions.

Returns:

Joint positions with shape (N, dof), where N is the number of environments.

Return type:

torch.Tensor

get_qpos_limits(joint_ids=None, env_ids=None)

Get joint position limits for selected environments and joints.

Parameters:

• joint_ids (Union[Sequence[int], Tensor, None]) – Joint indices to query. If None, all joints are queried.

• env_ids (Union[Sequence[int], Tensor, None]) – Environment indices to query. If None, all environments are queried.

Returns:

Joint position limits with shape (num_envs, num_joints, 2).

Return type:

torch.Tensor

get_qvel(target=False)

Get the current velocities (qvel) or target velocities (target_qvel) of the articulation.

Parameters:

target (bool) – If True, gets target velocities for simulation. If False, gets current velocities. The default is False.

Returns:

The current velocities of the articulation.

Return type:

torch.Tensor

get_qvel_limits(joint_ids=None, env_ids=None)

Get joint velocity limits for selected environments and joints.

Parameters:

• joint_ids (Union[Sequence[int], Tensor, None]) – Joint indices to query. If None, all joints are queried.

• env_ids (Union[Sequence[int], Tensor, None]) – Environment indices to query. If None, all environments are queried.

Returns:

Joint velocity limits with shape (num_envs, num_joints).

Return type:

torch.Tensor

get_user_ids(link_name=None, env_ids=None)

Get the user ids of the articulation.

Parameters:

• link_name (str | None) – (str | None): The name of the link. If None, returns user ids for all links.

• env_ids (Optional[Sequence[int]]) – (Sequence[int] | None): Environment indices. If None, then all indices are used.

Returns:

The user ids of the articulation with shape (N, 1) for given link_name or (N, num_links) if link_name is None.

Return type:

torch.Tensor

get_visual_material_inst(env_ids=None, link_names=None)

Get visual material instances for the rigid object.

Parameters:

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

• link_names (List[str] | None, optional) – List of link names to filter materials. If None, returns materials for all links.

Returns:

A list where each element corresponds to an environment and contains a dictionary mapping link names to their VisualMaterialInst.

Return type:

List[Dict[str, VisualMaterialInst]]

property joint_names: List[str]

Get the names of the joints in the articulation.

Returns:

The names of the actived joints in the articulation.

Return type:

List[str]

property link_names: List[str]

Get the names of the links in the articulation.

Returns:

The names of the links in the articulation.

Return type:

List[str]

property mimic_ids: List[int | None]

Get the mimic joint ids for the articulation.

Returns:

The mimic joint ids.

Return type:

List[int | None]

property mimic_multipliers: List[float]

Get the mimic joint multipliers for the articulation.

Returns:

The mimic joint multipliers.

Return type:

List[float]

property mimic_offsets: List[float]

Get the mimic joint offsets for the articulation.

Returns:

The mimic joint offsets.

Return type:

List[float]

property mimic_parents: List[int | None]

Get the mimic joint parent ids for the articulation.

Returns:

The mimic joint parent ids.

Return type:

List[int | None]

property num_links: int

Get the number of links in the articulation.

Returns:

The number of links in the articulation.

Return type:

int

reallocate_body_data()

Reallocate body data tensors to match the current articulation state in the GPU physics scene.

Return type:

None

reset(env_ids=None)

Reset the entity to its initial state.

Parameters:

env_ids (Sequence[int] | None) – The environment IDs to reset. If None, reset all environments.

Return type:

None

restore_visual_material(env_ids=None, link_names=None)

Restore visual materials captured when the articulation was created.

Parameters:

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are restored.

• link_names (Optional[List[str]]) – Links to restore. If None, all links are restored.

Return type:

None

property root_link_name: str

Get the name of the root link of the articulation.

Returns:

The name of the root link.

Return type:

str

property root_state: Tensor

Get the root state of the articulation.

Returns:

The root state of the articulation with shape (N, 13).

Return type:

torch.Tensor

set_collision_filter(filter_data, env_ids=None)

set collision filter data for the rigid object.

Parameters:

• filter_data (torch.Tensor) – [N, 4] of int. First element of each object is arena id. If 2nd element is 0, the object will collision with all other objects in world. 3rd and 4th elements are not used currently.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used. Defaults to None.

Return type:

None

set_fix_base(fix=True, env_ids=None)

Set whether the base of the articulation is fixed.

Parameters:

• fix (bool, optional) – Whether to fix the base. Defaults to True.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_joint_drive(stiffness=None, damping=None, max_effort=None, max_velocity=None, friction=None, armature=None, drive_type='none', joint_ids=None, env_ids=None)

Set the drive properties for the articulation.

Parameters:

• stiffness (torch.Tensor) – The stiffness of the joint drive with shape (len(env_ids), len(joint_ids)).

• damping (torch.Tensor) – The damping of the joint drive with shape (len(env_ids), len(joint_ids)).

• max_effort (torch.Tensor) – The maximum effort of the joint drive with shape (len(env_ids), len(joint_ids)).

• max_velocity (torch.Tensor) – The maximum velocity of the joint drive with shape (len(env_ids), len(joint_ids)).

• friction (torch.Tensor) – The joint friction coefficient with shape (len(env_ids), len(joint_ids)).

• armature (torch.Tensor) – The joint armature with shape (len(env_ids), len(joint_ids)).

• drive_type (str, optional) – The type of drive to apply. Defaults to “force”.

• joint_ids (Sequence[int] | None, optional) – The joint indices to apply the drive to. If None, applies to all joints. Defaults to None.

• env_ids (Sequence[int] | None, optional) – The environment indices to apply the drive to. If None, applies to all environments. Defaults to None.

Return type:

None

set_link_physical_attr(attrs, link_names=None, env_ids=None, *, base_attrs=None, replace_inertial=False)

Set physical attributes for selected articulation links.

Parameters:

• attrs (RigidBodyAttributesCfg | RigidBodyAttributesOverrideCfg | PhysicalAttr) – Full, partial, or DexSim physical attributes to apply.

• link_names (Union[str, Sequence[str], None]) – Link names or regex patterns. If None, all links are updated.

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, all environments are updated.

• base_attrs (RigidBodyAttributesCfg | None) – Base config used when attrs is a partial override.

• replace_inertial (bool) – Recompute inertia when mass changes.

Return type:

None

set_local_pose(pose, env_ids=None)

Set local pose of the articulation.

Parameters:

• pose (torch.Tensor) – The local pose of the articulation with shape (N, 7) or (N, 4, 4).

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_mass(mass, link_names, env_ids=None)

Set the mass of specific links in the articulation.

Parameters:

• mass (torch.Tensor) – The mass values to set with shape (N, len(link_names)).

• link_names (Sequence[str]) – The names of the links to set the mass for.

• env_ids (Sequence[int] | None, optional) – Environment indices to apply the mass change. If None, applies to all environments. Defaults to None.

Return type:

None

set_physical_visible(visible=True, link_names=None, rgba=None)

set collision

Parameters:

• visible (bool, optional) – is collision body visible. Defaults to True.

• link_names (List[str] | None, optional) – links to set visibility. Defaults to None.

• rgba (Sequence[float] | None, optional) – collision body visible rgba. It will be defined at the first time the function is called. Defaults to None.

set_qf(qf, joint_ids=None, env_ids=None)

Set the generalized efforts (qf) of the articulation.

Parameters:

• qf (torch.Tensor) – The generalized efforts with shape (N, dof).

• joint_ids (Sequence[int] | None, optional) – Joint indices to apply the efforts. If None, applies to all joints.

• env_ids (Sequence[int] | None, optional) – Environment indices. Defaults to all indices.

Return type:

None

set_qf_limits(qf_limits, joint_ids=None, env_ids=None)

Set joint effort limits for selected environments and joints.

Parameters:

• qf_limits (Tensor) – Joint effort limits with shape (num_envs, num_joints). When a single environment is selected, a (num_joints,) tensor is also accepted.

• joint_ids (Union[Sequence[int], Tensor, None]) – Joint indices to update. If None, all joints are updated.

• env_ids (Union[Sequence[int], Tensor, None]) – Environment indices to update. If None, all environments are updated.

Return type:

None

set_qpos(qpos, joint_ids=None, env_ids=None, target=True)

Set the joint positions (qpos) or target positions for the articulation.

Parameters:

• qpos (torch.Tensor) – Joint positions with shape (N, dof), where N is the number of environments.

• joint_ids (Sequence[int] | None, optional) – Joint indices to apply the positions. If None, applies to all joints.

• env_ids (Sequence[int] | None) – Environment indices to apply the positions. Defaults to all environments.

• target (bool) – If True, sets target positions for simulation. If False, updates current positions directly.

Raises:

ValueError – If the length of env_ids does not match the length of qpos.

Return type:

None

set_qpos_limits(qpos_limits, joint_ids=None, env_ids=None)

Set joint position limits for selected environments and joints.

Parameters:

• qpos_limits (Tensor) – Joint position limits with shape (num_envs, num_joints, 2). When a single environment is selected, a (num_joints, 2) tensor is also accepted.

• joint_ids (Union[Sequence[int], Tensor, None]) – Joint indices to update. If None, all joints are updated.

• env_ids (Union[Sequence[int], Tensor, None]) – Environment indices to update. If None, all environments are updated.

Return type:

None

set_qvel(qvel, joint_ids=None, env_ids=None, target=True)

Set the velocities (qvel) or target velocities of the articulation.

Parameters:

• qvel (torch.Tensor) – The velocities with shape (N, dof).

• joint_ids (Sequence[int] | None, optional) – Joint indices to apply the velocities. If None, applies to all joints.

• env_ids (Sequence[int] | None, optional) – Environment indices. Defaults to all indices.

• True (If)

• False (sets target positions for simulation. If)

• directly. (updates current positions)

Raises:

ValueError – If the length of env_ids does not match the length of qvel.

Return type:

None

set_qvel_limits(qvel_limits, joint_ids=None, env_ids=None)

Set joint velocity limits for selected environments and joints.

Parameters:

• qvel_limits (Tensor) – Joint velocity limits with shape (num_envs, num_joints). When a single environment is selected, a (num_joints,) tensor is also accepted.

• joint_ids (Union[Sequence[int], Tensor, None]) – Joint indices to update. If None, all joints are updated.

• env_ids (Union[Sequence[int], Tensor, None]) – Environment indices to update. If None, all environments are updated.

Return type:

None

set_self_collision(enable=False, env_ids=None)

Set whether self-collision is enabled for the articulation.

Parameters:

• enable (bool, optional) – Whether to enable self-collision. Defaults to True.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_visual_material(mat, env_ids=None, link_names=None, shared=False)

Set visual material for the rigid object.

Parameters:

• mat (VisualMaterial) – The material to set.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

• link_names (List[str] | None, optional) – List of link names to apply the material to. If None, applies to all links.

• shared (bool, optional) – Whether to share the material instance across links and environments. Defaults to False.

Return type:

None

property user_ids: Tensor

Get the user-defined IDs of the articulation.

Note

The return tensor has shape (num_instances, num_links), where each column corresponds to a link in the articulation.

Returns:

The user-defined IDs of the articulation with shape (num_instances, num_links).

Return type:

torch.Tensor

class embodichain.lab.sim.objects.ArticulationData

Bases: object

GPU data manager for articulation.

Methods:

__init__(entities, ps, device)

Initialize the ArticulationData.

Attributes:

body_link_pose	Get the pose of all links in the articulation.
body_link_vel	Get the velocities of all links in the articulation.
joint_armature	Get the joint armature of the articulation.
joint_damping	Get the joint damping of the articulation.
joint_friction	Get the joint friction of the articulation.
joint_stiffness	Get the joint stiffness of the articulation.
link_vert_face	Get the vertices and faces of all links in the articulation.
qacc	Get the current accelerations (qacc) of the articulation.
qf	Get the current forces (qf) of the articulation.
qf_limits	Get the joint effort limits of the articulation.
qpos	Get the current positions (qpos) of the articulation.
qpos_limits	Get the joint position limits of the articulation.
qvel	Get the current velocities (qvel) of the articulation.
qvel_limits	Get the joint velocity limits of the articulation.
root_ang_vel	Get the angular velocity of the root link of the articulation.
root_lin_vel	Get the linear velocity of the root link of the articulation.
root_pose	Get the root pose of the articulation.
root_vel	Get the velocity of the root link of the articulation.
target_qpos	Get the target positions (target_qpos) of the articulation.
target_qvel	Get the target velocities (target_qvel) of the articulation.

__init__(entities, ps, device)

Initialize the ArticulationData.

Parameters:

• entities (List[_Articulation]) – List of DexSim Articulation objects.

• ps (PhysicsScene) – The physics scene.

• device (torch.device) – The device to use for the articulation data.

property body_link_pose: Tensor

Get the pose of all links in the articulation.

Returns:

The poses of the links in the articulation with shape (N, num_links, 7).

Return type:

torch.Tensor

property body_link_vel: Tensor

Get the velocities of all links in the articulation.

Returns:

The poses of the links in the articulation with shape (N, num_links, 6).

Return type:

torch.Tensor

property joint_armature: Tensor

Get the joint armature of the articulation.

Returns:

The joint armature of the articulation with shape (N, dof).

Return type:

torch.Tensor

property joint_damping: Tensor

Get the joint damping of the articulation.

Returns:

The joint damping of the articulation with shape (N, dof).

Return type:

torch.Tensor

property joint_friction: Tensor

Get the joint friction of the articulation.

Returns:

The joint friction of the articulation with shape (N, dof).

Return type:

torch.Tensor

property joint_stiffness: Tensor

Get the joint stiffness of the articulation.

Returns:

The joint stiffness of the articulation with shape (N, dof).

Return type:

torch.Tensor

property link_vert_face: Dict[str, Tuple[Tensor, Tensor]]

Get the vertices and faces of all links in the articulation.

Returns:

• key (str): The name of the link.

• vertices (torch.Tensor): The vertices of the specified link with shape (V, 3).

• faces (torch.Tensor): The faces of the specified link with shape (F, 3).

Return type:

Dict[str, Tuple[torch.Tensor, torch.Tensor]]

property qacc: Tensor

Get the current accelerations (qacc) of the articulation.

Returns:

The current accelerations of the articulation with shape of (num_instances, dof).

Return type:

torch.Tensor

property qf: Tensor

Get the current forces (qf) of the articulation.

Returns:

The current forces of the articulation with shape of (num_instances, dof).

Return type:

torch.Tensor

property qf_limits: Tensor

Get the joint effort limits of the articulation.

Returns:

The joint effort limits of the articulation with shape (N, dof).

Return type:

torch.Tensor

property qpos: Tensor

Get the current positions (qpos) of the articulation.

Returns:

The current positions of the articulation with shape of (num_instances, dof).

Return type:

torch.Tensor

property qpos_limits: Tensor

Get the joint position limits of the articulation.

Returns:

The joint position limits of the articulation with shape (N, dof, 2).

Return type:

torch.Tensor

property qvel: Tensor

Get the current velocities (qvel) of the articulation.

Returns:

The current velocities of the articulation with shape of (num_instances, dof).

Return type:

torch.Tensor

property qvel_limits: Tensor

Get the joint velocity limits of the articulation.

Returns:

The joint velocity limits of the articulation with shape (N, dof).

Return type:

torch.Tensor

property root_ang_vel: Tensor

Get the angular velocity of the root link of the articulation.

Returns:

The angular velocity of the root link with shape of (num_instances, 3).

Return type:

torch.Tensor

property root_lin_vel: Tensor

Get the linear velocity of the root link of the articulation.

Returns:

The linear velocity of the root link with shape of (num_instances, 3).

Return type:

torch.Tensor

property root_pose: Tensor

Get the root pose of the articulation.

Returns:

The root pose of the articulation with shape of (num_instances, 7).

Return type:

torch.Tensor

property root_vel: Tensor

Get the velocity of the root link of the articulation.

Returns:

The velocity of the root link, concatenating linear and angular velocities.

Return type:

torch.Tensor

property target_qpos: Tensor

Get the target positions (target_qpos) of the articulation.

Returns:

The target positions of the articulation with shape of (num_instances, dof).

Return type:

torch.Tensor

property target_qvel: Tensor

Get the target velocities (target_qvel) of the articulation. :returns: The target velocities of the articulation with shape of (num_instances, dof). :rtype: torch.Tensor

class embodichain.lab.sim.objects.ArticulationCfg

Bases: ObjectBaseCfg

Configuration for an articulation asset in the simulation.

This class extends the base asset configuration to include specific properties for articulations, such as joint drive properties, physical attributes.

Attributes:

attrs	Physical attributes for all links.
body_scale	Scale of the articulation in the simulation world frame.
build_pk_chain	Whether to build pytorch-kinematics chain for forward kinematics and jacobian computation.
compute_uv	Whether to compute the UV mapping for the articulation link.
disable_self_collision	Whether to enable or disable self-collisions.
drive_pros	Properties to define the drive mechanism of a joint.
fix_base	Whether to fix the base of the articulation.
fpath	Path to the articulation asset file.
init_local_pose	4x4 transformation matrix of the root in local frame.
init_pos	Position of the root in simulation world frame.
init_qpos	Initial joint positions of the articulation.
init_rot	Euler angles (in degree) of the root in simulation world frame.
link_attrs	Named per-link physics override groups keyed by regex on link names.
min_position_iters	[1,255].
min_velocity_iters	[0,255].
qpos_limits	Override joint position limits of the articulation.
sleep_threshold	[0, max_float32]
use_usd_properties	Whether to use physical properties from USD file instead of config.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

attrs: RigidBodyAttributesCfg

Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

body_scale: tuple | list

Scale of the articulation in the simulation world frame.

build_pk_chain: bool

Whether to build pytorch-kinematics chain for forward kinematics and jacobian computation.

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

disable_self_collision: bool

Whether to enable or disable self-collisions.

drive_pros: JointDrivePropertiesCfg

Properties to define the drive mechanism of a joint.

fix_base: bool

Whether to fix the base of the articulation.

Set to True for articulations that should not move, such as a fixed base robot arm or a door. Set to False for articulations that should move freely, such as a mobile robot or a humanoid robot.

fpath: str

Path to the articulation asset file.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

ArticulationCfg

init_local_pose: ndarray | None

4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]

Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_qpos: Tensor | ndarray | Sequence[float]

Initial joint positions of the articulation.

If None, the joint positions will be set to zero. If provided, it should be a array of shape (num_joints,).

init_rot: tuple[float, float, float]

Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

min_position_iters: int

[1,255].

Type:

Number of position iterations the solver should perform for this articulation. Range

min_velocity_iters: int

[0,255].

Type:

Number of velocity iterations the solver should perform for this articulation. Range

qpos_limits: Tensor | ndarray | Sequence[float] | Dict[str, List[float]] | None

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_joints, 2), it is applied to all joints in the order of joint_names. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

sleep_threshold: float

[0, max_float32]

Type:

Energy below which the articulation may go to sleep. Range

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values (URDF behavior). Only effective for USD files, ignored for URDF files.

Soft Object

class embodichain.lab.sim.objects.SoftObject

Bases: BatchEntity

SoftObject represents a batch of soft body in the simulation.

Methods:

__init__(cfg[, entities, device])
destroy()	Destroy all entities managed by this batch entity.
get_current_collision_vertices()	Get the current collision vertices of the soft object.
get_current_sim_vertex_velocities()	Get the current sim vertex velocities of the soft object.
get_current_sim_vertices()	Get the current sim vertices of the soft object.
get_local_pose([to_matrix])	Get local pose of the soft object.
get_rest_collision_vertices()	Get the rest collision vertices of the soft object.
get_rest_sim_vertices()	Get the rest sim vertices of the soft object.
get_visual_material_inst([env_ids])	Get the material instance registered for each selected environment.
reset([env_ids])	Reset the entity to its initial state.
restore_visual_material([env_ids])	Restore visual materials captured when the soft object was created.
set_collision_filter(filter_data[, env_ids])	Set collision filter data for the soft object.
set_local_pose(pose[, env_ids])	Set local pose of the soft object.
set_visual_material(mat[, env_ids, shared])	Set visual material for the soft object.

Attributes:

body_data

Get the soft body data manager for this soft object.

__init__(cfg, entities=None, device=device(type='cpu'))

property body_data: SoftBodyData | None

Get the soft body data manager for this soft object.

Returns:

The soft body data manager.

Return type:

SoftBodyData | None

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

get_current_collision_vertices()

Get the current collision vertices of the soft object.

Returns:

The current collision vertices with shape (N, num_collision_vertices, 3).

Return type:

torch.Tensor

get_current_sim_vertex_velocities()

Get the current sim vertex velocities of the soft object.

Returns:

The current sim vertex velocities with shape (N, num_sim_vertices, 3).

Return type:

torch.Tensor

get_current_sim_vertices()

Get the current sim vertices of the soft object.

Returns:

The current sim vertices with shape (N, num_sim_vertices, 3).

Return type:

torch.Tensor

get_local_pose(to_matrix=False)

Get local pose of the soft object.

Parameters:

to_matrix (bool, optional) – If True, return the pose as a 4x4 matrix. If False, return as (x, y, z, qw, qx, qy, qz). Defaults to False.

Returns:

The local pose of the soft object with shape (N, 7) or (N, 4, 4) depending on to_matrix.

Return type:

torch.Tensor

get_rest_collision_vertices()

Get the rest collision vertices of the soft object.

Returns:

The rest collision vertices with shape (N, num_collision_vertices, 3).

Return type:

torch.Tensor

get_rest_sim_vertices()

Get the rest sim vertices of the soft object.

Returns:

The rest sim vertices with shape (N, num_sim_vertices, 3).

Return type:

torch.Tensor

get_visual_material_inst(env_ids=None)

Get the material instance registered for each selected environment.

Parameters:

env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are returned.

Return type:

List[VisualMaterialInst | None]

Returns:

The existing material wrappers, or None where an asset has no material.

reset(env_ids=None)

Reset the entity to its initial state.

Parameters:

env_ids (Sequence[int] | None) – The environment IDs to reset. If None, reset all environments.

Return type:

None

restore_visual_material(env_ids=None)

Restore visual materials captured when the soft object was created.

Parameters:

env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are restored.

Return type:

None

set_collision_filter(filter_data, env_ids=None)

Set collision filter data for the soft object.

Parameters:

• filter_data (torch.Tensor) – [N, 4] of int. First element of each object is arena id. If 2nd element is 0, the object will collision with all other objects in world. 3rd and 4th elements are not used currently.

• env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Return type:

None

set_local_pose(pose, env_ids=None)

Set local pose of the soft object.

Parameters:

• pose (torch.Tensor) – The local pose of the soft object with shape (N, 7) or (N, 4, 4).

• env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Return type:

None

set_visual_material(mat, env_ids=None, shared=False)

Set visual material for the soft object.

Parameters:

• mat (VisualMaterial) – The material template to assign.

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are used.

• shared (bool) – Whether selected environments share one material instance.

Return type:

None

class embodichain.lab.sim.objects.SoftBodyData

Bases: object

Data manager for soft body

Note

1. The pose data managed by dexsim is in the format of (qx, qy, qz, qw, x, y, z), but in EmbodiChain, we use (x, y, z, qw, qx, qy, qz) format.

Methods:

__init__(entities, ps, device)

Initialize the SoftBodyData.

Attributes:

collision_position	Get the current vertex position buffer of the soft bodies.
rest_collision_vertices	Get the rest position buffer of the soft bodies.
rest_sim_vertices	Get the rest sim position buffer of the soft bodies.
sim_vertex_position	Get the current sim vertex position buffer of the soft bodies.
sim_vertex_velocity	Get the current vertex velocity buffer of the soft bodies.

__init__(entities, ps, device)

Initialize the SoftBodyData.

Parameters:

• entities (List[MeshObject]) – List of MeshObjects representing the soft bodies.

• ps (PhysicsScene) – The physics scene.

• device (torch.device) – The device to use for the soft body data.

property collision_position

Get the current vertex position buffer of the soft bodies.

property rest_collision_vertices

Get the rest position buffer of the soft bodies.

property rest_sim_vertices

Get the rest sim position buffer of the soft bodies.

property sim_vertex_position

Get the current sim vertex position buffer of the soft bodies.

property sim_vertex_velocity

Get the current vertex velocity buffer of the soft bodies.

class embodichain.lab.sim.objects.SoftObjectCfg

Bases: ObjectBaseCfg

Configuration for a soft body asset in the simulation.

This class extends the base asset configuration to include specific properties for soft bodies, such as physical attributes and collision group.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

Attributes:

init_local_pose	4x4 transformation matrix of the root in local frame.
init_pos	Position of the root in simulation world frame.
init_rot	Euler angles (in degree) of the root in simulation world frame.
physical_attr	Physical attributes for the soft body.
shape	Mesh configuration for the soft body.
voxel_attr	Tetra mesh voxelization attributes for the soft body.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

ObjectBaseCfg

init_local_pose: ndarray | None

4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]

Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]

Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

physical_attr: SoftbodyPhysicalAttributesCfg

Physical attributes for the soft body.

shape: MeshCfg

Mesh configuration for the soft body.

voxel_attr: SoftbodyVoxelAttributesCfg

Tetra mesh voxelization attributes for the soft body.

Cloth Object

class embodichain.lab.sim.objects.ClothObject

Bases: BatchEntity

ClothObject represents a batch of cloth body in the simulation.

Methods:

__init__(cfg[, entities, device])
destroy()	Destroy all entities managed by this batch entity.
get_current_vertex_position()	Get the current vertex position of the cloth bodies.
get_current_vertex_velocity()	Get the current vertex velocity of the cloth bodies.
get_local_pose([to_matrix])	Get local pose of the cloth object.
get_rest_vertex_position()	Get the rest vertex position of the cloth bodies.
get_visual_material_inst([env_ids])	Get the material instance registered for each selected environment.
reset([env_ids])	Reset the entity to its initial state.
restore_visual_material([env_ids])	Restore visual materials captured when the cloth object was created.
set_collision_filter(filter_data[, env_ids])	Set collision filter data for the cloth object.
set_local_pose(pose[, env_ids])	Set local pose of the cloth object.
set_visual_material(mat[, env_ids, shared])	Set visual material for the cloth object.

Attributes:

body_data

Get the cloth body data manager for this cloth object.

__init__(cfg, entities=None, device=device(type='cpu'))

property body_data: ClothBodyData | None

Get the cloth body data manager for this cloth object.

Returns:

The cloth body data manager.

Return type:

ClothBodyData | None

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

get_current_vertex_position()

Get the current vertex position of the cloth bodies.

Returns:

The current vertex position of the cloth bodies, shape (num_instances, n_vertices, 3).

Return type:

torch.Tensor

get_current_vertex_velocity()

Get the current vertex velocity of the cloth bodies.

Returns:

The current vertex velocity of the cloth bodies, shape (num_instances, n_vertices, 3).

Return type:

torch.Tensor

get_local_pose(to_matrix=False)

Get local pose of the cloth object.

Parameters:

to_matrix (bool, optional) – If True, return the pose as a 4x4 matrix. If False, return as (x, y, z, qw, qx, qy, qz). Defaults to False.

Returns:

The local pose of the cloth object with shape (N, 7) or (N, 4, 4) depending on to_matrix.

Return type:

torch.Tensor

get_rest_vertex_position()

Get the rest vertex position of the cloth bodies.

Returns:

The rest vertex position of the cloth bodies, shape (num_instances, n_vertices, 3).

Return type:

torch.Tensor

get_visual_material_inst(env_ids=None)

Get the material instance registered for each selected environment.

Parameters:

env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are returned.

Return type:

List[VisualMaterialInst | None]

Returns:

The existing material wrappers, or None where an asset has no material.

reset(env_ids=None)

Reset the entity to its initial state.

Parameters:

env_ids (Sequence[int] | None) – The environment IDs to reset. If None, reset all environments.

Return type:

None

restore_visual_material(env_ids=None)

Restore visual materials captured when the cloth object was created.

Parameters:

env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are restored.

Return type:

None

set_collision_filter(filter_data, env_ids=None)

Set collision filter data for the cloth object.

Parameters:

• filter_data (torch.Tensor) – [N, 4] of int. First element of each object is arena id. If 2nd element is 0, the object will collision with all other objects in world. 3rd and 4th elements are not used currently.

• env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Return type:

None

set_local_pose(pose, env_ids=None)

Set local pose of the cloth object.

Parameters:

• pose (torch.Tensor) – The local pose of the cloth object with shape (N, 7) or (N, 4, 4).

• env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Return type:

None

set_visual_material(mat, env_ids=None, shared=False)

Set visual material for the cloth object.

Parameters:

• mat (VisualMaterial) – The material template to assign.

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are used.

• shared (bool) – Whether selected environments share one material instance.

Return type:

None

class embodichain.lab.sim.objects.ClothBodyData

Bases: object

Data manager for cloth.

Note

1. The pose data managed by dexsim is in the format of (qx, qy, qz, qw, x, y, z), but in EmbodiChain, we use (x, y, z, qw, qx, qy, qz) format.

Methods:

__init__(entities, ps, device)

Initialize the ClothBodyData.

Attributes:

rest_vertices	Get the rest position buffer of the cloth bodies.
vertex_position	Get the current vertex position buffer of the cloth bodies.
vertex_velocity	Get the current vertex velocity buffer of the cloth bodies.

__init__(entities, ps, device)

Initialize the ClothBodyData.

Parameters:

• entities (List[MeshObject]) – List of MeshObjects representing the cloth bodies.

• ps (PhysicsScene) – The physics scene.

• device (torch.device) – The device to use for the cloth body data.

property rest_vertices

Get the rest position buffer of the cloth bodies.

property vertex_position

Get the current vertex position buffer of the cloth bodies.

property vertex_velocity

Get the current vertex velocity buffer of the cloth bodies.

class embodichain.lab.sim.objects.ClothObjectCfg

Bases: ObjectBaseCfg

Configuration for a cloth body asset in the simulation.

This class extends the base asset configuration to include specific properties for cloth bodies, such as physical attributes and collision group.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

Attributes:

init_local_pose	4x4 transformation matrix of the root in local frame.
init_pos	Position of the root in simulation world frame.
init_rot	Euler angles (in degree) of the root in simulation world frame.
physical_attr	Physical attributes for the cloth body.
shape	Mesh configuration for the cloth body.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

ObjectBaseCfg

init_local_pose: ndarray | None

4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]

Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]

Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

physical_attr: ClothPhysicalAttributesCfg

Physical attributes for the cloth body.

shape: MeshCfg

Mesh configuration for the cloth body.

Robot

class embodichain.lab.sim.objects.Robot

Bases: Articulation

A class representing a batch of robots in the simulation environment.

Robot is a specific type of articulation that can have additional properties or methods. - control_parts: Specify the parts that can be controlled in a different manner. Different part may have

different joint ids, drive properties, pyhsical attributes, kinematic solvers or motion planners.

• solvers: Specify the kinematic solvers for the robot.

• planners: Specify the motion planner for the robot.

Methods:

__init__(cfg, entities[, device])
apply_render_material_inst(env_idx, ...[, ...])	Swap a dexsim MaterialInst onto a link's render-body segment for the given env.
build_pk_serial_chain()	Build the kinematic serial chain for the robot.
clear_dynamics([env_ids])	Clear the dynamics of the articulation.
compute_batch_fk(qpos, name[, env_ids, ...])	Compute the forward kinematics of the robot given joint positions and optionally a specific part name.
compute_batch_ik(pose, joint_seed, name[, ...])	Compute the inverse kinematics of the robot given joint positions and optionally a specific part name.
compute_fk(qpos[, name, link_names, ...])	Compute the forward kinematics of the robot given joint positions and optionally a specific part name.
compute_ik(pose[, joint_seed, name, ...])	Compute the inverse kinematics of the robot given joint positions and optionally a specific part name.
compute_jacobian(qpos[, end_link_name, ...])	Compute the Jacobian matrix for the given joint positions using the pk_serial_chain.
destroy()	Destroy all entities managed by this batch entity.
get_control_part_base_pose([name, env_ids, ...])	Retrieves the base pose of the control part for a specified robot.
get_control_part_link_names([name])	Get the link names of the control part.
get_existing_visual_material([env_ids, ...])	Build reuse state from materials dexsim parsed onto each link's render body.
get_joint_drive([joint_ids, env_ids])	Get the drive properties for the articulation.
get_joint_ids([name, remove_mimic])	Get the joint ids of the robot for a specific control part.
get_link_names([name])	Get the link names of the robot for a specific control part.
get_link_physical_attr([link_names, env_ids])	Get physical attributes for articulation links.
get_link_pose(link_name[, env_ids, to_matrix])	Get the pose of a specific link in the articulation.
get_link_vert_face(link_name)	Get the vertices and faces of a specific link in the articulation.
get_local_pose([to_matrix])	Get local pose (root link pose) of the articulation.
get_mass([link_names, env_ids])	Get the mass of specific links in the articulation.
get_proprioception()	Gets robot proprioception information, primarily for agent state representation in robot learning scenarios.
get_qf([name])	Get the joint efforts (qf) of the robot.
get_qf_limits([name, env_ids, joint_ids])	Get the joint effort limits (qf) of the robot for a specific control part.
get_qpos([name, target])	Get the joint positions (qpos) of the robot.
get_qpos_limits([name, env_ids, joint_ids])	Get the joint position limits (qpos) of the robot for a specific control part.
get_qvel([name, target])	Get the joint velocities (qvel) of the robot.
get_qvel_limits([name, env_ids, joint_ids])	Get the joint velocity limits (qvel) of the robot for a specific control part.
get_solver([name])	Get the kinematic solver for a specific control part.
get_user_ids([link_name, env_ids])	Get the user ids of the articulation.
get_visual_material_inst([env_ids, link_names])	Get visual material instances for the rigid object.
init_solver(cfg)	Initialize the kinematic solver for the robot.
reallocate_body_data()	Reallocate body data tensors to match the current articulation state in the GPU physics scene.
reset([env_ids])	Reset the entity to its initial state.
restore_visual_material([env_ids, link_names])	Restore visual materials captured when the articulation was created.
set_collision_filter(filter_data[, env_ids])	set collision filter data for the rigid object.
set_fix_base([fix, env_ids])	Set whether the base of the articulation is fixed.
set_joint_drive([stiffness, damping, ...])	Set the drive properties for the robot.
set_link_physical_attr(attrs[, link_names, ...])	Set physical attributes for selected articulation links.
set_local_pose(pose[, env_ids])	Set local pose of the articulation.
set_mass(mass, link_names[, env_ids])	Set the mass of specific links in the articulation.
set_physical_visible([visible, ...])	set collision of the robot or a specific control part.
set_qf(qf[, joint_ids, env_ids, name])	Set the joint efforts (qf) for the articulation.
set_qf_limits(qf_limits[, name, env_ids, ...])	Set the joint effort limits (qf) of the robot.
set_qpos(qpos[, joint_ids, env_ids, target, ...])	Set the joint positions (qpos) or target positions for the articulation.
set_qpos_limits(qpos_limits[, name, ...])	Set the joint position limits (qpos) of the robot.
set_qvel(qvel[, joint_ids, env_ids, target, ...])	Set the joint velocities (qvel) or target velocities for the articulation.
set_qvel_limits(qvel_limits[, name, ...])	Set the joint velocity limits (qvel) of the robot.
set_self_collision([enable, env_ids])	Set whether self-collision is enabled for the articulation.
set_visual_material(mat[, env_ids, ...])	Set visual material for the rigid object.

Attributes:

active_dof	Get the number of active degrees of freedom of the articulation.
active_joint_names	Get the names of the active joints in the articulation.
all_joint_names	Get the names of the joints in the articulation.
body_data	Get the rigid body data manager for this rigid object.
body_state	Get the body state of the articulation.
control_parts	Get the control parts of the robot.
dof	Get the degree of freedom of the articulation.
joint_names	Get the names of the joints in the articulation.
link_names	Get the names of the links in the articulation.
mimic_ids	Get the mimic joint ids for the articulation.
mimic_multipliers	Get the mimic joint multipliers for the articulation.
mimic_offsets	Get the mimic joint offsets for the articulation.
mimic_parents	Get the mimic joint parent ids for the articulation.
num_links	Get the number of links in the articulation.
root_link_name	Get the name of the root link of the articulation.
root_state	Get the root state of the articulation.
user_ids	Get the user-defined IDs of the articulation.

__init__(cfg, entities, device=device(type='cpu'))

property active_dof: int

Get the number of active degrees of freedom of the articulation.

Returns:

The number of active degrees of freedom of the articulation.

Return type:

int

property active_joint_names: List[str]

Get the names of the active joints in the articulation.

Returns:

The names of the active joints in the articulation.

Return type:

List[str]

property all_joint_names: List[str]

Get the names of the joints in the articulation.

Returns:

The names of the joints in the articulation.

Return type:

List[str]

apply_render_material_inst(env_idx, mat_inst, link_name, mesh_id=0)

Swap a dexsim MaterialInst onto a link’s render-body segment for the given env.

Parameters:

• env_idx (int) – Environment index.

• mat_inst (MaterialInst) – dexsim MaterialInst to attach.

• link_name (str) – Link whose render body receives the material.

• mesh_id (int) – Render-body segment index.

Return type:

None

property body_data: ArticulationData

Get the rigid body data manager for this rigid object.

Returns:

The rigid body data manager.

Return type:

RigidBodyData

property body_state: Tensor

Get the body state of the articulation.

Returns:

The body state of the articulation with shape (N, num_links, 13).

Return type:

torch.Tensor

build_pk_serial_chain()

Build the kinematic serial chain for the robot.

Return type:

None

This method is mainly used for robot learning scenarios, for example:

• Imitation learning dataset generation.

clear_dynamics(env_ids=None)

Clear the dynamics of the articulation.

Parameters:

env_ids (Sequence[int] | None) – Environment indices. If None, then all indices are used.

Return type:

None

compute_batch_fk(qpos, name, env_ids=None, to_matrix=False)

Compute the forward kinematics of the robot given joint positions and optionally a specific part name. The output pose will be in the local arena frame.

Parameters:

• qpos (torch.Tensor | np.ndarray | None) – Joint positions of the robot, (n_envs, n_batch, num_joints).

• name (str | None) – The name of the control part to compute the FK for. If None, the default part is used.

• env_ids (Sequence[int] | None) – The environment ids to compute the FK for. If None, all environments are used.

• to_matrix (bool) – If True, returns the transformation in the form of a 4x4 matrix.

Returns:

The forward kinematics result with shape (n_envs, batch, 7) or (n_envs, batch, 4, 4) if to_matrix is True.

Return type:

torch.Tensor

compute_batch_ik(pose, joint_seed, name, env_ids=None)

Compute the inverse kinematics of the robot given joint positions and optionally a specific part name. The input pose should be in the local arena frame.

Parameters:

• pose (torch.Tensor) – The end effector pose of the robot, (n_envs, n_batch, 7) or (n_envs, n_batch, 4, 4).

• joint_seed (torch.Tensor | None) – The joint positions to use as a seed for the IK computation, (n_envs, n_batch, dof). If None, the zero joint positions will be used as the seed.

• name (str | None) – The name of the control part to compute the IK for. If None, the default part is used.

• env_ids (Sequence[int] | None) – Environment indices to apply the positions. Defaults to all environments.

Returns:

Success Tensor with shape (n_envs, n_batch) Qpos Tensor with shape (n_envs, n_batch, dof).

Return type:

Tuple[torch.Tensor, torch.Tensor]

compute_fk(qpos, name=None, link_names=None, end_link_name=None, root_link_name=None, env_ids=None, to_matrix=False)

Compute the forward kinematics of the robot given joint positions and optionally a specific part name. The output pose will be in the local arena frame.

Parameters:

• qpos (torch.Tensor | np.ndarray | None) – Joint positions of the robot, (n_envs, num_joints).

• name (str | None) – The name of the control part to compute the FK for. If None, the default part is used.

• link_names (List[str] | None) – The names of the links to compute the FK for. If None, all links are used.

• end_link_name (str | None) – The name of the end link to compute the FK for. If None, the default end link is used.

• root_link_name (str | None) – The name of the root link to compute the FK for. If None, the default root link is used.

• env_ids (Sequence[int] | None) – The environment ids to compute the FK for. If None, all environments are used.

• to_matrix (bool) – If True, returns the transformation in the form of a 4x4 matrix.

Returns:

The forward kinematics result with shape (n_envs, 7) or (n_envs, 4, 4) if to_matrix is True.

Return type:

torch.Tensor

compute_ik(pose, joint_seed=None, name=None, env_ids=None, return_all_solutions=False)

Compute the inverse kinematics of the robot given joint positions and optionally a specific part name. The input pose should be in the local arena frame.

Parameters:

• pose (torch.Tensor) – The end effector pose of the robot, (n_envs, 7) or (n_envs, 4, 4).

• joint_seed (torch.Tensor | None) – The joint positions to use as a seed for the IK computation, (n_envs, dof). If None, the zero joint positions will be used as the seed.

• name (str | None) – The name of the control part to compute the IK for. If None, the default part is used.

• env_ids (Sequence[int] | None) – Environment indices to apply the positions. Defaults to all environments.

• return_all_solutions (bool) – Whether to return all IK solutions or just the best one. Defaults to False.

Returns:

The success Tensor with shape (n_envs, ) and qpos Tensor with shape (n_envs, max_results, dof), or None if solver not found.

Return type:

Tuple[torch.Tensor, torch.Tensor] | None

compute_jacobian(qpos, end_link_name=None, root_link_name=None, locations=None, jac_type='full')

Compute the Jacobian matrix for the given joint positions using the pk_serial_chain.

Parameters:

• qpos (torch.Tensor) – The joint positions. Shape can be (dof,) for a single configuration or (batch_size, dof) for batched configurations.

• end_link_name (str, optional) – The name of the end link for which the Jacobian is computed. Defaults to the last link in the chain.

• root_link_name (str, optional) – The name of the root link for which the Jacobian is computed. Defaults to the first link in the chain.

• locations (torch.Tensor | np.ndarray, optional) – Offset points relative to the end-effector frame for which the Jacobian is computed. Shape can be (batch_size, 3) or (3,) for a single offset. Defaults to None (origin of the end-effector frame).

• jac_type (str, optional) – Specifies the part of the Jacobian to return: - ‘full’: Returns the full Jacobian (6, dof) or (batch_size, 6, dof). - ‘trans’: Returns only the translational part (3, dof) or (batch_size, 3, dof). - ‘rot’: Returns only the rotational part (3, dof) or (batch_size, 3, dof). Defaults to ‘full’.

Raises:

• RuntimeError – If the pk_chain is not initialized.

• ValueError – If an invalid jac_type is provided.

Returns:

The Jacobian matrix. Shape depends on the input:

• For a single link: (6, dof) or (batch_size, 6, dof).

• For multiple links: (num_links, 6, dof) or (num_links, batch_size, 6, dof).

The shape also depends on the jac_type parameter.

Return type:

torch.Tensor

property control_parts: Dict[str, List[str]] | None

Get the control parts of the robot.

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

property dof: int

Get the degree of freedom of the articulation.

Returns:

The degree of freedom of the articulation.

Return type:

int

get_control_part_base_pose(name=None, env_ids=None, to_matrix=False)

Retrieves the base pose of the control part for a specified robot.

Parameters:

• name (str | None) – The name of the control part the solver adhere to. If None, the default solver is used.

• env_ids (Sequence[int] | None) – A sequence of environment IDs to specify the environments. If None, all indices are used.

• to_matrix (bool) – If True, returns the pose in the form of a 4x4 matrix.

Return type:

Tensor

Returns:

The pose of the specified link in the form of a matrix.

get_control_part_link_names(name=None)

Get the link names of the control part.

Parameters:

name (str | None) – The name of the control part. If None, return all link names.

Returns:

link names of the control part.

Return type:

List[str]

get_existing_visual_material(env_ids=None, link_names=None, shared=False)

Build reuse state from materials dexsim parsed onto each link’s render body.

Each segment keeps its original material for restoration. Segments on the same link share one working material so randomized property updates happen once per link instead of once per mesh segment.

Parameters:

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are used.

• link_names (Optional[List[str]]) – Links to include. If None, all links are used.

• shared (bool) – If True, build state for the first env only.

Return type:

List[Dict[str, List[ReuseSegmentState]]]

Returns:

Per-env dict mapping link name to per-segment ReuseSegmentState.

Raises:

ValueError – If a link/segment has no material or no retrievable template.

get_joint_drive(joint_ids=None, env_ids=None)

Get the drive properties for the articulation.

Parameters:

• joint_ids (Sequence[int] | None, optional) – The joint indices to get the drive properties for. If None, gets for all joints. Defaults to None.

• env_ids (Sequence[int] | None, optional) – The environment indices to get the drive properties for. If None, gets for all environments. Defaults to None.

Returns:

A tuple containing the stiffness, damping, max_effort,

max_velocity, friction, and armature tensors with shape (N, len(joint_ids)) for the specified environments.

Return type:

Tuple[torch.Tensor, …]

get_joint_ids(name=None, remove_mimic=False)

Get the joint ids of the robot for a specific control part.

Parameters:

• name (str | None) – The name of the control part to get the joint ids for. If None, the default part is used.

• remove_mimic (bool, optional) – If True, mimic joints will be excluded from the returned joint ids. Defaults to False.

Returns:

The joint ids of the robot for the specified control part.

Return type:

List[int]

get_link_names(name=None)

Get the link names of the robot for a specific control part.

If no control part is specified, return all link names.

Parameters:

name (str, optional) – The name of the control part to get the link names for. If None, the default part is used.

Returns:

The link names of the robot for the specified control part.

Return type:

List[str]

get_link_physical_attr(link_names=None, env_ids=None)

Get physical attributes for articulation links.

Parameters:

• link_names (Union[str, Sequence[str], None]) – Link names or regex patterns. If None, all links are returned.

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, only env 0 is queried.

Return type:

list[PhysicalAttr]

Returns:

List of PhysicalAttr, one per (env, link) pair in row-major order (env-major).

get_link_pose(link_name, env_ids=None, to_matrix=False)

Get the pose of a specific link in the articulation.

Parameters:

• link_name (str) – The name of the link.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

• to_matrix (bool, optional) – If True, return the pose as a 4x4 matrix. If False, return as (x, y, z, qw, qx, qy, qz). Defaults to False.

Returns:

The pose of the specified link with shape (N, 7) or (N, 4, 4) depending on to_matrix.

Return type:

torch.Tensor

get_link_vert_face(link_name)

Get the vertices and faces of a specific link in the articulation.

Parameters:

link_name (str) – The name of the link.

Returns:

• vertices (torch.Tensor): The vertices of the specified link with shape (V, 3).

• faces (torch.Tensor): The faces of the specified link with shape (F, 3).

Return type:

Tuple[torch.Tensor, torch.Tensor]

get_local_pose(to_matrix=False)

Get local pose (root link pose) of the articulation.

Parameters:

to_matrix (bool, optional) – If True, return the pose as a 4x4 matrix. If False, return as (x, y, z, qw, qx, qy, qz). Defaults to False.

Returns:

The local pose of the articulation with shape (N, 7) or (N, 4, 4) depending on to_matrix.

Return type:

torch.Tensor

get_mass(link_names=None, env_ids=None)

Get the mass of specific links in the articulation.

Parameters:

• link_names (Sequence[str] | None, optional) – The names of the links to get the mass for. If None, gets mass for all links. Defaults to None.

• env_ids (Sequence[int] | None, optional) – Environment indices to get the mass from. If None, gets from all environments. Defaults to None.

Returns:

The mass of the specified links with shape (N, len(link_names)).

Return type:

torch.Tensor

get_proprioception()

Gets robot proprioception information, primarily for agent state representation in robot learning scenarios.

The default proprioception information includes:

• qpos: Joint positions.

• qvel: Joint velocities.

• qf: Joint efforts.

Returns:

A dictionary containing the robot’s proprioception information

Return type:

Dict[str, torch.Tensor]

get_qf(name=None)

Get the joint efforts (qf) of the robot.

Parameters:

name (str | None) – The name of the control part to get the qf for. If None, the default part is used.

Returns:

Joint efforts with shape (N, dof), where N is the number of environments.

Return type:

torch.Tensor

get_qf_limits(name=None, env_ids=None, *, joint_ids=None)

Get the joint effort limits (qf) of the robot for a specific control part.

It returns all joint effort limits if no control part is specified.

Parameters:

• name (str | None) – The name of the control part to get the qf limits for.

• env_ids (Sequence[int] | torch.Tensor | None) – The environment ids to get the qf limits for. If None, all environments are used.

• joint_ids (Sequence[int] | torch.Tensor | None) – Joint indices to get the qf limits for. Must be passed as a keyword argument.

Returns:

Joint effort limits with shape (N, dof), where N is the number of environments.

Return type:

torch.Tensor

get_qpos(name=None, target=False)

Get the joint positions (qpos) of the robot.

Parameters:

• name (str | None) – The name of the control part to get the qpos for. If None, the default part is used.

• target (bool) – If True, gets target positions for simulation. If False, gets current positions. The default is False.

Returns:

Joint positions with shape (N, dof), where N is the number of environments.

Return type:

torch.Tensor

get_qpos_limits(name=None, env_ids=None, *, joint_ids=None)

Get the joint position limits (qpos) of the robot for a specific control part.

It returns all joint position limits if no control part is specified.

Parameters:

• name (str | None) – The name of the control part to get the qpos limits for.

• env_ids (Sequence[int] | torch.Tensor | None) – The environment ids to get the qpos limits for. If None, all environments are used.

• joint_ids (Sequence[int] | torch.Tensor | None) – Joint indices to get the qpos limits for. Must be passed as a keyword argument.

Returns:

Joint position limits with shape (N, dof, 2), where N is the number of environments.

Return type:

torch.Tensor

get_qvel(name=None, target=False)

Get the joint velocities (qvel) of the robot.

Parameters:

• name (str | None) – The name of the control part to get the qvel for. If None, the default part is used.

• target (bool) – If True, gets target velocities for simulation. If False, gets current velocities. The default is False.

Returns:

Joint velocities with shape (N, dof), where N is the number of environments.

Return type:

torch.Tensor

get_qvel_limits(name=None, env_ids=None, *, joint_ids=None)

Get the joint velocity limits (qvel) of the robot for a specific control part.

It returns all joint velocity limits if no control part is specified.

Parameters:

• name (str | None) – The name of the control part to get the qvel limits for.

• env_ids (Sequence[int] | torch.Tensor | None) – The environment ids to get the qvel limits for. If None, all environments are used.

• joint_ids (Sequence[int] | torch.Tensor | None) – Joint indices to get the qvel limits for. Must be passed as a keyword argument.

Returns:

Joint velocity limits with shape (N, dof), where N is the number of environments.

Return type:

torch.Tensor

get_solver(name=None)

Get the kinematic solver for a specific control part.

Parameters:

name (str | None) – The name of the control part to get the solver for. If None, the default part is used.

Returns:

The kinematic solver for the specified control part, or None if not found.

Return type:

BaseSolver | None

get_user_ids(link_name=None, env_ids=None)

Get the user ids of the articulation.

Parameters:

• link_name (str | None) – (str | None): The name of the link. If None, returns user ids for all links.

• env_ids (Optional[Sequence[int]]) – (Sequence[int] | None): Environment indices. If None, then all indices are used.

Returns:

The user ids of the articulation with shape (N, 1) for given link_name or (N, num_links) if link_name is None.

Return type:

torch.Tensor

get_visual_material_inst(env_ids=None, link_names=None)

Get visual material instances for the rigid object.

Parameters:

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

• link_names (List[str] | None, optional) – List of link names to filter materials. If None, returns materials for all links.

Returns:

A list where each element corresponds to an environment and contains a dictionary mapping link names to their VisualMaterialInst.

Return type:

List[Dict[str, VisualMaterialInst]]

init_solver(cfg)

Initialize the kinematic solver for the robot.

Parameters:

cfg (SolverCfg | Dict[str, SolverCfg]) – The configuration for the kinematic solver.

Return type:

None

property joint_names: List[str]

Get the names of the joints in the articulation.

Returns:

The names of the actived joints in the articulation.

Return type:

List[str]

property link_names: List[str]

Get the names of the links in the articulation.

Returns:

The names of the links in the articulation.

Return type:

List[str]

property mimic_ids: List[int | None]

Get the mimic joint ids for the articulation.

Returns:

The mimic joint ids.

Return type:

List[int | None]

property mimic_multipliers: List[float]

Get the mimic joint multipliers for the articulation.

Returns:

The mimic joint multipliers.

Return type:

List[float]

property mimic_offsets: List[float]

Get the mimic joint offsets for the articulation.

Returns:

The mimic joint offsets.

Return type:

List[float]

property mimic_parents: List[int | None]

Get the mimic joint parent ids for the articulation.

Returns:

The mimic joint parent ids.

Return type:

List[int | None]

property num_links: int

Get the number of links in the articulation.

Returns:

The number of links in the articulation.

Return type:

int

reallocate_body_data()

Reallocate body data tensors to match the current articulation state in the GPU physics scene.

Return type:

None

reset(env_ids=None)

Reset the entity to its initial state.

Parameters:

env_ids (Sequence[int] | None) – The environment IDs to reset. If None, reset all environments.

Return type:

None

restore_visual_material(env_ids=None, link_names=None)

Restore visual materials captured when the articulation was created.

Parameters:

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, all instances are restored.

• link_names (Optional[List[str]]) – Links to restore. If None, all links are restored.

Return type:

None

property root_link_name: str

Get the name of the root link of the articulation.

Returns:

The name of the root link.

Return type:

str

property root_state: Tensor

Get the root state of the articulation.

Returns:

The root state of the articulation with shape (N, 13).

Return type:

torch.Tensor

set_collision_filter(filter_data, env_ids=None)

set collision filter data for the rigid object.

Parameters:

• filter_data (torch.Tensor) – [N, 4] of int. First element of each object is arena id. If 2nd element is 0, the object will collision with all other objects in world. 3rd and 4th elements are not used currently.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used. Defaults to None.

Return type:

None

set_fix_base(fix=True, env_ids=None)

Set whether the base of the articulation is fixed.

Parameters:

• fix (bool, optional) – Whether to fix the base. Defaults to True.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_joint_drive(stiffness=None, damping=None, max_effort=None, max_velocity=None, friction=None, armature=None, drive_type='force', joint_ids=None, env_ids=None)

Set the drive properties for the robot.

Different from Articulation, default drive type is ‘force’ instead of ‘none’

Parameters:

• stiffness (torch.Tensor) – The stiffness of the joint drive with shape (len(env_ids), len(joint_ids)).

• damping (torch.Tensor) – The damping of the joint drive with shape (len(env_ids), len(joint_ids)).

• max_effort (torch.Tensor) – The maximum effort of the joint drive with shape (len(env_ids), len(joint_ids)).

• max_velocity (torch.Tensor) – The maximum velocity of the joint drive with shape (len(env_ids), len(joint_ids)).

• friction (torch.Tensor) – The joint friction coefficient with shape (len(env_ids), len(joint_ids)).

• armature (torch.Tensor) – The joint armature with shape (len(env_ids), len(joint_ids)).

• drive_type (str, optional) – The type of drive to apply. Defaults to “force”.

• joint_ids (Sequence[int] | None, optional) – The joint indices to apply the drive to. If None, applies to all joints. Defaults to None.

• env_ids (Sequence[int] | None, optional) – The environment indices to apply the drive to. If None, applies to all environments. Defaults to None.

Return type:

None

set_link_physical_attr(attrs, link_names=None, env_ids=None, *, base_attrs=None, replace_inertial=False)

Set physical attributes for selected articulation links.

Parameters:

• attrs (RigidBodyAttributesCfg | RigidBodyAttributesOverrideCfg | PhysicalAttr) – Full, partial, or DexSim physical attributes to apply.

• link_names (Union[str, Sequence[str], None]) – Link names or regex patterns. If None, all links are updated.

• env_ids (Optional[Sequence[int]]) – Environment indices. If None, all environments are updated.

• base_attrs (RigidBodyAttributesCfg | None) – Base config used when attrs is a partial override.

• replace_inertial (bool) – Recompute inertia when mass changes.

Return type:

None

set_local_pose(pose, env_ids=None)

Set local pose of the articulation.

Parameters:

• pose (torch.Tensor) – The local pose of the articulation with shape (N, 7) or (N, 4, 4).

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_mass(mass, link_names, env_ids=None)

Set the mass of specific links in the articulation.

Parameters:

• mass (torch.Tensor) – The mass values to set with shape (N, len(link_names)).

• link_names (Sequence[str]) – The names of the links to set the mass for.

• env_ids (Sequence[int] | None, optional) – Environment indices to apply the mass change. If None, applies to all environments. Defaults to None.

Return type:

None

set_physical_visible(visible=True, control_part=None, rgba=None)

set collision of the robot or a specific control part.

Parameters:

• visible (bool, optional) – is collision body visible. Defaults to True.

• control_part (str | None, optional) – control part to set visibility. Defaults to None. If None, all links are set.

• rgba (Sequence[float] | None, optional) – collision body visible rgba. It will be defined at the first time the function is called. Defaults to None.

set_qf(qf, joint_ids=None, env_ids=None, name=None)

Set the joint efforts (qf) for the articulation.

Parameters:

• qf (torch.Tensor) – Joint efforts with shape (N, dof), where N is the number of environments.

• joint_ids (Sequence[int] | None, optional) – Joint indices to apply the efforts. If None, applies to all joints.

• env_ids (Sequence[int] | None) – Environment indices to apply the efforts. Defaults to all environments.

• name (str | None) – The name of the control part to set the qf for. If None, the default part is used.

Raises:

ValueError – If the length of env_ids does not match the length of qf.

Return type:

None

set_qf_limits(qf_limits, name=None, env_ids=None, *, joint_ids=None)

Set the joint effort limits (qf) of the robot.

Parameters:

• qf_limits (Tensor) – Joint effort limits with shape (N, num_joints).

• name (str | None) – The name of the control part to set the qf limits for.

• env_ids (Sequence[int] | torch.Tensor | None) – The environment ids to set the qf limits for.

• joint_ids (Sequence[int] | torch.Tensor | None) – Joint indices to set the qf limits for. Must be passed as a keyword argument; ignored when name is provided.

Return type:

None

set_qpos(qpos, joint_ids=None, env_ids=None, target=True, name=None)

Set the joint positions (qpos) or target positions for the articulation.

Parameters:

• qpos (torch.Tensor) – Joint positions with shape (N, dof), where N is the number of environments.

• joint_ids (Sequence[int] | None, optional) – Joint indices to apply the positions. If None, applies to all joints.

• env_ids (Sequence[int] | None) – Environment indices to apply the positions. Defaults to all environments.

• target (bool) – If True, sets target positions for simulation. If False, updates current positions directly.

• name (str | None) – The name of the control part to set the qpos for. If None, the default part is used.

Raises:

ValueError – If the length of env_ids does not match the length of qpos.

Return type:

None

set_qpos_limits(qpos_limits, name=None, env_ids=None, *, joint_ids=None)

Set the joint position limits (qpos) of the robot.

Parameters:

• qpos_limits (Tensor) – Joint position limits with shape (N, num_joints, 2).

• name (str | None) – The name of the control part to set the qpos limits for.

• env_ids (Sequence[int] | torch.Tensor | None) – The environment ids to set the qpos limits for.

• joint_ids (Sequence[int] | torch.Tensor | None) – Joint indices to set the qpos limits for. Must be passed as a keyword argument; ignored when name is provided.

Return type:

None

set_qvel(qvel, joint_ids=None, env_ids=None, target=True, name=None)

Set the joint velocities (qvel) or target velocities for the articulation.

Parameters:

• qvel (torch.Tensor) – Joint velocities with shape (N, dof), where N is the number of environments.

• joint_ids (Sequence[int] | None, optional) – Joint indices to apply the velocities. If None, applies to all joints.

• env_ids (Sequence[int] | None) – Environment indices to apply the velocities. Defaults to all environments.

• target (bool) – If True, sets target velocities for simulation. If False, updates current velocities directly.

• name (str | None) – The name of the control part to set the qvel for. If None, the default part is used.

Raises:

ValueError – If the length of env_ids does not match the length of qvel.

Return type:

None

set_qvel_limits(qvel_limits, name=None, env_ids=None, *, joint_ids=None)

Set the joint velocity limits (qvel) of the robot.

Parameters:

• qvel_limits (Tensor) – Joint velocity limits with shape (N, num_joints).

• name (str | None) – The name of the control part to set the qvel limits for.

• env_ids (Sequence[int] | torch.Tensor | None) – The environment ids to set the qvel limits for.

• joint_ids (Sequence[int] | torch.Tensor | None) – Joint indices to set the qvel limits for. Must be passed as a keyword argument; ignored when name is provided.

Return type:

None

set_self_collision(enable=False, env_ids=None)

Set whether self-collision is enabled for the articulation.

Parameters:

• enable (bool, optional) – Whether to enable self-collision. Defaults to True.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

Return type:

None

set_visual_material(mat, env_ids=None, link_names=None, shared=False)

Set visual material for the rigid object.

Parameters:

• mat (VisualMaterial) – The material to set.

• env_ids (Sequence[int] | None, optional) – Environment indices. If None, then all indices are used.

• link_names (List[str] | None, optional) – List of link names to apply the material to. If None, applies to all links.

• shared (bool, optional) – Whether to share the material instance across links and environments. Defaults to False.

Return type:

None

property user_ids: Tensor

Get the user-defined IDs of the articulation.

Note

The return tensor has shape (num_instances, num_links), where each column corresponds to a link in the articulation.

Returns:

The user-defined IDs of the articulation with shape (num_instances, num_links).

Return type:

torch.Tensor

class embodichain.lab.sim.objects.RobotCfg

Bases: ArticulationCfg

RobotCfg(uid: ‘str | None’ = <factory>, init_pos: ‘tuple[float, float, float]’ = <factory>, init_rot: ‘tuple[float, float, float]’ = <factory>, init_local_pose: ‘np.ndarray | None’ = <factory>, fpath: ‘str’ = <factory>, drive_pros: ‘JointDrivePropertiesCfg’ = <factory>, body_scale: ‘tuple | list’ = <factory>, attrs: ‘RigidBodyAttributesCfg’ = <factory>, link_attrs: ‘dict[str, LinkPhysicsOverrideCfg] | None’ = <factory>, fix_base: ‘bool’ = <factory>, disable_self_collision: ‘bool’ = <factory>, init_qpos: ‘torch.Tensor | np.ndarray | Sequence[float]’ = <factory>, qpos_limits: ‘torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None’ = <factory>, sleep_threshold: ‘float’ = <factory>, min_position_iters: ‘int’ = <factory>, min_velocity_iters: ‘int’ = <factory>, build_pk_chain: ‘bool’ = <factory>, compute_uv: ‘bool’ = <factory>, use_usd_properties: ‘bool’ = <factory>, control_parts: ‘Dict[str, List[str]] | None’ = <factory>, urdf_cfg: ‘URDFCfg | None’ = <factory>, solver_cfg: ‘SolverCfg | Dict[str, SolverCfg] | None’ = <factory>)

Classes:

SolverCfg

Configuration for the kinematic solver used in the robot simulation.

Attributes:

attrs	Physical attributes for all links.
body_scale	Scale of the articulation in the simulation world frame.
build_pk_chain	Whether to build pytorch-kinematics chain for forward kinematics and jacobian computation.
compute_uv	Whether to compute the UV mapping for the articulation link.
control_parts	Control parts is the mapping from part name to joint names.
disable_self_collision	Whether to enable or disable self-collisions.
drive_pros	Properties to define the drive mechanism of a joint.
fix_base	Whether to fix the base of the articulation.
fpath	Path to the articulation asset file.
init_local_pose	4x4 transformation matrix of the root in local frame.
init_pos	Position of the root in simulation world frame.
init_qpos	Initial joint positions of the articulation.
init_rot	Euler angles (in degree) of the root in simulation world frame.
link_attrs	Named per-link physics override groups keyed by regex on link names.
min_position_iters	[1,255].
min_velocity_iters	[0,255].
qpos_limits	Override joint position limits of the articulation.
sleep_threshold	[0, max_float32]
solver_cfg	Solver is used to compute forward and inverse kinematics for the robot.
urdf_cfg	URDF assembly configuration which allows for assembling a robot from multiple URDF components.
use_usd_properties	Whether to use physical properties from USD file instead of config.

Methods:

build_pk_serial_chain([device])	Build the serial chain from the URDF file.
from_dict(init_dict)	Initialize the configuration from a dictionary.
save_to_file(filepath)	Save config to a local file as JSON.
to_string()	Return config as a JSON string.

class SolverCfg

Bases: object

Configuration for the kinematic solver used in the robot simulation.

Attributes:

class_type	The class type of the solver to be used.
end_link_name	The name of the end-effector link for the solver.
ik_nearest_weight	Weights for the inverse kinematics nearest calculation.
joint_names	List of joint names for the solver.
root_link_name	The name of the root/base link for the solver.
tcp	The tool center point (TCP) position as a 4x4 homogeneous matrix.
urdf_path	The file path to the URDF model of the robot.
user_qpos_limits	User defined Joint position limits [2, DOF] for the solver.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

class_type: str

The class type of the solver to be used.

end_link_name: str

The name of the end-effector link for the solver.

This defines the target link for forward/inverse kinematics calculations. Must match a link name in the URDF file.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

SolverCfg

ik_nearest_weight: List[float] | None

Weights for the inverse kinematics nearest calculation.

The weights influence how the solver prioritizes closeness to the seed position when multiple solutions are available.

joint_names: list[str] | None

List of joint names for the solver.

If None, all joints in the URDF will be used. If specified, only these named joints will be included in the kinematic chain.

root_link_name: str

The name of the root/base link for the solver.

This defines the starting point of the kinematic chain. Must match a link name in the URDF file.

tcp: Tensor | ndarray

The tool center point (TCP) position as a 4x4 homogeneous matrix.

This represents the position and orientation of the tool in the robot’s end-effector frame.

urdf_path: str | None

The file path to the URDF model of the robot.

user_qpos_limits: List[float] | None

User defined Joint position limits [2, DOF] for the solver. If not provided (None), this value will replace by joint limits defined in urdf when solver init from robot. If provided, the solver will use the intersection of user defined limits and urdf limits as the final joint limits.

attrs: RigidBodyAttributesCfg

Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

body_scale: tuple | list

Scale of the articulation in the simulation world frame.

build_pk_chain: bool

Whether to build pytorch-kinematics chain for forward kinematics and jacobian computation.

build_pk_serial_chain(device=device(type='cpu'), **kwargs)

Build the serial chain from the URDF file.

Note

This method is usually used in imitation dataset saving (compute eef pose from qpos using FK) and model training (provide a differentiable FK layer or loss computation).

Parameters:

• device (torch.device) – The device to which the chain will be moved. Defaults to CPU.

• **kwargs – Additional arguments for building the serial chain.

Returns:

The serial chain of the robot for specified control part.

Return type:

Dict[str, pk.SerialChain]

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

control_parts: Dict[str, List[str]] | None

Control parts is the mapping from part name to joint names.

For example, {‘left_arm’: [‘joint1’, ‘joint2’], ‘right_arm’: [‘joint3’, ‘joint4’]} If no control part is specified, the robot will use all joints as a single control part.

Note

• if control_parts is specified, solver_cfg must be a dict with part names as

  keys corresponding to the control parts name.

• The joint names in the control parts support regular expressions, e.g., ‘joint[1-6]’.

  After initialization of robot, the names will be expanded to a list of full joint names.

• Robot is a derived class of Articulation, with control parts support. So the drive_pros

  in ArticulationCfg can use control part as key to specify the corresponding joint drive properties, which will be overridden if these joint names are already specified.

disable_self_collision: bool

Whether to enable or disable self-collisions.

drive_pros: JointDrivePropertiesCfg

Properties to define the drive mechanism of a joint.

fix_base: bool

Whether to fix the base of the articulation.

Set to True for articulations that should not move, such as a fixed base robot arm or a door. Set to False for articulations that should move freely, such as a mobile robot or a humanoid robot.

fpath: str

Path to the articulation asset file.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

RobotCfg

init_local_pose: np.ndarray | None

4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]

Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_qpos: torch.Tensor | np.ndarray | Sequence[float]

Initial joint positions of the articulation.

If None, the joint positions will be set to zero. If provided, it should be a array of shape (num_joints,).

init_rot: tuple[float, float, float]

Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

min_position_iters: int

[1,255].

Type:

Number of position iterations the solver should perform for this articulation. Range

min_velocity_iters: int

[0,255].

Type:

Number of velocity iterations the solver should perform for this articulation. Range

qpos_limits: torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_joints, 2), it is applied to all joints in the order of joint_names. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

save_to_file(filepath)

Save config to a local file as JSON.

sleep_threshold: float

[0, max_float32]

Type:

Energy below which the articulation may go to sleep. Range

solver_cfg: SolverCfg | Dict[str, SolverCfg] | None

Solver is used to compute forward and inverse kinematics for the robot.

to_string()

Return config as a JSON string.

urdf_cfg: URDFCfg | None

URDF assembly configuration which allows for assembling a robot from multiple URDF components.

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values (URDF behavior). Only effective for USD files, ignored for URDF files.