omni.isaac.lab.assets

omni.isaac.lab.assets#

Sub-package for different assets, such as rigid objects and articulations.

An asset is a physical object that can be spawned in the simulation. The class handles both the spawning of the asset into the USD stage as well as initialization of necessary physics handles to interact with the asset.

Upon construction of the asset instance, the prim corresponding to the asset is spawned into the USD stage if the spawn configuration is not None. The spawn configuration is defined in the AssetBaseCfg.spawn attribute. In case the configured AssetBaseCfg.prim_path is an expression, then the prim is spawned at all the matching paths. Otherwise, a single prim is spawned at the configured path. For more information on the spawn configuration, see the omni.isaac.lab.sim.spawners module.

The asset class also registers callbacks for the stage play/stop events. These are used to construct the physics handles for the asset as the physics engine is only available when the stage is playing. Additionally, the class registers a callback for debug visualization of the asset. This can be enabled by setting the AssetBaseCfg.debug_vis attribute to True.

The asset class follows the following naming convention for its methods:

set_xxx(): These are used to only set the buffers into the data instance. However, they do not write the data into the simulator. The writing of data only happens when the write_data_to_sim() method is called.
write_xxx_to_sim(): These are used to set the buffers into the data instance and write the corresponding data into the simulator as well.
update(dt): These are used to update the buffers in the data instance. This should be called after a simulation step is performed.

The main reason to separate the set and write operations is to provide flexibility to the user when they need to perform a post-processing operation of the buffers before applying them into the simulator. A common example for this is dealing with explicit actuator models where the specified joint targets are not directly applied to the simulator but are instead used to compute the corresponding actuator torques.

Classes

`AssetBase`	The base interface class for assets.
`AssetBaseCfg`	The base configuration class for an asset's parameters.
`RigidObject`	A rigid object asset class.
`RigidObjectData`	Data container for a rigid object.
`RigidObjectCfg`	Configuration parameters for a rigid object.
`RigidObjectCollection`	A rigid object collection class.
`RigidObjectCollectionData`	Data container for a rigid object collection.
`RigidObjectCollectionCfg`	Configuration parameters for a rigid object collection.
`Articulation`	An articulation asset class.
`ArticulationData`	Data container for an articulation.
`ArticulationCfg`	Configuration parameters for an articulation.
`DeformableObject`	A deformable object asset class.
`DeformableObjectData`	Data container for a deformable object.
`DeformableObjectCfg`	Configuration parameters for a deformable object.

Asset Base#

class omni.isaac.lab.assets.AssetBase[source]#

The base interface class for assets.

An asset corresponds to any physics-enabled object that can be spawned in the simulation. These include rigid objects, articulated objects, deformable objects etc. The core functionality of an asset is to provide a set of buffers that can be used to interact with the simulator. The buffers are updated by the asset class and can be written into the simulator using the their respective write methods. This allows a convenient way to perform post-processing operations on the buffers before writing them into the simulator and obtaining the corresponding simulation results.

The class handles both the spawning of the asset into the USD stage as well as initialization of necessary physics handles to interact with the asset. Upon construction of the asset instance, the prim corresponding to the asset is spawned into the USD stage if the spawn configuration is not None. The spawn configuration is defined in the AssetBaseCfg.spawn attribute. In case the configured AssetBaseCfg.prim_path is an expression, then the prim is spawned at all the matching paths. Otherwise, a single prim is spawned at the configured path. For more information on the spawn configuration, see the omni.isaac.lab.sim.spawners module.

Unlike Isaac Sim interface, where one usually needs to call the omni.isaac.core.prims.XFormPrimView.initialize() method to initialize the PhysX handles, the asset class automatically initializes and invalidates the PhysX handles when the stage is played/stopped. This is done by registering callbacks for the stage play/stop events.

Additionally, the class registers a callback for debug visualization of the asset if a debug visualization is implemented in the asset class. This can be enabled by setting the AssetBaseCfg.debug_vis attribute to True. The debug visualization is implemented through the _set_debug_vis_impl() and _debug_vis_callback() methods.

Methods:

`__init__`(cfg)	Initialize the asset base.
`set_debug_vis`(debug_vis)	Sets whether to visualize the asset data.
`reset`([env_ids])	Resets all internal buffers of selected environments.
`write_data_to_sim`()	Writes data to the simulator.
`update`(dt)	Update the internal buffers.

Attributes:

`is_initialized`	Whether the asset is initialized.
`num_instances`	Number of instances of the asset.
`device`	Memory device for computation.
`data`	Data related to the asset.
`has_debug_vis_implementation`	Whether the asset has a debug visualization implemented.

__init__(cfg: AssetBaseCfg)[source]#

Initialize the asset base.

Parameters:: cfg – The configuration class for the asset.
Raises:: RuntimeError – If no prims found at input prim path or prim path expression.

property is_initialized: bool#

Whether the asset is initialized.

Returns True if the asset is initialized, False otherwise.

abstract property num_instances: int#

Number of instances of the asset.

This is equal to the number of asset instances per environment multiplied by the number of environments.

property device: str#: Memory device for computation.

abstract property data: Any#: Data related to the asset.

property has_debug_vis_implementation: bool#: Whether the asset has a debug visualization implemented.

set_debug_vis(debug_vis: bool) → bool[source]#

Sets whether to visualize the asset data.

Parameters:: debug_vis – Whether to visualize the asset data.
Returns:: Whether the debug visualization was successfully set. False if the asset does not support debug visualization.

abstract reset(env_ids: Sequence[int] | None = None)[source]#

Resets all internal buffers of selected environments.

Parameters:: env_ids – The indices of the object to reset. Defaults to None (all instances).

abstract write_data_to_sim()[source]#: Writes data to the simulator.

abstract update(dt: float)[source]#

Update the internal buffers.

The time step dt is used to compute numerical derivatives of quantities such as joint accelerations which are not provided by the simulator.

Parameters:: dt – The amount of time passed from last update call.

class omni.isaac.lab.assets.AssetBaseCfg[source]#

The base configuration class for an asset’s parameters.

Please see the AssetBase class for more information on the asset class.

Classes:

InitialStateCfg

Initial state of the asset.

Attributes:

`prim_path`	Prim path (or expression) to the asset.
`spawn`	Spawn configuration for the asset.
`init_state`	Initial state of the rigid object.
`collision_group`	Collision group of the asset.
`debug_vis`	Whether to enable debug visualization for the asset.

class InitialStateCfg[source]#

Initial state of the asset.

This defines the default initial state of the asset when it is spawned into the simulation, as well as the default state when the simulation is reset.

After parsing the initial state, the asset class stores this information in the data attribute of the asset class. This can then be accessed by the user to modify the state of the asset during the simulation, for example, at resets.

Attributes:

`pos`	Position of the root in simulation world frame.
`rot`	Quaternion rotation (w, x, y, z) of the root in simulation world frame.

pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

rot: tuple[float, float, float, float]#: Quaternion rotation (w, x, y, z) of the root in simulation world frame. Defaults to (1.0, 0.0, 0.0, 0.0).

prim_path: str#: Prim path (or expression) to the asset.

Note

The expression can contain the environment namespace regex {ENV_REGEX_NS} which will be replaced with the environment namespace.

Example: {ENV_REGEX_NS}/Robot will be replaced with /World/envs/env_.*/Robot.

spawn: SpawnerCfg | None#

Spawn configuration for the asset. Defaults to None.

If None, then no prims are spawned by the asset class. Instead, it is assumed that the asset is already present in the scene.

init_state: InitialStateCfg#: Initial state of the rigid object. Defaults to identity pose.

collision_group: Literal[0, -1]#

Collision group of the asset. Defaults to 0.

-1: global collision group (collides with all assets in the scene).
0: local collision group (collides with other assets in the same environment).

debug_vis: bool#: Whether to enable debug visualization for the asset. Defaults to False.

Rigid Object#

class omni.isaac.lab.assets.RigidObject[source]#

Bases: AssetBase

A rigid object asset class.

Rigid objects are assets comprising of rigid bodies. They can be used to represent dynamic objects such as boxes, spheres, etc. A rigid body is described by its pose, velocity and mass distribution.

For an asset to be considered a rigid object, the root prim of the asset must have the USD RigidBodyAPI applied to it. This API is used to define the simulation properties of the rigid body. On playing the simulation, the physics engine will automatically register the rigid body and create a corresponding rigid body handle. This handle can be accessed using the root_physx_view attribute.

Note

For users familiar with Isaac Sim, the PhysX view class API is not the exactly same as Isaac Sim view class API. Similar to Isaac Lab, Isaac Sim wraps around the PhysX view API. However, as of now (2023.1 release), we see a large difference in initializing the view classes in Isaac Sim. This is because the view classes in Isaac Sim perform additional USD-related operations which are slow and also not required.

Attributes:

`cfg`	Configuration instance for the rigid object.
`data`	Data related to the asset.
`num_instances`	Number of instances of the asset.
`num_bodies`	Number of bodies in the asset.
`body_names`	Ordered names of bodies in the rigid object.
`root_physx_view`	Rigid body view for the asset (PhysX).
`device`	Memory device for computation.
`has_debug_vis_implementation`	Whether the asset has a debug visualization implemented.
`is_initialized`	Whether the asset is initialized.

Methods:

`__init__`(cfg)	Initialize the rigid object.
`reset`([env_ids])	Resets all internal buffers of selected environments.
`write_data_to_sim`()	Write external wrench to the simulation.
`update`(dt)	Update the internal buffers.
`find_bodies`(name_keys[, preserve_order])	Find bodies in the rigid body based on the name keys.
`write_root_state_to_sim`(root_state[, env_ids])	Set the root state over selected environment indices into the simulation.
`write_root_pose_to_sim`(root_pose[, env_ids])	Set the root pose over selected environment indices into the simulation.
`write_root_velocity_to_sim`(root_velocity[, ...])	Set the root velocity over selected environment indices into the simulation.
`set_external_force_and_torque`(forces, torques)	Set external force and torque to apply on the asset's bodies in their local frame.
`set_debug_vis`(debug_vis)	Sets whether to visualize the asset data.

cfg: RigidObjectCfg#: Configuration instance for the rigid object.

__init__(cfg: RigidObjectCfg)[source]#

Initialize the rigid object.

Parameters:: cfg – A configuration instance.

property data: RigidObjectData#: Data related to the asset.

property num_instances: int#

Number of instances of the asset.

This is equal to the number of asset instances per environment multiplied by the number of environments.

property num_bodies: int#

Number of bodies in the asset.

This is always 1 since each object is a single rigid body.

property body_names: list[str]#: Ordered names of bodies in the rigid object.

property root_physx_view: omni.physics.tensors.impl.api.RigidBodyView#: Rigid body view for the asset (PhysX).

Note

Use this view with caution. It requires handling of tensors in a specific way.

reset(env_ids: Sequence[int] | None = None)[source]#

Resets all internal buffers of selected environments.

Parameters:: env_ids – The indices of the object to reset. Defaults to None (all instances).

write_data_to_sim()[source]#: Write external wrench to the simulation.

Note

We write external wrench to the simulation here since this function is called before the simulation step. This ensures that the external wrench is applied at every simulation step.

update(dt: float)[source]#

Update the internal buffers.

The time step dt is used to compute numerical derivatives of quantities such as joint accelerations which are not provided by the simulator.

Parameters:: dt – The amount of time passed from last update call.

find_bodies(name_keys: str | Sequence[str], preserve_order: bool = False) → tuple[list[int], list[str]][source]#

Find bodies in the rigid body based on the name keys.

Please check the omni.isaac.lab.utils.string_utils.resolve_matching_names() function for more information on the name matching.

Parameters:

name_keys – A regular expression or a list of regular expressions to match the body names.
preserve_order – Whether to preserve the order of the name keys in the output. Defaults to False.

Returns:

A tuple of lists containing the body indices and names.

write_root_state_to_sim(root_state: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the root state over selected environment indices into the simulation.

The root state comprises of the cartesian position, quaternion orientation in (w, x, y, z), and linear and angular velocity. All the quantities are in the simulation frame.

Parameters:

root_state – Root state in simulation frame. Shape is (len(env_ids), 13).
env_ids – Environment indices. If None, then all indices are used.

write_root_pose_to_sim(root_pose: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the root pose over selected environment indices into the simulation.

The root pose comprises of the cartesian position and quaternion orientation in (w, x, y, z).

Parameters:

root_pose – Root poses in simulation frame. Shape is (len(env_ids), 7).
env_ids – Environment indices. If None, then all indices are used.

write_root_velocity_to_sim(root_velocity: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the root velocity over selected environment indices into the simulation.

Parameters:

root_velocity – Root velocities in simulation frame. Shape is (len(env_ids), 6).
env_ids – Environment indices. If None, then all indices are used.

set_external_force_and_torque(forces: torch.Tensor, torques: torch.Tensor, body_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set external force and torque to apply on the asset’s bodies in their local frame.

For many applications, we want to keep the applied external force on rigid bodies constant over a period of time (for instance, during the policy control). This function allows us to store the external force and torque into buffers which are then applied to the simulation at every step.

Caution

If the function is called with empty forces and torques, then this function disables the application of external wrench to the simulation.

# example of disabling external wrench
asset.set_external_force_and_torque(forces=torch.zeros(0, 3), torques=torch.zeros(0, 3))

Note

This function does not apply the external wrench to the simulation. It only fills the buffers with the desired values. To apply the external wrench, call the write_data_to_sim() function right before the simulation step.

Parameters:

forces – External forces in bodies’ local frame. Shape is (len(env_ids), len(body_ids), 3).
torques – External torques in bodies’ local frame. Shape is (len(env_ids), len(body_ids), 3).
body_ids – Body indices to apply external wrench to. Defaults to None (all bodies).
env_ids – Environment indices to apply external wrench to. Defaults to None (all instances).

property device: str#: Memory device for computation.

property has_debug_vis_implementation: bool#: Whether the asset has a debug visualization implemented.

property is_initialized: bool#

Whether the asset is initialized.

Returns True if the asset is initialized, False otherwise.

set_debug_vis(debug_vis: bool) → bool#

Sets whether to visualize the asset data.

Parameters:: debug_vis – Whether to visualize the asset data.
Returns:: Whether the debug visualization was successfully set. False if the asset does not support debug visualization.

class omni.isaac.lab.assets.RigidObjectData[source]#

Bases: object

Data container for a rigid object.

This class contains the data for a rigid object in the simulation. The data includes the state of the root rigid body and the state of all the bodies in the object. The data is stored in the simulation world frame unless otherwise specified.

For a rigid body, there are two frames of reference that are used:

Actor frame: The frame of reference of the rigid body prim. This typically corresponds to the Xform prim with the rigid body schema.
Center of mass frame: The frame of reference of the center of mass of the rigid body.

Depending on the settings of the simulation, the actor frame and the center of mass frame may be the same. This needs to be taken into account when interpreting the data.

The data is lazily updated, meaning that the data is only updated when it is accessed. This is useful when the data is expensive to compute or retrieve. The data is updated when the timestamp of the buffer is older than the current simulation timestamp. The timestamp is updated whenever the data is updated.

Methods:

update(dt)

Updates the data for the rigid object.

Attributes:

`body_names`	Body names in the order parsed by the simulation view.
`default_root_state`	Default root state `[pos, quat, lin_vel, ang_vel]` in local environment frame.
`default_mass`	Default mass read from the simulation.
`default_inertia`	Default inertia tensor read from the simulation.
`root_state_w`	Root state `[pos, quat, lin_vel, ang_vel]` in simulation world frame.
`body_state_w`	State of all bodies [pos, quat, lin_vel, ang_vel] in simulation world frame.
`body_acc_w`	Acceleration of all bodies.
`projected_gravity_b`	Projection of the gravity direction on base frame.
`heading_w`	Yaw heading of the base frame (in radians).
`root_pos_w`	Root position in simulation world frame.
`root_quat_w`	Root orientation (w, x, y, z) in simulation world frame.
`root_vel_w`	Root velocity in simulation world frame.
`root_lin_vel_w`	Root linear velocity in simulation world frame.
`root_ang_vel_w`	Root angular velocity in simulation world frame.
`root_lin_vel_b`	Root linear velocity in base frame.
`root_ang_vel_b`	Root angular velocity in base world frame.
`body_pos_w`	Positions of all bodies in simulation world frame.
`body_quat_w`	Orientation (w, x, y, z) of all bodies in simulation world frame.
`body_vel_w`	Velocity of all bodies in simulation world frame.
`body_lin_vel_w`	Linear velocity of all bodies in simulation world frame.
`body_ang_vel_w`	Angular velocity of all bodies in simulation world frame.
`body_lin_acc_w`	Linear acceleration of all bodies in simulation world frame.
`body_ang_acc_w`	Angular acceleration of all bodies in simulation world frame.

update(dt: float)[source]#

Updates the data for the rigid object.

Parameters:: dt – The time step for the update. This must be a positive value.

body_names: list[str] = None#: Body names in the order parsed by the simulation view.

default_root_state: torch.Tensor = None#

Default root state [pos, quat, lin_vel, ang_vel] in local environment frame. Shape is (num_instances, 13).

The position and quaternion are of the rigid body’s actor frame. Meanwhile, the linear and angular velocities are of the center of mass frame.

default_mass: torch.Tensor = None#: Default mass read from the simulation. Shape is (num_instances, 1).

default_inertia: torch.Tensor = None#

Default inertia tensor read from the simulation. Shape is (num_instances, 9).

The inertia is the inertia tensor relative to the center of mass frame. The values are stored in the order \([I_{xx}, I_{xy}, I_{xz}, I_{yx}, I_{yy}, I_{yz}, I_{zx}, I_{zy}, I_{zz}]\).

property root_state_w#

Root state [pos, quat, lin_vel, ang_vel] in simulation world frame. Shape is (num_instances, 13).

The position and orientation are of the rigid body’s actor frame. Meanwhile, the linear and angular velocities are of the rigid body’s center of mass frame.

property body_state_w#

State of all bodies [pos, quat, lin_vel, ang_vel] in simulation world frame. Shape is (num_instances, 1, 13).

The position and orientation are of the rigid bodies’ actor frame. Meanwhile, the linear and angular velocities are of the rigid bodies’ center of mass frame.

property body_acc_w#

Acceleration of all bodies. Shape is (num_instances, 1, 6).

This quantity is the acceleration of the rigid bodies’ center of mass frame.

property projected_gravity_b#: Projection of the gravity direction on base frame. Shape is (num_instances, 3).

property heading_w#: Yaw heading of the base frame (in radians). Shape is (num_instances,).

Note

This quantity is computed by assuming that the forward-direction of the base frame is along x-direction, i.e. \((1, 0, 0)\).

property root_pos_w: torch.Tensor#

Root position in simulation world frame. Shape is (num_instances, 3).

This quantity is the position of the actor frame of the root rigid body.

property root_quat_w: torch.Tensor#

Root orientation (w, x, y, z) in simulation world frame. Shape is (num_instances, 4).

This quantity is the orientation of the actor frame of the root rigid body.

property root_vel_w: torch.Tensor#

Root velocity in simulation world frame. Shape is (num_instances, 6).

This quantity contains the linear and angular velocities of the root rigid body’s center of mass frame.

property root_lin_vel_w: torch.Tensor#

Root linear velocity in simulation world frame. Shape is (num_instances, 3).

This quantity is the linear velocity of the root rigid body’s center of mass frame.

property root_ang_vel_w: torch.Tensor#

Root angular velocity in simulation world frame. Shape is (num_instances, 3).

This quantity is the angular velocity of the root rigid body’s center of mass frame.

property root_lin_vel_b: torch.Tensor#

Root linear velocity in base frame. Shape is (num_instances, 3).

This quantity is the linear velocity of the root rigid body’s center of mass frame with respect to the rigid body’s actor frame.

property root_ang_vel_b: torch.Tensor#

Root angular velocity in base world frame. Shape is (num_instances, 3).

This quantity is the angular velocity of the root rigid body’s center of mass frame with respect to the rigid body’s actor frame.

property body_pos_w: torch.Tensor#

Positions of all bodies in simulation world frame. Shape is (num_instances, 1, 3).

This quantity is the position of the rigid bodies’ actor frame.

property body_quat_w: torch.Tensor#

Orientation (w, x, y, z) of all bodies in simulation world frame. Shape is (num_instances, 1, 4).

This quantity is the orientation of the rigid bodies’ actor frame.

property body_vel_w: torch.Tensor#

Velocity of all bodies in simulation world frame. Shape is (num_instances, 1, 6).

This quantity contains the linear and angular velocities of the rigid bodies’ center of mass frame.

property body_lin_vel_w: torch.Tensor#

Linear velocity of all bodies in simulation world frame. Shape is (num_instances, 1, 3).

This quantity is the linear velocity of the rigid bodies’ center of mass frame.

property body_ang_vel_w: torch.Tensor#

Angular velocity of all bodies in simulation world frame. Shape is (num_instances, 1, 3).

This quantity is the angular velocity of the rigid bodies’ center of mass frame.

property body_lin_acc_w: torch.Tensor#

Linear acceleration of all bodies in simulation world frame. Shape is (num_instances, 1, 3).

This quantity is the linear acceleration of the rigid bodies’ center of mass frame.

property body_ang_acc_w: torch.Tensor#

Angular acceleration of all bodies in simulation world frame. Shape is (num_instances, 1, 3).

This quantity is the angular acceleration of the rigid bodies’ center of mass frame.

class omni.isaac.lab.assets.RigidObjectCfg[source]#

Bases: AssetBaseCfg

Configuration parameters for a rigid object.

Classes:

InitialStateCfg

Initial state of the rigid body.

Attributes:

`prim_path`	Prim path (or expression) to the asset.
`spawn`	Spawn configuration for the asset.
`collision_group`	Collision group of the asset.
`debug_vis`	Whether to enable debug visualization for the asset.
`init_state`	Initial state of the rigid object.

class InitialStateCfg[source]#

Bases: InitialStateCfg

Initial state of the rigid body.

Attributes:

`lin_vel`	Linear velocity of the root in simulation world frame.
`ang_vel`	Angular velocity of the root in simulation world frame.
`pos`	Position of the root in simulation world frame.
`rot`	Quaternion rotation (w, x, y, z) of the root in simulation world frame.

lin_vel: tuple[float, float, float]#: Linear velocity of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

ang_vel: tuple[float, float, float]#: Angular velocity of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

rot: tuple[float, float, float, float]#: Quaternion rotation (w, x, y, z) of the root in simulation world frame. Defaults to (1.0, 0.0, 0.0, 0.0).

prim_path: str#: Prim path (or expression) to the asset.

Note

The expression can contain the environment namespace regex {ENV_REGEX_NS} which will be replaced with the environment namespace.

Example: {ENV_REGEX_NS}/Robot will be replaced with /World/envs/env_.*/Robot.

spawn: SpawnerCfg | None#

Spawn configuration for the asset. Defaults to None.

If None, then no prims are spawned by the asset class. Instead, it is assumed that the asset is already present in the scene.

collision_group: Literal[0, -1]#

Collision group of the asset. Defaults to 0.

-1: global collision group (collides with all assets in the scene).
0: local collision group (collides with other assets in the same environment).

debug_vis: bool#: Whether to enable debug visualization for the asset. Defaults to False.

init_state: InitialStateCfg#: Initial state of the rigid object. Defaults to identity pose with zero velocity.

Rigid Object Collection#

class omni.isaac.lab.assets.RigidObjectCollection[source]#

Bases: AssetBase

A rigid object collection class.

This class represents a collection of rigid objects in the simulation, where the state of the rigid objects can be accessed and modified using a batched (env_ids, object_ids) API.

For each rigid body in the collection, the root prim of the asset must have the USD RigidBodyAPI applied to it. This API is used to define the simulation properties of the rigid bodies. On playing the simulation, the physics engine will automatically register the rigid bodies and create a corresponding rigid body handle. This handle can be accessed using the root_physx_view attribute.

Note

Rigid objects in the collection are uniquely identified via the key of the dictionary rigid_objects in RigidObjectCollectionCfg. This differs from the class RigidObject, where a rigid object is identified by the name of the Xform where the USD RigidBodyAPI is applied. This would not be possible for the rigid object collection since the rigid_objects dictionary could contain the same rigid object multiple times, leading to ambiguity.

Methods:

`__init__`(cfg)	Initialize the rigid object collection.
`reset`([env_ids, object_ids])	Resets all internal buffers of selected environments and objects.
`write_data_to_sim`()	Write external wrench to the simulation.
`update`(dt)	Update the internal buffers.
`find_objects`(name_keys[, preserve_order])	Find objects in the collection based on the name keys.
`write_object_state_to_sim`(object_state[, ...])	Set the object state over selected environment and object indices into the simulation.
`write_object_pose_to_sim`(object_pose[, ...])	Set the object pose over selected environment and object indices into the simulation.
`write_object_velocity_to_sim`(object_velocity)	Set the object velocity over selected environment and object indices into the simulation.
`set_external_force_and_torque`(forces, torques)	Set external force and torque to apply on the objects' bodies in their local frame.
`reshape_view_to_data`(data)	Reshapes and arranges the data coming from the `root_physx_view` to (num_instances, num_objects, data_size).
`reshape_data_to_view`(data)	Reshapes and arranges the data to the be consistent with data from the `root_physx_view`.
`set_debug_vis`(debug_vis)	Sets whether to visualize the asset data.

Attributes:

`cfg`	Configuration instance for the rigid object collection.
`data`	Data related to the asset.
`num_instances`	Number of instances of the collection.
`num_objects`	Number of objects in the collection.
`object_names`	Ordered names of objects in the rigid object collection.
`root_physx_view`	Rigid body view for the rigid body collection (PhysX).
`device`	Memory device for computation.
`has_debug_vis_implementation`	Whether the asset has a debug visualization implemented.
`is_initialized`	Whether the asset is initialized.

__init__(cfg: RigidObjectCollectionCfg)[source]#

Initialize the rigid object collection.

Parameters:: cfg – A configuration instance.

cfg: RigidObjectCollectionCfg#: Configuration instance for the rigid object collection.

property data: RigidObjectCollectionData#: Data related to the asset.

property num_instances: int#: Number of instances of the collection.

property num_objects: int#

Number of objects in the collection.

This corresponds to the distinct number of rigid bodies in the collection.

property object_names: list[str]#: Ordered names of objects in the rigid object collection.

property root_physx_view: omni.physics.tensors.impl.api.RigidBodyView#: Rigid body view for the rigid body collection (PhysX).

Note

Use this view with caution. It requires handling of tensors in a specific way.

reset(env_ids: torch.Tensor | None = None, object_ids: slice | torch.Tensor | None = None)[source]#

Resets all internal buffers of selected environments and objects.

Parameters:

env_ids – The indices of the object to reset. Defaults to None (all instances).
object_ids – The indices of the object to reset. Defaults to None (all objects).

write_data_to_sim()[source]#: Write external wrench to the simulation.

Note

We write external wrench to the simulation here since this function is called before the simulation step. This ensures that the external wrench is applied at every simulation step.

update(dt: float)[source]#

Update the internal buffers.

The time step dt is used to compute numerical derivatives of quantities such as joint accelerations which are not provided by the simulator.

Parameters:: dt – The amount of time passed from last update call.

find_objects(name_keys: str | Sequence[str], preserve_order: bool = False) → tuple[torch.Tensor, list[str]][source]#

Find objects in the collection based on the name keys.

Please check the omni.isaac.lab.utils.string_utils.resolve_matching_names() function for more information on the name matching.

Parameters:

name_keys – A regular expression or a list of regular expressions to match the object names.
preserve_order – Whether to preserve the order of the name keys in the output. Defaults to False.

Returns:

A tuple containing the object indices and names.

write_object_state_to_sim(object_state: torch.Tensor, env_ids: torch.Tensor | None = None, object_ids: slice | torch.Tensor | None = None)[source]#

Set the object state over selected environment and object indices into the simulation.

The object state comprises of the cartesian position, quaternion orientation in (w, x, y, z), and linear and angular velocity. All the quantities are in the simulation frame.

Parameters:

object_state – Object state in simulation frame. Shape is (len(env_ids), len(object_ids), 13).
env_ids – Environment indices. If None, then all indices are used.
object_ids – Object indices. If None, then all indices are used.

write_object_pose_to_sim(object_pose: torch.Tensor, env_ids: torch.Tensor | None = None, object_ids: slice | torch.Tensor | None = None)[source]#

Set the object pose over selected environment and object indices into the simulation.

The object pose comprises of the cartesian position and quaternion orientation in (w, x, y, z).

Parameters:

object_pose – Object poses in simulation frame. Shape is (len(env_ids), len(object_ids), 7).
env_ids – Environment indices. If None, then all indices are used.
object_ids – Object indices. If None, then all indices are used.

write_object_velocity_to_sim(object_velocity: torch.Tensor, env_ids: torch.Tensor | None = None, object_ids: slice | torch.Tensor | None = None)[source]#

Set the object velocity over selected environment and object indices into the simulation.

Parameters:

object_velocity – Object velocities in simulation frame. Shape is (len(env_ids), len(object_ids), 6).
env_ids – Environment indices. If None, then all indices are used.
object_ids – Object indices. If None, then all indices are used.

set_external_force_and_torque(forces: torch.Tensor, torques: torch.Tensor, object_ids: slice | torch.Tensor | None = None, env_ids: torch.Tensor | None = None)[source]#

Set external force and torque to apply on the objects’ bodies in their local frame.

For many applications, we want to keep the applied external force on rigid bodies constant over a period of time (for instance, during the policy control). This function allows us to store the external force and torque into buffers which are then applied to the simulation at every step.

Caution

If the function is called with empty forces and torques, then this function disables the application of external wrench to the simulation.

# example of disabling external wrench
asset.set_external_force_and_torque(forces=torch.zeros(0, 0, 3), torques=torch.zeros(0, 0, 3))

Note

This function does not apply the external wrench to the simulation. It only fills the buffers with the desired values. To apply the external wrench, call the write_data_to_sim() function right before the simulation step.

Parameters:

forces – External forces in bodies’ local frame. Shape is (len(env_ids), len(object_ids), 3).
torques – External torques in bodies’ local frame. Shape is (len(env_ids), len(object_ids), 3).
object_ids – Object indices to apply external wrench to. Defaults to None (all objects).
env_ids – Environment indices to apply external wrench to. Defaults to None (all instances).

reshape_view_to_data(data: torch.Tensor) → torch.Tensor[source]#

Reshapes and arranges the data coming from the root_physx_view to (num_instances, num_objects, data_size).

Parameters:: data – The data coming from the root_physx_view. Shape is (num_instances*num_objects, data_size).
Returns:: The reshaped data. Shape is (num_instances, num_objects, data_size).

reshape_data_to_view(data: torch.Tensor) → torch.Tensor[source]#

Reshapes and arranges the data to the be consistent with data from the root_physx_view.

Parameters:: data – The data to be reshaped. Shape is (num_instances, num_objects, data_size).
Returns:: The reshaped data. Shape is (num_instances*num_objects, data_size).

property device: str#: Memory device for computation.

property has_debug_vis_implementation: bool#: Whether the asset has a debug visualization implemented.

property is_initialized: bool#

Whether the asset is initialized.

Returns True if the asset is initialized, False otherwise.

set_debug_vis(debug_vis: bool) → bool#

Sets whether to visualize the asset data.

Parameters:: debug_vis – Whether to visualize the asset data.
Returns:: Whether the debug visualization was successfully set. False if the asset does not support debug visualization.

class omni.isaac.lab.assets.RigidObjectCollectionData[source]#

Bases: object

Data container for a rigid object collection.

This class contains the data for a rigid object collection in the simulation. The data includes the state of all the bodies in the collection. The data is stored in the simulation world frame unless otherwise specified. The data is in the order (num_instances, num_objects, data_size), where data_size is the size of the data.

For a rigid body, there are two frames of reference that are used:

Actor frame: The frame of reference of the rigid body prim. This typically corresponds to the Xform prim with the rigid body schema.
Center of mass frame: The frame of reference of the center of mass of the rigid body.

Depending on the settings of the simulation, the actor frame and the center of mass frame may be the same. This needs to be taken into account when interpreting the data.

The data is lazily updated, meaning that the data is only updated when it is accessed. This is useful when the data is expensive to compute or retrieve. The data is updated when the timestamp of the buffer is older than the current simulation timestamp. The timestamp is updated whenever the data is updated.

Methods:

update(dt)

Updates the data for the rigid object collection.

Attributes:

`object_names`	Object names in the order parsed by the simulation view.
`default_object_state`	Default object state `[pos, quat, lin_vel, ang_vel]` in local environment frame.
`default_mass`	Default object mass read from the simulation.
`default_inertia`	Default object inertia tensor read from the simulation.
`object_state_w`	Object state `[pos, quat, lin_vel, ang_vel]` in simulation world frame.
`object_acc_w`	Acceleration of all objects.
`projected_gravity_b`	Projection of the gravity direction on base frame.
`heading_w`	Yaw heading of the base frame (in radians).
`object_pos_w`	Object position in simulation world frame.
`object_quat_w`	Object orientation (w, x, y, z) in simulation world frame.
`object_vel_w`	Object velocity in simulation world frame.
`object_lin_vel_w`	Object linear velocity in simulation world frame.
`object_ang_vel_w`	Object angular velocity in simulation world frame.
`object_lin_vel_b`	Object linear velocity in base frame.
`object_ang_vel_b`	Object angular velocity in base world frame.
`object_lin_acc_w`	Linear acceleration of all bodies in simulation world frame.
`object_ang_acc_w`	Angular acceleration of all bodies in simulation world frame.

update(dt: float)[source]#

Updates the data for the rigid object collection.

Parameters:: dt – The time step for the update. This must be a positive value.

object_names: list[str] = None#: Object names in the order parsed by the simulation view.

default_object_state: torch.Tensor = None#

Default object state [pos, quat, lin_vel, ang_vel] in local environment frame. Shape is (num_instances, num_objects, 13).

The position and quaternion are of each object’s rigid body’s actor frame. Meanwhile, the linear and angular velocities are of the center of mass frame.

default_mass: torch.Tensor = None#: Default object mass read from the simulation. Shape is (num_instances, num_objects, 1).

default_inertia: torch.Tensor = None#

Default object inertia tensor read from the simulation. Shape is (num_instances, num_objects, 9).

The inertia is the inertia tensor relative to the center of mass frame. The values are stored in the order \([I_{xx}, I_{xy}, I_{xz}, I_{yx}, I_{yy}, I_{yz}, I_{zx}, I_{zy}, I_{zz}]\).

property object_state_w#

Object state [pos, quat, lin_vel, ang_vel] in simulation world frame. Shape is (num_instances, num_objects, 13).

The position and orientation are of the rigid body’s actor frame. Meanwhile, the linear and angular velocities are of the rigid body’s center of mass frame.

property object_acc_w#

Acceleration of all objects. Shape is (num_instances, num_objects, 6).

This quantity is the acceleration of the rigid bodies’ center of mass frame.

property projected_gravity_b#: Projection of the gravity direction on base frame. Shape is (num_instances, num_objects, 3).

property heading_w#: Yaw heading of the base frame (in radians). Shape is (num_instances, num_objects,).

Note

This quantity is computed by assuming that the forward-direction of the base frame is along x-direction, i.e. \((1, 0, 0)\).

property object_pos_w: torch.Tensor#

Object position in simulation world frame. Shape is (num_instances, num_objects, 3).

This quantity is the position of the actor frame of the rigid bodies.

property object_quat_w: torch.Tensor#

Object orientation (w, x, y, z) in simulation world frame. Shape is (num_instances, num_objects, 4).

This quantity is the orientation of the actor frame of the rigid bodies.

property object_vel_w: torch.Tensor#

Object velocity in simulation world frame. Shape is (num_instances, num_objects, 6).

This quantity contains the linear and angular velocities of the rigid bodies’ center of mass frame.

property object_lin_vel_w: torch.Tensor#

Object linear velocity in simulation world frame. Shape is (num_instances, num_objects, 3).

This quantity is the linear velocity of the rigid bodies’ center of mass frame.

property object_ang_vel_w: torch.Tensor#

Object angular velocity in simulation world frame. Shape is (num_instances, num_objects, 3).

This quantity is the angular velocity of the rigid bodies’ center of mass frame.

property object_lin_vel_b: torch.Tensor#

Object linear velocity in base frame. Shape is (num_instances, num_objects, 3).

This quantity is the linear velocity of the rigid bodies’ center of mass frame with respect to the rigid body’s actor frame.

property object_ang_vel_b: torch.Tensor#

Object angular velocity in base world frame. Shape is (num_instances, num_objects, 3).

This quantity is the angular velocity of the rigid bodies’ center of mass frame with respect to the rigid body’s actor frame.

property object_lin_acc_w: torch.Tensor#

Linear acceleration of all bodies in simulation world frame. Shape is (num_instances, num_objects, 3).

This quantity is the linear acceleration of the rigid bodies’ center of mass frame.

property object_ang_acc_w: torch.Tensor#

Angular acceleration of all bodies in simulation world frame. Shape is (num_instances, num_objects, 3).

This quantity is the angular acceleration of the rigid bodies’ center of mass frame.

class omni.isaac.lab.assets.RigidObjectCollectionCfg[source]#

Bases: object

Configuration parameters for a rigid object collection.

Attributes:

rigid_objects

Dictionary of rigid object configurations to spawn.

rigid_objects: dict[str, omni.isaac.lab.assets.rigid_object.rigid_object_cfg.RigidObjectCfg]#

Dictionary of rigid object configurations to spawn.

The keys are the names for the objects, which are used as unique identifiers throughout the code.

Articulation#

class omni.isaac.lab.assets.Articulation[source]#

Bases: AssetBase

An articulation asset class.

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, prismatic, D-6, etc. However, the articulation class has currently been tested with revolute and prismatic joints. The class supports both floating-base and fixed-base articulations. The type of articulation is determined based on the root joint of the articulation. If the root joint is fixed, then the articulation is considered a fixed-base system. Otherwise, it is considered a floating-base system. This can be checked using the Articulation.is_fixed_base attribute.

For an asset to be considered an articulation, the root prim of the asset must have the USD ArticulationRootAPI. This API is used to define the sub-tree of the articulation using the reduced coordinate formulation. On playing the simulation, the physics engine parses the articulation root prim and creates the corresponding articulation in the physics engine. The articulation root prim can be specified using the AssetBaseCfg.prim_path attribute.

The articulation class also provides the functionality to augment the simulation of an articulated system with custom actuator models. These models can either be explicit or implicit, as detailed in the omni.isaac.lab.actuators module. The actuator models are specified using the ArticulationCfg.actuators attribute. These are then parsed and used to initialize the corresponding actuator models, when the simulation is played.

During the simulation step, the articulation class first applies the actuator models to compute the joint commands based on the user-specified targets. These joint commands are then applied into the simulation. The joint commands can be either position, velocity, or effort commands. As an example, the following snippet shows how this can be used for position commands:

# an example instance of the articulation class
my_articulation = Articulation(cfg)

# set joint position targets
my_articulation.set_joint_position_target(position)
# propagate the actuator models and apply the computed commands into the simulation
my_articulation.write_data_to_sim()

# step the simulation using the simulation context
sim_context.step()

# update the articulation state, where dt is the simulation time step
my_articulation.update(dt)

Attributes:

`cfg`	Configuration instance for the articulations.
`actuators`	Dictionary of actuator instances for the articulation.
`data`	Data related to the asset.
`num_instances`	Number of instances of the asset.
`is_fixed_base`	Whether the articulation is a fixed-base or floating-base system.
`num_joints`	Number of joints in articulation.
`num_fixed_tendons`	Number of fixed tendons in articulation.
`num_bodies`	Number of bodies in articulation.
`joint_names`	Ordered names of joints in articulation.
`fixed_tendon_names`	Ordered names of fixed tendons in articulation.
`body_names`	Ordered names of bodies in articulation.
`root_physx_view`	Articulation view for the asset (PhysX).
`device`	Memory device for computation.
`has_debug_vis_implementation`	Whether the asset has a debug visualization implemented.
`is_initialized`	Whether the asset is initialized.

Methods:

`__init__`(cfg)	Initialize the articulation.
`reset`([env_ids])	Resets all internal buffers of selected environments.
`write_data_to_sim`()	Write external wrenches and joint commands to the simulation.
`update`(dt)	Update the internal buffers.
`find_bodies`(name_keys[, preserve_order])	Find bodies in the articulation based on the name keys.
`find_joints`(name_keys[, joint_subset, ...])	Find joints in the articulation based on the name keys.
`find_fixed_tendons`(name_keys[, ...])	Find fixed tendons in the articulation based on the name keys.
`write_root_state_to_sim`(root_state[, env_ids])	Set the root state over selected environment indices into the simulation.
`write_root_pose_to_sim`(root_pose[, env_ids])	Set the root pose over selected environment indices into the simulation.
`write_root_velocity_to_sim`(root_velocity[, ...])	Set the root velocity over selected environment indices into the simulation.
`write_joint_state_to_sim`(position, velocity)	Write joint positions and velocities to the simulation.
`write_joint_stiffness_to_sim`(stiffness[, ...])	Write joint stiffness into the simulation.
`write_joint_damping_to_sim`(damping[, ...])	Write joint damping into the simulation.
`write_joint_effort_limit_to_sim`(limits[, ...])	Write joint effort limits into the simulation.
`write_joint_armature_to_sim`(armature[, ...])	Write joint armature into the simulation.
`write_joint_friction_to_sim`(joint_friction)	Write joint friction into the simulation.
`write_joint_limits_to_sim`(limits[, ...])	Write joint limits into the simulation.
`set_external_force_and_torque`(forces, torques)	Set external force and torque to apply on the asset's bodies in their local frame.
`set_joint_position_target`(target[, ...])	Set joint position targets into internal buffers.
`set_joint_velocity_target`(target[, ...])	Set joint velocity targets into internal buffers.
`set_joint_effort_target`(target[, joint_ids, ...])	Set joint efforts into internal buffers.
`set_fixed_tendon_stiffness`(stiffness[, ...])	Set fixed tendon stiffness into internal buffers.
`set_fixed_tendon_damping`(damping[, ...])	Set fixed tendon damping into internal buffers.
`set_fixed_tendon_limit_stiffness`(limit_stiffness)	Set fixed tendon limit stiffness efforts into internal buffers.
`set_fixed_tendon_limit`(limit[, ...])	Set fixed tendon limit efforts into internal buffers.
`set_fixed_tendon_rest_length`(rest_length[, ...])	Set fixed tendon rest length efforts into internal buffers.
`set_fixed_tendon_offset`(offset[, ...])	Set fixed tendon offset efforts into internal buffers.
`write_fixed_tendon_properties_to_sim`([...])	Write fixed tendon properties into the simulation.
`set_debug_vis`(debug_vis)	Sets whether to visualize the asset data.

cfg: ArticulationCfg#: Configuration instance for the articulations.

actuators: dict[str, ActuatorBase]#

Dictionary of actuator instances for the articulation.

The keys are the actuator names and the values are the actuator instances. The actuator instances are initialized based on the actuator configurations specified in the ArticulationCfg.actuators attribute. They are used to compute the joint commands during the write_data_to_sim() function.

__init__(cfg: ArticulationCfg)[source]#

Initialize the articulation.

Parameters:: cfg – A configuration instance.

property data: ArticulationData#: Data related to the asset.

property num_instances: int#

Number of instances of the asset.

This is equal to the number of asset instances per environment multiplied by the number of environments.

property is_fixed_base: bool#: Whether the articulation is a fixed-base or floating-base system.

property num_joints: int#: Number of joints in articulation.

property num_fixed_tendons: int#: Number of fixed tendons in articulation.

property num_bodies: int#: Number of bodies in articulation.

property joint_names: list[str]#: Ordered names of joints in articulation.

property fixed_tendon_names: list[str]#: Ordered names of fixed tendons in articulation.

property body_names: list[str]#: Ordered names of bodies in articulation.

property root_physx_view: omni.physics.tensors.impl.api.ArticulationView#: Articulation view for the asset (PhysX).

Note

Use this view with caution. It requires handling of tensors in a specific way.

reset(env_ids: Sequence[int] | None = None)[source]#

Resets all internal buffers of selected environments.

Parameters:: env_ids – The indices of the object to reset. Defaults to None (all instances).

write_data_to_sim()[source]#

Write external wrenches and joint commands to the simulation.

If any explicit actuators are present, then the actuator models are used to compute the joint commands. Otherwise, the joint commands are directly set into the simulation.

Note

We write external wrench to the simulation here since this function is called before the simulation step. This ensures that the external wrench is applied at every simulation step.

update(dt: float)[source]#

Update the internal buffers.

The time step dt is used to compute numerical derivatives of quantities such as joint accelerations which are not provided by the simulator.

Parameters:: dt – The amount of time passed from last update call.

find_bodies(name_keys: str | Sequence[str], preserve_order: bool = False) → tuple[list[int], list[str]][source]#

Find bodies in the articulation based on the name keys.

Please check the omni.isaac.lab.utils.string_utils.resolve_matching_names() function for more information on the name matching.

Parameters:

name_keys – A regular expression or a list of regular expressions to match the body names.
preserve_order – Whether to preserve the order of the name keys in the output. Defaults to False.

Returns:

A tuple of lists containing the body indices and names.

find_joints(name_keys: str | Sequence[str], joint_subset: list[str] | None = None, preserve_order: bool = False) → tuple[list[int], list[str]][source]#

Find joints in the articulation based on the name keys.

Please see the omni.isaac.lab.utils.string.resolve_matching_names() function for more information on the name matching.

Parameters:

name_keys – A regular expression or a list of regular expressions to match the joint names.
joint_subset – A subset of joints to search for. Defaults to None, which means all joints in the articulation are searched.
preserve_order – Whether to preserve the order of the name keys in the output. Defaults to False.

Returns:

A tuple of lists containing the joint indices and names.

find_fixed_tendons(name_keys: str | Sequence[str], tendon_subsets: list[str] | None = None, preserve_order: bool = False) → tuple[list[int], list[str]][source]#

Find fixed tendons in the articulation based on the name keys.

Please see the omni.isaac.lab.utils.string.resolve_matching_names() function for more information on the name matching.

Parameters:

name_keys – A regular expression or a list of regular expressions to match the joint names with fixed tendons.
tendon_subsets – A subset of joints with fixed tendons to search for. Defaults to None, which means all joints in the articulation are searched.
preserve_order – Whether to preserve the order of the name keys in the output. Defaults to False.

Returns:

A tuple of lists containing the tendon indices and names.

write_root_state_to_sim(root_state: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the root state over selected environment indices into the simulation.

The root state comprises of the cartesian position, quaternion orientation in (w, x, y, z), and linear and angular velocity. All the quantities are in the simulation frame.

Parameters:

root_state – Root state in simulation frame. Shape is (len(env_ids), 13).
env_ids – Environment indices. If None, then all indices are used.

write_root_pose_to_sim(root_pose: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the root pose over selected environment indices into the simulation.

The root pose comprises of the cartesian position and quaternion orientation in (w, x, y, z).

Parameters:

root_pose – Root poses in simulation frame. Shape is (len(env_ids), 7).
env_ids – Environment indices. If None, then all indices are used.

write_root_velocity_to_sim(root_velocity: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the root velocity over selected environment indices into the simulation.

Parameters:

root_velocity – Root velocities in simulation frame. Shape is (len(env_ids), 6).
env_ids – Environment indices. If None, then all indices are used.

write_joint_state_to_sim(position: torch.Tensor, velocity: torch.Tensor, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | slice | None = None)[source]#

Write joint positions and velocities to the simulation.

Parameters:

position – Joint positions. Shape is (len(env_ids), len(joint_ids)).
velocity – Joint velocities. Shape is (len(env_ids), len(joint_ids)).
joint_ids – The joint indices to set the targets for. Defaults to None (all joints).
env_ids – The environment indices to set the targets for. Defaults to None (all environments).

write_joint_stiffness_to_sim(stiffness: torch.Tensor | float, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Write joint stiffness into the simulation.

Parameters:

stiffness – Joint stiffness. Shape is (len(env_ids), len(joint_ids)).
joint_ids – The joint indices to set the stiffness for. Defaults to None (all joints).
env_ids – The environment indices to set the stiffness for. Defaults to None (all environments).

write_joint_damping_to_sim(damping: torch.Tensor | float, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Write joint damping into the simulation.

Parameters:

damping – Joint damping. Shape is (len(env_ids), len(joint_ids)).
joint_ids – The joint indices to set the damping for. Defaults to None (all joints).
env_ids – The environment indices to set the damping for. Defaults to None (all environments).

write_joint_effort_limit_to_sim(limits: torch.Tensor | float, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Write joint effort limits into the simulation.

Parameters:

limits – Joint torque limits. Shape is (len(env_ids), len(joint_ids)).
joint_ids – The joint indices to set the joint torque limits for. Defaults to None (all joints).
env_ids – The environment indices to set the joint torque limits for. Defaults to None (all environments).

write_joint_armature_to_sim(armature: torch.Tensor | float, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Write joint armature into the simulation.

Parameters:

armature – Joint armature. Shape is (len(env_ids), len(joint_ids)).
joint_ids – The joint indices to set the joint torque limits for. Defaults to None (all joints).
env_ids – The environment indices to set the joint torque limits for. Defaults to None (all environments).

write_joint_friction_to_sim(joint_friction: torch.Tensor | float, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Write joint friction into the simulation.

Parameters:

joint_friction – Joint friction. Shape is (len(env_ids), len(joint_ids)).
joint_ids – The joint indices to set the joint torque limits for. Defaults to None (all joints).
env_ids – The environment indices to set the joint torque limits for. Defaults to None (all environments).

write_joint_limits_to_sim(limits: torch.Tensor | float, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Write joint limits into the simulation.

Parameters:

limits – Joint limits. Shape is (len(env_ids), len(joint_ids), 2).
joint_ids – The joint indices to set the limits for. Defaults to None (all joints).
env_ids – The environment indices to set the limits for. Defaults to None (all environments).

set_external_force_and_torque(forces: torch.Tensor, torques: torch.Tensor, body_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set external force and torque to apply on the asset’s bodies in their local frame.

For many applications, we want to keep the applied external force on rigid bodies constant over a period of time (for instance, during the policy control). This function allows us to store the external force and torque into buffers which are then applied to the simulation at every step.

Caution

If the function is called with empty forces and torques, then this function disables the application of external wrench to the simulation.

# example of disabling external wrench
asset.set_external_force_and_torque(forces=torch.zeros(0, 3), torques=torch.zeros(0, 3))

Note

This function does not apply the external wrench to the simulation. It only fills the buffers with the desired values. To apply the external wrench, call the write_data_to_sim() function right before the simulation step.

Parameters:

forces – External forces in bodies’ local frame. Shape is (len(env_ids), len(body_ids), 3).
torques – External torques in bodies’ local frame. Shape is (len(env_ids), len(body_ids), 3).
body_ids – Body indices to apply external wrench to. Defaults to None (all bodies).
env_ids – Environment indices to apply external wrench to. Defaults to None (all instances).

set_joint_position_target(target: torch.Tensor, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set joint position targets into internal buffers.

Note

This function does not apply the joint targets to the simulation. It only fills the buffers with the desired values. To apply the joint targets, call the write_data_to_sim() function.

Parameters:

target – Joint position targets. Shape is (len(env_ids), len(joint_ids)).
joint_ids – The joint indices to set the targets for. Defaults to None (all joints).
env_ids – The environment indices to set the targets for. Defaults to None (all environments).

set_joint_velocity_target(target: torch.Tensor, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set joint velocity targets into internal buffers.

Note

This function does not apply the joint targets to the simulation. It only fills the buffers with the desired values. To apply the joint targets, call the write_data_to_sim() function.

Parameters:

target – Joint velocity targets. Shape is (len(env_ids), len(joint_ids)).
joint_ids – The joint indices to set the targets for. Defaults to None (all joints).
env_ids – The environment indices to set the targets for. Defaults to None (all environments).

set_joint_effort_target(target: torch.Tensor, joint_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set joint efforts into internal buffers.

Note

This function does not apply the joint targets to the simulation. It only fills the buffers with the desired values. To apply the joint targets, call the write_data_to_sim() function.

Parameters:

target – Joint effort targets. Shape is (len(env_ids), len(joint_ids)).
joint_ids – The joint indices to set the targets for. Defaults to None (all joints).
env_ids – The environment indices to set the targets for. Defaults to None (all environments).

set_fixed_tendon_stiffness(stiffness: torch.Tensor, fixed_tendon_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set fixed tendon stiffness into internal buffers.

Note

This function does not apply the tendon stiffness to the simulation. It only fills the buffers with the desired values. To apply the tendon stiffness, call the write_fixed_tendon_properties_to_sim() function.

Parameters:

stiffness – Fixed tendon stiffness. Shape is (len(env_ids), len(fixed_tendon_ids)).
fixed_tendon_ids – The tendon indices to set the stiffness for. Defaults to None (all fixed tendons).
env_ids – The environment indices to set the stiffness for. Defaults to None (all environments).

set_fixed_tendon_damping(damping: torch.Tensor, fixed_tendon_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set fixed tendon damping into internal buffers.

Note

This function does not apply the tendon damping to the simulation. It only fills the buffers with the desired values. To apply the tendon damping, call the write_fixed_tendon_properties_to_sim() function.

Parameters:

damping – Fixed tendon damping. Shape is (len(env_ids), len(fixed_tendon_ids)).
fixed_tendon_ids – The tendon indices to set the damping for. Defaults to None (all fixed tendons).
env_ids – The environment indices to set the damping for. Defaults to None (all environments).

set_fixed_tendon_limit_stiffness(limit_stiffness: torch.Tensor, fixed_tendon_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set fixed tendon limit stiffness efforts into internal buffers.

Note

This function does not apply the tendon limit stiffness to the simulation. It only fills the buffers with the desired values. To apply the tendon limit stiffness, call the write_fixed_tendon_properties_to_sim() function.

Parameters:

limit_stiffness – Fixed tendon limit stiffness. Shape is (len(env_ids), len(fixed_tendon_ids)).
fixed_tendon_ids – The tendon indices to set the limit stiffness for. Defaults to None (all fixed tendons).
env_ids – The environment indices to set the limit stiffness for. Defaults to None (all environments).

set_fixed_tendon_limit(limit: torch.Tensor, fixed_tendon_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set fixed tendon limit efforts into internal buffers.

Note

This function does not apply the tendon limit to the simulation. It only fills the buffers with the desired values. To apply the tendon limit, call the write_fixed_tendon_properties_to_sim() function.

Args:: limit: Fixed tendon limit. Shape is (len(env_ids), len(fixed_tendon_ids)). fixed_tendon_ids: The tendon indices to set the limit for. Defaults to None (all fixed tendons). env_ids: The environment indices to set the limit for. Defaults to None (all environments).

set_fixed_tendon_rest_length(rest_length: torch.Tensor, fixed_tendon_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set fixed tendon rest length efforts into internal buffers.

Note

This function does not apply the tendon rest length to the simulation. It only fills the buffers with the desired values. To apply the tendon rest length, call the write_fixed_tendon_properties_to_sim() function.

Parameters:

rest_length – Fixed tendon rest length. Shape is (len(env_ids), len(fixed_tendon_ids)).
fixed_tendon_ids – The tendon indices to set the rest length for. Defaults to None (all fixed tendons).
env_ids – The environment indices to set the rest length for. Defaults to None (all environments).

set_fixed_tendon_offset(offset: torch.Tensor, fixed_tendon_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Set fixed tendon offset efforts into internal buffers.

Note

This function does not apply the tendon offset to the simulation. It only fills the buffers with the desired values. To apply the tendon offset, call the write_fixed_tendon_properties_to_sim() function.

Parameters:

offset – Fixed tendon offset. Shape is (len(env_ids), len(fixed_tendon_ids)).
fixed_tendon_ids – The tendon indices to set the offset for. Defaults to None (all fixed tendons).
env_ids – The environment indices to set the offset for. Defaults to None (all environments).

write_fixed_tendon_properties_to_sim(fixed_tendon_ids: Sequence[int] | slice | None = None, env_ids: Sequence[int] | None = None)[source]#

Write fixed tendon properties into the simulation.

Parameters:

fixed_tendon_ids – The fixed tendon indices to set the limits for. Defaults to None (all fixed tendons).
env_ids – The environment indices to set the limits for. Defaults to None (all environments).

property device: str#: Memory device for computation.

property has_debug_vis_implementation: bool#: Whether the asset has a debug visualization implemented.

property is_initialized: bool#

Whether the asset is initialized.

Returns True if the asset is initialized, False otherwise.

set_debug_vis(debug_vis: bool) → bool#

Sets whether to visualize the asset data.

Parameters:: debug_vis – Whether to visualize the asset data.
Returns:: Whether the debug visualization was successfully set. False if the asset does not support debug visualization.

class omni.isaac.lab.assets.ArticulationData[source]#

Bases: object

Data container for an articulation.

This class contains the data for an articulation in the simulation. The data includes the state of the root rigid body, the state of all the bodies in the articulation, and the joint state. The data is stored in the simulation world frame unless otherwise specified.

An articulation is comprised of multiple rigid bodies or links. For a rigid body, there are two frames of reference that are used:

Actor frame: The frame of reference of the rigid body prim. This typically corresponds to the Xform prim with the rigid body schema.
Center of mass frame: The frame of reference of the center of mass of the rigid body.

Depending on the settings, the two frames may not coincide with each other. In the robotics sense, the actor frame can be interpreted as the link frame.

Attributes:

`body_names`	Body names in the order parsed by the simulation view.
`joint_names`	Joint names in the order parsed by the simulation view.
`fixed_tendon_names`	Fixed tendon names in the order parsed by the simulation view.
`default_root_state`	Default root state `[pos, quat, lin_vel, ang_vel]` in local environment frame.
`default_mass`	Default mass read from the simulation.
`default_inertia`	Default inertia read from the simulation.
`default_joint_pos`	Default joint positions of all joints.
`default_joint_vel`	Default joint velocities of all joints.
`default_joint_stiffness`	Default joint stiffness of all joints.
`default_joint_damping`	Default joint damping of all joints.
`default_joint_armature`	Default joint armature of all joints.
`default_joint_friction`	Default joint friction of all joints.
`default_joint_limits`	Default joint limits of all joints.
`default_fixed_tendon_stiffness`	Default tendon stiffness of all tendons.
`default_fixed_tendon_damping`	Default tendon damping of all tendons.
`default_fixed_tendon_limit_stiffness`	Default tendon limit stiffness of all tendons.
`default_fixed_tendon_rest_length`	Default tendon rest length of all tendons.
`default_fixed_tendon_offset`	Default tendon offset of all tendons.
`default_fixed_tendon_limit`	Default tendon limits of all tendons.
`joint_pos_target`	Joint position targets commanded by the user.
`joint_vel_target`	Joint velocity targets commanded by the user.
`joint_effort_target`	Joint effort targets commanded by the user.
`computed_torque`	Joint torques computed from the actuator model (before clipping).
`applied_torque`	Joint torques applied from the actuator model (after clipping).
`joint_stiffness`	Joint stiffness provided to simulation.
`joint_damping`	Joint damping provided to simulation.
`joint_armature`	Joint armature provided to simulation.
`joint_friction`	Joint friction provided to simulation.
`joint_limits`	Joint limits provided to simulation.
`fixed_tendon_stiffness`	Fixed tendon stiffness provided to simulation.
`fixed_tendon_damping`	Fixed tendon damping provided to simulation.
`fixed_tendon_limit_stiffness`	Fixed tendon limit stiffness provided to simulation.
`fixed_tendon_rest_length`	Fixed tendon rest length provided to simulation.
`fixed_tendon_offset`	Fixed tendon offset provided to simulation.
`fixed_tendon_limit`	Fixed tendon limits provided to simulation.
`soft_joint_pos_limits`	Joint positions limits for all joints.
`soft_joint_vel_limits`	Joint velocity limits for all joints.
`gear_ratio`	Gear ratio for relating motor torques to applied Joint torques.
`root_state_w`	Root state `[pos, quat, lin_vel, ang_vel]` in simulation world frame.
`body_state_w`	State of all bodies [pos, quat, lin_vel, ang_vel] in simulation world frame.
`body_acc_w`	Acceleration of all bodies.
`projected_gravity_b`	Projection of the gravity direction on base frame.
`heading_w`	Yaw heading of the base frame (in radians).
`joint_pos`	Joint positions of all joints.
`joint_vel`	Joint velocities of all joints.
`joint_acc`	Joint acceleration of all joints.
`root_pos_w`	Root position in simulation world frame.
`root_quat_w`	Root orientation (w, x, y, z) in simulation world frame.
`root_vel_w`	Root velocity in simulation world frame.
`root_lin_vel_w`	Root linear velocity in simulation world frame.
`root_ang_vel_w`	Root angular velocity in simulation world frame.
`root_lin_vel_b`	Root linear velocity in base frame.
`root_ang_vel_b`	Root angular velocity in base world frame.
`body_pos_w`	Positions of all bodies in simulation world frame.
`body_quat_w`	Orientation (w, x, y, z) of all bodies in simulation world frame.
`body_vel_w`	Velocity of all bodies in simulation world frame.
`body_lin_vel_w`	Linear velocity of all bodies in simulation world frame.
`body_ang_vel_w`	Angular velocity of all bodies in simulation world frame.
`body_lin_acc_w`	Linear acceleration of all bodies in simulation world frame.
`body_ang_acc_w`	Angular acceleration of all bodies in simulation world frame.

body_names: list[str] = None#: Body names in the order parsed by the simulation view.

joint_names: list[str] = None#: Joint names in the order parsed by the simulation view.

fixed_tendon_names: list[str] = None#: Fixed tendon names in the order parsed by the simulation view.

default_root_state: torch.Tensor = None#

Default root state [pos, quat, lin_vel, ang_vel] in local environment frame. Shape is (num_instances, 13).

The position and quaternion are of the articulation root’s actor frame. Meanwhile, the linear and angular velocities are of its center of mass frame.

default_mass: torch.Tensor = None#: Default mass read from the simulation. Shape is (num_instances, num_bodies).

default_inertia: torch.Tensor = None#

Default inertia read from the simulation. Shape is (num_instances, num_bodies, 9).

The inertia is the inertia tensor relative to the center of mass frame. The values are stored in the order \([I_{xx}, I_{xy}, I_{xz}, I_{yx}, I_{yy}, I_{yz}, I_{zx}, I_{zy}, I_{zz}]\).

default_joint_pos: torch.Tensor = None#: Default joint positions of all joints. Shape is (num_instances, num_joints).

default_joint_vel: torch.Tensor = None#: Default joint velocities of all joints. Shape is (num_instances, num_joints).

default_joint_stiffness: torch.Tensor = None#: Default joint stiffness of all joints. Shape is (num_instances, num_joints).

default_joint_damping: torch.Tensor = None#: Default joint damping of all joints. Shape is (num_instances, num_joints).

default_joint_armature: torch.Tensor = None#: Default joint armature of all joints. Shape is (num_instances, num_joints).

default_joint_friction: torch.Tensor = None#: Default joint friction of all joints. Shape is (num_instances, num_joints).

default_joint_limits: torch.Tensor = None#: Default joint limits of all joints. Shape is (num_instances, num_joints, 2).

default_fixed_tendon_stiffness: torch.Tensor = None#: Default tendon stiffness of all tendons. Shape is (num_instances, num_fixed_tendons).

default_fixed_tendon_damping: torch.Tensor = None#: Default tendon damping of all tendons. Shape is (num_instances, num_fixed_tendons).

default_fixed_tendon_limit_stiffness: torch.Tensor = None#: Default tendon limit stiffness of all tendons. Shape is (num_instances, num_fixed_tendons).

default_fixed_tendon_rest_length: torch.Tensor = None#: Default tendon rest length of all tendons. Shape is (num_instances, num_fixed_tendons).

default_fixed_tendon_offset: torch.Tensor = None#: Default tendon offset of all tendons. Shape is (num_instances, num_fixed_tendons).

default_fixed_tendon_limit: torch.Tensor = None#: Default tendon limits of all tendons. Shape is (num_instances, num_fixed_tendons, 2).

joint_pos_target: torch.Tensor = None#

Joint position targets commanded by the user. Shape is (num_instances, num_joints).

For an implicit actuator model, the targets are directly set into the simulation. For an explicit actuator model, the targets are used to compute the joint torques (see applied_torque), which are then set into the simulation.

joint_vel_target: torch.Tensor = None#

Joint velocity targets commanded by the user. Shape is (num_instances, num_joints).

For an implicit actuator model, the targets are directly set into the simulation. For an explicit actuator model, the targets are used to compute the joint torques (see applied_torque), which are then set into the simulation.

joint_effort_target: torch.Tensor = None#

Joint effort targets commanded by the user. Shape is (num_instances, num_joints).

For an implicit actuator model, the targets are directly set into the simulation. For an explicit actuator model, the targets are used to compute the joint torques (see applied_torque), which are then set into the simulation.

computed_torque: torch.Tensor = None#

Joint torques computed from the actuator model (before clipping). Shape is (num_instances, num_joints).

This quantity is the raw torque output from the actuator mode, before any clipping is applied. It is exposed for users who want to inspect the computations inside the actuator model. For instance, to penalize the learning agent for a difference between the computed and applied torques.

Note: The torques are zero for implicit actuator models.

applied_torque: torch.Tensor = None#

Joint torques applied from the actuator model (after clipping). Shape is (num_instances, num_joints).

These torques are set into the simulation, after clipping the computed_torque based on the actuator model.

Note: The torques are zero for implicit actuator models.

joint_stiffness: torch.Tensor = None#: Joint stiffness provided to simulation. Shape is (num_instances, num_joints).

joint_damping: torch.Tensor = None#: Joint damping provided to simulation. Shape is (num_instances, num_joints).

joint_armature: torch.Tensor = None#: Joint armature provided to simulation. Shape is (num_instances, num_joints).

joint_friction: torch.Tensor = None#: Joint friction provided to simulation. Shape is (num_instances, num_joints).

joint_limits: torch.Tensor = None#: Joint limits provided to simulation. Shape is (num_instances, num_joints, 2).

fixed_tendon_stiffness: torch.Tensor = None#: Fixed tendon stiffness provided to simulation. Shape is (num_instances, num_fixed_tendons).

fixed_tendon_damping: torch.Tensor = None#: Fixed tendon damping provided to simulation. Shape is (num_instances, num_fixed_tendons).

fixed_tendon_limit_stiffness: torch.Tensor = None#: Fixed tendon limit stiffness provided to simulation. Shape is (num_instances, num_fixed_tendons).

fixed_tendon_rest_length: torch.Tensor = None#: Fixed tendon rest length provided to simulation. Shape is (num_instances, num_fixed_tendons).

fixed_tendon_offset: torch.Tensor = None#: Fixed tendon offset provided to simulation. Shape is (num_instances, num_fixed_tendons).

fixed_tendon_limit: torch.Tensor = None#: Fixed tendon limits provided to simulation. Shape is (num_instances, num_fixed_tendons, 2).

soft_joint_pos_limits: torch.Tensor = None#: Joint positions limits for all joints. Shape is (num_instances, num_joints, 2).

soft_joint_vel_limits: torch.Tensor = None#: Joint velocity limits for all joints. Shape is (num_instances, num_joints).

gear_ratio: torch.Tensor = None#: Gear ratio for relating motor torques to applied Joint torques. Shape is (num_instances, num_joints).

property root_state_w#

Root state [pos, quat, lin_vel, ang_vel] in simulation world frame. Shape is (num_instances, 13).

The position and quaternion are of the articulation root’s actor frame. Meanwhile, the linear and angular velocities are of the articulation root’s center of mass frame.

property body_state_w#

State of all bodies [pos, quat, lin_vel, ang_vel] in simulation world frame. Shape is (num_instances, num_bodies, 13).

The position and quaternion are of all the articulation links’s actor frame. Meanwhile, the linear and angular velocities are of the articulation links’s center of mass frame.

property body_acc_w#

Acceleration of all bodies. Shape is (num_instances, num_bodies, 6).

This quantity is the acceleration of the articulation links’ center of mass frame.

property projected_gravity_b#: Projection of the gravity direction on base frame. Shape is (num_instances, 3).

property heading_w#: Yaw heading of the base frame (in radians). Shape is (num_instances,).

Note

This quantity is computed by assuming that the forward-direction of the base frame is along x-direction, i.e. \((1, 0, 0)\).

property joint_pos#: Joint positions of all joints. Shape is (num_instances, num_joints).

property joint_vel#: Joint velocities of all joints. Shape is (num_instances, num_joints).

property joint_acc#: Joint acceleration of all joints. Shape is (num_instances, num_joints).

property root_pos_w: torch.Tensor#

Root position in simulation world frame. Shape is (num_instances, 3).

This quantity is the position of the actor frame of the articulation root.

property root_quat_w: torch.Tensor#

Root orientation (w, x, y, z) in simulation world frame. Shape is (num_instances, 4).

This quantity is the orientation of the actor frame of the articulation root.

property root_vel_w: torch.Tensor#

Root velocity in simulation world frame. Shape is (num_instances, 6).

This quantity contains the linear and angular velocities of the articulation root’s center of mass frame.

property root_lin_vel_w: torch.Tensor#

Root linear velocity in simulation world frame. Shape is (num_instances, 3).

This quantity is the linear velocity of the articulation root’s center of mass frame.

property root_ang_vel_w: torch.Tensor#

Root angular velocity in simulation world frame. Shape is (num_instances, 3).

This quantity is the angular velocity of the articulation root’s center of mass frame.

property root_lin_vel_b: torch.Tensor#

Root linear velocity in base frame. Shape is (num_instances, 3).

This quantity is the linear velocity of the articulation root’s center of mass frame with respect to the articulation root’s actor frame.

property root_ang_vel_b: torch.Tensor#

Root angular velocity in base world frame. Shape is (num_instances, 3).

This quantity is the angular velocity of the articulation root’s center of mass frame with respect to the articulation root’s actor frame.

property body_pos_w: torch.Tensor#

Positions of all bodies in simulation world frame. Shape is (num_instances, num_bodies, 3).

This quantity is the position of the rigid bodies’ actor frame.

property body_quat_w: torch.Tensor#

Orientation (w, x, y, z) of all bodies in simulation world frame. Shape is (num_instances, num_bodies, 4).

This quantity is the orientation of the rigid bodies’ actor frame.

property body_vel_w: torch.Tensor#

Velocity of all bodies in simulation world frame. Shape is (num_instances, num_bodies, 6).

This quantity contains the linear and angular velocities of the rigid bodies’ center of mass frame.

property body_lin_vel_w: torch.Tensor#

Linear velocity of all bodies in simulation world frame. Shape is (num_instances, num_bodies, 3).

This quantity is the linear velocity of the rigid bodies’ center of mass frame.

property body_ang_vel_w: torch.Tensor#

Angular velocity of all bodies in simulation world frame. Shape is (num_instances, num_bodies, 3).

This quantity is the angular velocity of the rigid bodies’ center of mass frame.

property body_lin_acc_w: torch.Tensor#

Linear acceleration of all bodies in simulation world frame. Shape is (num_instances, num_bodies, 3).

This quantity is the linear acceleration of the rigid bodies’ center of mass frame.

property body_ang_acc_w: torch.Tensor#

Angular acceleration of all bodies in simulation world frame. Shape is (num_instances, num_bodies, 3).

This quantity is the angular acceleration of the rigid bodies’ center of mass frame.

class omni.isaac.lab.assets.ArticulationCfg[source]#

Bases: AssetBaseCfg

Configuration parameters for an articulation.

Classes:

InitialStateCfg

Initial state of the articulation.

Attributes:

`prim_path`	Prim path (or expression) to the asset.
`spawn`	Spawn configuration for the asset.
`collision_group`	Collision group of the asset.
`debug_vis`	Whether to enable debug visualization for the asset.
`init_state`	Initial state of the articulated object.
`soft_joint_pos_limit_factor`	Fraction specifying the range of DOF position limits (parsed from the asset) to use.
`actuators`	Actuators for the robot with corresponding joint names.

class InitialStateCfg[source]#

Bases: InitialStateCfg

Initial state of the articulation.

Attributes:

`lin_vel`	Linear velocity of the root in simulation world frame.
`ang_vel`	Angular velocity of the root in simulation world frame.
`joint_pos`	Joint positions of the joints.
`joint_vel`	Joint velocities of the joints.
`pos`	Position of the root in simulation world frame.
`rot`	Quaternion rotation (w, x, y, z) of the root in simulation world frame.

lin_vel: tuple[float, float, float]#: Linear velocity of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

ang_vel: tuple[float, float, float]#: Angular velocity of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

joint_pos: dict[str, float]#: Joint positions of the joints. Defaults to 0.0 for all joints.

joint_vel: dict[str, float]#: Joint velocities of the joints. Defaults to 0.0 for all joints.

pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

rot: tuple[float, float, float, float]#: Quaternion rotation (w, x, y, z) of the root in simulation world frame. Defaults to (1.0, 0.0, 0.0, 0.0).

prim_path: str#: Prim path (or expression) to the asset.

Note

The expression can contain the environment namespace regex {ENV_REGEX_NS} which will be replaced with the environment namespace.

Example: {ENV_REGEX_NS}/Robot will be replaced with /World/envs/env_.*/Robot.

spawn: SpawnerCfg | None#

Spawn configuration for the asset. Defaults to None.

If None, then no prims are spawned by the asset class. Instead, it is assumed that the asset is already present in the scene.

collision_group: Literal[0, -1]#

Collision group of the asset. Defaults to 0.

-1: global collision group (collides with all assets in the scene).
0: local collision group (collides with other assets in the same environment).

debug_vis: bool#: Whether to enable debug visualization for the asset. Defaults to False.

init_state: InitialStateCfg#: Initial state of the articulated object. Defaults to identity pose with zero velocity and zero joint state.

soft_joint_pos_limit_factor: float#

Fraction specifying the range of DOF position limits (parsed from the asset) to use. Defaults to 1.0.

The joint position limits are scaled by this factor to allow for a limited range of motion. This is accessible in the articulation data through ArticulationData.soft_joint_pos_limits attribute.

actuators: dict[str, omni.isaac.lab.actuators.actuator_cfg.ActuatorBaseCfg]#: Actuators for the robot with corresponding joint names.

Deformable Object#

class omni.isaac.lab.assets.DeformableObject[source]#

Bases: AssetBase

A deformable object asset class.

Deformable objects are assets that can be deformed in the simulation. They are typically used for soft bodies, such as stuffed animals and food items.

Unlike rigid object assets, deformable objects have a more complex structure and require additional handling for simulation. The simulation of deformable objects follows a finite element approach, where the object is discretized into a mesh of nodes and elements. The nodes are connected by elements, which define the material properties of the object. The nodes can be moved and deformed, and the elements respond to these changes.

The state of a deformable object comprises of its nodal positions and velocities, and not the object’s root position and orientation. The nodal positions and velocities are in the simulation frame.

Soft bodies can be partially kinematic, where some nodes are driven by kinematic targets, and the rest are simulated. The kinematic targets are the desired positions of the nodes, and the simulation drives the nodes towards these targets. This is useful for partial control of the object, such as moving a stuffed animal’s head while the rest of the body is simulated.

Attention

This class is experimental and subject to change due to changes on the underlying PhysX API on which it depends. We will try to maintain backward compatibility as much as possible but some changes may be necessary.

Attributes:

`cfg`	Configuration instance for the deformable object.
`data`	Data related to the asset.
`num_instances`	Number of instances of the asset.
`num_bodies`	Number of bodies in the asset.
`root_physx_view`	Deformable body view for the asset (PhysX).
`material_physx_view`	Deformable material view for the asset (PhysX).
`max_sim_elements_per_body`	The maximum number of simulation mesh elements per deformable body.
`max_collision_elements_per_body`	The maximum number of collision mesh elements per deformable body.
`max_sim_vertices_per_body`	The maximum number of simulation mesh vertices per deformable body.
`max_collision_vertices_per_body`	The maximum number of collision mesh vertices per deformable body.
`device`	Memory device for computation.
`has_debug_vis_implementation`	Whether the asset has a debug visualization implemented.
`is_initialized`	Whether the asset is initialized.

Methods:

`__init__`(cfg)	Initialize the deformable object.
`reset`([env_ids])	Resets all internal buffers of selected environments.
`write_data_to_sim`()	Writes data to the simulator.
`update`(dt)	Update the internal buffers.
`write_nodal_state_to_sim`(nodal_state[, env_ids])	Set the nodal state over selected environment indices into the simulation.
`write_nodal_pos_to_sim`(nodal_pos[, env_ids])	Set the nodal positions over selected environment indices into the simulation.
`write_nodal_velocity_to_sim`(nodal_vel[, env_ids])	Set the nodal velocity over selected environment indices into the simulation.
`write_nodal_kinematic_target_to_sim`(targets)	Set the kinematic targets of the simulation mesh for the deformable bodies indicated by the indices.
`transform_nodal_pos`(nodal_pos[, pos, quat])	Transform the nodal positions based on the pose transformation.
`set_debug_vis`(debug_vis)	Sets whether to visualize the asset data.

cfg: DeformableObjectCfg#: Configuration instance for the deformable object.

__init__(cfg: DeformableObjectCfg)[source]#

Initialize the deformable object.

Parameters:: cfg – A configuration instance.

property data: DeformableObjectData#: Data related to the asset.

property num_instances: int#

Number of instances of the asset.

This is equal to the number of asset instances per environment multiplied by the number of environments.

property num_bodies: int#

Number of bodies in the asset.

This is always 1 since each object is a single deformable body.

property root_physx_view: omni.physics.tensors.impl.api.SoftBodyView#: Deformable body view for the asset (PhysX).

Note

Use this view with caution. It requires handling of tensors in a specific way.

property material_physx_view: physx.SoftBodyMaterialView | None#

Deformable material view for the asset (PhysX).

This view is optional and may not be available if the material is not bound to the deformable body. If the material is not available, then the material properties will be set to default values.

Note

Use this view with caution. It requires handling of tensors in a specific way.

property max_sim_elements_per_body: int#: The maximum number of simulation mesh elements per deformable body.

property max_collision_elements_per_body: int#: The maximum number of collision mesh elements per deformable body.

property max_sim_vertices_per_body: int#: The maximum number of simulation mesh vertices per deformable body.

property max_collision_vertices_per_body: int#: The maximum number of collision mesh vertices per deformable body.

reset(env_ids: Sequence[int] | None = None)[source]#

Resets all internal buffers of selected environments.

Parameters:: env_ids – The indices of the object to reset. Defaults to None (all instances).

write_data_to_sim()[source]#: Writes data to the simulator.

update(dt: float)[source]#

Update the internal buffers.

The time step dt is used to compute numerical derivatives of quantities such as joint accelerations which are not provided by the simulator.

Parameters:: dt – The amount of time passed from last update call.

write_nodal_state_to_sim(nodal_state: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the nodal state over selected environment indices into the simulation.

The nodal state comprises of the nodal positions and velocities. Since these are nodes, the velocity only has a translational component. All the quantities are in the simulation frame.

Parameters:

nodal_state – Nodal state in simulation frame. Shape is (len(env_ids), max_sim_vertices_per_body, 6).
env_ids – Environment indices. If None, then all indices are used.

write_nodal_pos_to_sim(nodal_pos: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the nodal positions over selected environment indices into the simulation.

The nodal position comprises of individual nodal positions of the simulation mesh for the deformable body. The positions are in the simulation frame.

Parameters:

nodal_pos – Nodal positions in simulation frame. Shape is (len(env_ids), max_sim_vertices_per_body, 3).
env_ids – Environment indices. If None, then all indices are used.

write_nodal_velocity_to_sim(nodal_vel: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the nodal velocity over selected environment indices into the simulation.

The nodal velocity comprises of individual nodal velocities of the simulation mesh for the deformable body. Since these are nodes, the velocity only has a translational component. The velocities are in the simulation frame.

Parameters:

nodal_vel – Nodal velocities in simulation frame. Shape is (len(env_ids), max_sim_vertices_per_body, 3).
env_ids – Environment indices. If None, then all indices are used.

write_nodal_kinematic_target_to_sim(targets: torch.Tensor, env_ids: Sequence[int] | None = None)[source]#

Set the kinematic targets of the simulation mesh for the deformable bodies indicated by the indices.

The kinematic targets comprise of individual nodal positions of the simulation mesh for the deformable body and a flag indicating whether the node is kinematically driven or not. The positions are in the simulation frame.

Note

The flag is set to 0.0 for kinematically driven nodes and 1.0 for free nodes.

Parameters:

targets – The kinematic targets comprising of nodal positions and flags. Shape is (len(env_ids), max_sim_vertices_per_body, 4).
env_ids – Environment indices. If None, then all indices are used.

transform_nodal_pos(nodal_pos: torch.tensor, pos: torch.Tensor | None = None, quat: torch.Tensor | None = None) → torch.Tensor[source]#

Transform the nodal positions based on the pose transformation.

This function computes the transformation of the nodal positions based on the pose transformation. It multiplies the nodal positions with the rotation matrix of the pose and adds the translation. Internally, it calls the omni.isaac.lab.utils.math.transform_points() function.

Parameters:

nodal_pos – The nodal positions in the simulation frame. Shape is (N, max_sim_vertices_per_body, 3).
pos – The position transformation. Shape is (N, 3). Defaults to None, in which case the position is assumed to be zero.
quat – The orientation transformation as quaternion (w, x, y, z). Shape is (N, 4). Defaults to None, in which case the orientation is assumed to be identity.

Returns:

The transformed nodal positions. Shape is (N, max_sim_vertices_per_body, 3).

property device: str#: Memory device for computation.

property has_debug_vis_implementation: bool#: Whether the asset has a debug visualization implemented.

property is_initialized: bool#

Whether the asset is initialized.

Returns True if the asset is initialized, False otherwise.

set_debug_vis(debug_vis: bool) → bool#

Sets whether to visualize the asset data.

Parameters:: debug_vis – Whether to visualize the asset data.
Returns:: Whether the debug visualization was successfully set. False if the asset does not support debug visualization.

class omni.isaac.lab.assets.DeformableObjectData[source]#

Bases: object

Data container for a deformable object.

This class contains the data for a deformable object in the simulation. The data includes the nodal states of the root deformable body in the object. The data is stored in the simulation world frame unless otherwise specified.

A deformable object in PhysX uses two tetrahedral meshes to represent the object:

Simulation mesh: This mesh is used for the simulation and is the one that is deformed by the solver.
Collision mesh: This mesh only needs to match the surface of the simulation mesh and is used for collision detection.

The APIs exposed provides the data for both the simulation and collision meshes. These are specified by the sim and collision prefixes in the property names.

The data is lazily updated, meaning that the data is only updated when it is accessed. This is useful when the data is expensive to compute or retrieve. The data is updated when the timestamp of the buffer is older than the current simulation timestamp. The timestamp is updated whenever the data is updated.

Methods:

update(dt)

Updates the data for the deformable object.

Attributes:

`default_nodal_state_w`	Default nodal state `[nodal_pos, nodal_vel]` in simulation world frame.
`nodal_kinematic_target`	Simulation mesh kinematic targets for the deformable bodies.
`nodal_pos_w`	Nodal positions in simulation world frame.
`nodal_vel_w`	Nodal velocities in simulation world frame.
`nodal_state_w`	Nodal state `[nodal_pos, nodal_vel]` in simulation world frame.
`sim_element_quat_w`	Simulation mesh element-wise rotations as quaternions for the deformable bodies in simulation world frame.
`collision_element_quat_w`	Collision mesh element-wise rotations as quaternions for the deformable bodies in simulation world frame.
`sim_element_deform_gradient_w`	Simulation mesh element-wise second-order deformation gradient tensors for the deformable bodies in simulation world frame.
`collision_element_deform_gradient_w`	Collision mesh element-wise second-order deformation gradient tensors for the deformable bodies in simulation world frame.
`sim_element_stress_w`	Simulation mesh element-wise second-order Cauchy stress tensors for the deformable bodies in simulation world frame.
`collision_element_stress_w`	Collision mesh element-wise second-order Cauchy stress tensors for the deformable bodies in simulation world frame.
`root_pos_w`	Root position from nodal positions of the simulation mesh for the deformable bodies in simulation world frame.
`root_vel_w`	Root velocity from vertex velocities for the deformable bodies in simulation world frame.

update(dt: float)[source]#

Updates the data for the deformable object.

Parameters:: dt – The time step for the update. This must be a positive value.

default_nodal_state_w: torch.Tensor = None#: Default nodal state [nodal_pos, nodal_vel] in simulation world frame. Shape is (num_instances, max_sim_vertices_per_body, 6).

nodal_kinematic_target: torch.Tensor = None#

Simulation mesh kinematic targets for the deformable bodies. Shape is (num_instances, max_sim_vertices_per_body, 4).

The kinematic targets are used to drive the simulation mesh vertices to the target positions. The targets are stored as (x, y, z, is_not_kinematic) where “is_not_kinematic” is a binary flag indicating whether the vertex is kinematic or not. The flag is set to 0 for kinematic vertices and 1 for non-kinematic vertices.

property nodal_pos_w#: Nodal positions in simulation world frame. Shape is (num_instances, max_sim_vertices_per_body, 3).

property nodal_vel_w#: Nodal velocities in simulation world frame. Shape is (num_instances, max_sim_vertices_per_body, 3).

property nodal_state_w#: Nodal state [nodal_pos, nodal_vel] in simulation world frame. Shape is (num_instances, max_sim_vertices_per_body, 6).

property sim_element_quat_w#

Simulation mesh element-wise rotations as quaternions for the deformable bodies in simulation world frame. Shape is (num_instances, max_sim_elements_per_body, 4).

The rotations are stored as quaternions in the order (w, x, y, z).

property collision_element_quat_w#

Collision mesh element-wise rotations as quaternions for the deformable bodies in simulation world frame. Shape is (num_instances, max_collision_elements_per_body, 4).

The rotations are stored as quaternions in the order (w, x, y, z).

property sim_element_deform_gradient_w#: Simulation mesh element-wise second-order deformation gradient tensors for the deformable bodies in simulation world frame. Shape is (num_instances, max_sim_elements_per_body, 3, 3).

property collision_element_deform_gradient_w#: Collision mesh element-wise second-order deformation gradient tensors for the deformable bodies in simulation world frame. Shape is (num_instances, max_collision_elements_per_body, 3, 3).

property sim_element_stress_w#: Simulation mesh element-wise second-order Cauchy stress tensors for the deformable bodies in simulation world frame. Shape is (num_instances, max_sim_elements_per_body, 3, 3).

property collision_element_stress_w#: Collision mesh element-wise second-order Cauchy stress tensors for the deformable bodies in simulation world frame. Shape is (num_instances, max_collision_elements_per_body, 3, 3).

property root_pos_w: torch.Tensor#

Root position from nodal positions of the simulation mesh for the deformable bodies in simulation world frame. Shape is (num_instances, 3).

This quantity is computed as the mean of the nodal positions.

property root_vel_w: torch.Tensor#

Root velocity from vertex velocities for the deformable bodies in simulation world frame. Shape is (num_instances, 3).

This quantity is computed as the mean of the nodal velocities.

class omni.isaac.lab.assets.DeformableObjectCfg[source]#

Bases: AssetBaseCfg

Configuration parameters for a deformable object.

Classes:

InitialStateCfg

Initial state of the asset.

Attributes:

`prim_path`	Prim path (or expression) to the asset.
`spawn`	Spawn configuration for the asset.
`init_state`	Initial state of the rigid object.
`collision_group`	Collision group of the asset.
`debug_vis`	Whether to enable debug visualization for the asset.
`visualizer_cfg`	The configuration object for the visualization markers.

class InitialStateCfg#

Bases: object

Initial state of the asset.

This defines the default initial state of the asset when it is spawned into the simulation, as well as the default state when the simulation is reset.

After parsing the initial state, the asset class stores this information in the data attribute of the asset class. This can then be accessed by the user to modify the state of the asset during the simulation, for example, at resets.

Attributes:

`pos`	Position of the root in simulation world frame.
`rot`	Quaternion rotation (w, x, y, z) of the root in simulation world frame.

pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

rot: tuple[float, float, float, float]#: Quaternion rotation (w, x, y, z) of the root in simulation world frame. Defaults to (1.0, 0.0, 0.0, 0.0).

prim_path: str#: Prim path (or expression) to the asset.

Note

The expression can contain the environment namespace regex {ENV_REGEX_NS} which will be replaced with the environment namespace.

Example: {ENV_REGEX_NS}/Robot will be replaced with /World/envs/env_.*/Robot.

spawn: SpawnerCfg | None#

Spawn configuration for the asset. Defaults to None.

If None, then no prims are spawned by the asset class. Instead, it is assumed that the asset is already present in the scene.

init_state: InitialStateCfg#: Initial state of the rigid object. Defaults to identity pose.

collision_group: Literal[0, -1]#

Collision group of the asset. Defaults to 0.

-1: global collision group (collides with all assets in the scene).
0: local collision group (collides with other assets in the same environment).

debug_vis: bool#: Whether to enable debug visualization for the asset. Defaults to False.

visualizer_cfg: VisualizationMarkersCfg#: The configuration object for the visualization markers. Defaults to DEFORMABLE_TARGET_MARKER_CFG.

Note

This attribute is only used when debug visualization is enabled.

omni.isaac.lab.assets

Contents

omni.isaac.lab.assets#

Asset Base#

Rigid Object#

Rigid Object Collection#

Articulation#

Deformable Object#