embodichain.lab.sim.objects

Scene-object classes spawned into the SimulationManager.

Covers lights, render-only objects, 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 *Cfg config and, for physical assets, a *Data buffer. The hierarchy covers lights (Light), rigid bodies (RigidObject and grouped RigidObjectGroup), articulated chains (Articulation) and their robot specialization (Robot), deformables (VolumeDeformableObject, SurfaceDeformableObject), 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.
VisualObject	A replicated visual asset with no rigid-body state or collision API.
VisualObjectCfg	Configure a render-only object, without a rigid body or colliders.
RigidObject	RigidObject represents a batch of rigid body in the simulation.
CollisionShapeDesc	Planner-independent snapshot of one DexSim physical collision shape.
RigidBodyData	Scene-batch data manager for dynamic or kinematic rigid bodies.
RigidObjectCfg	Configuration for a rigid body asset in the simulation.
RigidObjectGroup	A two-dimensional view over rigid objects owned by DexSim Spawn.
RigidBodyGroupData	Expose one flat Scene rigid-body batch as [env, object, ...] tensors.
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	Scene-batch data manager for articulations.
ArticulationCfg	Configuration for an articulation 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>, body_scale: 'tuple | list' = <factory>, compute_uv: 'bool' = <factory>, asset_physics_mode: 'AssetPhysicsMode' = <factory>, attrs: 'RigidBodyPhysicsCfg' = <factory>, link_attrs: 'dict[str, LinkPhysicsOverrideCfg] | None' = <factory>, root_props: 'ArticulationRootPropertiesCfg' = <factory>, joint_drive_props: 'JointDrivePropertiesCfg' = <factory>, init_qpos: 'torch.Tensor | np.ndarray | Sequence[float]' = <factory>, qpos_limits: 'torch.Tensor | np.ndarray | Sequence[Sequence[float]] | Dict[str, List[float]] | None' = <factory>, build_pk_chain: '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>, sensors: 'list[SensorCfg]' = <factory>, enable_sensor: 'bool' = <factory>, *, source: 'UsdSourceCfg | None' = None)
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

Bases: BatchEntity

Light represents a batch of lights in the simulation.

Each light supports the following properties:

• Color (3 floats)

• Intensity (1 float)

• Falloff (1 float)

• Location (3 floats)

Methods:

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

Attributes:

is_global

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

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

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

enable_shadow(flags, env_ids=None)

Enable or disable shadow casting.

Applies to all light types.

Parameters:

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

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

Return type:

None

get_local_pose(to_matrix=False)

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

Parameters:

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

Returns:

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

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

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

Return type:

torch.Tensor

property is_global: bool

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

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

Returns:

True if the light is a global scene light.

Return type:

bool

reset(env_ids=None)

Reset the light to its initial configuration state.

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

Attention

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

Parameters:

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

Return type:

None

set_color(colors, env_ids=None)

Set color for one or more lights.

Parameters:

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

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

Return type:

None

set_direction(directions, env_ids=None)

Set direction for directional-type lights.

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

Parameters:

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

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

Return type:

None

set_falloff(falloffs, env_ids=None)

Set falloff (radius) for one or more lights.

Parameters:

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

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

Return type:

None

set_intensity(intensities, env_ids=None)

Set intensity for one or more lights.

Parameters:

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

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

Return type:

None

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

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

Parameters:

• pose (torch.Tensor) –

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

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

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

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

Return type:

None

set_mesh(mesh, env_ids=None)

Set the mesh for mesh-type lights.

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

Parameters:

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

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

Return type:

None

set_rect_wh(widths, heights, env_ids=None)

Set width and height for rectangular area lights.

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

Parameters:

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

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

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

Return type:

None

set_spot_angle(inner_angles, outer_angles, env_ids=None)

Set inner and outer cone angles for spot lights.

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

Parameters:

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

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

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

Return type:

None

class embodichain.lab.sim.objects.LightCfg

Bases: ObjectBaseCfg

Configuration for a light asset in the simulation.

Supports six light types matching the dexsim rendering backend:

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

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

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

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

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

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

Attention

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

Attributes:

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

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

angular_radius: float

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

color: tuple[float, float, float]

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

direction: tuple[float, float, float]

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

enable_shadow: bool

Whether the light casts shadows. Defaults to True.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

ObjectBaseCfg

halo_falloff: float

Halo falloff for sun light. Reserved for future use.

halo_size: float

Halo size for sun light. Reserved for future use.

init_local_pose: ndarray | None

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

init_pos: tuple[float, float, float]

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

init_rot: tuple[float, float, float]

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

intensity: float

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

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

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

Type:

Light type. Supported

mesh_path: str

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

radius: float

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

rect_height: float

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

rect_width: float

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

spot_angle_inner: float

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

spot_angle_outer: float

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

Visual Object

VisualObject owns render-only appearance and arena-local transforms. It provides selected-environment visibility and material-assignment reset without creating a rigid body or collision geometry. Declare it with SimulationManager.add_visual_object() and prepare the shared Spawn scene. Whole-scene USD imports classify objects without physics or colliders as visuals; explicit visual-object USD loading can select one object’s appearance by prim path.

class embodichain.lab.sim.objects.VisualObject

Bases: BatchEntity

A replicated visual asset with no rigid-body state or collision API.

Declare through SimulationManager.add_visual_object() or add_usd() and call prepare() before accessing runtime state. Poses are arena-local and use EmbodiChain’s xyz + xyzw convention.

Parameters:

• cfg (VisualObjectCfg) – Visual geometry and initial state.

• device (device) – Device for returned tensors.

Methods:

__init__(cfg[, device])	Create a facade whose runtime handles will be supplied by Spawn.
attach_spawn_handles(entities)	Attach borrowed render handles supplied by Spawn.
bind_spawn(result)	Capture initial visual state after Spawn materializes the object.
destroy()	Leave resource removal to SimulationManager and the owning Spawn scene.
get_body_scale([env_ids])	Read visual geometry scales, independent of root transforms.
get_local_pose([to_matrix, env_ids])	Read independent arena-local poses.
get_triangles([env_ids])	Read triangle indices addressing the combined visual mesh.
get_vertices([env_ids, scale])	Read combined local mesh vertices for selected instances.
get_visibility([env_ids])	Read selected visibility flags.
get_visual_material_inst([env_ids])	Read current material wrappers for selected environments.
reset([env_ids])	Restore selected initial poses, visibility and material assignments.
set_local_pose(pose[, env_ids])	Write selected root poses without advancing simulation.
set_visible([visible, env_ids])	Set visibility for selected environments.
set_visual_material(mat[, env_ids])	Assign separate material instances to selected environments.

Attributes:

is_declared	Whether this facade is waiting for preparation.
is_spawn_bound	Whether this facade is bound to a finalized Scene.
num_instances	Number of instances declared by Spawn, including before preparation.
user_ids	Return native render-instance IDs as an (N,) integer tensor.

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

Create a facade whose runtime handles will be supplied by Spawn.

Parameters:

• cfg (VisualObjectCfg) – Appearance and initial state.

• device (device) – Device for returned tensors.

attach_spawn_handles(entities)

Attach borrowed render handles supplied by Spawn.

Parameters:

entities (Sequence[SpawnedRigidBody]) – One render-only handle per environment.

Return type:

None

bind_spawn(result)

Capture initial visual state after Spawn materializes the object.

Parameters:

result (Scene) – Finalized Scene owning the attached handles.

Return type:

None

destroy()

Leave resource removal to SimulationManager and the owning Spawn scene.

Return type:

None

get_body_scale(env_ids=None)

Read visual geometry scales, independent of root transforms.

Parameters:

env_ids (Union[Sequence[int], Tensor, None]) – Selected environments, or all environments.

Return type:

Tensor

Returns:

Scale tensor shaped (M, 3).

get_local_pose(to_matrix=False, env_ids=None)

Read independent arena-local poses.

Parameters:

• to_matrix (bool) – Return matrices instead of xyz + xyzw poses.

• env_ids (Union[Sequence[int], Tensor, None]) – Selected environments in output order, or all environments.

Return type:

Tensor

Returns:

Tensor shaped (M, 4, 4) or (M, 7) for the selected rows.

get_triangles(env_ids=None)

Read triangle indices addressing the combined visual mesh.

Parameters:

env_ids (Union[Sequence[int], Tensor, None]) – Selected environments, or all environments.

Return type:

Tensor

Returns:

Indices shaped (M, F, 3).

get_vertices(env_ids=None, scale=False)

Read combined local mesh vertices for selected instances.

Parameters:

• env_ids (Union[Sequence[int], Tensor, None]) – Selected environments, or all environments.

• scale (bool) – Include the visual geometry scale.

Return type:

Tensor

Returns:

Vertices shaped (M, V, 3).

get_visibility(env_ids=None)

Read selected visibility flags.

Parameters:

env_ids (Union[Sequence[int], Tensor, None]) – Selected environments, or all environments.

Return type:

Tensor

Returns:

Boolean tensor shaped (M,).

get_visual_material_inst(env_ids=None)

Read current material wrappers for selected environments.

Parameters:

env_ids (Union[Sequence[int], Tensor, None]) – Selected environments, or all environments.

Return type:

list[VisualMaterialInst | None]

Returns:

One wrapper per selected instance, possibly None without a material.

property is_declared: bool

Whether this facade is waiting for preparation.

property is_spawn_bound: bool

Whether this facade is bound to a finalized Scene.

property num_instances: int

Number of instances declared by Spawn, including before preparation.

reset(env_ids=None)

Restore selected initial poses, visibility and material assignments.

Parameters:

env_ids (Union[Sequence[int], Tensor, None]) – Selected environments, or all environments.

Return type:

None

set_local_pose(pose, env_ids=None)

Write selected root poses without advancing simulation.

Parameters:

• pose (Tensor) – (M, 7) xyz/xyzw poses or (M, 4, 4) rigid transforms.

• env_ids (Union[Sequence[int], Tensor, None]) – Selected environments, or all environments.

Return type:

None

set_visible(visible=True, env_ids=None)

Set visibility for selected environments.

Parameters:

• visible (bool) – Whether selected instances are visible.

• env_ids (Union[Sequence[int], Tensor, None]) – Selected environments, or all environments.

Return type:

None

set_visual_material(mat, env_ids=None)

Assign separate material instances to selected environments.

Parameters:

• mat (VisualMaterial) – Material template from the simulation manager.

• env_ids (Union[Sequence[int], Tensor, None]) – Selected environments, or all environments.

Return type:

None

property user_ids: Tensor

Return native render-instance IDs as an (N,) integer tensor.

Configuration fields are documented under embodichain.lab.sim.cfg.VisualObjectCfg.

Rigid Object

class embodichain.lab.sim.objects.RigidObject

Bases: BatchEntity

RigidObject represents a batch of rigid body in the simulation.

There are three types of rigid body:

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

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

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

Parameters:

• cfg (RigidObjectCfg) – Configuration for the rigid object.

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

Methods:

__init__(cfg[, device])	Create an unregistered rigid-object facade.
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.
attach_spawn_handles(entities)	Store materialized handles without initializing runtime Batch data.
bind_spawn(result)	Atomically bind a declared facade to stable Spawn handles.
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_collision_shapes([env_id])	Snapshot the physical collision shapes used by DexSim.
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])	Restore selected instances' initial state without advancing physics.
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.
default_mass	Initialization-time mass retained for backward compatibility.
is_declared	Whether this facade is waiting for its Scene binding.
is_non_dynamic	Check if the rigid object is non-dynamic (static or kinematic).
is_spawn_bound	Whether this facade is bound to one finalized Scene.
is_static	Check if the rigid object is static.
user_ids	Get the user ids of the rigid object.

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

Create an unregistered rigid-object facade.

SpawnScene supplies the replicated instance count when it registers the facade and supplies the finalized Scene only when binding it. This keeps construction independent of a process-global manager.

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

Add force and/or torque to the rigid object.

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

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

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

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

Parameters:

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

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

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

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

Return type:

None

apply_render_material_inst(env_idx, mat_inst, mesh_id=0)

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

Parameters:

• env_idx (int) – Environment index.

• mat_inst (MaterialInst) – dexsim MaterialInst to attach.

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

Return type:

None

attach_spawn_handles(entities)

Store materialized handles without initializing runtime Batch data.

Default may call this before Spawn finalization so native metadata is available early. bind_spawn() remains responsible for creating result-dependent Batch/Data state after finalization.

Return type:

None

bind_spawn(result)

Atomically bind a declared facade to stable Spawn handles.

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, qx, qy, qz, qw, lin_x, lin_y, lin_z, ang_x, ang_y, ang_z]

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

Returns:

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

Return type:

torch.Tensor

clear_dynamics(env_ids=None)

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

Parameters:

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

Return type:

None

property default_mass: Tensor

Initialization-time mass retained for backward compatibility.

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

enable_collision(enable, env_ids=None)

Enable or disable collision for the rigid bodies.

Parameters:

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

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

Return type:

None

get_body_scale(env_ids=None)

Retrieve the body scale for specified environment instances.

Parameters:

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

Returns:

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

Return type:

torch.Tensor

get_collision_shapes(env_id=0)

Snapshot the physical collision shapes used by DexSim.

Unlike get_vertices() and get_triangles(), this method reads the physics body’s collision descriptors rather than render meshes. For batched objects, every row is checked for identical shape topology before the requested row is returned.

Attention

The installed DexSim binding must populate ShapeGeometry.local_pose and dispatch SDF geometry through get_shape_geometry. This method preserves the values returned by DexSim and raises an actionable error when a descriptor cannot be retrieved.

Parameters:

env_id (int) – Environment row whose collision geometry is returned.

Return type:

list[CollisionShapeDesc]

Returns:

Physical collision-shape descriptors in stable shape-index order.

Raises:

• IndexError – If env_id is outside the object batch.

• RuntimeError – If DexSim cannot expose a collision descriptor.

• ValueError – If collision topology differs between environment rows.

get_damping(env_ids=None)

Get linear and angular damping for the rigid object.

Parameters:

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

Returns:

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

Return type:

torch.Tensor

get_existing_visual_material(env_ids=None, shared=False)

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

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

Parameters:

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

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

Return type:

List[List[ReuseSegmentState]]

Returns:

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

Raises:

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

get_friction(env_ids=None)

Get friction for the rigid object.

Parameters:

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

Returns:

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

Return type:

torch.Tensor

get_inertia(env_ids=None)

Get inertia tensor for the rigid object.

Parameters:

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

Returns:

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

Return type:

torch.Tensor

get_local_pose(to_matrix=False)

Get local pose of the rigid object.

Parameters:

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

Returns:

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

Return type:

torch.Tensor

get_mass(env_ids=None)

Get mass for the rigid object.

Parameters:

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

Returns:

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

Return type:

torch.Tensor

get_triangles(env_ids=None)

Retrieve 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)

Get the user ids of the rigid bodies.

Parameters:

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

Returns:

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

Return type:

torch.Tensor

get_vertices(env_ids=None, scale=False)

Retrieve the 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)

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_declared: bool

Whether this facade is waiting for its Scene binding.

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_spawn_bound: bool

Whether this facade is bound to one finalized Scene.

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)

Restore selected instances’ initial state without advancing physics.

Parameters:

env_ids (Optional[Sequence[int]]) – Environment indices to reset. None resets all instances.

Return type:

None

restore_visual_material(env_ids=None)

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

Parameters:

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

Return type:

None

set_attrs(attrs, env_ids=None)

Set physical attributes for the rigid object.

Parameters:

• attrs (RigidBodyPhysicsCfg | list[RigidBodyPhysicsCfg]) – Grouped physical attributes, shared or one per environment.

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

Return type:

None

set_body_scale(scale, env_ids=None)

Set the scale of the rigid body.

Parameters:

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

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

Return type:

None

set_body_type(body_type)

Set the body type of the rigid object.

Note

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

Parameters:

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

Return type:

None

Attention

On the Newton backend, body type (dynamic/kinematic/static) is fixed at body registration and cannot be changed at runtime; switching it would require re-registering the body and rebuilding the model. This call is therefore a no-op on Newton.

set_collision_filter(filter_data, env_ids=None)

set collision filter data for the rigid object.

Parameters:

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

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

Return type:

None

set_com_pose(com_pose, env_ids=None)

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

Parameters:

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

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

Return type:

None

set_damping(damping, env_ids=None)

Set linear and angular damping for the rigid object.

Parameters:

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

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

Return type:

None

Attention

The Newton backend does not simulate per-body linear/angular damping (its damping is a global solver knob). On Newton this call mirrors the values onto the attribute metadata so get_damping() and scene rebuilds stay consistent, but has no runtime effect.

set_friction(friction, env_ids=None)

Set friction for the rigid object.

Parameters:

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

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

Return type:

None

set_inertia(inertia, env_ids=None)

Set inertia tensor for the rigid object.

Parameters:

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

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

Return type:

None

set_local_pose(pose, env_ids=None)

Set local pose of the rigid object.

Pose writes do not advance physics or move other scene objects.

Parameters:

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

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

Return type:

None

set_mass(mass, env_ids=None)

Set mass for the rigid object.

Parameters:

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

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

Return type:

None

set_physical_visible(visible=True, rgba=None)

set collion render visibility

Parameters:

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

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

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

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

Parameters:

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

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

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

Return type:

None

set_visible(visible=True)

Set the visibility of the rigid object.

Parameters:

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

Return type:

None

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

Set visual material for the rigid object.

Note

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

Parameters:

• mat (VisualMaterial) – The material to set.

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

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

• 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)

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.CollisionShapeDesc

Planner-independent snapshot of one DexSim physical collision shape.

Geometry values are copied from DexSim’s runtime collision descriptor and therefore already include its geometry scale. Consumers must not apply RigidObjectCfg.body_scale again.

name

Stable shape name within the owning rigid object.

shape_type

DexSim collision-shape type.

local_pose

Shape pose relative to the rigid object’s frame, as (4, 4).

half_extents

Box half-extents, when applicable.

radius

Sphere or capsule radius, when applicable.

half_height

Capsule cylinder half-height, when applicable.

vertices

Scaled collision-mesh vertices, when applicable.

triangles

Collision-mesh triangle indices, when applicable.

Methods:

__init__(name, shape_type, local_pose[, ...])

__init__(name, shape_type, local_pose, half_extents=None, radius=None, half_height=None, vertices=None, triangles=None)

class embodichain.lab.sim.objects.RigidBodyData

Bases: object

Scene-batch data manager for dynamic or kinematic rigid bodies.

All pose/velocity/acceleration data uses EmbodiChain convention: (x, y, z, qx, qy, qz, qw).

Methods:

__init__(entities, scene, device)	Initialize the RigidBodyData.
capture_default_physical_properties(*, mass, ...)	Capture backend-resolved physical properties exactly once.

Attributes:

acc	Get the linear and angular accelerations of the rigid bodies.
com_pose	Get the center of mass pose of the rigid bodies.
default_com_pose	Initialization-time local COM pose as an xyz + xyzw tensor.
default_inertia	Initialization-time inertia diagonal with shape (N, 3).
default_mass	Initialization-time mass with shape (N,).
default_physical_properties_initialized	Whether the backend-resolved physical-property defaults are available.
gpu_indices	Body ID tensor (backward-compatible alias for body_view.body_ids_tensor).
inertia	Get current inertia diagonals with shape (N, 3).
mass	Get current masses with shape (N,).
vel	Get the linear and angular velocities of the rigid bodies.

__init__(entities, scene, device)

Initialize the RigidBodyData.

Parameters:

• entities (Sequence[SpawnedRigidBody]) – Rigid-body handles owned by scene.

• scene (Scene) – Finalized DexSim Scene.

• device (device) – 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

capture_default_physical_properties(*, mass, inertia, com_pose)

Capture backend-resolved physical properties exactly once.

Return type:

None

property com_pose: Tensor

Get the center of mass pose of the rigid bodies.

Returns:

The center-of-mass pose with shape (N, 7) in (x, y, z, qx, qy, qz, qw) order.

Return type:

torch.Tensor

property default_com_pose: Tensor

Initialization-time local COM pose as an xyz + xyzw tensor.

property default_inertia: Tensor

Initialization-time inertia diagonal with shape (N, 3).

property default_mass: Tensor

Initialization-time mass with shape (N,).

property default_physical_properties_initialized: bool

Whether the backend-resolved physical-property defaults are available.

property gpu_indices: Tensor

Body ID tensor (backward-compatible alias for body_view.body_ids_tensor).

property inertia: Tensor

Get current inertia diagonals with shape (N, 3).

property mass: Tensor

Get current masses with shape (N,).

property vel: Tensor

Get the linear and angular velocities of the rigid bodies.

Returns:

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

Return type:

torch.Tensor

class embodichain.lab.sim.objects.RigidObjectCfg

Bases: ObjectBaseCfg

Configuration for a rigid body asset in the simulation.

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

Attributes:

asset_physics_mode	How a file-backed asset's physical properties are handled.
attrs	Rigid-body physics.
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.
shape	Shape configuration for the rigid body.
source	USD source asset; mutually exclusive with shape.

Methods:

from_dict(init_dict)	Parse a rigid object and normalize legacy mesh collision ownership.
resolve_asset_physics_mode()	Return the effective file-backed physics policy.
to_dexsim_body_type()	Convert the body type to dexsim ActorType.

asset_physics_mode: AssetPhysicsMode

How a file-backed asset’s physical properties are handled.

"preserve" keeps the USD-authored physics. "overlay" applies configured properties on top of the parsed asset. Procedural shapes always use config.

attrs: RigidBodyPhysicsCfg

Rigid-body physics.

RigidBodyPhysicsCfg groups portable and backend-native intent.

body_scale: tuple | list

Scale of the rigid body in the simulation world frame.

classmethod from_dict(init_dict)

Parse a rigid object and normalize legacy mesh collision ownership.

Return type:

RigidObjectCfg

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_rot: tuple[float, float, float]

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

resolve_asset_physics_mode()

Return the effective file-backed physics policy.

Return type:

Literal['preserve', 'overlay']

shape: ShapeCfg | None

Shape configuration for the rigid body.

source: UsdSourceCfg | None = None

USD source asset; mutually exclusive with shape.

to_dexsim_body_type()

Convert the body type to dexsim ActorType.

Return type:

ActorType

Rigid Object Group

class embodichain.lab.sim.objects.RigidObjectGroup

Bases: BatchEntity

A two-dimensional view over rigid objects owned by DexSim Spawn.

Methods:

__init__(cfg[, device])	Create an unregistered rigid-object-group facade.
attach_spawn_handles(entities)	Store env-major handles without initializing the group's Batch data.
bind_spawn(result)	Atomically bind the declaration facade to env-major Spawn handles.
clear_dynamics([env_ids])	Clear velocity and one-step wrench buffers for selected envs.
destroy()	Leave topology destruction to SimulationManager and Scene.
get_com_pose([env_ids, obj_ids])	Return selected local COM poses in Group xyz + xyzw order.
get_inertia([env_ids, obj_ids])	Return selected inertia diagonals with shape [env, object, 3].
get_local_pose([to_matrix])	Return all Group poses as xyz+xyzw or homogeneous matrices.
get_mass([env_ids, obj_ids])	Return selected masses with shape [env, object].
get_object_triangles(object_id[, env_ids])	Return one member's render triangles across selected environments.
get_object_vertices(object_id[, env_ids, scale])	Return one member's render vertices across selected environments.
get_user_ids()	Return render user ids with shape [env, object].
reset([env_ids])	Reset the entity to its initial state.
set_collision_filter(filter_data[, env_ids])	Set one collision filter value for every selected member in each env.
set_com_pose(com_pose[, env_ids, obj_ids])	Set selected local COM poses in Group xyz + xyzw order.
set_inertia(inertia[, env_ids, obj_ids])	Set selected inertia diagonals.
set_local_pose(pose[, env_ids, obj_ids])	Set Group poses in xyz+xyzw or homogeneous-matrix form.
set_mass(mass[, env_ids, obj_ids])	Set selected masses from a tensor shaped [env, object].
set_physical_visible([visible, rgba])	Set collision-geometry visibility for every Group member.
set_visible([visible])	Set render visibility for every Group member.
set_visual_material(mat[, env_ids, ...])	Assign one material instance to all members in each selected env.

Attributes:

body_state	Pose and velocity with shape [env, object, 13].
is_declared	Whether this facade is waiting for Spawn materialization.
is_spawn_bound	Whether this facade is bound to a finalized Scene.

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

Create an unregistered rigid-object-group facade.

SpawnScene supplies the replicated instance count at declaration time and the finalized Scene at binding time.

attach_spawn_handles(entities)

Store env-major handles without initializing the group’s Batch data.

bind_spawn() creates the result-dependent runtime view after Spawn finalization.

Return type:

None

bind_spawn(result)

Atomically bind the declaration facade to env-major Spawn handles.

Return type:

None

property body_state: Tensor

Pose and velocity with shape [env, object, 13].

clear_dynamics(env_ids=None)

Clear velocity and one-step wrench buffers for selected envs.

Return type:

None

destroy()

Leave topology destruction to SimulationManager and Scene.

Return type:

None

get_com_pose(env_ids=None, obj_ids=None)

Return selected local COM poses in Group xyz + xyzw order.

Return type:

Tensor

get_inertia(env_ids=None, obj_ids=None)

Return selected inertia diagonals with shape [env, object, 3].

Return type:

Tensor

get_local_pose(to_matrix=False)

Return all Group poses as xyz+xyzw or homogeneous matrices.

Return type:

Tensor

get_mass(env_ids=None, obj_ids=None)

Return selected masses with shape [env, object].

Return type:

Tensor

get_object_triangles(object_id, env_ids=None)

Return one member’s render triangles across selected environments.

Return type:

Tensor

get_object_vertices(object_id, env_ids=None, scale=False)

Return one member’s render vertices across selected environments.

Return type:

Tensor

get_user_ids()

Return render user ids with shape [env, object].

Return type:

Tensor

property is_declared: bool

Whether this facade is waiting for Spawn materialization.

property is_spawn_bound: bool

Whether this facade is bound to a finalized Scene.

reset(env_ids=None)

Reset the entity to its initial state.

Parameters:

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

Return type:

None

set_collision_filter(filter_data, env_ids=None)

Set one collision filter value for every selected member in each env.

Return type:

None

set_com_pose(com_pose, env_ids=None, obj_ids=None)

Set selected local COM poses in Group xyz + xyzw order.

Return type:

None

set_inertia(inertia, env_ids=None, obj_ids=None)

Set selected inertia diagonals.

Return type:

None

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

Set Group poses in xyz+xyzw or homogeneous-matrix form.

Return type:

None

set_mass(mass, env_ids=None, obj_ids=None)

Set selected masses from a tensor shaped [env, object].

Return type:

None

set_physical_visible(visible=True, rgba=None)

Set collision-geometry visibility for every Group member.

Return type:

None

set_visible(visible=True)

Set render visibility for every Group member.

Return type:

None

set_visual_material(mat, env_ids=None, *, reset_properties=False)

Assign one material instance to all members in each selected env.

Parameters:

• mat (VisualMaterial) – Material template to assign.

• env_ids (Optional[Sequence[int]]) – Environments to change, or all environments.

• reset_properties (bool) – Explicitly restore template properties on selected instances, as required by deterministic material reset events.

Return type:

None

class embodichain.lab.sim.objects.RigidBodyGroupData

Bases: object

Expose one flat Scene rigid-body batch as [env, object, ...] tensors.

Methods:

__init__(body_view, *, num_instances, ...)
capture_default_physical_properties(*, mass, ...)	Capture backend-resolved Group mass properties exactly once.

Attributes:

com_pose	Current local COM poses in Group xyz + xyzw convention.
default_com_pose	Initialization-time local COM poses in xyz + xyzw order.
default_inertia	Initialization-time inertia diagonals.
default_mass	Initialization-time masses with shape [env, object].
default_physical_properties_initialized	Whether initialization-time mass properties are available.
inertia	Current inertia diagonals with shape [env, object, 3].
mass	Current masses with shape [env, object].
pose	Local poses in EmbodiChain xyz + xyzw order.
vel	Linear and angular velocities with shape [env, object, 6].

__init__(body_view, *, num_instances, num_objects, device)

capture_default_physical_properties(*, mass, inertia, com_pose)

Capture backend-resolved Group mass properties exactly once.

Return type:

None

property com_pose: Tensor

Current local COM poses in Group xyz + xyzw convention.

property default_com_pose: Tensor

Initialization-time local COM poses in xyz + xyzw order.

property default_inertia: Tensor

Initialization-time inertia diagonals.

property default_mass: Tensor

Initialization-time masses with shape [env, object].

property default_physical_properties_initialized: bool

Whether initialization-time mass properties are available.

property inertia: Tensor

Current inertia diagonals with shape [env, object, 3].

property mass: Tensor

Current masses with shape [env, object].

property pose: Tensor

Local poses in EmbodiChain xyz + xyzw order.

property vel: Tensor

Linear and angular velocities with shape [env, object, 6].

class embodichain.lab.sim.objects.RigidObjectGroupCfg

Bases: object

Configuration for a rigid object group asset in the simulation.

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

For example: ```python rigid_object_group: RigidObjectGroupCfg(

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

“template_obj”: RigidObjectCfg(

shape=MeshCfg(

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

), body_type=”dynamic”,

)

}

)

Attributes:

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

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

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

Body type for all rigid objects in the group.

ext: str

File extension for the rigid object assets.

This is only used when folder_path is specified.

folder_path: str | None

Path to the folder containing the rigid object assets.

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

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

RigidObjectGroupCfg

max_num: int

Maximum number of rigid objects to initialize from the folder.

This is only used when folder_path is specified.

rigid_objects: Dict[str, RigidObjectCfg]

Configuration for the rigid objects in the group.

Articulation

robot.body_data.fetch_state() reads joint position, joint velocity, root pose and root velocities together through DexSim’s batch state interface. Each call refreshes the values after stepping or state writes. The returned tensors reuse the data object’s buffers; clone tensors when keeping a past snapshot. Individual data properties remain available for single-field reads.

class embodichain.lab.sim.objects.Articulation

Bases: BatchEntity

Articulation represents a batch of articulations in the simulation.

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

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

Parameters:

• cfg (ArticulationCfg) – Configuration for the articulation.

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

Methods:

__init__(cfg[, device])	Create an unregistered articulation facade.
apply_render_material_inst(env_idx, ...[, ...])	Swap a dexsim MaterialInst onto a link's render-body segment for the given env.
attach_spawn_handles(entities)	Store handles and expose metadata without initializing Batch data.
bind_spawn(result)	Initialize this declared facade from Spawn articulation handles.
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_com_pose([link_names, env_ids])	Get local COM poses in EmbodiChain xyz + xyzw convention.
get_existing_visual_material([env_ids, ...])	Build reuse state from materials dexsim parsed onto each link's render body.
get_inertia([link_names, env_ids])	Get principal moments of inertia for selected links.
get_joint_drive([joint_ids, env_ids])	Get the drive properties for the articulation.
get_joint_drive_type([joint_ids, env_ids])	Get the portable drive type for the selected joints.
get_joint_target_mode([joint_ids, env_ids])	Get Newton JointTargetMode integer values by environment.
get_joint_type(joint_name)	Return the normalized backend-neutral type of one joint.
get_link_physical_attr([link_names, env_ids])	Get DexSim-native 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_newton_link_properties([link_names, env_ids])	Get Newton model mass properties as typed Spawn descriptors.
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, clear_dynamics])	Restore configured state for selected articulation instances.
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_com_pose(com_pose[, link_names, env_ids])	Set local COM poses in EmbodiChain xyz + xyzw convention.
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_inertia(inertia[, link_names, env_ids])	Set principal moments of inertia for selected links.
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_root_velocity(velocity[, env_ids])	Set root-link linear and angular velocity in world coordinates.
set_self_collision([enable, env_ids])	Set whether self-collision is enabled for the articulation.
set_state(*[, env_ids, joint_ids, ...])	Write selected physical state in one backend operation.
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.
default_link_masses	Initialization-time link masses retained for compatibility.
dof	Get the degree of freedom of the articulation.
is_declared	Whether this facade is waiting for its Scene binding.
is_spawn_bound	Whether this facade is bound to one finalized Scene.
joint_names	Get active joint names in public qpos-buffer order.
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, device=device(type='cpu'))

Create an unregistered articulation facade.

SpawnScene owns the replicated instance count and the finalized Scene. It injects them at declaration and binding time instead of exposing either lifecycle dependency through this constructor.

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_spawn_handles(entities)

Store handles and expose metadata without initializing Batch data.

This pre-finalize step supports eager Default loading and only reads articulation metadata. bind_spawn() performs result-dependent Batch/Data initialization after finalization.

Return type:

None

bind_spawn(result)

Initialize this declared facade from Spawn articulation handles.

Return type:

None

property body_data: ArticulationData

Get the rigid body data manager for this rigid object.

Returns:

The rigid body data manager.

Return type:

RigidBodyData

property body_state: Tensor

Get the body state of the articulation.

Returns:

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

Return type:

torch.Tensor

clear_dynamics(env_ids=None)

Clear the dynamics of the articulation.

Parameters:

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

Return type:

None

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

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

Parameters:

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

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

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

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

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

• 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')

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

Parameters:

• qpos (Tensor | ndarray | None) – Joint positions with shape (dof,) or (batch_size, dof) in public joint_names order. The selected chain’s joint values are extracted and reordered by name. A narrower vector containing exactly the serial chain’s joints is also accepted in serial-chain parameter order. When both widths match, public state order takes precedence. None evaluates the zero state.

• 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) – full returns all six rows; trans returns the translational rows and rot the rotational rows. Defaults to full.

Raises:

• RuntimeError – If the pk_chain is not initialized.

• ValueError – If jac_type is invalid, the joint-state shape does not match the articulation or selected chain, or the chain contains joint names absent from the public state.

Return type:

Tensor

Returns:

Jacobian with shape (batch_size, 6, chain_dof) for full or (batch_size, 3, chain_dof) for trans/rot. A one-dimensional input has batch size one. Columns follow the selected serial chain’s get_joint_parameter_names() order, not the public state order; sibling joints outside the selected chain have no columns.

property default_link_masses: Tensor

Initialization-time link masses retained for compatibility.

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

property dof: int

Get the degree of freedom of the articulation.

Returns:

The degree of freedom of the articulation.

Return type:

int

get_com_pose(link_names=None, env_ids=None)

Get local COM poses in EmbodiChain xyz + xyzw convention.

Return type:

Tensor

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_inertia(link_names=None, env_ids=None)

Get principal moments of inertia for selected links.

Return type:

Tensor

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 portable 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:

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

Newton has no acceleration-drive equivalent. Its passive and direct-effort target modes map to DriveType.NONE because neither installs a PD drive; position and velocity target modes map to DriveType.FORCE.

get_joint_target_mode(joint_ids=None, env_ids=None)

Get Newton JointTargetMode integer values by environment.

Parameters:

• joint_ids (Optional[Sequence[int]]) – Flattened DOF indices. If None, all DOFs are queried.

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

Return type:

list[list[int]]

Returns:

Integer target modes grouped by selected environment.

get_joint_type(joint_name)

Return the normalized backend-neutral type of one joint.

The native joint descriptor is resolved through the active backend adapter and is not exposed to callers. Returned values are lowercase names such as "fixed", "revolute", or "prismatic".

Parameters:

joint_name (str) – Name of the joint to query.

Return type:

str

Returns:

The normalized lowercase joint type.

Raises:

• TypeError – If joint_name is not a non-empty string.

• ValueError – If the joint is unknown or has no type descriptor.

get_link_physical_attr(link_names=None, env_ids=None)

Get DexSim-native 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).

Attention

PhysicalAttr.com_quaternion uses DexSim’s native wxyz order. Use get_com_pose() when an EmbodiChain xyz + xyzw tensor is required.

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, qx, qy, qz, qw). 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, qx, qy, qz, qw). 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 (Union[str, Sequence[str], None]) – Link names to query. If None, all links are returned.

• env_ids (Union[Sequence[int], Tensor, None]) – Environment indices. If None, all rows are returned.

Return type:

Tensor

Returns:

Selected link masses with shape (num_envs, num_links).

get_newton_link_properties(link_names=None, env_ids=None)

Get Newton model mass properties as typed Spawn descriptors.

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 environment 0 is queried.

Return type:

list[RigidBodyPhysicsDesc]

Returns:

One typed descriptor per selected (environment, link) pair in environment-major order.

Attention

The returned Spawn descriptor stores a body-frame (3, 3) inertia tensor and COM position, with no separate quaternion. Use get_com_pose() for the EmbodiChain xyz + xyzw view.

get_parent_joint_chain(link_name)

Return the joints from a link toward the articulation root.

The immediate parent joint is first. Backend-native joint-info values or Newton’s backend-neutral joint descriptors 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()

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)

Get joint effort limits for selected environments and joints.

Parameters:

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

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

Returns:

Joint effort limits with shape (num_envs, num_joints).

Return type:

torch.Tensor

get_qpos(target=False)

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

Parameters:

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

Returns:

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

Return type:

torch.Tensor

get_qpos_limits(joint_ids=None, env_ids=None)

Get joint position limits for selected environments and joints.

Parameters:

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

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

Returns:

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

Return type:

torch.Tensor

get_qvel(target=False)

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

Parameters:

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

Returns:

The current velocities of the articulation.

Return type:

torch.Tensor

get_qvel_limits(joint_ids=None, env_ids=None)

Get joint velocity limits for selected environments and joints.

Parameters:

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

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

Returns:

Joint velocity limits with shape (num_envs, num_joints).

Return type:

torch.Tensor

get_user_ids(link_name=None, env_ids=None)

Get the user ids of the articulation.

Parameters:

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

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

Returns:

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

Return type:

torch.Tensor

get_visual_material_inst(env_ids=None, link_names=None)

Get visual material instances for the rigid object.

Parameters:

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

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

Returns:

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

Return type:

List[Dict[str, VisualMaterialInst]]

property is_declared: bool

Whether this facade is waiting for its Scene binding.

property is_spawn_bound: bool

Whether this facade is bound to one finalized Scene.

property joint_names: List[str]

Get active joint names in public qpos-buffer order.

Returns:

Active joint names aligned with qpos, qvel, and qf.

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, *, clear_dynamics=True)

Restore configured state for selected articulation instances.

State writes and Scene kinematics publish the restored state without advancing physics, preserving motion in unselected instances and other scene objects.

Parameters:

• env_ids (Optional[Sequence[int]]) – Environment indices to reset. Defaults to all instances.

• clear_dynamics (bool) – Whether to clear native dynamics immediately. The simulation manager disables this only while coordinating one Newton clear across every articulation in selected worlds.

Return type:

None

restore_visual_material(env_ids=None, link_names=None)

Restore visual materials captured when the articulation was created.

Parameters:

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

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

Return type:

None

property root_link_name: str

Get the name of the root link of the articulation.

Returns:

The name of the root link.

Return type:

str

property root_state: Tensor

Get the root state of the articulation.

Returns:

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

Return type:

torch.Tensor

set_collision_filter(filter_data, env_ids=None)

set collision filter data for the rigid object.

Parameters:

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

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

Return type:

None

set_com_pose(com_pose, link_names=None, env_ids=None)

Set local COM poses in EmbodiChain xyz + xyzw convention.

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_inertia(inertia, link_names=None, env_ids=None)

Set principal moments of inertia for selected links.

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, *, target_mode=None)

Set the drive properties for the articulation.

Parameters:

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

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

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

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

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

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

• drive_type (str | None) – force, acceleration, or none. None preserves the current mode unless a target mode activates a force drive.

• 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.

• target_mode (str | int | None) – Portable target mode: none, position, velocity, position_velocity, effort, or integer value 0 through 4.

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 (RigidBodyPhysicsCfg | PhysicalAttr) – Grouped 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 (RigidBodyPhysicsCfg | None) – Base config used when attrs is a partial override.

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

Return type:

None

Attention

This compatibility API exposes DexSim PhysicalAttr semantics. Pass a RigidBodyPhysicsCfg for EmbodiChain xyz + xyzw COM values; a supplied PhysicalAttr must keep DexSim’s native wxyz quaternion order. Newton properties must use typed Spawn descriptors.

set_local_pose(pose, env_ids=None)

Set local pose of the articulation.

The pose write does not advance physics or move other scene objects.

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=None, env_ids=None)

Set the mass of specific links in the articulation.

Parameters:

• mass (Tensor) – Mass values with shape (num_envs, num_links).

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

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

Return type:

None

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

set collision

Parameters:

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

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

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

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

Set the generalized efforts (qf) of the articulation.

Parameters:

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

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

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

Return type:

None

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

Set joint effort limits for selected environments and joints.

Parameters:

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

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

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

Return type:

None

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

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

Parameters:

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

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

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

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

Raises:

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

Return type:

None

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

Set joint position limits for selected environments and joints.

Parameters:

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

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

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

Return type:

None

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

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

Parameters:

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

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

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

• True (If)

• False (sets target positions for simulation. If)

• directly. (updates current positions)

Raises:

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

Return type:

None

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

Set joint velocity limits for selected environments and joints.

Parameters:

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

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

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

Return type:

None

set_root_velocity(velocity, env_ids=None)

Set root-link linear and angular velocity in world coordinates.

Default snapshots both components and attempts to restore them if a native write fails. A failed restoration raises a rollback error chained from the original write error. Newton validates both components before writing through the batch API; execution failures do not roll back state.

Parameters:

• velocity (Tensor) – Selected root velocities with shape (N, 6); linear velocity precedes angular velocity.

• env_ids (Union[Sequence[int], Tensor, None]) – Selected environment rows, or all rows when omitted.

Raises:

ValueError – The input shape does not match the selected rows.

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_state(*, env_ids=None, joint_ids=None, root_pose=None, qpos=None, target_qpos=None, qvel=None, target_qvel=None, qf=None, root_velocity=None, clear_dynamics=False)

Write selected physical state in one backend operation.

Parameters:

• env_ids (Union[Sequence[int], Tensor, None]) – Environment rows; None selects all environments.

• joint_ids (Union[Sequence[int], Tensor, None]) – Joint columns for all supplied joint tensors.

• root_pose (Tensor | None) – Environment-local xyz + xyzw, shape (N, 7).

• qpos (Tensor | None) – Current joint positions, shape (N, J), clipped to limits.

• target_qpos (Tensor | None) – Position targets, shape (N, J), clipped to limits.

• qvel (Tensor | None) – Current joint velocities, shape (N, J).

• target_qvel (Tensor | None) – Velocity targets, shape (N, J).

• qf (Tensor | None) – Generalized joint efforts, shape (N, J).

• root_velocity (Tensor | None) – Root world linear + angular velocity, shape (N, 6).

• clear_dynamics (bool) – Clear velocities, forces and solver history for selected environments and hold their final joint positions. Explicit fields override these defaults.

Return type:

None

Unspecified positions and unselected environments retain their values. Scene backends validate all field shapes before changing physics state. Joint/root positions are propagated after the final fields are written.

Raises:

• ValueError – A supplied field has an incompatible shape.

• RuntimeError – The backend cannot write the selected state.

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.ArticulationJointKinematics

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

Bases: object

Scene-batch data manager for articulations.

Methods:

__init__(entities, scene, device)	Initialize the ArticulationData.
capture_default_physical_properties(*, mass, ...)	Capture backend-resolved link mass properties exactly once.
fetch_state()	Read current joint and root state together into reusable buffers.
read_physical_properties()	Refresh current mass, inertia diagonal, and local COM pose buffers.

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.
com_pose	Current local link COM poses as xyz + xyzw tensors.
default_com_pose	Initialization-time local link COM poses in xyz + xyzw order.
default_inertia	Initialization-time link inertia diagonals.
default_mass	Initialization-time link masses with shape (N, num_links).
default_physical_properties_initialized	Whether initialization-time link mass properties are available.
inertia	Current link inertia diagonals with shape (N, num_links, 3).
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.
mass	Current link masses with shape (N, num_links).
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, scene, device)

Initialize the ArticulationData.

Parameters:

• entities (Sequence[SpawnedArticulation]) – Articulation handles owned by scene.

• scene (Scene) – Finalized DexSim Scene.

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

property body_link_pose: Tensor

Get the pose of all links in the articulation.

Returns:

Link poses with shape (N, num_links, 7) in (x, y, z, qx, qy, qz, qw) order.

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

capture_default_physical_properties(*, mass, inertia, com_pose)

Capture backend-resolved link mass properties exactly once.

Return type:

None

property com_pose: Tensor

Current local link COM poses as xyz + xyzw tensors.

property default_com_pose: Tensor

Initialization-time local link COM poses in xyz + xyzw order.

property default_inertia: Tensor

Initialization-time link inertia diagonals.

property default_mass: Tensor

Initialization-time link masses with shape (N, num_links).

property default_physical_properties_initialized: bool

Whether initialization-time link mass properties are available.

fetch_state()

Read current joint and root state together into reusable buffers.

Return type:

dict[str, Tensor]

Returns:

A mapping with qpos, qvel, root_pose, root_lin_vel, and root_ang_vel. Poses use xyz + xyzw and root velocities are in the world frame. Tensor storage belongs to this data object and is overwritten by subsequent reads of the same fields. Clone a returned tensor when retaining a historical snapshot.

This call always fetches live data; it does not reuse a previous step’s values. Scene views delegate to DexSim’s batched state reader.

property inertia: Tensor

Current link inertia diagonals with shape (N, num_links, 3).

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 mass: Tensor

Current link masses with shape (N, num_links).

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

read_physical_properties()

Refresh current mass, inertia diagonal, and local COM pose buffers.

COM poses use the EmbodiChain convention xyz + xyzw and all tensors use the public link ordering. Legacy DexSim physical attributes use wxyz and are converted at this boundary. Newton reads use the Scene batch to avoid per-link device-to-host transfers.

Return type:

tuple[Tensor, Tensor, 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:

Root poses with shape (num_instances, 7) in (x, y, z, qx, qy, qz, qw) order.

Return type:

torch.Tensor

property root_vel: Tensor

Get the velocity of the root link of the articulation.

Returns:

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

Return type:

torch.Tensor

property target_qpos: Tensor

Get the target positions (target_qpos) of the articulation.

Returns:

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

Return type:

torch.Tensor

property target_qvel: Tensor

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

class embodichain.lab.sim.objects.ArticulationCfg

Bases: ObjectBaseCfg

Configuration for an articulation asset in the simulation.

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

Attributes:

asset_physics_mode	How source-authored articulation physics is handled.
attrs	Physical attributes for all links.
body_scale	Scale of the articulation in the simulation world frame.
build_pk_chain	Build a pytorch-kinematics chain for FK and Jacobian computation.
compute_uv	Whether to compute the UV mapping for the articulation link.
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.
joint_drive_props	Optional joint-drive and joint-dynamics overrides.
link_attrs	Named per-link physics override groups keyed by regex on link names.
qpos_limits	Override joint position limits of the articulation.
root_props	Grouped articulation-root properties.
source	USD source asset; mutually exclusive with fpath.

Methods:

from_dict(init_dict)	Initialize the configuration from a dictionary.
resolve_asset_physics_mode()	Return the effective file-backed physics policy.

asset_physics_mode: Literal['preserve', 'overlay']

How source-authored articulation physics is handled.

"preserve" keeps link, joint-drive, and joint-limit properties from either USD or URDF. "overlay" applies only explicitly configured values after the source has been resolved.

Import policy such as root fixation and body scale remains controlled by root_props and body_scale.

attrs: RigidBodyPhysicsCfg

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

Build a pytorch-kinematics chain for FK and Jacobian computation.

USD assets use resolved simulation joint descriptors after preparation; URDF assets use their source kinematic tree. USD kinematics supports trees of fixed, revolute, and prismatic joints, including child-side joint frames. Set False to load other joint topologies for simulation without FK.

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.

fpath: str

Path to the articulation asset file.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

ArticulationCfg

init_local_pose: ndarray | None

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

init_pos: tuple[float, float, float]

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

init_qpos: 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 an array of shape (num_dofs,).

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).

joint_drive_props: JointDrivePropertiesCfg | None

Optional joint-drive and joint-dynamics overrides.

None preserves source drive properties. Individual None fields in a provided config also preserve the corresponding source values.

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.

qpos_limits: Union[Tensor, ndarray, Sequence[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_dofs, 2), it is applied in flattened source-resolved DOF order before the backend model is built. 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.

resolve_asset_physics_mode()

Return the effective file-backed physics policy.

Return type:

Literal['preserve', 'overlay']

root_props: ArticulationRootPropertiesCfg

Grouped articulation-root properties.

Fixed-base and self-collision intent is portable. Root sleep and solver iterations are Default-only fields and are ignored by Newton. The portable fields default to a fixed base with self-collision disabled. Set either field to None to preserve an authored USD/backend value; URDF imports then use the established fixed-base, self-collision-off defaults.

source: UsdSourceCfg | None = None

USD source asset; mutually exclusive with fpath.

Robot

class embodichain.lab.sim.objects.Robot

Bases: Articulation

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

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

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

• solvers: Specify the kinematic solvers for the robot.

• planners: Specify the motion planner for the robot.

Methods:

__init__(cfg[, device])	Create an unregistered robot facade.
apply_render_material_inst(env_idx, ...[, ...])	Swap a dexsim MaterialInst onto a link's render-body segment for the given env.
attach_spawn_handles(entities)	Store handles and expose robot metadata without creating Batch data.
attach_workspace(workspace[, name])	Attach a runtime workspace to a control part.
bind_spawn(result)	Initialize this declared facade from Spawn articulation handles.
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 batched inverse kinematics for arena-frame poses.
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_com_pose([link_names, env_ids])	Get local COM poses in EmbodiChain xyz + xyzw convention.
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_inertia([link_names, env_ids])	Get principal moments of inertia for selected links.
get_joint_drive([joint_ids, env_ids])	Get the drive properties for the articulation.
get_joint_drive_type([joint_ids, env_ids])	Get the portable 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_joint_target_mode([joint_ids, env_ids])	Get Newton JointTargetMode integer values by environment.
get_joint_type(joint_name)	Return the normalized backend-neutral type of one joint.
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 DexSim-native 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_newton_link_properties([link_names, env_ids])	Get Newton model mass properties as typed Spawn descriptors.
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, clear_dynamics])	Restore configured state for selected articulation instances.
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_com_pose(com_pose[, link_names, env_ids])	Set local COM poses in EmbodiChain xyz + xyzw convention.
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_inertia(inertia[, link_names, env_ids])	Set principal moments of inertia for selected links.
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_root_velocity(velocity[, env_ids])	Set root-link linear and angular velocity in world coordinates.
set_self_collision([enable, env_ids])	Set whether self-collision is enabled for the articulation.
set_state(*[, env_ids, joint_ids, ...])	Write selected physical state in one backend operation.
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.
default_link_masses	Initialization-time link masses retained for compatibility.
dof	Get the degree of freedom of the articulation.
is_declared	Whether this facade is waiting for its Scene binding.
is_spawn_bound	Whether this facade is bound to one finalized Scene.
joint_names	Get active joint names in public qpos-buffer order.
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, device=device(type='cpu'))

Create an unregistered robot facade.

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_spawn_handles(entities)

Store handles and expose robot metadata without creating Batch data.

Runtime Batch/Data initialization remains the responsibility of bind_spawn() after Spawn finalization.

Return type:

None

attach_workspace(workspace, name=None)

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

bind_spawn(result)

Initialize this declared facade from Spawn articulation handles.

Return type:

None

property body_data: ArticulationData

Get the rigid body data manager for this rigid object.

Returns:

The rigid body data manager.

Return type:

RigidBodyData

property body_state: Tensor

Get the body state of the articulation.

Returns:

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

Return type:

torch.Tensor

build_pk_serial_chain()

Build the kinematic serial chain for the robot.

Return type:

None

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

• Imitation learning dataset generation.

clear_dynamics(env_ids=None)

Clear the dynamics of the articulation.

Parameters:

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

Return type:

None

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

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

Parameters:

• qpos (torch.Tensor | np.ndarray | None) – Joint positions of the robot, (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) in xyz + xyzw order, 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, *, continuous=False)

Compute batched inverse kinematics for arena-frame poses.

When continuous is enabled, all solver candidates are generated in one solver call and the branch nearest to the previous path sample is selected sequentially. The selected solver must support continuous candidate selection.

Parameters:

• pose (Tensor | ndarray) – End-effector poses shaped (B, N, 7) or (B, N, 4, 4) in the local arena frame.

• joint_seed (Tensor | ndarray | None) – Independent seeds shaped (B, N, DOF). In continuous mode, the initial path seed shaped (B, DOF). Defaults to zero independent seeds when omitted.

• name (str) – Control part whose solver should be used.

• env_ids (Optional[Sequence[int]]) – Optional environment indices. Defaults to all environments.

• continuous (bool) – Preserve one temporally continuous IK branch across the N path samples. Defaults to False.

Return type:

tuple[Tensor, Tensor] | None

Returns:

Per-sample success shaped (B, N) and joint positions shaped (B, N, DOF), or None when no solver is configured.

Raises:

ValueError – If an input shape is invalid or continuous selection is unsupported by the configured solver.

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)

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) in (x, y, z, qx, qy, qz, qw) order, 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)

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 as (num_envs, 7) in (x, y, z, qx, qy, qz, qw) order 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 (Tensor | ndarray | None) – Joint positions with shape (dof,) or (batch_size, dof) in public joint_names order. The selected chain’s joint values are extracted and reordered by name. A narrower vector containing exactly the serial chain’s joints is also accepted in serial-chain parameter order. When both widths match, public state order takes precedence. None evaluates the zero state.

• 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) – full returns all six rows; trans returns the translational rows and rot the rotational rows. Defaults to full.

Raises:

• RuntimeError – If the pk_chain is not initialized.

• ValueError – If jac_type is invalid, the joint-state shape does not match the articulation or selected chain, or the chain contains joint names absent from the public state.

Return type:

Tensor

Returns:

Jacobian with shape (batch_size, 6, chain_dof) for full or (batch_size, 3, chain_dof) for trans/rot. A one-dimensional input has batch size one. Columns follow the selected serial chain’s get_joint_parameter_names() order, not the public state order; sibling joints outside the selected chain have no columns.

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

Get the control parts of the robot.

property default_link_masses: Tensor

Initialization-time link masses retained for compatibility.

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

property dof: int

Get the degree of freedom of the articulation.

Returns:

The degree of freedom of the articulation.

Return type:

int

get_com_pose(link_names=None, env_ids=None)

Get local COM poses in EmbodiChain xyz + xyzw convention.

Return type:

Tensor

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

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

Parameters:

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

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

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

Return type:

Tensor

Returns:

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

get_control_part_link_names(name=None)

Get the link names of the control part.

Parameters:

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

Returns:

link names of the control part.

Return type:

List[str]

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

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

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

Parameters:

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

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

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

Return type:

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

Returns:

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

Raises:

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

get_inertia(link_names=None, env_ids=None)

Get principal moments of inertia for selected links.

Return type:

Tensor

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 portable 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:

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

Newton has no acceleration-drive equivalent. Its passive and direct-effort target modes map to DriveType.NONE because neither installs a PD drive; position and velocity target modes map to DriveType.FORCE.

get_joint_ids(name=None, remove_mimic=False)

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

Parameters:

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

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

Returns:

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

Return type:

List[int]

get_joint_target_mode(joint_ids=None, env_ids=None)

Get Newton JointTargetMode integer values by environment.

Parameters:

• joint_ids (Optional[Sequence[int]]) – Flattened DOF indices. If None, all DOFs are queried.

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

Return type:

list[list[int]]

Returns:

Integer target modes grouped by selected environment.

get_joint_type(joint_name)

Return the normalized backend-neutral type of one joint.

The native joint descriptor is resolved through the active backend adapter and is not exposed to callers. Returned values are lowercase names such as "fixed", "revolute", or "prismatic".

Parameters:

joint_name (str) – Name of the joint to query.

Return type:

str

Returns:

The normalized lowercase joint type.

Raises:

• TypeError – If joint_name is not a non-empty string.

• ValueError – If the joint is unknown or has no type descriptor.

get_link_names(name=None)

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

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

Parameters:

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

Returns:

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

Return type:

List[str]

get_link_physical_attr(link_names=None, env_ids=None)

Get DexSim-native 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).

Attention

PhysicalAttr.com_quaternion uses DexSim’s native wxyz order. Use get_com_pose() when an EmbodiChain xyz + xyzw tensor is required.

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, qx, qy, qz, qw). 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, qx, qy, qz, qw). 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 (Union[str, Sequence[str], None]) – Link names to query. If None, all links are returned.

• env_ids (Union[Sequence[int], Tensor, None]) – Environment indices. If None, all rows are returned.

Return type:

Tensor

Returns:

Selected link masses with shape (num_envs, num_links).

get_newton_link_properties(link_names=None, env_ids=None)

Get Newton model mass properties as typed Spawn descriptors.

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 environment 0 is queried.

Return type:

list[RigidBodyPhysicsDesc]

Returns:

One typed descriptor per selected (environment, link) pair in environment-major order.

Attention

The returned Spawn descriptor stores a body-frame (3, 3) inertia tensor and COM position, with no separate quaternion. Use get_com_pose() for the EmbodiChain xyz + xyzw view.

get_parent_joint_chain(link_name)

Return the joints from a link toward the articulation root.

The immediate parent joint is first. Backend-native joint-info values or Newton’s backend-neutral joint descriptors 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()

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

The default proprioception information includes:

• qpos: Joint positions.

• qvel: Joint velocities.

• qf: Joint efforts.

Returns:

A dictionary containing the robot’s proprioception information

Return type:

Dict[str, torch.Tensor]

get_qf(name=None)

Get the joint efforts (qf) of the robot.

Parameters:

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

Returns:

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

Return type:

torch.Tensor

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

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

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

Parameters:

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

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

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

Returns:

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

Return type:

torch.Tensor

get_qpos(name=None, target=False)

Get the joint positions (qpos) of the robot.

Parameters:

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

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

Returns:

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

Return type:

torch.Tensor

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

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

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

Parameters:

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

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

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

Returns:

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

Return type:

torch.Tensor

get_qvel(name=None, target=False)

Get the joint velocities (qvel) of the robot.

Parameters:

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

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

Returns:

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

Return type:

torch.Tensor

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

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

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

Parameters:

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

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

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

Returns:

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

Return type:

torch.Tensor

get_solver(name=None)

Get the kinematic solver for a specific control part.

Parameters:

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

Returns:

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

Return type:

BaseSolver | None

get_user_ids(link_name=None, env_ids=None)

Get the user ids of the articulation.

Parameters:

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

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

Returns:

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

Return type:

torch.Tensor

get_visual_material_inst(env_ids=None, link_names=None)

Get visual material instances for the rigid object.

Parameters:

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

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

Returns:

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

Return type:

List[Dict[str, VisualMaterialInst]]

get_workspace(name=None)

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)

Initialize the kinematic solver for the robot.

Parameters:

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

Return type:

None

property is_declared: bool

Whether this facade is waiting for its Scene binding.

property is_spawn_bound: bool

Whether this facade is bound to one finalized Scene.

property joint_names: List[str]

Get active joint names in public qpos-buffer order.

Returns:

Active joint names aligned with qpos, qvel, and qf.

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, *, clear_dynamics=True)

Restore configured state for selected articulation instances.

State writes and Scene kinematics publish the restored state without advancing physics, preserving motion in unselected instances and other scene objects.

Parameters:

• env_ids (Optional[Sequence[int]]) – Environment indices to reset. Defaults to all instances.

• clear_dynamics (bool) – Whether to clear native dynamics immediately. The simulation manager disables this only while coordinating one Newton clear across every articulation in selected worlds.

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)

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_com_pose(com_pose, link_names=None, env_ids=None)

Set local COM poses in EmbodiChain xyz + xyzw convention.

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_inertia(inertia, link_names=None, env_ids=None)

Set principal moments of inertia for selected links.

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, *, target_mode=None)

Set the drive properties for the robot.

With no explicit mode, robots retain their position+velocity force drive default.

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 | None) – Drive type 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.

• target_mode (str | int | None) – Portable target mode name or integer value 0 through 4.

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 (RigidBodyPhysicsCfg | PhysicalAttr) – Grouped 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 (RigidBodyPhysicsCfg | None) – Base config used when attrs is a partial override.

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

Return type:

None

Attention

This compatibility API exposes DexSim PhysicalAttr semantics. Pass a RigidBodyPhysicsCfg for EmbodiChain xyz + xyzw COM values; a supplied PhysicalAttr must keep DexSim’s native wxyz quaternion order. Newton properties must use typed Spawn descriptors.

set_local_pose(pose, env_ids=None)

Set local pose of the articulation.

The pose write does not advance physics or move other scene objects.

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=None, env_ids=None)

Set the mass of specific links in the articulation.

Parameters:

• mass (Tensor) – Mass values with shape (num_envs, num_links).

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

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

Return type:

None

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

set collision of the robot or a specific control part.

Parameters:

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

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

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

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

Set the joint efforts (qf) for the articulation.

Parameters:

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

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

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

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

Raises:

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

Return type:

None

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

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

Parameters:

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

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

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

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

Return type:

None

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

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

Parameters:

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

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

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

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

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

Raises:

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

Return type:

None

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

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

Parameters:

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

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

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

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

Return type:

None

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

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

Parameters:

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

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

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

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

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

Raises:

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

Return type:

None

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

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

Parameters:

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

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

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

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

Return type:

None

set_root_velocity(velocity, env_ids=None)

Set root-link linear and angular velocity in world coordinates.

Default snapshots both components and attempts to restore them if a native write fails. A failed restoration raises a rollback error chained from the original write error. Newton validates both components before writing through the batch API; execution failures do not roll back state.

Parameters:

• velocity (Tensor) – Selected root velocities with shape (N, 6); linear velocity precedes angular velocity.

• env_ids (Union[Sequence[int], Tensor, None]) – Selected environment rows, or all rows when omitted.

Raises:

ValueError – The input shape does not match the selected rows.

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_state(*, env_ids=None, joint_ids=None, root_pose=None, qpos=None, target_qpos=None, qvel=None, target_qvel=None, qf=None, root_velocity=None, clear_dynamics=False)

Write selected physical state in one backend operation.

Parameters:

• env_ids (Union[Sequence[int], Tensor, None]) – Environment rows; None selects all environments.

• joint_ids (Union[Sequence[int], Tensor, None]) – Joint columns for all supplied joint tensors.

• root_pose (Tensor | None) – Environment-local xyz + xyzw, shape (N, 7).

• qpos (Tensor | None) – Current joint positions, shape (N, J), clipped to limits.

• target_qpos (Tensor | None) – Position targets, shape (N, J), clipped to limits.

• qvel (Tensor | None) – Current joint velocities, shape (N, J).

• target_qvel (Tensor | None) – Velocity targets, shape (N, J).

• qf (Tensor | None) – Generalized joint efforts, shape (N, J).

• root_velocity (Tensor | None) – Root world linear + angular velocity, shape (N, 6).

• clear_dynamics (bool) – Clear velocities, forces and solver history for selected environments and hold their final joint positions. Explicit fields override these defaults.

Return type:

None

Unspecified positions and unselected environments retain their values. Scene backends validate all field shapes before changing physics state. Joint/root positions are propagated after the final fields are written.

Raises:

• ValueError – A supplied field has an incompatible shape.

• RuntimeError – The backend cannot write the selected state.

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

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>, body_scale: ‘tuple | list’ = <factory>, compute_uv: ‘bool’ = <factory>, asset_physics_mode: ‘AssetPhysicsMode’ = <factory>, attrs: ‘RigidBodyPhysicsCfg’ = <factory>, link_attrs: ‘dict[str, LinkPhysicsOverrideCfg] | None’ = <factory>, root_props: ‘ArticulationRootPropertiesCfg’ = <factory>, joint_drive_props: ‘JointDrivePropertiesCfg’ = <factory>, init_qpos: ‘torch.Tensor | np.ndarray | Sequence[float]’ = <factory>, qpos_limits: ‘torch.Tensor | np.ndarray | Sequence[Sequence[float]] | Dict[str, List[float]] | None’ = <factory>, build_pk_chain: ‘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>, sensors: ‘list[SensorCfg]’ = <factory>, enable_sensor: ‘bool’ = <factory>, *, source: ‘UsdSourceCfg | None’ = None)

Classes:

SolverCfg

Configuration for the kinematic solver used in the robot simulation.

Attributes:

asset_physics_mode	Apply configured robot physics on top of source-authored values.
attrs	Physical attributes for all links.
body_scale	Scale of the articulation in the simulation world frame.
build_pk_chain	Build a pytorch-kinematics chain for FK 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.
enable_sensor	Initialize mounted sensors when adding the robot.
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.
joint_drive_props	Joint drive, limit, friction, and armature properties.
link_attrs	Named per-link physics override groups keyed by regex on link names.
qpos_limits	Override joint position limits of the articulation.
root_props	Grouped articulation-root properties.
sensors	Mounted camera configurations with robot-local parent link names.
solver_cfg	Solver is used to compute forward and inverse kinematics for the robot.
source	USD source asset; mutually exclusive with fpath.
urdf_cfg	URDF assembly configuration which allows for assembling a robot from multiple URDF components.
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.
resolve_asset_physics_mode()	Return the effective file-backed physics policy.
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. It must be a finite SE(3) rigid transform; affine transforms are not supported.

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.

asset_physics_mode: AssetPhysicsMode

Apply configured robot physics on top of source-authored values.

attrs: RigidBodyPhysicsCfg

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

Build a pytorch-kinematics chain for FK and Jacobian computation.

USD assets use resolved simulation joint descriptors after preparation; URDF assets use their source kinematic tree. USD kinematics supports trees of fixed, revolute, and prismatic joints, including child-side joint frames. Set False to load other joint topologies for simulation without FK.

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

Build the serial chain from the URDF file.

Note

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

Parameters:

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

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

Returns:

The serial chain of the robot for specified control part.

Return type:

Dict[str, pk.SerialChain]

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

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

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

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

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

Official defaults use arm / eef for single-arm robots and left_arm, right_arm, left_eef, right_eef for dual-arm robots. These are naming conventions only: caller-defined part names are preserved without reserved names, automatic aliases, or inferred capabilities.

Note

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

  keys corresponding to the control parts name.

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

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

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

  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.

enable_sensor: bool

Initialize mounted sensors when adding the robot. Gym overrides this with its environment-wide acquisition switch, which defaults to True.

fpath: str

Path to the articulation asset file.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

RobotCfg

init_local_pose: np.ndarray | None

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

init_pos: tuple[float, float, float]

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

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

Initial joint positions of the articulation.

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

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).

joint_drive_props: JointDrivePropertiesCfg

Joint drive, limit, friction, and armature properties.

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.

qpos_limits: torch.Tensor | np.ndarray | Sequence[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_dofs, 2), it is applied in flattened source-resolved DOF order before the backend model is built. 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.

resolve_asset_physics_mode()

Return the effective file-backed physics policy.

Return type:

Literal['preserve', 'overlay']

root_props: ArticulationRootPropertiesCfg

Grouped articulation-root properties.

Fixed-base and self-collision intent is portable. Root sleep and solver iterations are Default-only fields and are ignored by Newton. The portable fields default to a fixed base with self-collision disabled. Set either field to None to preserve an authored USD/backend value; URDF imports then use the established fixed-base, self-collision-off defaults.

save_to_file(filepath)

Save config to a local file as JSON.

sensors: list[SensorCfg]

Mounted camera configurations with robot-local parent link names.

An explicit list replaces the robot’s default suite; an empty list clears it. Sensor UIDs must be unique in the simulation. Runtime parent binding uses a copy, preserving these local calibration declarations.

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

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

source: UsdSourceCfg | None = None

USD source asset; mutually exclusive with fpath.

to_string()

Return config as a JSON string.

urdf_cfg: URDFCfg | None

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

workspace_cfg: Dict[str, RobotWorkspaceCfg] | None

Runtime workspace cache configuration keyed by control-part name.

class embodichain.lab.sim.objects.RobotWorkspaceCfg

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

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)

begin_interaction(source_id)

Acquire this Gizmo for one Viser drag source.

Return type:

bool

cancel_interaction(source_prefix=None)

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()

Release target and IK references.

Return type:

None

detach_native_window()

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

Return type:

None

end_interaction(source_id)

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

Return type:

bool

get_control_pose()

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

Return type:

Tensor

is_visible()

Return the active native visibility or configured Viser visibility.

Return type:

bool

request_local_pose(pose, *, source_id)

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

Return type:

bool

set_visible(visible)

Set Gizmo visibility, including an activated native controller.

Return type:

None

property target_type: str

Return rigid_object, robot, or camera.

toggle_visibility()

Toggle Gizmo visibility and return the new state.

Return type:

bool

update()

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

Return type:

None

update_native(world)

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

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)

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

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)

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)

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)

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)

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)

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.

Backend Views

Backend views normalize tensor layouts and row selection over backend-neutral DexSim Scene batches. The package import path exposes the common contracts, Scene adapters, and the Newton Scene predicate. Scene*View.from_entities() owns Scene batch creation so object facades do not depend directly on DexSim’s batch-factory signatures.

ArticulationViewBase	Abstract interface for physics-backend articulation data access.
RigidBodyViewBase	Abstract interface for physics-backend rigid body data access.
is_newton_scene(scene)	Return whether an object is a current DexSim Newton Scene.
SceneArticulationView	Backend-neutral articulation state view backed by ArticulationBatch.
SceneRigidBodyView	Backend-neutral rigid-body view backed by RigidBodyBatch.

class embodichain.lab.sim.objects.backends.ArticulationViewBase

Abstract interface for physics-backend articulation data access.

Public root/link poses use EmbodiChain convention: (x, y, z, qx, qy, qz, qw).

Methods:

apply_qf(qf, env_ids, joint_ids)	Apply joint forces for selected envs and joints.
apply_qpos(qpos, env_ids, joint_ids, *, target)	Apply joint positions for selected envs and joints.
apply_qvel(qvel, env_ids, joint_ids, *, target)	Apply joint velocities for selected envs and joints.
apply_root_pose(pose, env_ids)	Apply root poses from EmbodiChain xyz + xyzw tensors.
apply_root_velocity(velocity, env_ids)	Apply world-frame root linear and angular velocities.
apply_state([env_ids, joint_ids, root_pose, ...])	Submit selected final physical state without intermediate propagation.
clear_dynamics(env_ids)	Clear backend-owned articulation dynamics for selected environments.
compute_kinematics(env_ids)	Refresh articulation kinematics if required by the backend.
fetch_joint_properties(*[, position_limits, ...])	Read current joint parameters in public DOF order.
fetch_link_physical_properties(mass, ...)	Refresh current link properties in public link order.
fetch_link_pose(data)	Fetch link poses into data.
fetch_link_velocity(data, linear_data, ...)	Fetch link velocities into data using provided scratch buffers.
fetch_qacc(data)	Fetch current joint accelerations into data.
fetch_qf(data)	Fetch current joint forces into data.
fetch_qpos(data)	Fetch current joint positions into data.
fetch_qvel(data)	Fetch current joint velocities into data.
fetch_root_angular_velocity(data)	Fetch root angular velocities into data and return a tensor.
fetch_root_linear_velocity(data)	Fetch root linear velocities into data and return a tensor.
fetch_root_pose(data)	Fetch root poses into data and return a view/result tensor.
fetch_state(qpos, qvel, root_pose, ...)	Read joint and root state into caller-owned buffers.
fetch_target_qpos(data)	Fetch target joint positions into data.
fetch_target_qvel(data)	Fetch target joint velocities into data.
select_articulation_ids(env_ids)	Return backend articulation ids for the given environment ids.

Attributes:

articulation_ids_tensor	Backend articulation ids as an int32 tensor, if the backend uses ids.
dof	Scalar degree-of-freedom width exposed by the view.
is_newton_backend	Whether this view targets the DexSim Newton backend.
is_ready	Whether backend runtime data can be accessed through batch APIs.
joint_names	Active joint names in public flattened-DOF order.
link_names	Link names in public link-buffer order.
num_links	Link width exposed by the view.

abstract apply_qf(qf, env_ids, joint_ids)

Apply joint forces for selected envs and joints.

Return type:

None

abstract apply_qpos(qpos, env_ids, joint_ids, *, target)

Apply joint positions for selected envs and joints.

Return type:

None

abstract apply_qvel(qvel, env_ids, joint_ids, *, target)

Apply joint velocities for selected envs and joints.

Return type:

None

abstract apply_root_pose(pose, env_ids)

Apply root poses from EmbodiChain xyz + xyzw tensors.

Return type:

None

abstract apply_root_velocity(velocity, env_ids)

Apply world-frame root linear and angular velocities.

Parameters:

• velocity (Tensor) – Selected root velocities with shape (N, 6).

• env_ids (Union[Sequence[int], Tensor]) – Environment rows in the same order as velocity.

Return type:

None

abstract apply_state(env_ids=None, joint_ids=None, *, root_pose=None, qpos=None, target_qpos=None, qvel=None, target_qvel=None, qf=None, root_velocity=None, clear_dynamics=False)

Submit selected final physical state without intermediate propagation.

Parameters:

• env_ids (Union[Sequence[int], Tensor, None]) – Environment rows; None selects all rows.

• joint_ids (Union[Sequence[int], Tensor, None]) – Joint columns; None selects all joints.

• root_pose (Tensor | None) – Environment-local xyz + xyzw poses, shape (N, 7).

• qpos (Tensor | None) – Joint positions, shape (N, J).

• target_qpos (Tensor | None) – Joint position targets, shape (N, J).

• qvel (Tensor | None) – Joint velocities, shape (N, J).

• target_qvel (Tensor | None) – Joint velocity targets, shape (N, J).

• qf (Tensor | None) – Joint efforts, shape (N, J).

• root_velocity (Tensor | None) – World linear + angular velocities, shape (N, 6).

• clear_dynamics (bool) – Clear selected rows’ dynamic state and hold their final joint positions. Explicit fields override these defaults.

Return type:

None

abstract property articulation_ids_tensor: Tensor | None

Backend articulation ids as an int32 tensor, if the backend uses ids.

abstract clear_dynamics(env_ids)

Clear backend-owned articulation dynamics for selected environments.

Return type:

None

abstract compute_kinematics(env_ids)

Refresh articulation kinematics if required by the backend.

Return type:

None

dof: int

Scalar degree-of-freedom width exposed by the view.

fetch_joint_properties(*, position_limits=None, velocity_limit=None, effort_limit=None, stiffness=None, damping=None, friction=None, armature=None)

Read current joint parameters in public DOF order.

Parameters:

• position_limits (Tensor | None) – Lower/upper output, shape (N, dof, 2).

• velocity_limit (Tensor | None) – Velocity-limit output, shape (N, dof).

• effort_limit (Tensor | None) – Effort-limit output, shape (N, dof).

• stiffness (Tensor | None) – Drive-stiffness output, shape (N, dof).

• damping (Tensor | None) – Drive-damping output, shape (N, dof).

• friction (Tensor | None) – Joint-friction output, shape (N, dof).

• armature (Tensor | None) – Joint-armature output, shape (N, dof).

Return type:

None

Outputs are caller-owned. Omitted fields are not read; at least one output is required. Values follow the backend’s current model, with retained descriptor changes becoming visible after Scene rebuild.

Raises:

NotImplementedError – If this view has no batch property reader.

fetch_link_physical_properties(mass, inertia, com_pose)

Refresh current link properties in public link order.

Parameters:

• mass (Tensor) – Output buffer with shape (N, num_links).

• inertia (Tensor) – Output principal moments, shape (N, num_links, 3).

• com_pose (Tensor) – Output local COM poses, shape (N, num_links, 7), using xyz + xyzw.

Raises:

NotImplementedError – If this view has no batch property reader.

Return type:

None

abstract fetch_link_pose(data)

Fetch link poses into data.

Return type:

Tensor

abstract fetch_link_velocity(data, linear_data, angular_data)

Fetch link velocities into data using provided scratch buffers.

Return type:

Tensor

abstract fetch_qacc(data)

Fetch current joint accelerations into data.

Return type:

Tensor

abstract fetch_qf(data)

Fetch current joint forces into data.

Return type:

Tensor

abstract fetch_qpos(data)

Fetch current joint positions into data.

Return type:

Tensor

abstract fetch_qvel(data)

Fetch current joint velocities into data.

Return type:

Tensor

abstract fetch_root_angular_velocity(data)

Fetch root angular velocities into data and return a tensor.

Return type:

Tensor

abstract fetch_root_linear_velocity(data)

Fetch root linear velocities into data and return a tensor.

Return type:

Tensor

abstract fetch_root_pose(data)

Fetch root poses into data and return a view/result tensor.

Return type:

Tensor

fetch_state(qpos, qvel, root_pose, root_lin_vel, root_ang_vel)

Read joint and root state into caller-owned buffers.

Parameters:

• qpos (Tensor) – Joint positions, shape (N, dof).

• qvel (Tensor) – Joint velocities, shape (N, dof).

• root_pose (Tensor) – Root poses, shape (N, 7), in xyz + xyzw order.

• root_lin_vel (Tensor) – Root world-frame linear velocities, shape (N, 3).

• root_ang_vel (Tensor) – Root world-frame angular velocities, shape (N, 3).

Return type:

None

abstract fetch_target_qpos(data)

Fetch target joint positions into data.

Return type:

Tensor

abstract fetch_target_qvel(data)

Fetch target joint velocities into data.

Return type:

Tensor

property is_newton_backend: bool

Whether this view targets the DexSim Newton backend.

abstract property is_ready: bool

Whether backend runtime data can be accessed through batch APIs.

joint_names: list[str]

Active joint names in public flattened-DOF order.

link_names: list[str]

Link names in public link-buffer order.

num_links: int

Link width exposed by the view.

abstract select_articulation_ids(env_ids)

Return backend articulation ids for the given environment ids.

Return type:

Tensor

class embodichain.lab.sim.objects.backends.RigidBodyViewBase

Abstract interface for physics-backend rigid body data access.

All pose/velocity/acceleration data uses EmbodiChain convention: (x, y, z, qx, qy, qz, qw).

Methods:

apply_angular_velocity(data, body_ids)	Set angular velocities from (N, 3) tensor.
apply_collision_filter(data, body_ids)	Apply collision-filter rows from an (N, 4) tensor.
apply_com_local_pose(data, body_ids)	Apply COM-local poses from (x, y, z, qx, qy, qz, qw).
apply_contact_offset(data, body_ids)	Apply contact offsets from (N, 1) tensor.
apply_damping(data, body_ids)	Apply linear/angular damping from an (N, 2) tensor.
apply_force(data, body_ids)	Apply external forces (N, 3).
apply_friction(data, body_ids)	Apply friction coefficients from (N, 1) tensor.
apply_inertia_diagonal(data, body_ids)	Apply inertia diagonals from (N, 3) tensor.
apply_linear_velocity(data, body_ids)	Set linear velocities from (N, 3) tensor.
apply_mass(data, body_ids)	Apply masses from (N, 1) tensor.
apply_pose(pose, body_ids)	Apply poses from (N, 7) tensor in (x, y, z, qx, qy, qz, qw).
apply_restitution(data, body_ids)	Apply restitution coefficients from (N, 1) tensor.
apply_torque(data, body_ids)	Apply external torques (N, 3).
fetch_angular_acceleration(data[, body_ids])	Fetch angular accelerations into data as (N, 3).
fetch_angular_velocity(data[, body_ids])	Fetch angular velocities into data as (N, 3).
fetch_collision_filter(data[, body_ids])	Fetch collision-filter rows into data as (N, 4).
fetch_com_local_pose(data[, body_ids])	Fetch COM-local poses as (x, y, z, qx, qy, qz, qw).
fetch_contact_offset(data[, body_ids])	Fetch contact offsets into data as (N, 1).
fetch_damping(data[, body_ids])	Fetch linear/angular damping into data as (N, 2).
fetch_friction(data[, body_ids])	Fetch friction coefficients into data as (N, 1).
fetch_inertia_diagonal(data[, body_ids])	Fetch inertia diagonals into data as (N, 3).
fetch_linear_acceleration(data[, body_ids])	Fetch linear accelerations into data as (N, 3).
fetch_linear_velocity(data[, body_ids])	Fetch linear velocities into data as (N, 3).
fetch_mass(data[, body_ids])	Fetch masses into data as (N, 1).
fetch_pose(data[, body_ids])	Fetch poses into data as (N, 7) in (x, y, z, qx, qy, qz, qw).
fetch_restitution(data[, body_ids])	Fetch restitution coefficients into data as (N, 1).
select_body_ids(indices)	Return body IDs for the given entity indices.

Attributes:

body_ids	Backend body IDs for all managed entities.
body_ids_tensor	Body IDs as an int32 tensor on device.
can_apply_pose	Whether world poses can be written through the backend view.
can_fetch_pose	Whether world poses can be read through the backend view.
is_newton_backend	Whether this view targets the DexSim Newton backend.
is_ready	Whether the backend simulation is finalized and data can be accessed.

abstract apply_angular_velocity(data, body_ids)

Set angular velocities from (N, 3) tensor.

Return type:

None

apply_collision_filter(data, body_ids)

Apply collision-filter rows from an (N, 4) tensor.

Return type:

None

abstract apply_com_local_pose(data, body_ids)

Apply COM-local poses from (x, y, z, qx, qy, qz, qw).

Return type:

None

abstract apply_contact_offset(data, body_ids)

Apply contact offsets from (N, 1) tensor.

Return type:

None

apply_damping(data, body_ids)

Apply linear/angular damping from an (N, 2) tensor.

Return type:

None

abstract apply_force(data, body_ids)

Apply external forces (N, 3). One-shot — consumed on next step.

Return type:

None

abstract apply_friction(data, body_ids)

Apply friction coefficients from (N, 1) tensor.

Return type:

None

abstract apply_inertia_diagonal(data, body_ids)

Apply inertia diagonals from (N, 3) tensor.

Return type:

None

abstract apply_linear_velocity(data, body_ids)

Set linear velocities from (N, 3) tensor.

Return type:

None

abstract apply_mass(data, body_ids)

Apply masses from (N, 1) tensor.

Return type:

None

abstract apply_pose(pose, body_ids)

Apply poses from (N, 7) tensor in (x, y, z, qx, qy, qz, qw).

Return type:

None

abstract apply_restitution(data, body_ids)

Apply restitution coefficients from (N, 1) tensor.

Return type:

None

abstract apply_torque(data, body_ids)

Apply external torques (N, 3). One-shot — consumed on next step.

Return type:

None

property body_ids: list[int]

Backend body IDs for all managed entities.

property body_ids_tensor: Tensor

Body IDs as an int32 tensor on device.

property can_apply_pose: bool

Whether world poses can be written through the backend view.

property can_fetch_pose: bool

Whether world poses can be read through the backend view.

abstract fetch_angular_acceleration(data, body_ids=None)

Fetch angular accelerations into data as (N, 3).

Return type:

None

abstract fetch_angular_velocity(data, body_ids=None)

Fetch angular velocities into data as (N, 3).

Return type:

None

fetch_collision_filter(data, body_ids=None)

Fetch collision-filter rows into data as (N, 4).

Return type:

None

abstract fetch_com_local_pose(data, body_ids=None)

Fetch COM-local poses as (x, y, z, qx, qy, qz, qw).

Return type:

None

abstract fetch_contact_offset(data, body_ids=None)

Fetch contact offsets into data as (N, 1).

Return type:

None

fetch_damping(data, body_ids=None)

Fetch linear/angular damping into data as (N, 2).

Return type:

None

abstract fetch_friction(data, body_ids=None)

Fetch friction coefficients into data as (N, 1).

Return type:

None

abstract fetch_inertia_diagonal(data, body_ids=None)

Fetch inertia diagonals into data as (N, 3).

Return type:

None

abstract fetch_linear_acceleration(data, body_ids=None)

Fetch linear accelerations into data as (N, 3).

Return type:

None

abstract fetch_linear_velocity(data, body_ids=None)

Fetch linear velocities into data as (N, 3).

Return type:

None

abstract fetch_mass(data, body_ids=None)

Fetch masses into data as (N, 1).

Return type:

None

abstract fetch_pose(data, body_ids=None)

Fetch poses into data as (N, 7) in (x, y, z, qx, qy, qz, qw).

Return type:

None

abstract fetch_restitution(data, body_ids=None)

Fetch restitution coefficients into data as (N, 1).

Return type:

None

property is_newton_backend: bool

Whether this view targets the DexSim Newton backend.

abstract property is_ready: bool

Whether the backend simulation is finalized and data can be accessed.

abstract select_body_ids(indices)

Return body IDs for the given entity indices.

Return type:

Tensor

class embodichain.lab.sim.objects.backends.SceneArticulationView

Bases: _SceneBatchSelectionAdapter, ArticulationViewBase

Backend-neutral articulation state view backed by ArticulationBatch.

Joint selections currently require one scalar DOF per selected joint. The public DexSim layout already describes multi-DOF joints; supporting them without ambiguity requires a DOF-selection API in DexSim and is therefore kept as an explicit boundary rather than guessed here.

Methods:

__init__(scene, batch, device)
apply_qf(qf, env_ids, joint_ids)	Apply joint forces for selected envs and joints.
apply_qpos(qpos, env_ids, joint_ids, *, target)	Apply joint positions for selected envs and joints.
apply_qvel(qvel, env_ids, joint_ids, *, target)	Apply joint velocities for selected envs and joints.
apply_root_pose(pose, env_ids)	Apply root poses from EmbodiChain xyz + xyzw tensors.
apply_root_velocity(velocity, env_ids)	Write selected root velocities through the existing Scene batch.
apply_state([env_ids, joint_ids, root_pose, ...])	Map EC fields once and submit one selected Scene batch write.
clear_dynamics(env_ids)	Clear backend-owned articulation dynamics for selected environments.
compute_kinematics(env_ids)	Refresh articulation kinematics if required by the backend.
fetch_joint_properties(*[, position_limits, ...])	Read current parameters without tracking model gradients.
fetch_link_physical_properties(mass, ...)	Read live batch properties into caller-owned output buffers.
fetch_link_pose(data)	Fetch link poses into data.
fetch_link_velocity(data, linear_data, ...)	Fetch link velocities into data using provided scratch buffers.
fetch_qacc(data)	Fetch current joint accelerations into data.
fetch_qf(data)	Fetch current joint forces into data.
fetch_qpos(data)	Fetch current joint positions into data.
fetch_qvel(data)	Fetch current joint velocities into data.
fetch_root_angular_velocity(data)	Fetch root angular velocities into data and return a tensor.
fetch_root_linear_velocity(data)	Fetch root linear velocities into data and return a tensor.
fetch_root_pose(data)	Fetch root poses into data and return a view/result tensor.
fetch_state(qpos, qvel, root_pose, ...)	Read joint and root state through DexSim's existing batch operation.
fetch_target_qpos(data)	Fetch target joint positions into data.
fetch_target_qvel(data)	Fetch target joint velocities into data.
from_entities(scene, entities, device)	Create a view from articulation handles owned by scene.
select_articulation_ids(env_ids)	Return backend articulation ids for the given environment ids.

Attributes:

articulation_ids_tensor	Backend articulation ids as an int32 tensor, if the backend uses ids.
dof	Scalar DOF width shared by every articulation row.
is_newton_backend	Whether this view targets the DexSim Newton backend.
is_ready	Whether backend runtime data can be accessed through batch APIs.
joint_names	Active joints in public flattened-DOF order.
link_names	Links in public link-buffer order.
num_links	Link count shared by every articulation row.

__init__(scene, batch, device)

apply_qf(qf, env_ids, joint_ids)

Apply joint forces for selected envs and joints.

Return type:

None

apply_qpos(qpos, env_ids, joint_ids, *, target)

Apply joint positions for selected envs and joints.

Return type:

None

apply_qvel(qvel, env_ids, joint_ids, *, target)

Apply joint velocities for selected envs and joints.

Return type:

None

apply_root_pose(pose, env_ids)

Apply root poses from EmbodiChain xyz + xyzw tensors.

Return type:

None

apply_root_velocity(velocity, env_ids)

Write selected root velocities through the existing Scene batch.

Parameters:

• velocity (Tensor) – World-frame linear and angular velocities, shape (N, 6).

• env_ids (Union[Sequence[int], Tensor]) – Environment rows in the same order as velocity.

Raises:

RuntimeError – A batch write fails. Both velocity components are restored first on the default backend; a failed rollback is reported with the original write error as its cause. Newton uses the batch state writer, which validates both components before writing and does not roll back execution failures.

Return type:

None

apply_state(env_ids=None, joint_ids=None, *, root_pose=None, qpos=None, target_qpos=None, qvel=None, target_qvel=None, qf=None, root_velocity=None, clear_dynamics=False)

Map EC fields once and submit one selected Scene batch write.

Shapes and selection semantics follow ArticulationViewBase.apply_state().

Return type:

None

property articulation_ids_tensor: Tensor

Backend articulation ids as an int32 tensor, if the backend uses ids.

clear_dynamics(env_ids)

Clear backend-owned articulation dynamics for selected environments.

Return type:

None

compute_kinematics(env_ids)

Refresh articulation kinematics if required by the backend.

Return type:

None

property dof: int

Scalar DOF width shared by every articulation row.

fetch_joint_properties(*, position_limits=None, velocity_limit=None, effort_limit=None, stiffness=None, damping=None, friction=None, armature=None)

Read current parameters without tracking model gradients.

See ArticulationViewBase.fetch_joint_properties() for buffer shapes, units and lifetime.

Return type:

None

fetch_link_physical_properties(mass, inertia, com_pose)

Read live batch properties into caller-owned output buffers.

Parameters:

• mass (Tensor) – Output masses, shape (N, num_links).

• inertia (Tensor) – Output principal moments, shape (N, num_links, 3).

• com_pose (Tensor) – Output local poses, shape (N, num_links, 7), in EmbodiChain’s xyz + xyzw convention.

Return type:

None

fetch_link_pose(data)

Fetch link poses into data.

Return type:

Tensor

fetch_link_velocity(data, linear_data, angular_data)

Fetch link velocities into data using provided scratch buffers.

Return type:

Tensor

fetch_qacc(data)

Fetch current joint accelerations into data.

Return type:

Tensor

fetch_qf(data)

Fetch current joint forces into data.

Return type:

Tensor

fetch_qpos(data)

Fetch current joint positions into data.

Return type:

Tensor

fetch_qvel(data)

Fetch current joint velocities into data.

Return type:

Tensor

fetch_root_angular_velocity(data)

Fetch root angular velocities into data and return a tensor.

Return type:

Tensor

fetch_root_linear_velocity(data)

Fetch root linear velocities into data and return a tensor.

Return type:

Tensor

fetch_root_pose(data)

Fetch root poses into data and return a view/result tensor.

Return type:

Tensor

fetch_state(qpos, qvel, root_pose, root_lin_vel, root_ang_vel)

Read joint and root state through DexSim’s existing batch operation.

Buffer shapes and frames follow ArticulationViewBase.fetch_state(). Each call reads current simulation data, including writes since the previous call; the reusable scratch buffer stores no cached state.

Return type:

None

fetch_target_qpos(data)

Fetch target joint positions into data.

Return type:

Tensor

fetch_target_qvel(data)

Fetch target joint velocities into data.

Return type:

Tensor

classmethod from_entities(scene, entities, device)

Create a view from articulation handles owned by scene.

Return type:

SceneArticulationView

property is_newton_backend: bool

Whether this view targets the DexSim Newton backend.

property is_ready: bool

Whether backend runtime data can be accessed through batch APIs.

property joint_names: list[str]

Active joints in public flattened-DOF order.

property link_names: list[str]

Links in public link-buffer order.

property num_links: int

Link count shared by every articulation row.

select_articulation_ids(env_ids)

Return backend articulation ids for the given environment ids.

Return type:

Tensor

class embodichain.lab.sim.objects.backends.SceneRigidBodyView

Bases: _SceneBatchSelectionAdapter, RigidBodyViewBase

Backend-neutral rigid-body view backed by RigidBodyBatch.

Methods:

__init__(scene, batch, device)
apply_angular_velocity(data, body_ids)	Set angular velocities from (N, 3) tensor.
apply_collision_filter(data, body_ids)	Apply collision-filter rows from an (N, 4) tensor.
apply_com_local_pose(data, body_ids)	Apply COM-local poses from (x, y, z, qx, qy, qz, qw).
apply_contact_offset(data, body_ids)	Apply contact offsets from (N, 1) tensor.
apply_damping(data, body_ids)	Apply linear/angular damping from an (N, 2) tensor.
apply_force(data, body_ids)	Apply external forces (N, 3).
apply_friction(data, body_ids)	Apply friction coefficients from (N, 1) tensor.
apply_inertia_diagonal(data, body_ids)	Apply inertia diagonals from (N, 3) tensor.
apply_linear_velocity(data, body_ids)	Set linear velocities from (N, 3) tensor.
apply_mass(data, body_ids)	Apply masses from (N, 1) tensor.
apply_pose(pose, body_ids)	Apply poses from (N, 7) tensor in (x, y, z, qx, qy, qz, qw).
apply_restitution(data, body_ids)	Apply restitution coefficients from (N, 1) tensor.
apply_torque(data, body_ids)	Apply external torques (N, 3).
fetch_angular_acceleration(data[, body_ids])	Fetch angular accelerations into data as (N, 3).
fetch_angular_velocity(data[, body_ids])	Fetch angular velocities into data as (N, 3).
fetch_collision_filter(data[, body_ids])	Fetch collision-filter rows into data as (N, 4).
fetch_com_local_pose(data[, body_ids])	Fetch COM-local poses as (x, y, z, qx, qy, qz, qw).
fetch_contact_offset(data[, body_ids])	Fetch contact offsets into data as (N, 1).
fetch_damping(data[, body_ids])	Fetch linear/angular damping into data as (N, 2).
fetch_friction(data[, body_ids])	Fetch friction coefficients into data as (N, 1).
fetch_inertia_diagonal(data[, body_ids])	Fetch inertia diagonals into data as (N, 3).
fetch_linear_acceleration(data[, body_ids])	Fetch linear accelerations into data as (N, 3).
fetch_linear_velocity(data[, body_ids])	Fetch linear velocities into data as (N, 3).
fetch_mass(data[, body_ids])	Fetch masses into data as (N, 1).
fetch_pose(data[, body_ids])	Fetch poses into data as (N, 7) in (x, y, z, qx, qy, qz, qw).
fetch_restitution(data[, body_ids])	Fetch restitution coefficients into data as (N, 1).
from_entities(scene, entities, device)	Create a view from rigid-body handles owned by scene.
select_body_ids(indices)	Return body IDs for the given entity indices.

Attributes:

body_ids	Backend body IDs for all managed entities.
body_ids_tensor	Body IDs as an int32 tensor on device.
is_newton_backend	Whether this view targets the DexSim Newton backend.
is_ready	Whether the backend simulation is finalized and data can be accessed.

__init__(scene, batch, device)

apply_angular_velocity(data, body_ids)

Set angular velocities from (N, 3) tensor.

Return type:

None

apply_collision_filter(data, body_ids)

Apply collision-filter rows from an (N, 4) tensor.

Return type:

None

apply_com_local_pose(data, body_ids)

Apply COM-local poses from (x, y, z, qx, qy, qz, qw).

Return type:

None

apply_contact_offset(data, body_ids)

Apply contact offsets from (N, 1) tensor.

Return type:

None

apply_damping(data, body_ids)

Apply linear/angular damping from an (N, 2) tensor.

Return type:

None

apply_force(data, body_ids)

Apply external forces (N, 3). One-shot — consumed on next step.

Return type:

None

apply_friction(data, body_ids)

Apply friction coefficients from (N, 1) tensor.

Return type:

None

apply_inertia_diagonal(data, body_ids)

Apply inertia diagonals from (N, 3) tensor.

Return type:

None

apply_linear_velocity(data, body_ids)

Set linear velocities from (N, 3) tensor.

Return type:

None

apply_mass(data, body_ids)

Apply masses from (N, 1) tensor.

Return type:

None

apply_pose(pose, body_ids)

Apply poses from (N, 7) tensor in (x, y, z, qx, qy, qz, qw).

Return type:

None

apply_restitution(data, body_ids)

Apply restitution coefficients from (N, 1) tensor.

Return type:

None

apply_torque(data, body_ids)

Apply external torques (N, 3). One-shot — consumed on next step.

Return type:

None

property body_ids: list[int]

Backend body IDs for all managed entities.

property body_ids_tensor: Tensor

Body IDs as an int32 tensor on device.

fetch_angular_acceleration(data, body_ids=None)

Fetch angular accelerations into data as (N, 3).

Return type:

None

fetch_angular_velocity(data, body_ids=None)

Fetch angular velocities into data as (N, 3).

Return type:

None

fetch_collision_filter(data, body_ids=None)

Fetch collision-filter rows into data as (N, 4).

Return type:

None

fetch_com_local_pose(data, body_ids=None)

Fetch COM-local poses as (x, y, z, qx, qy, qz, qw).

Return type:

None

fetch_contact_offset(data, body_ids=None)

Fetch contact offsets into data as (N, 1).

Return type:

None

fetch_damping(data, body_ids=None)

Fetch linear/angular damping into data as (N, 2).

Return type:

None

fetch_friction(data, body_ids=None)

Fetch friction coefficients into data as (N, 1).

Return type:

None

fetch_inertia_diagonal(data, body_ids=None)

Fetch inertia diagonals into data as (N, 3).

Return type:

None

fetch_linear_acceleration(data, body_ids=None)

Fetch linear accelerations into data as (N, 3).

Return type:

None

fetch_linear_velocity(data, body_ids=None)

Fetch linear velocities into data as (N, 3).

Return type:

None

fetch_mass(data, body_ids=None)

Fetch masses into data as (N, 1).

Return type:

None

fetch_pose(data, body_ids=None)

Fetch poses into data as (N, 7) in (x, y, z, qx, qy, qz, qw).

Return type:

None

fetch_restitution(data, body_ids=None)

Fetch restitution coefficients into data as (N, 1).

Return type:

None

classmethod from_entities(scene, entities, device)

Create a view from rigid-body handles owned by scene.

Return type:

SceneRigidBodyView

property is_newton_backend: bool

Whether this view targets the DexSim Newton backend.

property is_ready: bool

Whether the backend simulation is finalized and data can be accessed.

select_body_ids(indices)

Return body IDs for the given entity indices.

Return type:

Tensor

embodichain.lab.sim.objects.backends.is_newton_scene(scene)

Return whether an object is a current DexSim Newton Scene.

Return type:

bool

Backend helper functions

The backend package also exposes the small adapters used by object facades to translate drives, state layouts, geometry, physical properties, controls, and lifecycle operations across Default and Newton implementations.

apply_joint_drive(entity, *, is_newton, ...)	Translate and apply one public joint-drive row for a backend.
collision_shapes_from_entity(entity, *, ...)	Read one entity's physical collision shapes across DexSim backends.

embodichain.lab.sim.objects.backends.apply_joint_drive(entity, *, is_newton, joint_ids, row_index, resolved_drive_type, target_mode_value, stiffness=None, damping=None, max_effort=None, max_velocity=None, friction=None, armature=None)

Translate and apply one public joint-drive row for a backend.

Return type:

None

embodichain.lab.sim.objects.backends.collision_shapes_from_entity(entity, *, object_uid)

Read one entity’s physical collision shapes across DexSim backends.

DexSim versions before the SpawnedRigidBody facade exposed a native get_physical_body method. Newer facades retain collision descriptors and expose Newton’s collision mesh through the private binding instead. This adapter keeps those backend-specific details out of RigidObject.

Parameters:

• entity (object) – Materialized DexSim rigid-body handle.

• object_uid (str) – Logical EmbodiChain object ID used in diagnostics.

Return type:

list[CollisionShapeDesc]

Returns:

Planner-independent collision-shape snapshots.

Raises:

RuntimeError – If no supported physical collision representation exists.

Articulation drive adapters

apply_joint_drive(entity, *, is_newton, ...)	Translate and apply one public joint-drive row for a backend.
read_drive_properties(entity, *, is_newton)	Read backend-native joint drive values.

embodichain.lab.sim.objects.backends.articulation_drive.apply_joint_drive(entity, *, is_newton, joint_ids, row_index, resolved_drive_type, target_mode_value, stiffness=None, damping=None, max_effort=None, max_velocity=None, friction=None, armature=None)

Translate and apply one public joint-drive row for a backend.

Return type:

None

embodichain.lab.sim.objects.backends.articulation_drive.read_drive_properties(entity, *, is_newton)

Read backend-native joint drive values.

Return type:

tuple[object, ...]

Articulation geometry and lifecycle adapters

get_link_vert_face(entity, link_name, *, ...)

Read complete link mesh geometry through the active backend API.

embodichain.lab.sim.objects.backends.articulation_geometry.get_link_vert_face(entity, link_name, *, is_newton)

Read complete link mesh geometry through the active backend API.

Return type:

tuple[ndarray, ndarray]

prepare_default_spawn_runtime_config(result, ...)

Apply Default root properties before its GPU runtime is initialized.

embodichain.lab.sim.objects.backends.articulation_lifecycle.prepare_default_spawn_runtime_config(result, entities, root_props, prepared_topology_revision)

Apply Default root properties before its GPU runtime is initialized.

Return type:

int

Articulation physics, state, and topology adapters

apply_link_com_pose(entity, link_name, ...)	Apply one link local COM pose and return a Spawn status when available.
apply_link_inertia(entity, link_name, value, *)	Apply one link inertia and return a Spawn status when available.
apply_link_mass(entity, link_name, value, *, ...)	Apply one link mass using Spawn, Newton, or legacy APIs.
get_link_properties(entity, link_name, *, ...)	Read a link's physical properties through the active backend API.
set_link_physical_attr(entity, ...)	Apply a DexSim PhysicalAttr to one articulation link.

embodichain.lab.sim.objects.backends.articulation_physics.apply_link_com_pose(entity, link_name, position, quaternion, *, inertia=None, is_spawn_bound, is_newton)

Apply one link local COM pose and return a Spawn status when available.

Return type:

int | None

embodichain.lab.sim.objects.backends.articulation_physics.apply_link_inertia(entity, link_name, value, *, quaternion_xyzw=None, is_spawn_bound, is_newton)

Apply one link inertia and return a Spawn status when available.

Return type:

int | None

embodichain.lab.sim.objects.backends.articulation_physics.apply_link_mass(entity, link_name, value, *, is_spawn_bound, is_newton)

Apply one link mass using Spawn, Newton, or legacy APIs.

Return type:

None

embodichain.lab.sim.objects.backends.articulation_physics.get_link_properties(entity, link_name, *, is_newton)

Read a link’s physical properties through the active backend API.

Return type:

Any

embodichain.lab.sim.objects.backends.articulation_physics.set_link_physical_attr(entity, physical_attr, link_name, *, replace_inertial)

Apply a DexSim PhysicalAttr to one articulation link.

Return type:

None

get_state_joint_names(entity)	Return active joint names in the backing state-buffer order.
map_source_qpos_to_state_order(entity, qpos, ...)	Map source-ordered initial qpos values into runtime state order.
read_state_mimic_info(entity)	Read mimic metadata and map source joint ids into state-buffer ids.

embodichain.lab.sim.objects.backends.articulation_state.get_state_joint_names(entity)

Return active joint names in the backing state-buffer order.

Return type:

list[str]

embodichain.lab.sim.objects.backends.articulation_state.map_source_qpos_to_state_order(entity, qpos, *, is_spawn_bound)

Map source-ordered initial qpos values into runtime state order.

Return type:

Tensor

embodichain.lab.sim.objects.backends.articulation_state.read_state_mimic_info(entity)

Read mimic metadata and map source joint ids into state-buffer ids.

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

get_joint_descriptor(entity, joint_name, *, ...)

Read one joint descriptor through the active backend contract.

embodichain.lab.sim.objects.backends.articulation_topology.get_joint_descriptor(entity, joint_name, *, is_newton)

Read one joint descriptor through the active backend contract.

Newton exposes backend-neutral joint descriptors directly. Current DexSim versions expose the same descriptor API for Default, so prefer it there as well and retain the legacy joint-info call only for older backends.

Return type:

object

Collision, control, and lifecycle adapters

collision_shapes_from_entity(entity, *, ...)

Read one entity's physical collision shapes across DexSim backends.

embodichain.lab.sim.objects.backends.collision.collision_shapes_from_entity(entity, *, object_uid)

Read one entity’s physical collision shapes across DexSim backends.

DexSim versions before the SpawnedRigidBody facade exposed a native get_physical_body method. Newer facades retain collision descriptors and expose Newton’s collision mesh through the private binding instead. This adapter keeps those backend-specific details out of RigidObject.

Parameters:

• entity (object) – Materialized DexSim rigid-body handle.

• object_uid (str) – Logical EmbodiChain object ID used in diagnostics.

Return type:

list[CollisionShapeDesc]

Returns:

Planner-independent collision-shape snapshots.

Raises:

RuntimeError – If no supported physical collision representation exists.

get_body_scale(entity)	Read one native rigid-body visual scale.
set_articulation_flag(entity, flag, enabled)	Set one native articulation flag.
set_body_scale(entity, scale)	Set one native rigid-body visual scale.
set_collision_enabled(entity, enabled)	Enable or disable collision on one native rigid entity.
set_physical_visible(entity, visible[, ...])	Set native collision-visual visibility for an entity or link.
set_gravity_enabled(entity, enabled)	Enable or disable gravity on one native articulation.
create_physical_visible_node(entity, rgba[, ...])	Create a native collision-visual node for an entity or link.
set_visible(entity, visible)	Set one native entity's render visibility.

embodichain.lab.sim.objects.backends.controls.get_body_scale(entity)

Read one native rigid-body visual scale.

Return type:

Any

embodichain.lab.sim.objects.backends.controls.set_articulation_flag(entity, flag, enabled)

Set one native articulation flag.

Return type:

None

embodichain.lab.sim.objects.backends.controls.set_body_scale(entity, scale)

Set one native rigid-body visual scale.

Return type:

None

embodichain.lab.sim.objects.backends.controls.set_collision_enabled(entity, enabled)

Enable or disable collision on one native rigid entity.

Return type:

None

embodichain.lab.sim.objects.backends.controls.set_physical_visible(entity, visible, link_name=None)

Set native collision-visual visibility for an entity or link.

Return type:

None

embodichain.lab.sim.objects.backends.controls.set_gravity_enabled(entity, enabled)

Enable or disable gravity on one native articulation.

Return type:

None

embodichain.lab.sim.objects.backends.controls.create_physical_visible_node(entity, rgba, link_name=None)

Create a native collision-visual node for an entity or link.

Return type:

None

embodichain.lab.sim.objects.backends.controls.set_visible(entity, visible)

Set one native entity’s render visibility.

Return type:

None

destroy_articulation_entities(world, scene, ...)	Remove unbound articulation entities using the active backend's API.
destroy_rigid_entities(world, scene, entities, *)	Remove unbound rigid entities using the active backend's API.
finalize_articulation_spawn(articulation, result)	Apply backend-specific initial-state handling after Spawn binding.
apply_rigid_initial_state(rigid_object)	Apply backend-specific initial state without advancing physics.

embodichain.lab.sim.objects.backends.lifecycle.destroy_articulation_entities(world, scene, entities, *, is_newton=None)

Remove unbound articulation entities using the active backend’s API.

Return type:

None

embodichain.lab.sim.objects.backends.lifecycle.destroy_rigid_entities(world, scene, entities, *, is_newton=None)

Remove unbound rigid entities using the active backend’s API.

Return type:

None

embodichain.lab.sim.objects.backends.lifecycle.finalize_articulation_spawn(articulation, result)

Apply backend-specific initial-state handling after Spawn binding.

Return type:

None

embodichain.lab.sim.objects.backends.lifecycle.apply_rigid_initial_state(rigid_object)

Apply backend-specific initial state without advancing physics.

Return type:

None

Rigid physical-property adapters

apply_legacy_physical_attr(entity, physical_attr)	Apply a DexSim PhysicalAttr through the legacy entity API.
get_legacy_damping(entity)	Read legacy linear and angular damping.
get_legacy_friction(entity)	Read dynamic friction through the legacy physical-body API.
get_legacy_inertia(entity)	Read legacy mass-space inertia diagonal.
get_legacy_mass(entity)	Read mass through the legacy physical-body API.
can_use_newton_entity_dynamics_fallback(scene)	Whether legacy Newton entity dynamics helpers are safe to call.
get_newton_physical_attr(scene, entity, ...)	Return required Newton metadata physical attributes for an entity.
get_newton_physical_attr_or_none(scene, entity)	Return Newton metadata physical attributes when available.
mirror_newton_physical_attr(scene, entity, ...)	Copy public physical attributes onto the Newton rebuild metadata.
newton_lifecycle_state(scene)	Return the current Newton lifecycle state name.
set_legacy_collision_filter(entity, filter_data)	Set collision filters through the legacy physical-body API.
set_legacy_damping(entity, linear, angular)	Set legacy linear and angular damping.
set_legacy_friction(entity, value)	Set both legacy static and dynamic friction coefficients.
set_legacy_inertia(entity, value)	Set legacy mass-space inertia diagonal.
set_legacy_mass(entity, value)	Set mass through the legacy physical-body API.

embodichain.lab.sim.objects.backends.rigid_physics.apply_legacy_physical_attr(entity, physical_attr)

Apply a DexSim PhysicalAttr through the legacy entity API.

Return type:

None

embodichain.lab.sim.objects.backends.rigid_physics.get_legacy_damping(entity)

Read legacy linear and angular damping.

Return type:

tuple[Any, Any]

embodichain.lab.sim.objects.backends.rigid_physics.get_legacy_friction(entity)

Read dynamic friction through the legacy physical-body API.

Return type:

Any

embodichain.lab.sim.objects.backends.rigid_physics.get_legacy_inertia(entity)

Read legacy mass-space inertia diagonal.

Return type:

Any

embodichain.lab.sim.objects.backends.rigid_physics.get_legacy_mass(entity)

Read mass through the legacy physical-body API.

Return type:

Any

embodichain.lab.sim.objects.backends.rigid_physics.can_use_newton_entity_dynamics_fallback(scene)

Whether legacy Newton entity dynamics helpers are safe to call.

Return type:

bool

embodichain.lab.sim.objects.backends.rigid_physics.get_newton_physical_attr(scene, entity, env_idx, object_uid)

Return required Newton metadata physical attributes for an entity.

Return type:

Any

embodichain.lab.sim.objects.backends.rigid_physics.get_newton_physical_attr_or_none(scene, entity)

Return Newton metadata physical attributes when available.

Return type:

Any

embodichain.lab.sim.objects.backends.rigid_physics.mirror_newton_physical_attr(scene, entity, env_idx, object_uid, physical_attr)

Copy public physical attributes onto the Newton rebuild metadata.

Return type:

None

embodichain.lab.sim.objects.backends.rigid_physics.newton_lifecycle_state(scene)

Return the current Newton lifecycle state name.

Return type:

str

embodichain.lab.sim.objects.backends.rigid_physics.set_legacy_collision_filter(entity, filter_data)

Set collision filters through the legacy physical-body API.

Return type:

None

embodichain.lab.sim.objects.backends.rigid_physics.set_legacy_damping(entity, linear, angular)

Set legacy linear and angular damping.

Return type:

None

embodichain.lab.sim.objects.backends.rigid_physics.set_legacy_friction(entity, value)

Set both legacy static and dynamic friction coefficients.

Return type:

None

embodichain.lab.sim.objects.backends.rigid_physics.set_legacy_inertia(entity, value)

Set legacy mass-space inertia diagonal.

Return type:

None

embodichain.lab.sim.objects.backends.rigid_physics.set_legacy_mass(entity, value)

Set mass through the legacy physical-body API.

Return type:

None

Backend implementation import paths

RigidBodyViewBase	Abstract interface for physics-backend rigid body data access.
ArticulationViewBase	Abstract interface for physics-backend articulation data access.

is_newton_scene(scene)

Return whether an object is a current DexSim Newton Scene.

SceneArticulationView	Backend-neutral articulation state view backed by ArticulationBatch.
SceneRigidBodyView	Backend-neutral rigid-body view backed by RigidBodyBatch.

Unified Deformable Objects

Surface and volume objects share one concrete DeformableObjectData backed by DexSim Newton particle batches. After sim.prepare(), prefer obj.data for state reads: n_nodes gives the particle count without fetching state, nodal_pos_w and nodal_vel_w return world-frame tensors of shape (num_instances, n_nodes, 3), and nodal_state_w concatenates the two. State reads return independent snapshots. default_nodal_state_w retains the state captured at Spawn binding; root_pos_w is the mean node position, not a mass-weighted center of mass.

Use obj.deformable_type to distinguish physical topology. Read simulation nodes through data. Render vertices and triangles are available through get_surface_vertices() and get_surface_triangles(); volume objects also expose tetrahedral boundary triangles through get_collision_surface_triangles(). Use SimulationManager.add_deformable_object() and get_deformable_object() to manage both topologies.

DeformableObject	Common facade over a batch of Newton particle-set deformables.
DeformableObjectData	Common nodal-state view for volume and surface deformables.
SurfaceDeformableObject	A batch of Newton cloth particle sets.
VolumeDeformableObject	A batch of Newton volumetric soft-body particle sets.

class embodichain.lab.sim.objects.deformable.DeformableObject

Bases: BatchEntity

Common facade over a batch of Newton particle-set deformables.

Volume and surface objects retain EmbodiChain’s public nodal contract, but their runtime ownership is exclusively DexSim Spawn’s Newton scene. The Default backend and direct native soft/cloth body buffers are unsupported.

Methods:

__init__(cfg[, device])	Create an unregistered deformable facade.
attach_spawn_handles(entities)	Store materialized handles before final Spawn binding.
bind_spawn(result)	Bind a declared facade to finalized native handles in place.
destroy()	Leave particle lifetime ownership with the finalized Spawn scene.
get_local_pose([to_matrix])	Reject root-pose reads because deformables have no rigid root pose.
get_surface_triangles([env_ids])	Return render-surface triangle indices for selected environments.
get_surface_vertices()	Return live render-surface vertices in world frame.
get_visual_material_inst([env_ids])	Return registered material wrappers for selected environments.
reset([env_ids])	Restore the configured pose, zero velocity, and source materials.
restore_visual_material([env_ids])	Restore materials captured when the deformable was created.
set_local_pose(pose[, env_ids])	Set a deformable pose by transforming its captured rest particles.
set_visual_material(mat[, env_ids, shared])	Assign visual material instances to selected environments.

Attributes:

data	Return the common deformable data view after Spawn binding.
deformable_type	Physical topology supplied by the concrete object class.
is_declared	Whether this facade is waiting for its Spawn scene binding.
is_spawn_bound	Whether this facade is bound to one finalized Spawn scene.
num_instances	Return the materialized or declared instance count.

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

Create an unregistered deformable facade.

SpawnScene supplies the replicated instance count when declaring this facade and the finalized Scene when binding it.

attach_spawn_handles(entities)

Store materialized handles before final Spawn binding.

Return type:

None

bind_spawn(result)

Bind a declared facade to finalized native handles in place.

Return type:

None

property data: DeformableObjectData | None

Return the common deformable data view after Spawn binding.

abstract property deformable_type: Literal['volume', 'surface']

Physical topology supplied by the concrete object class.

destroy()

Leave particle lifetime ownership with the finalized Spawn scene.

Return type:

None

get_local_pose(to_matrix=False)

Reject root-pose reads because deformables have no rigid root pose.

Return type:

Tensor

get_surface_triangles(env_ids=None)

Return render-surface triangle indices for selected environments.

Return type:

Tensor

get_surface_vertices()

Return live render-surface vertices in world frame.

Return type:

Tensor

get_visual_material_inst(env_ids=None)

Return registered material wrappers for selected environments.

Return type:

list[VisualMaterialInst | None]

property is_declared: bool

Whether this facade is waiting for its Spawn scene binding.

property is_spawn_bound: bool

Whether this facade is bound to one finalized Spawn scene.

property num_instances: int

Return the materialized or declared instance count.

reset(env_ids=None)

Restore the configured pose, zero velocity, and source materials.

Return type:

None

restore_visual_material(env_ids=None)

Restore materials captured when the deformable was created.

Return type:

None

set_local_pose(pose, env_ids=None)

Set a deformable pose by transforming its captured rest particles.

Return type:

None

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

Assign visual material instances to selected environments.

Return type:

None

class embodichain.lab.sim.objects.deformable.DeformableObjectData

Common nodal-state view for volume and surface deformables.

Positions and velocities use the simulation world frame. Consumers can rely on a stable (num_instances, n_nodes, 3) contract. State properties return independent snapshots; the default state is captured at Spawn binding.

Parameters:

• entities (Sequence[SpawnedParticleSet]) – Replicated particle sets with equal node counts.

• scene (Scene) – Finalized DexSim scene that owns the particle sets.

• device (device) – Device used for state tensors and batch transfers.

Methods:

__init__(entities, scene, device)

Attributes:

default_nodal_state_w	Return the particle state captured when Spawn was bound.
nodal_pos_w	Return current Newton particle positions in world frame.
nodal_state_w	Return current nodal state [position, velocity] in world frame.
nodal_vel_w	Return current Newton particle velocities in world frame.
root_pos_w	Return the mean nodal position for each deformable instance.
root_vel_w	Return the mean nodal velocity for each deformable instance.

__init__(entities, scene, device)

property default_nodal_state_w: Tensor

Return the particle state captured when Spawn was bound.

property nodal_pos_w: Tensor

Return current Newton particle positions in world frame.

property nodal_state_w: Tensor

Return current nodal state [position, velocity] in world frame.

property nodal_vel_w: Tensor

Return current Newton particle velocities in world frame.

property root_pos_w: Tensor

Return the mean nodal position for each deformable instance.

property root_vel_w: Tensor

Return the mean nodal velocity for each deformable instance.

class embodichain.lab.sim.objects.deformable.SurfaceDeformableObject

Bases: DeformableObject

A batch of Newton cloth particle sets.

class embodichain.lab.sim.objects.deformable.VolumeDeformableObject

Bases: DeformableObject

A batch of Newton volumetric soft-body particle sets.

Methods:

get_collision_surface_triangles([env_ids])

Return the tetrahedral surface topology for selected instances.

get_collision_surface_triangles(env_ids=None)

Return the tetrahedral surface topology for selected instances.

Return type:

Tensor

Deformable implementation import paths

DeformableObject

Common facade over a batch of Newton particle-set deformables.

DeformableObjectData

Common nodal-state view for volume and surface deformables.

SurfaceDeformableObject

A batch of Newton cloth particle sets.

VolumeDeformableObject

A batch of Newton volumetric soft-body particle sets.