omni.isaac.lab.sim

omni.isaac.lab.sim#

Sub-package containing simulation-specific functionalities.

These include:

Ability to spawn different objects and materials into Omniverse
Define and modify various schemas on USD prims
Converters to obtain USD file from other file formats (such as URDF, OBJ, STL, FBX)
Utility class to control the simulator

Note

Currently, only a subset of all possible schemas and prims in Omniverse are supported. We are expanding the these set of functions on a need basis. In case, there are specific prims or schemas that you would like to include, please open an issue on GitHub as a feature request elaborating on the required application.

To make it convenient to use the module, we recommend importing the module as follows:

import omni.isaac.lab.sim as sim_utils

Submodules

`converters`	Sub-module containing converters for converting various file types to USD.
`schemas`	Sub-module containing utilities for schemas used in Omniverse.
`spawners`	Sub-module containing utilities for creating prims in Omniverse.
`utils`	Sub-module with USD-related utilities.

Classes

`SimulationContext`	A class to control simulation-related events such as physics stepping and rendering.
`SimulationCfg`	Configuration for simulation physics.
`PhysxCfg`	Configuration for PhysX solver-related parameters.
`RenderCfg`	Configuration for Omniverse RTX Renderer.

Functions

simulation_context.build_simulation_context([...])

Context manager to build a simulation context with the provided settings.

Simulation Context#

class omni.isaac.lab.sim.SimulationContext[source]#

Bases: SimulationContext

A class to control simulation-related events such as physics stepping and rendering.

The simulation context helps control various simulation aspects. This includes:

configure the simulator with different settings such as the physics time-step, the number of physics substeps, and the physics solver parameters (for more information, see omni.isaac.lab.sim.SimulationCfg)
playing, pausing, stepping and stopping the simulation
adding and removing callbacks to different simulation events such as physics stepping, rendering, etc.

This class inherits from the omni.isaac.core.simulation_context.SimulationContext class and adds additional functionalities such as setting up the simulation context with a configuration object, exposing other commonly used simulator-related functions, and performing version checks of Isaac Sim to ensure compatibility between releases.

The simulation context is a singleton object. This means that there can only be one instance of the simulation context at any given time. This is enforced by the parent class. Therefore, it is not possible to create multiple instances of the simulation context. Instead, the simulation context can be accessed using the instance() method.

Attention

Since we only support the PyTorch backend for simulation, the simulation context is configured to use the torch backend by default. This means that all the data structures used in the simulation are torch.Tensor objects.

The simulation context can be used in two different modes of operations:

Standalone python script: In this mode, the user has full control over the simulation and can trigger stepping events synchronously (i.e. as a blocking call). In this case the user has to manually call step() step the physics simulation and render() to render the scene.
Omniverse extension: In this mode, the user has limited control over the simulation stepping and all the simulation events are triggered asynchronously (i.e. as a non-blocking call). In this case, the user can only trigger the simulation to start, pause, and stop. The simulation takes care of stepping the physics simulation and rendering the scene.

Based on above, for most functions in this class there is an equivalent function that is suffixed with _async. The _async functions are used in the Omniverse extension mode and the non-_async functions are used in the standalone python script mode.

Classes:

RenderMode

Different rendering modes for the simulation.

Methods:

`__init__`([cfg])	Creates a simulation context to control the simulator.
`has_gui`()	Returns whether the simulation has a GUI enabled.
`has_rtx_sensors`()	Returns whether the simulation has any RTX-rendering related sensors.
`is_fabric_enabled`()	Returns whether the fabric interface is enabled.
`get_version`()	Returns the version of the simulator.
`set_camera_view`(eye, target[, camera_prim_path])	Set the location and target of the viewport camera in the stage.
`set_render_mode`(mode)	Change the current render mode of the simulation.
`set_setting`(name, value)	Set simulation settings using the Carbonite SDK.
`get_setting`(name)	Read the simulation setting using the Carbonite SDK.
`step`([render])	Steps the simulation.
`render`([mode])	Refreshes the rendering components including UI elements and view-ports depending on the render mode.

class RenderMode[source]#

Bases: IntEnum

Different rendering modes for the simulation.

Render modes correspond to how the viewport and other UI elements (such as listeners to keyboard or mouse events) are updated. There are three main components that can be updated when the simulation is rendered:

UI elements and other extensions: These are UI elements (such as buttons, sliders, etc.) and other extensions that are running in the background that need to be updated when the simulation is running.
Cameras: These are typically based on Hydra textures and are used to render the scene from different viewpoints. They can be attached to a viewport or be used independently to render the scene.
Viewports: These are windows where you can see the rendered scene.

Updating each of the above components has a different overhead. For example, updating the viewports is computationally expensive compared to updating the UI elements. Therefore, it is useful to be able to control what is updated when the simulation is rendered. This is where the render mode comes in. There are four different render modes:

NO_GUI_OR_RENDERING: The simulation is running without a GUI and off-screen rendering flag is disabled, so none of the above are updated.
NO_RENDERING: No rendering, where only 1 is updated at a lower rate.
PARTIAL_RENDERING: Partial rendering, where only 1 and 2 are updated.
FULL_RENDERING: Full rendering, where everything (1, 2, 3) is updated.

Attributes:

`NO_GUI_OR_RENDERING`	The simulation is running without a GUI and off-screen rendering is disabled.
`NO_RENDERING`	No rendering, where only other UI elements are updated at a lower rate.
`PARTIAL_RENDERING`	Partial rendering, where the simulation cameras and UI elements are updated.
`FULL_RENDERING`	Full rendering, where all the simulation viewports, cameras and UI elements are updated.

NO_GUI_OR_RENDERING = -1#: The simulation is running without a GUI and off-screen rendering is disabled.

NO_RENDERING = 0#: No rendering, where only other UI elements are updated at a lower rate.

PARTIAL_RENDERING = 1#: Partial rendering, where the simulation cameras and UI elements are updated.

FULL_RENDERING = 2#: Full rendering, where all the simulation viewports, cameras and UI elements are updated.

__init__(cfg: SimulationCfg | None = None)[source]#

Creates a simulation context to control the simulator.

Parameters:: cfg – The configuration of the simulation. Defaults to None, in which case the default configuration is used.

has_gui() → bool[source]#

Returns whether the simulation has a GUI enabled.

True if the simulation has a GUI enabled either locally or live-streamed.

has_rtx_sensors() → bool[source]#

Returns whether the simulation has any RTX-rendering related sensors.

This function returns the value of the simulation parameter "/isaaclab/render/rtx_sensors". The parameter is set to True when instances of RTX-related sensors (cameras or LiDARs) are created using Isaac Lab’s sensor classes.

True if the simulation has RTX sensors (such as USD Cameras or LiDARs).

For more information, please check NVIDIA RTX documentation.

is_fabric_enabled() → bool[source]#

Returns whether the fabric interface is enabled.

When fabric interface is enabled, USD read/write operations are disabled. Instead all applications read and write the simulation state directly from the fabric interface. This reduces a lot of overhead that occurs during USD read/write operations.

For more information, please check Fabric documentation.

get_version() → tuple[int, int, int][source]#

Returns the version of the simulator.

This is a wrapper around the omni.isaac.version.get_version() function.

The returned tuple contains the following information:

Major version (int): This is the year of the release (e.g. 2022).
Minor version (int): This is the half-year of the release (e.g. 1 or 2).
Patch version (int): This is the patch number of the release (e.g. 0).

set_camera_view(eye: tuple[float, float, float], target: tuple[float, float, float], camera_prim_path: str = '/OmniverseKit_Persp')[source]#

Set the location and target of the viewport camera in the stage.

Note

This is a wrapper around the \(omni.isaac.core.utils.viewports.set_camera_view\) function. It is provided here for convenience to reduce the amount of imports needed.

Parameters:

eye – The location of the camera eye.
target – The location of the camera target.
camera_prim_path – The path to the camera primitive in the stage. Defaults to “/OmniverseKit_Persp”.

set_render_mode(mode: RenderMode)[source]#

Change the current render mode of the simulation.

Please see RenderMode for more information on the different render modes.

Note

When no GUI is available (locally or livestreamed), we do not need to choose whether the viewport needs to render or not (since there is no GUI). Thus, in this case, calling the function will not change the render mode.

Parameters:

mode (RenderMode) – The rendering mode. If different than SimulationContext’s rendering mode,
mode. (SimulationContext's mode is changed to the new) –

Raises:

ValueError – If the input mode is not supported.

set_setting(name: str, value: Any)[source]#

Set simulation settings using the Carbonite SDK.

Note

If the input setting name does not exist, it will be created. If it does exist, the value will be overwritten. Please make sure to use the correct setting name.

To understand the settings interface, please refer to the Carbonite SDK documentation.

Parameters:

name – The name of the setting.
value – The value of the setting.

get_setting(name: str) → Any[source]#

Read the simulation setting using the Carbonite SDK.

Parameters:: name – The name of the setting.
Returns:: The value of the setting.

step(render: bool = True)[source]#

Steps the simulation.

Note

This function blocks if the timeline is paused. It only returns when the timeline is playing.

Parameters:: render – Whether to render the scene after stepping the physics simulation. If set to False, the scene is not rendered and only the physics simulation is stepped.

render(mode: RenderMode | None = None)[source]#

Refreshes the rendering components including UI elements and view-ports depending on the render mode.

This function is used to refresh the rendering components of the simulation. This includes updating the view-ports, UI elements, and other extensions (besides physics simulation) that are running in the background. The rendering components are refreshed based on the render mode.

Please see RenderMode for more information on the different render modes.

Parameters:: mode – The rendering mode. Defaults to None, in which case the current rendering mode is used.

Simulation Configuration#

class omni.isaac.lab.sim.SimulationCfg[source]#

Bases: object

Configuration for simulation physics.

Attributes:

`physics_prim_path`	The prim path where the USD PhysicsScene is created.
`device`	The device to run the simulation on.
`dt`	The physics simulation time-step (in seconds).
`render_interval`	The number of physics simulation steps per rendering step.
`gravity`	The gravity vector (in m/s^2).
`enable_scene_query_support`	Enable/disable scene query support for collision shapes.
`use_fabric`	Enable/disable reading of physics buffers directly.
`disable_contact_processing`	Enable/disable contact processing.
`physx`	PhysX solver settings.
`physics_material`	Default physics material settings for rigid bodies.
`render`	Render settings.

physics_prim_path: str#: The prim path where the USD PhysicsScene is created. Default is “/physicsScene”.

device: str#

The device to run the simulation on. Default is "cuda:0".

Valid options are:

"cpu": Use CPU.
"cuda": Use GPU, where the device ID is inferred from AppLauncher’s config.
"cuda:N": Use GPU, where N is the device ID. For example, “cuda:0”.

dt: float#: The physics simulation time-step (in seconds). Default is 0.0167 seconds.

render_interval: int#: The number of physics simulation steps per rendering step. Default is 1.

gravity: tuple[float, float, float]#

The gravity vector (in m/s^2). Default is (0.0, 0.0, -9.81).

If set to (0.0, 0.0, 0.0), gravity is disabled.

enable_scene_query_support: bool#

Enable/disable scene query support for collision shapes. Default is False.

This flag allows performing collision queries (raycasts, sweeps, and overlaps) on actors and attached shapes in the scene. This is useful for implementing custom collision detection logic outside of the physics engine.

If set to False, the physics engine does not create the scene query manager and the scene query functionality will not be available. However, this provides some performance speed-up.

Note

This flag is overridden to True inside the SimulationContext class when running the simulation with the GUI enabled. This is to allow certain GUI features to work properly.

use_fabric: bool#

Enable/disable reading of physics buffers directly. Default is True.

When running the simulation, updates in the states in the scene is normally synchronized with USD. This leads to an overhead in reading the data and does not scale well with massive parallelization. This flag allows disabling the synchronization and reading the data directly from the physics buffers.

It is recommended to set this flag to True when running the simulation with a large number of primitives in the scene.

Note

When enabled, the GUI will not update the physics parameters in real-time. To enable real-time updates, please set this flag to False.

disable_contact_processing: bool#

Enable/disable contact processing. Default is False.

By default, the physics engine processes all the contacts in the scene. However, reporting this contact information can be expensive due to its combinatorial complexity. This flag allows disabling the contact processing and querying the contacts manually by the user over a limited set of primitives in the scene.

Note

It is required to set this flag to True when using the TensorAPIs for contact reporting.

physx: PhysxCfg#: PhysX solver settings. Default is PhysxCfg().

physics_material: RigidBodyMaterialCfg#

Default physics material settings for rigid bodies. Default is RigidBodyMaterialCfg().

The physics engine defaults to this physics material for all the rigid body prims that do not have any physics material specified on them.

The material is created at the path: {physics_prim_path}/defaultMaterial.

render: RenderCfg#: Render settings. Default is RenderCfg().

class omni.isaac.lab.sim.PhysxCfg[source]#

Bases: object

Configuration for PhysX solver-related parameters.

These parameters are used to configure the PhysX solver. For more information, see the PhysX 5 SDK documentation.

PhysX 5 supports GPU-accelerated physics simulation. This is enabled by default, but can be disabled by setting the device to cpu in SimulationCfg. Unlike CPU PhysX, the GPU simulation feature is unable to dynamically grow all the buffers. Therefore, it is necessary to provide a reasonable estimate of the buffer sizes for GPU features. If insufficient buffer sizes are provided, the simulation will fail with errors and lead to adverse behaviors. The buffer sizes can be adjusted through the gpu_* parameters.

Attributes:

`solver_type`	The type of solver to use.Default is 1 (TGS).
`min_position_iteration_count`	Minimum number of solver position iterations (rigid bodies, cloth, particles etc.).
`max_position_iteration_count`	Maximum number of solver position iterations (rigid bodies, cloth, particles etc.).
`min_velocity_iteration_count`	Minimum number of solver velocity iterations (rigid bodies, cloth, particles etc.).
`max_velocity_iteration_count`	Maximum number of solver velocity iterations (rigid bodies, cloth, particles etc.).
`enable_ccd`	Enable a second broad-phase pass that makes it possible to prevent objects from tunneling through each other.
`enable_stabilization`	Enable/disable additional stabilization pass in solver.
`enable_enhanced_determinism`	Enable/disable improved determinism at the expense of performance.
`bounce_threshold_velocity`	Relative velocity threshold for contacts to bounce (in m/s).
`friction_offset_threshold`	Threshold for contact point to experience friction force (in m).
`friction_correlation_distance`	Distance threshold for merging contacts into a single friction anchor point (in m).
`gpu_max_rigid_contact_count`	Size of rigid contact stream buffer allocated in pinned host memory.
`gpu_max_rigid_patch_count`	Size of the rigid contact patch stream buffer allocated in pinned host memory.
`gpu_found_lost_pairs_capacity`	Capacity of found and lost buffers allocated in GPU global memory.
`gpu_found_lost_aggregate_pairs_capacity`	Capacity of found and lost buffers in aggregate system allocated in GPU global memory.
`gpu_total_aggregate_pairs_capacity`	Capacity of total number of aggregate pairs allocated in GPU global memory.
`gpu_collision_stack_size`	Size of the collision stack buffer allocated in pinned host memory.
`gpu_heap_capacity`	Initial capacity of the GPU and pinned host memory heaps.
`gpu_temp_buffer_capacity`	Capacity of temp buffer allocated in pinned host memory.
`gpu_max_num_partitions`	Limitation for the partitions in the GPU dynamics pipeline.
`gpu_max_soft_body_contacts`	Size of soft body contacts stream buffer allocated in pinned host memory.
`gpu_max_particle_contacts`	Size of particle contacts stream buffer allocated in pinned host memory.

solver_type: Literal[0, 1]#

The type of solver to use.Default is 1 (TGS).

Available solvers:

0: PGS (Projective Gauss-Seidel)
1: TGS (Truncated Gauss-Seidel)

min_position_iteration_count: int#: Minimum number of solver position iterations (rigid bodies, cloth, particles etc.). Default is 1.

Note

Each physics actor in Omniverse specifies its own solver iteration count. The solver takes the number of iterations specified by the actor with the highest iteration and clamps it to the range [min_position_iteration_count, max_position_iteration_count].

max_position_iteration_count: int#: Maximum number of solver position iterations (rigid bodies, cloth, particles etc.). Default is 255.

Note

Each physics actor in Omniverse specifies its own solver iteration count. The solver takes the number of iterations specified by the actor with the highest iteration and clamps it to the range [min_position_iteration_count, max_position_iteration_count].

min_velocity_iteration_count: int#: Minimum number of solver velocity iterations (rigid bodies, cloth, particles etc.). Default is 0.

Note

Each physics actor in Omniverse specifies its own solver iteration count. The solver takes the number of iterations specified by the actor with the highest iteration and clamps it to the range [min_velocity_iteration_count, max_velocity_iteration_count].

max_velocity_iteration_count: int#: Maximum number of solver velocity iterations (rigid bodies, cloth, particles etc.). Default is 255.

Note

Each physics actor in Omniverse specifies its own solver iteration count. The solver takes the number of iterations specified by the actor with the highest iteration and clamps it to the range [min_velocity_iteration_count, max_velocity_iteration_count].

enable_ccd: bool#: Enable a second broad-phase pass that makes it possible to prevent objects from tunneling through each other. Default is False.

enable_stabilization: bool#: Enable/disable additional stabilization pass in solver. Default is True.

enable_enhanced_determinism: bool#

Enable/disable improved determinism at the expense of performance. Defaults to False.

For more information on PhysX determinism, please check here.

bounce_threshold_velocity: float#: Relative velocity threshold for contacts to bounce (in m/s). Default is 0.5 m/s.

friction_offset_threshold: float#: Threshold for contact point to experience friction force (in m). Default is 0.04 m.

friction_correlation_distance: float#: Distance threshold for merging contacts into a single friction anchor point (in m). Default is 0.025 m.

gpu_max_rigid_contact_count: int#: Size of rigid contact stream buffer allocated in pinned host memory. Default is 2 ** 23.

gpu_max_rigid_patch_count: int#: Size of the rigid contact patch stream buffer allocated in pinned host memory. Default is 5 * 2 ** 15.

gpu_found_lost_pairs_capacity: int#

Capacity of found and lost buffers allocated in GPU global memory. Default is 2 ** 21.

This is used for the found/lost pair reports in the BP.

gpu_found_lost_aggregate_pairs_capacity: int#

Capacity of found and lost buffers in aggregate system allocated in GPU global memory. Default is 2 ** 25.

This is used for the found/lost pair reports in AABB manager.

gpu_total_aggregate_pairs_capacity: int#: Capacity of total number of aggregate pairs allocated in GPU global memory. Default is 2 ** 21.

gpu_collision_stack_size: int#: Size of the collision stack buffer allocated in pinned host memory. Default is 2 ** 26.

gpu_heap_capacity: int#: Initial capacity of the GPU and pinned host memory heaps. Additional memory will be allocated if more memory is required. Default is 2 ** 26.

gpu_temp_buffer_capacity: int#: Capacity of temp buffer allocated in pinned host memory. Default is 2 ** 24.

gpu_max_num_partitions: int#

Limitation for the partitions in the GPU dynamics pipeline. Default is 8.

This variable must be power of 2. A value greater than 32 is currently not supported. Range: (1, 32)

gpu_max_soft_body_contacts: int#: Size of soft body contacts stream buffer allocated in pinned host memory. Default is 2 ** 20.

gpu_max_particle_contacts: int#: Size of particle contacts stream buffer allocated in pinned host memory. Default is 2 ** 20.

class omni.isaac.lab.sim.RenderCfg[source]#

Bases: object

Configuration for Omniverse RTX Renderer.

These parameters are used to configure the Omniverse RTX Renderer. For more information, see the Omniverse RTX Renderer documentation.

Attributes:

`enable_translucency`	Enables translucency for specular transmissive surfaces such as glass at the cost of some performance.
`enable_reflections`	Enables reflections at the cost of some performance.
`enable_global_illumination`	Enables Diffused Global Illumination at the cost of some performance.
`antialiasing_mode`	Selects the anti-aliasing mode to use.
`enable_dlssg`	"Enables the use of DLSS-G.
`dlss_mode`	For DLSS anti-aliasing, selects the performance/quality tradeoff mode.
`enable_direct_lighting`	Enable direct light contributions from lights.
`samples_per_pixel`	Defines the Direct Lighting samples per pixel.
`enable_shadows`	Enables shadows at the cost of performance.
`enable_ambient_occlusion`	Enables ambient occlusion at the cost of some performance.

enable_translucency: bool#: Enables translucency for specular transmissive surfaces such as glass at the cost of some performance. Default is False.

enable_reflections: bool#: Enables reflections at the cost of some performance. Default is False.

enable_global_illumination: bool#: Enables Diffused Global Illumination at the cost of some performance. Default is False.

antialiasing_mode: Literal['Off', 'FXAA', 'DLSS', 'TAA', 'DLAA']#: Selects the anti-aliasing mode to use. Defaults to DLSS.

enable_dlssg: bool#: “Enables the use of DLSS-G. DLSS Frame Generation boosts performance by using AI to generate more frames. DLSS analyzes sequential frames and motion data to create additional high quality frames. This feature requires an Ada Lovelace architecture GPU. Enabling this feature also enables additional thread-related activities, which can hurt performance. Default is False.

dlss_mode: Literal[0, 1, 2, 3]#: For DLSS anti-aliasing, selects the performance/quality tradeoff mode. Valid values are 0 (Performance), 1 (Balanced), 2 (Quality), or 3 (Auto). Default is 0.

enable_direct_lighting: bool#: Enable direct light contributions from lights.

samples_per_pixel: int#: Defines the Direct Lighting samples per pixel. Higher values increase the direct lighting quality at the cost of performance. Default is 1.

enable_shadows: bool#: Enables shadows at the cost of performance. When disabled, lights will not cast shadows. Defaults to True.

enable_ambient_occlusion: bool#: Enables ambient occlusion at the cost of some performance. Default is False.

Simulation Context Builder#

simulation_context.build_simulation_context(gravity_enabled: bool = True, device: str = 'cuda:0', dt: float = 0.01, sim_cfg: SimulationCfg | None = None, add_ground_plane: bool = False, add_lighting: bool = False, auto_add_lighting: bool = False) → Iterator[SimulationContext]#

Context manager to build a simulation context with the provided settings.

This function facilitates the creation of a simulation context and provides flexibility in configuring various aspects of the simulation, such as time step, gravity, device, and scene elements like ground plane and lighting.

If sim_cfg is None, then an instance of SimulationCfg is created with default settings, with parameters overwritten based on arguments to the function.

An example usage of the context manager function:

with build_simulation_context() as sim:
     # Design the scene

     # Play the simulation
     sim.reset()
     while sim.is_playing():
         sim.step()

Parameters:

create_new_stage – Whether to create a new stage. Defaults to True.
gravity_enabled – Whether to enable gravity in the simulation. Defaults to True.
device – Device to run the simulation on. Defaults to “cuda:0”.
dt – Time step for the simulation: Defaults to 0.01.
sim_cfg – omni.isaac.lab.sim.SimulationCfg to use for the simulation. Defaults to None.
add_ground_plane – Whether to add a ground plane to the simulation. Defaults to False.
add_lighting – Whether to add a dome light to the simulation. Defaults to False.
auto_add_lighting – Whether to automatically add a dome light to the simulation if the simulation has a GUI. Defaults to False. This is useful for debugging tests in the GUI.

Yields:

The simulation context to use for the simulation.

Utilities#

Sub-module with USD-related utilities.

Functions:

`safe_set_attribute_on_usd_schema`(schema_api, ...)	Set the value of an attribute on its USD schema if it exists.
`safe_set_attribute_on_usd_prim`(prim, ...)	Set the value of a attribute on its USD prim.
`apply_nested`(func)	Decorator to apply a function to all prims under a specified prim-path.
`clone`(func)	Decorator for cloning a prim based on matching prim paths of the prim's parent.
`bind_visual_material`(prim_path, material_path)	Bind a visual material to a prim.
`bind_physics_material`(prim_path, material_path)	Bind a physics material to a prim.
`export_prim_to_file`(path, source_prim_path)	Exports a prim from a given stage to a USD file.
`make_uninstanceable`(prim_path[, stage])	Check if a prim and its descendants are instanced and make them uninstanceable.
`get_first_matching_child_prim`(prim_path, ...)	Recursively get the first USD Prim at the path string that passes the predicate function
`get_all_matching_child_prims`(prim_path[, ...])	Performs a search starting from the root and returns all the prims matching the predicate.
`find_first_matching_prim`(prim_path_regex[, ...])	Find the first matching prim in the stage based on input regex expression.
`find_matching_prims`(prim_path_regex[, stage])	Find all the matching prims in the stage based on input regex expression.
`find_matching_prim_paths`(prim_path_regex[, ...])	Find all the matching prim paths in the stage based on input regex expression.
`find_global_fixed_joint_prim`(prim_path[, ...])	Find the fixed joint prim under the specified prim path that connects the target to the simulation world.
`select_usd_variants`(prim_path, variants[, stage])	Sets the variant selections from the specified variant sets on a USD prim.

omni.isaac.lab.sim.utils.safe_set_attribute_on_usd_schema(schema_api: pxr.Usd.APISchemaBase, name: str, value: Any, camel_case: bool)[source]#

Set the value of an attribute on its USD schema if it exists.

A USD API schema serves as an interface or API for authoring and extracting a set of attributes. They typically derive from the pxr.Usd.SchemaBase class. This function checks if the attribute exists on the schema and sets the value of the attribute if it exists.

Parameters:

schema_api – The USD schema to set the attribute on.
name – The name of the attribute.
value – The value to set the attribute to.
camel_case – Whether to convert the attribute name to camel case.

Raises:

TypeError – When the input attribute name does not exist on the provided schema API.

omni.isaac.lab.sim.utils.safe_set_attribute_on_usd_prim(prim: pxr.Usd.Prim, attr_name: str, value: Any, camel_case: bool)[source]#

Set the value of a attribute on its USD prim.

The function creates a new attribute if it does not exist on the prim. This is because in some cases (such as with shaders), their attributes are not exposed as USD prim properties that can be altered. This function allows us to set the value of the attributes in these cases.

Parameters:

prim – The USD prim to set the attribute on.
attr_name – The name of the attribute.
value – The value to set the attribute to.
camel_case – Whether to convert the attribute name to camel case.

omni.isaac.lab.sim.utils.apply_nested(func: Callable) → Callable[source]#

Decorator to apply a function to all prims under a specified prim-path.

The function iterates over the provided prim path and all its children to apply input function to all prims under the specified prim path.

If the function succeeds to apply to a prim, it will not look at the children of that prim. This is based on the physics behavior that nested schemas are not allowed. For example, a parent prim and its child prim cannot both have a rigid-body schema applied on them, or it is not possible to have nested articulations.

While traversing the prims under the specified prim path, the function will throw a warning if it does not succeed to apply the function to any prim. This is because the user may have intended to apply the function to a prim that does not have valid attributes, or the prim may be an instanced prim.

Parameters:: func – The function to apply to all prims under a specified prim-path. The function must take the prim-path and other arguments. It should return a boolean indicating whether the function succeeded or not.
Returns:: The wrapped function that applies the function to all prims under a specified prim-path.
Raises:: ValueError – If the prim-path does not exist on the stage.

omni.isaac.lab.sim.utils.clone(func: Callable) → Callable[source]#

Decorator for cloning a prim based on matching prim paths of the prim’s parent.

The decorator checks if the parent prim path matches any prim paths in the stage. If so, it clones the spawned prim at each matching prim path. For example, if the input prim path is: /World/Table_[0-9]/Bottle, the decorator will clone the prim at each matching prim path of the parent prim: /World/Table_0/Bottle, /World/Table_1/Bottle, etc.

Note

For matching prim paths, the decorator assumes that valid prims exist for all matching prim paths. In case no matching prim paths are found, the decorator raises a RuntimeError.

Parameters:: func – The function to decorate.
Returns:: The decorated function that spawns the prim and clones it at each matching prim path. It returns the spawned source prim, i.e., the first prim in the list of matching prim paths.

omni.isaac.lab.sim.utils.bind_visual_material(prim_path: str | Sdf.Path, material_path: str | Sdf.Path, stage: Usd.Stage | None = None, stronger_than_descendants: bool = True)[source]#

Bind a visual material to a prim.

This function is a wrapper around the USD command BindMaterialCommand.

Note

The function is decorated with apply_nested() to allow applying the function to a prim path and all its descendants.

Parameters:

prim_path – The prim path where to apply the material.
material_path – The prim path of the material to apply.
stage – The stage where the prim and material exist. Defaults to None, in which case the current stage is used.
stronger_than_descendants – Whether the material should override the material of its descendants. Defaults to True.

Raises:

ValueError – If the provided prim paths do not exist on stage.

omni.isaac.lab.sim.utils.bind_physics_material(prim_path: str | Sdf.Path, material_path: str | Sdf.Path, stage: Usd.Stage | None = None, stronger_than_descendants: bool = True)[source]#

Bind a physics material to a prim.

Physics material can be applied only to a prim with physics-enabled on them. This includes having collision APIs, or deformable body APIs, or being a particle system. In case the prim does not have any of these APIs, the function will not apply the material and return False.

Note

The function is decorated with apply_nested() to allow applying the function to a prim path and all its descendants.

Parameters:

prim_path – The prim path where to apply the material.
material_path – The prim path of the material to apply.
stage – The stage where the prim and material exist. Defaults to None, in which case the current stage is used.
stronger_than_descendants – Whether the material should override the material of its descendants. Defaults to True.

Raises:

ValueError – If the provided prim paths do not exist on stage.

Exports a prim from a given stage to a USD file.

The function creates a new layer at the provided path and copies the prim to the layer. It sets the copied prim as the default prim in the target layer. Additionally, it updates the stage up-axis and meters-per-unit to match the current stage.

Parameters:

path – The filepath path to export the prim to.
source_prim_path – The prim path to export.
target_prim_path – The prim path to set as the default prim in the target layer. Defaults to None, in which case the source prim path is used.
stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Raises:

ValueError – If the prim paths are not global (i.e: do not start with ‘/’).

omni.isaac.lab.sim.utils.make_uninstanceable(prim_path: str | Sdf.Path, stage: Usd.Stage | None = None)[source]#

Check if a prim and its descendants are instanced and make them uninstanceable.

This function checks if the prim at the specified prim path and its descendants are instanced. If so, it makes the respective prim uninstanceable by disabling instancing on the prim.

This is useful when we want to modify the properties of a prim that is instanced. For example, if we want to apply a different material on an instanced prim, we need to make the prim uninstanceable first.

Parameters:

prim_path – The prim path to check.
stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

omni.isaac.lab.sim.utils.get_first_matching_child_prim(prim_path: str | Sdf.Path, predicate: Callable[[Usd.Prim], bool], stage: Usd.Stage | None = None) → Usd.Prim | None[source]#

Recursively get the first USD Prim at the path string that passes the predicate function

Parameters:

prim_path – The path of the prim in the stage.
predicate – The function to test the prims against. It takes a prim as input and returns a boolean.
stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

The first prim on the path that passes the predicate. If no prim passes the predicate, it returns None.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

omni.isaac.lab.sim.utils.get_all_matching_child_prims(prim_path: str | Sdf.Path, predicate: Callable[[Usd.Prim], bool] = <function <lambda>>, depth: int | None = None, stage: Usd.Stage | None = None) → list[Usd.Prim][source]#

Performs a search starting from the root and returns all the prims matching the predicate.

Parameters:

prim_path – The root prim path to start the search from.
predicate – The predicate that checks if the prim matches the desired criteria. It takes a prim as input and returns a boolean. Defaults to a function that always returns True.
depth – The maximum depth for traversal, should be bigger than zero if specified. Defaults to None (i.e: traversal happens till the end of the tree).
stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

A list containing all the prims matching the predicate.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

omni.isaac.lab.sim.utils.find_first_matching_prim(prim_path_regex: str, stage: Usd.Stage | None = None) → Usd.Prim | None[source]#

Find the first matching prim in the stage based on input regex expression.

Parameters:

prim_path_regex – The regex expression for prim path.
stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

The first prim that matches input expression. If no prim matches, returns None.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

omni.isaac.lab.sim.utils.find_matching_prims(prim_path_regex: str, stage: Usd.Stage | None = None) → list[Usd.Prim][source]#

Find all the matching prims in the stage based on input regex expression.

Parameters:

prim_path_regex – The regex expression for prim path.
stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

A list of prims that match input expression.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

omni.isaac.lab.sim.utils.find_matching_prim_paths(prim_path_regex: str, stage: Usd.Stage | None = None) → list[str][source]#

Find all the matching prim paths in the stage based on input regex expression.

Parameters:

prim_path_regex – The regex expression for prim path.
stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

A list of prim paths that match input expression.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

omni.isaac.lab.sim.utils.find_global_fixed_joint_prim(prim_path: str | Sdf.Path, check_enabled_only: bool = False, stage: Usd.Stage | None = None) → UsdPhysics.Joint | None[source]#

Find the fixed joint prim under the specified prim path that connects the target to the simulation world.

A joint is a connection between two bodies. A fixed joint is a joint that does not allow relative motion between the two bodies. When a fixed joint has only one target body, it is considered to attach the body to the simulation world.

This function finds the fixed joint prim that has only one target under the specified prim path. If no such fixed joint prim exists, it returns None.

Parameters:

prim_path – The prim path to search for the fixed joint prim.
check_enabled_only – Whether to consider only enabled fixed joints. Defaults to False. If False, then all joints (enabled or disabled) are considered.
stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

The fixed joint prim that has only one target. If no such fixed joint prim exists, it returns None.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).
ValueError – If the prim path does not exist on the stage.

omni.isaac.lab.sim.utils.select_usd_variants(prim_path: str, variants: object | dict[str, str], stage: Usd.Stage | None = None)[source]#

Sets the variant selections from the specified variant sets on a USD prim.

USD Variants are a very powerful tool in USD composition that allows prims to have different options on a single asset. This can be done by modifying variations of the same prim parameters per variant option in a set. This function acts as a script-based utility to set the variant selections for the specified variant sets on a USD prim.

The function takes a dictionary or a config class mapping variant set names to variant selections. For instance, if we have a prim at "/World/Table" with two variant sets: “color” and “size”, we can set the variant selections as follows:

select_usd_variants(
    prim_path="/World/Table",
    variants={
        "color": "red",
        "size": "large",
    },
)

Alternatively, we can use a config class to define the variant selections:

@configclass
class TableVariants:
    color: Literal["blue", "red"] = "red"
    size: Literal["small", "large"] = "large"

select_usd_variants(
    prim_path="/World/Table",
    variants=TableVariants(),
)

Parameters:

prim_path – The path of the USD prim.
variants – A dictionary or config class mapping variant set names to variant selections.
stage – The USD stage. Defaults to None, in which case, the current stage is used.

Raises:

ValueError – If the prim at the specified path is not valid.

omni.isaac.lab.sim

Contents

omni.isaac.lab.sim#

Simulation Context#

Simulation Configuration#

Simulation Context Builder#

Utilities#