embodichain.lab.sim.objects

embodichain.lab.sim.objects#

Scene-object classes spawned into the SimulationManager.

Covers lights, rigid bodies (and groups), articulations, robots, deformables (soft/cloth), gizmos, and rigid constraints; every object derives from BatchEntity.

Overview#

Scene-object classes spawned into the SimulationManager. Every object derives from BatchEntity and pairs a runtime class with a *Data buffer and a *Cfg config. The hierarchy covers lights (Light), rigid bodies (RigidObject and grouped RigidObjectGroup), articulated chains (Articulation) and their robot specialization (Robot), deformables (SoftObject, ClothObject), interactive Gizmo handles, and RigidConstraint attachments between bodies.

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.

ArticulationJointKinematics

Backend-neutral kinematic description of one articulation joint.

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>, enable_gravity: '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>, workspace_cfg: 'Dict[str, RobotWorkspaceCfg] | None' = <factory>)

RobotWorkspaceCfg

Runtime configuration for a control-part workspace cache.

Gizmo

Manage native robot IK or Viser control for one simulation target.

GizmoCfg

Configure Gizmo appearance and native or Viser robot IK behavior.

create_robot_ik_gizmo_controller(robot[, ...])

Create DexSim's native IK controller for one EmbodiChain control part.

RigidConstraint

Batch of fixed constraints linking two RigidObject instances.

Light#

class embodichain.lab.sim.objects.Light[source]#

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'))[source]#

destroy()#

Destroy all entities managed by this batch entity.

Return type:: None

enable_shadow(flags, env_ids=None)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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[source]#

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[source]#

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 triangle indices for the combined visual meshes.
`get_user_ids`([env_ids])	Get the user ids of the rigid bodies.
`get_vertices`([env_ids, scale])	Retrieve the combined visual-mesh 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'))[source]#

add_force_torque(force=None, torque=None, pos=None, env_ids=None)[source]#

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)[source]#

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)[source]#

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()[source]#

Destroy all entities managed by this batch entity.

Return type:: None

enable_collision(enable, env_ids=None)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

Retrieve triangle indices for the combined visual meshes.

Face indices from each render mesh are offset to reference the concatenated vertex array returned by get_vertices().

Parameters:: env_ids (Optional[Sequence[int]]) – Environment IDs for which to retrieve triangle indices. If None, retrieves triangle indices for all instances.
Return type:: Tensor
Returns:: Triangle indices with shape (N, num_triangles, 3).

get_user_ids(env_ids=None)[source]#

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)[source]#

Retrieve the combined visual-mesh vertices of the rigid objects.

Assets such as GLB files can contain multiple render meshes. Their vertices are concatenated in render-mesh order so the result represents the complete object instead of only the first mesh.

Parameters:

env_ids (Optional[Sequence[int]]) – 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.

Return type:

Tensor

Returns:

Combined vertices with shape (N, num_vertices, 3).

get_visual_material_inst(env_ids=None)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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, update_default=False)[source]#

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.
update_default (bool) – Whether the assigned material should become the baseline restored by reset(). Defaults to False.

Return type:

None

share_visual_material_inst(mat_insts)[source]#

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[source]#

Bases: object

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

Note

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)[source]#

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[source]#

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.

"visacd", "coacd", and "vhacd" are supported. Only used when max_convex_hull_num is set to larger than 1. "visacd" requires CUDA support.

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.

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()[source]#

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[source]#

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_object_triangles`(object_id[, env_ids])	Get one constituent object's triangle indices.
`get_object_vertices`(object_id[, env_ids, scale])	Get one constituent object's vertices across selected environments.
`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'))[source]#

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)[source]#

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()[source]#

Destroy all entities managed by this batch entity.

Return type:: None

get_local_pose(to_matrix=False)[source]#

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_object_triangles(object_id, env_ids=None)[source]#

Get one constituent object’s triangle indices.

Parameters:

object_id (int) – Constituent object index within the group.
env_ids (Optional[Sequence[int]]) – Environment indices. If None, returns all instances.

Return type:

Tensor

Returns:

Triangle indices with shape (N, num_triangles, 3).

get_object_vertices(object_id, env_ids=None, scale=False)[source]#

Get one constituent object’s vertices across selected environments.

Parameters:

object_id (int) – Constituent object index within the group.
env_ids (Optional[Sequence[int]]) – Environment indices. If None, returns all instances.
scale (bool) – Whether to apply each object’s body scale.

Return type:

Tensor

Returns:

Vertices with shape (N, num_vertices, 3).

get_user_ids()[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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[source]#

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)[source]#

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[source]#

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)[source]#

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[source]#

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_joint_drive_type`([joint_ids, env_ids])	Get the backend drive type for the selected joints.
`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_render_nodes`(link_name)	Get a link's native render node for every articulation instance.
`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_parent_joint_chain`(link_name)	Return the joints from a link toward the articulation root.
`get_qf`()	Get the current generalized efforts (qf) of 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_gravity`([enable, env_ids])	Set whether gravity is enabled for the articulation.
`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'))[source]#

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)[source]#

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)[source]#

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, *, qpos_joint_names=None, **kwargs)[source]#

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.
qpos_joint_names (Sequence[str] | None) – Optional names corresponding to the last dimension of qpos. When supplied, the values are reordered into the kinematic chain’s parameter order before FK.
**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')[source]#

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()[source]#

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)[source]#

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)[source]#

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_drive_type(joint_ids=None, env_ids=None)[source]#

Get the backend drive type for the selected joints.

Parameters:

joint_ids (Optional[Sequence[int]]) – Joint indices to query. If None, queries all joints.
env_ids (Optional[Sequence[int]]) – Environment indices to query. If None, queries all environments.

Return type:

list[list[DriveType]]

Returns:

Backend drive types grouped by environment, with one DriveType per selected joint.

get_link_physical_attr(link_names=None, env_ids=None)[source]#

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)[source]#

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_render_nodes(link_name)[source]#

Get a link’s native render node for every articulation instance.

This is the render-attachment boundary for cameras and other scene integrations. Returned nodes belong to this articulation and must not be used after the owning asset is destroyed.

Parameters:

link_name (str) – Canonical link name, without backend clone suffixes.

Return type:

list[Node]

Returns:

Render nodes ordered by environment index.

Raises:

ValueError – If the link is not part of this articulation.
RuntimeError – If any instance is missing the link or its render node.

get_link_vert_face(link_name)[source]#

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)[source]#

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)[source]#

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_parent_joint_chain(link_name)[source]#

Return the joints from a link toward the articulation root.

The immediate parent joint is first. Native simulator joint-info values are copied into ArticulationJointKinematics, keeping callers independent of DexSim objects and the private entity collection.

Parameters:

link_name (str) – Link whose parent chain should be queried.

Return type:

tuple[ArticulationJointKinematics, ...]

Returns:

Parent-joint chain ordered from the requested link toward the root.

Raises:

TypeError – If link_name is not a string.
ValueError – If the link is unknown, native topology is incomplete, multiple joints own one child link, or the chain contains a cycle.

get_qf()[source]#

Get the current generalized efforts (qf) of the articulation.

Returns:

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

Return type:

torch.Tensor

get_qf_limits(joint_ids=None, env_ids=None)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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()[source]#

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

Return type:: None

reset(env_ids=None)[source]#

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)[source]#

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)[source]#

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)[source]#

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_gravity(enable=True, env_ids=None)[source]#

Set whether gravity is enabled for the articulation.

Parameters:

enable (bool) – Whether to enable gravity. Defaults to True.
env_ids (Optional[Sequence[int]]) – Environment indices. If None, all environments 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)[source]#

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 “none”.
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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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, update_default=False)[source]#

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.
update_default (bool) – Whether the assigned material should become the baseline restored by reset(). 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.ArticulationJointKinematics[source]#

Bases: object

Backend-neutral kinematic description of one articulation joint.

The value contains only stable names and copied numeric geometry. It does not expose the simulator’s native joint-info object.

Parameters:

name (str) – Stable joint name.
joint_type (str) – Normalized lowercase joint type, such as fixed, revolute, or prismatic.
parent_link_name (str) – Name of the joint’s parent link.
child_link_name (str) – Name of the joint’s child link.
origin_pose (Tensor) – Joint-frame pose in the parent-link frame with shape (4, 4).
axis (Tensor) – Joint axis in the joint frame with shape (3,).
joint_limits (tuple[float, float] | None) – Optional lower and upper position limits.

Methods:

__init__(name, joint_type, parent_link_name, ...)

__init__(name, joint_type, parent_link_name, child_link_name, origin_pose, axis, joint_limits=None)#

class embodichain.lab.sim.objects.ArticulationData[source]#

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)[source]#

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[source]#

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.
`enable_gravity`	Whether gravity is enabled for the articulation.
`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.

enable_gravity: bool#

Whether gravity is enabled for the articulation.

This runtime flag is applied regardless of use_usd_properties.

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)[source]#

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: Union[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: Union[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[source]#

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_collision_surface_triangles`([env_ids])	Get approximate collision-surface triangles for selected instances.
`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_triangles`([env_ids])	Get approximate surface triangles for generic mesh consumers.
`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'))[source]#

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()[source]#

Destroy all entities managed by this batch entity.

Return type:: None

get_collision_surface_triangles(env_ids=None)[source]#

Get approximate collision-surface triangles for selected instances.

DexSim currently exposes live soft-body collision vertices without their topology. This method returns a cached convex-hull topology, so it is suitable for low-frequency external visualization but does not preserve concave details of the render mesh.

Parameters:: env_ids (Optional[Sequence[int]]) – Environment indices. If None, returns all instances.
Return type:: Tensor
Returns:: Triangle indices with shape (N, num_triangles, 3).

get_current_collision_vertices()[source]#

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()[source]#

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()[source]#

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)[source]#

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()[source]#

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()[source]#

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_triangles(env_ids=None)[source]#

Get approximate surface triangles for generic mesh consumers.

Parameters:: env_ids (Optional[Sequence[int]]) – Environment indices. If None, returns all instances.
Return type:: Tensor
Returns:: Triangle indices with shape (N, num_triangles, 3).

get_visual_material_inst(env_ids=None)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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[source]#

Bases: object

Data manager for soft body

Note

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.
`collision_surface_triangles`	Build a stable surface approximation for collision vertices.
`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)[source]#

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 collision_surface_triangles: Tensor#

Build a stable surface approximation for collision vertices.

DexSim exposes live PhysX collision vertices but not their triangle connectivity. The convex hull provides a stable topology whose indices continue to reference the live collision-vertex buffer.

Returns:: Cached convex-hull triangle indices.

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[source]#

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[source]#

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_triangles`([env_ids])	Get surface triangle indices for selected cloth instances.
`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'))[source]#

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()[source]#

Destroy all entities managed by this batch entity.

Return type:: None

get_current_vertex_position()[source]#

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()[source]#

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)[source]#

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()[source]#

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_triangles(env_ids=None)[source]#

Get surface triangle indices for selected cloth instances.

Parameters:: env_ids (Optional[Sequence[int]]) – Environment indices. If None, returns all instances.
Return type:: Tensor
Returns:: Triangle indices with shape (N, num_triangles, 3).

get_visual_material_inst(env_ids=None)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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[source]#

Bases: object

Data manager for cloth.

Note

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)[source]#

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[source]#

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[source]#

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.
`attach_workspace`(workspace[, name])	Attach a runtime workspace to a control part.
`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_drive_type`([joint_ids, env_ids])	Get the backend drive type for the selected joints.
`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_render_nodes`(link_name)	Get a link's native render node for every articulation instance.
`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_parent_joint_chain`(link_name)	Return the joints from a link toward the articulation root.
`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.
`get_workspace`([name])	Get or lazily load the workspace for a control part.
`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.
`sample_reachable_pose`([name, env_ids, ...])	Sample kinematically reachable end-effector poses.
`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_gravity`([enable, env_ids])	Set whether gravity is enabled for the articulation.
`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'))[source]#

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

attach_workspace(workspace, name=None)[source]#

Attach a runtime workspace to a control part.

Parameters:

workspace (RobotWorkspace) – Runtime workspace to attach.
name (str | None) – Control-part name. Use None for the default solver.

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()[source]#

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)[source]#

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, (num_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 (num_envs, batch, 7) or (num_envs, batch, 4, 4) if to_matrix is True.

Return type:

torch.Tensor

compute_batch_ik(pose, joint_seed, name, env_ids=None)[source]#

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, (num_envs, n_batch, 7) or (num_envs, n_batch, 4, 4).
joint_seed (torch.Tensor | None) – The joint positions to use as a seed for the IK computation, (num_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 (num_envs, n_batch) Qpos Tensor with shape (num_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, *, qpos_joint_names=None)[source]#

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, (num_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.
qpos_joint_names (Optional[Sequence[str]]) – Optional names corresponding to the last dimension of qpos for full-articulation FK.

Returns:

The forward kinematics result with shape (num_envs, 7) or (num_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)[source]#

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, (num_envs, 7) or (num_envs, 4, 4).
joint_seed (torch.Tensor | None) – The joint positions to use as a seed for the IK computation, (num_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 (num_envs, ) and qpos Tensor with shape (num_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()[source]#

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)[source]#

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)[source]#

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_drive_type(joint_ids=None, env_ids=None)#

Get the backend drive type for the selected joints.

Parameters:

joint_ids (Optional[Sequence[int]]) – Joint indices to query. If None, queries all joints.
env_ids (Optional[Sequence[int]]) – Environment indices to query. If None, queries all environments.

Return type:

list[list[DriveType]]

Returns:

Backend drive types grouped by environment, with one DriveType per selected joint.

get_joint_ids(name=None, remove_mimic=False)[source]#

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)[source]#

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_render_nodes(link_name)#

Get a link’s native render node for every articulation instance.

This is the render-attachment boundary for cameras and other scene integrations. Returned nodes belong to this articulation and must not be used after the owning asset is destroyed.

Parameters:

link_name (str) – Canonical link name, without backend clone suffixes.

Return type:

list[Node]

Returns:

Render nodes ordered by environment index.

Raises:

ValueError – If the link is not part of this articulation.
RuntimeError – If any instance is missing the link or its render node.

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_parent_joint_chain(link_name)#

Return the joints from a link toward the articulation root.

The immediate parent joint is first. Native simulator joint-info values are copied into ArticulationJointKinematics, keeping callers independent of DexSim objects and the private entity collection.

Parameters:

link_name (str) – Link whose parent chain should be queried.

Return type:

tuple[ArticulationJointKinematics, ...]

Returns:

Parent-joint chain ordered from the requested link toward the root.

Raises:

TypeError – If link_name is not a string.
ValueError – If the link is unknown, native topology is incomplete, multiple joints own one child link, or the chain contains a cycle.

get_proprioception()[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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]]

get_workspace(name=None)[source]#

Get or lazily load the workspace for a control part.

Parameters:: name (str | None) – Control-part name. If omitted and exactly one workspace is configured, that workspace is selected automatically.
Return type:: RobotWorkspace
Returns:: Runtime robot workspace.
Raises:: ValueError – If no unambiguous workspace configuration exists.

init_solver(cfg)[source]#

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

sample_reachable_pose(name=None, env_ids=None, num_samples=1, strategy=None, position_bounds=None, min_score=None, max_attempts=64, generator=None)[source]#

Sample kinematically reachable end-effector poses.

Cached joint configurations are sampled first and then evaluated with runtime FK. This accounts for the current control-part base pose in every target environment. A valid sample is kinematically reachable, but is not guaranteed to have a collision-free trajectory from the robot’s current state.

Parameters:

name (str | None) – Control-part name.
env_ids (Union[Sequence[int], Tensor, None]) – Target environment IDs. Defaults to all environments.
num_samples (int) – Number of samples per environment.
strategy (Optional[Literal['point_uniform', 'voxel_uniform']]) – Sampling strategy. Defaults to the workspace config.
position_bounds (Tensor | tuple[Sequence[float], Sequence[float]] | None) – Optional arena-frame bounds ((xmin, ymin, zmin), (xmax, ymax, zmax)) applied after FK.
min_score (float | None) – Optional minimum cached reachability score.
max_attempts (int) – Candidate count per environment when applying bounds.
generator (Generator | None) – Optional torch random number generator.

Return type:

WorkspaceSample

Returns:

Batched workspace samples. Entries that could not satisfy bounds have valid=False and indices=-1.

Raises:

ValueError – If sampling arguments are invalid.

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_gravity(enable=True, env_ids=None)#

Set whether gravity is enabled for the articulation.

Parameters:

enable (bool) – Whether to enable gravity. Defaults to True.
env_ids (Optional[Sequence[int]]) – Environment indices. If None, all environments 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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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, update_default=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.
update_default (bool) – Whether the assigned material should become the baseline restored by reset(). 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[source]#

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>, enable_gravity: ‘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>, workspace_cfg: ‘Dict[str, RobotWorkspaceCfg] | 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.
`enable_gravity`	Whether gravity is enabled for the articulation.
`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.
`workspace_cfg`	Runtime workspace cache configuration keyed by control-part name.

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 concrete solver 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 concrete solver configuration from a dictionary.

The concrete config receives all recognized dataclass init fields in its constructor so initialization and __post_init__ observe the final inputs exactly once. Legacy unannotated config attributes are applied afterward. Unknown fields preserve the historical behavior: they are ignored with a warning.

Return type:: SolverCfg

ik_nearest_weight: Optional[List[float]]#

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: Optional[List[float]]#: 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)[source]#

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

control_parts can be used without solver_cfg. If solver_cfg is a
dictionary, its keys must correspond to control-part names.
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.

enable_gravity: bool#

Whether gravity is enabled for the articulation.

This runtime flag is applied regardless of use_usd_properties.

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)[source]#

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)[source]#: 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()[source]#: 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.

workspace_cfg: Dict[str, RobotWorkspaceCfg] | None#: Runtime workspace cache configuration keyed by control-part name.

class embodichain.lab.sim.objects.RobotWorkspaceCfg[source]#

Bases: object

Runtime configuration for a control-part workspace cache.

Attributes:

`cache_path`	Path to a workspace cache entry directory or `results.npz` file.
`min_score`	Optional minimum cached reachability score accepted for sampling.
`strategy`	Default runtime sampling strategy.
`voxel_size`	Cartesian voxel edge length in meters for voxel-uniform sampling.

cache_path: str#: Path to a workspace cache entry directory or results.npz file.

min_score: float | None#: Optional minimum cached reachability score accepted for sampling.

strategy: Literal['point_uniform', 'voxel_uniform']#: Default runtime sampling strategy.

voxel_size: float#: Cartesian voxel edge length in meters for voxel-uniform sampling.

Gizmo#

class embodichain.lab.sim.objects.Gizmo[source]#

Bases: object

Manage native robot IK or Viser control for one simulation target.

Native-window entity manipulation is owned by DexSim. Use SimulationManager.enable_entity_gizmo() for entity roots. The manager discovers robot TCP controls and owns their updates and cleanup.

Attention

Gizmo control supports exactly one simulation environment.

Parameters:

target (BatchEntity) – Robot, or a rigid object or camera controlled from Viser.
cfg (GizmoCfg | None) – Gizmo appearance and robot IK configuration.
control_part (str | None) – Robot control part used for FK and IK.

Methods:

`__init__`(target[, cfg, control_part])
`begin_interaction`(source_id)	Acquire this Gizmo for one Viser drag source.
`cancel_interaction`([source_prefix])	Cancel the active owner, optionally only for a source prefix.
`destroy`()	Release target and IK references.
`detach_native_window`()	Detach input before window close while retaining IK state and visibility.
`end_interaction`(source_id)	Release a Viser drag source's ownership of this Gizmo.
`get_control_pose`()	Return the Gizmo pose in the local arena frame as `(1, 4, 4)`.
`is_visible`()	Return the active native visibility or configured Viser visibility.
`request_local_pose`(pose, *, source_id)	Queue a local target pose for application by `update()`.
`set_visible`(visible)	Set Gizmo visibility, including an activated native controller.
`toggle_visibility`()	Toggle Gizmo visibility and return the new state.
`update`()	Apply the latest queued Viser target pose on the simulation thread.
`update_native`(world)	Activate robot IK on startup or a toggle, then update its controller.

Attributes:

`control_part`	Return the robot control part, if applicable.
`target_type`	Return `rigid_object`, `robot`, or `camera`.

__init__(target, cfg=None, control_part=None)[source]#

begin_interaction(source_id)[source]#

Acquire this Gizmo for one Viser drag source.

Return type:: bool

cancel_interaction(source_prefix=None)[source]#

Cancel the active owner, optionally only for a source prefix.

Return type:: bool

property control_part: str | None#: Return the robot control part, if applicable.

destroy()[source]#

Release target and IK references.

Return type:: None

detach_native_window()[source]#

Detach input before window close while retaining IK state and visibility.

Return type:: None

end_interaction(source_id)[source]#

Release a Viser drag source’s ownership of this Gizmo.

Return type:: bool

get_control_pose()[source]#

Return the Gizmo pose in the local arena frame as (1, 4, 4).

Return type:: Tensor

is_visible()[source]#

Return the active native visibility or configured Viser visibility.

Return type:: bool

request_local_pose(pose, *, source_id)[source]#

Queue a local target pose for application by update().

Return type:: bool

set_visible(visible)[source]#

Set Gizmo visibility, including an activated native controller.

Return type:: None

property target_type: str#: Return rigid_object, robot, or camera.

toggle_visibility()[source]#

Toggle Gizmo visibility and return the new state.

Return type:: bool

update()[source]#

Apply the latest queued Viser target pose on the simulation thread.

Return type:: None

update_native(world)[source]#

Activate robot IK on startup or a toggle, then update its controller.

Startup activation is opt-in; otherwise only the toggle key activates IK. Registration and window reopening never write robot drive targets. Explicit factory-created controllers remain owned by their caller.

Parameters:: world (World) – Simulation world with an open native window.
Return type:: None

class embodichain.lab.sim.objects.GizmoCfg[source]#

Bases: object

Configure Gizmo appearance and native or Viser robot IK behavior.

Attributes:

`axis_length_x`	Length of the X-axis arrow.
`axis_length_y`	Length of the Y-axis arrow.
`axis_length_z`	Length of the Z-axis arrow.
`axis_size`	Thickness of the Viser axis lines.
`ik_device`	Warp device for Newton IK, or the robot device when omitted.
`ik_end_link_name`	Robot IK chain end link, or the configured solver end when omitted.
`ik_gizmo_scale`	Isotropic scale of a native DexSim robot IK target.
`ik_iterations`	Number of Newton IK iterations per changed target.
`ik_root_link_name`	Robot IK chain root link, or the configured solver root when omitted.
`ik_solver`	Use native Newton IK, or the control part's configured EmbodiChain solver.
`ik_start_enabled`	Activate managed native IK on the first update with an open window.
`ik_tcp_pose`	End-link-to-TCP transform.
`ik_toggle_key`	Native-window key used to toggle a DexSim robot IK target.
`rings_radius`	Radius of the rotation rings.
`rings_size`	Thickness of the rotation rings.

axis_length_x: float#: Length of the X-axis arrow.

axis_length_y: float#: Length of the Y-axis arrow.

axis_length_z: float#: Length of the Z-axis arrow.

axis_size: float#: Thickness of the Viser axis lines.

ik_device: str | None#: Warp device for Newton IK, or the robot device when omitted.

ik_end_link_name: str | None#: Robot IK chain end link, or the configured solver end when omitted.

ik_gizmo_scale: float#: Isotropic scale of a native DexSim robot IK target.

ik_iterations: int#: Number of Newton IK iterations per changed target.

ik_root_link_name: str | None#: Robot IK chain root link, or the configured solver root when omitted.

ik_solver: Literal['dexsim', 'embodichain']#

Use native Newton IK, or the control part’s configured EmbodiChain solver.

The native window always uses DexSim’s IKGizmoController. Selecting embodichain reuses robot.get_solver(control_part) (for example, PinkSolver), including that solver’s convergence and joint-limit settings.

ik_start_enabled: bool#

Activate managed native IK on the first update with an open window.

Defaults to waiting for the toggle key. Explicit startup activation creates the controller and initializes its drive targets from the current pose. This is a one-time request: later toggles and window reopening retain their normal behavior. Viser still builds its solver on the first drag.

ik_tcp_pose: Tensor | ndarray | list[list[float]] | None#: End-link-to-TCP transform.

ik_toggle_key: InputKey#: Native-window key used to toggle a DexSim robot IK target.

rings_radius: float#: Radius of the rotation rings.

rings_size: float#: Thickness of the rotation rings.

embodichain.lab.sim.objects.create_robot_ik_gizmo_controller(robot, control_part='arm', cfg=None, *, world=None)[source]#

Create DexSim’s native IK controller for one EmbodiChain control part.

The caller owns the returned objects and must call controller.update() once per frame. Retain the input controller while the native window exists.

Parameters:

robot (Robot) – Single-instance EmbodiChain robot.
control_part (str) – Robot control part driven by IK.
cfg (GizmoCfg | None) – IK chain, solver selection, and target appearance settings.
world (World | None) – DexSim world, or the current default world when omitted.

Return type:

tuple[IKGizmoController, GizmoController]

Returns:

(ik_controller, input_controller) owned by the caller.

SimulationManager automatically discovers robot control parts with configured IK chain metadata. Native controllers activate on the first I press by default, while Viser constructs its solver on the first drag. sim.update() owns updates and cleanup; ordinary applications do not need the explicit factory. Use SimulationManagerCfg(robot_ik_gizmo=None) to disable automatic setup. Set GizmoCfg(ik_start_enabled=True) to activate native IK on the first update with an open window; subsequent visibility toggles and reopening are preserved.

The native controller defaults to DexSim Newton IK. With a PinkSolverCfg (or another EmbodiChain solver) configured for the robot’s control part, pass GizmoCfg(ik_solver="embodichain") to select that solver for either a native controller or a Viser gizmo. Its iteration limits and convergence settings remain owned by the configured solver; ik_iterations applies to Newton IK. Only the selected control part’s drive targets are written, and failed EmbodiChain IK solutions preserve the current joint positions.

The runnable example examples/sim/gizmo/gizmo_robot.py exposes --ik-solver dexsim|pytorch|pink for both the native window and --viser.

Rigid Constraint#

class embodichain.lab.sim.objects.RigidConstraint[source]#

Bases: object

Batch of fixed constraints linking two RigidObject instances.

Each entry binds rigid_object_a._entities[i] to rigid_object_b._entities[i] within arena i via a dexsim FixedConstraint. The constraint_handles list has length num_envs with None wherever the constraint is not active in that arena, so arena index always equals list index.

Parameters:

cfg (RigidConstraintCfg) – The constraint configuration.
constraint_handles (list[Any]) – Per-arena dexsim constraint handles (None where inactive).
rigid_object_a (RigidObject | None) – The first RigidObject (None only until set at creation).
rigid_object_b (RigidObject | None) – The second RigidObject (None only until set at creation).
device (device) – The torch device.

Methods:

`__init__`(cfg[, constraint_handles, ...])
`destroy`([env_ids, arena_resolver])	Remove this constraint from the specified arenas.
`get_local_pose`(actor_index[, env_ids])	Get the local pose of the constraint frame for the given actor.
`get_name`(env_id)	Get the per-arena constraint name.
`get_relative_transform`([env_ids])	Get the relative transform of B in A for each active env.
`is_valid`([env_ids])	Check validity of each active constraint handle.

Attributes:

num_envs

Number of arenas covered by this constraint.

__init__(cfg, constraint_handles=<factory>, rigid_object_a=None, rigid_object_b=None, device=<factory>)#

destroy(env_ids=None, arena_resolver=None)[source]#

Remove this constraint from the specified arenas.

Parameters:

env_ids (Sequence[int] | None) – Subset of arenas to clear. None -> all active arenas.
arena_resolver (Callable[[int], Any] | None) – Callable returning the arena for a given env index. Required to actually remove constraints from dexsim.

Return type:

None

get_local_pose(actor_index, env_ids=None)[source]#

Get the local pose of the constraint frame for the given actor.

Parameters:

actor_index (int) – 0 for object A, 1 for object B.
env_ids (Sequence[int] | None) – Subset of arenas. None -> all. Inactive handles skipped.

Return type:

list[ndarray]

Returns:

A list of 4x4 numpy arrays, one per active env.

get_name(env_id)[source]#

Get the per-arena constraint name.

For single-env constraints, returns the base name. For multi-env constraints, returns f"{base}_{env_id}".

Parameters:: env_id (int) – The arena index.
Return type:: str
Returns:: The constraint name registered in that arena.

get_relative_transform(env_ids=None)[source]#

Get the relative transform of B in A for each active env.

Parameters:: env_ids (Sequence[int] | None) – Subset of arenas. None -> all arenas. Inactive (None) handles are skipped.
Return type:: list[ndarray]
Returns:: A list of 4x4 numpy arrays, one per active env.

is_valid(env_ids=None)[source]#

Check validity of each active constraint handle.

Parameters:: env_ids (Sequence[int] | None) – Subset of arenas. None -> all. Inactive handles skipped.
Return type:: list[bool]
Returns:: A list of bools, one per active env.

property num_envs: int#: Number of arenas covered by this constraint.

`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.
`ArticulationJointKinematics`	Backend-neutral kinematic description of one articulation joint.
`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>, enable_gravity: '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>, workspace_cfg: 'Dict[str, RobotWorkspaceCfg] \| None' = <factory>)
`RobotWorkspaceCfg`	Runtime configuration for a control-part workspace cache.
`Gizmo`	Manage native robot IK or Viser control for one simulation target.
`GizmoCfg`	Configure Gizmo appearance and native or Viser robot IK behavior.
`create_robot_ik_gizmo_controller`(robot[, ...])	Create DexSim's native IK controller for one EmbodiChain control part.
`RigidConstraint`	Batch of fixed constraints linking two `RigidObject` instances.

embodichain.lab.sim.objects

Contents

embodichain.lab.sim.objects#

Overview#

Light#

Rigid Object#

Rigid Object Group#

Articulation#

Soft Object#

Cloth Object#

Robot#

Gizmo#

Rigid Constraint#