omni.isaac.lab.app

omni.isaac.lab.app#

Sub-package containing app-specific functionalities.

These include:

Ability to launch the simulation app with different configurations
Run tests with the simulation app

Classes

AppLauncher

A utility class to launch Isaac Sim application based on command-line arguments and environment variables.

Environment variables#

The following details the behavior of the class based on the environment variables:

Headless mode: If the environment variable HEADLESS=1, then SimulationApp will be started in headless mode. If LIVESTREAM={1,2}, then it will supersede the HEADLESS envvar and force headlessness.
- HEADLESS=1 causes the app to run in headless mode.
Livestreaming: If the environment variable LIVESTREAM={1,2} , then livestream is enabled. Any of the livestream modes being true forces the app to run in headless mode.
- LIVESTREAM=1 enables streaming via the Isaac Native Livestream extension. This allows users to connect through the Omniverse Streaming Client.
- LIVESTREAM=2 enables streaming via the WebRTC Livestream extension. This allows users to connect in a browser using the WebRTC protocol.
Note

Each Isaac Sim instance can only connect to one streaming client. Connecting to an Isaac Sim instance that is currently serving a streaming client results in an error for the second user.
Enable cameras: If the environment variable ENABLE_CAMERAS is set to 1, then the cameras are enabled. This is useful for running the simulator without a GUI but still rendering the viewport and camera images.
- ENABLE_CAMERAS=1: Enables the offscreen-render pipeline which allows users to render the scene without launching a GUI.
Note

The off-screen rendering pipeline only works when used in conjunction with the omni.isaac.lab.sim.SimulationContext class. This is because the off-screen rendering pipeline enables flags that are internally used by the SimulationContext class.

To set the environment variables, one can use the following command in the terminal:

export REMOTE_DEPLOYMENT=3
export ENABLE_CAMERAS=1
# run the python script
./isaaclab.sh -p source/standalone/demo/play_quadrupeds.py

Alternatively, one can set the environment variables to the python script directly:

REMOTE_DEPLOYMENT=3 ENABLE_CAMERAS=1 ./isaaclab.sh -p source/standalone/demo/play_quadrupeds.py

Overriding the environment variables#

The environment variables can be overridden in the python script itself using the AppLauncher. These can be passed as a dictionary, a argparse.Namespace object or as keyword arguments. When the passed arguments are not the default values, then they override the environment variables.

The following snippet shows how use the AppLauncher in different ways:

import argparser

from omni.isaac.lab.app import AppLauncher

# add argparse arguments
parser = argparse.ArgumentParser()
# add your own arguments
# ....
# add app launcher arguments for cli
AppLauncher.add_app_launcher_args(parser)
# parse arguments
args = parser.parse_args()

# launch omniverse isaac-sim app
# -- Option 1: Pass the settings as a Namespace object
app_launcher = AppLauncher(args).app
# -- Option 2: Pass the settings as keywords arguments
app_launcher = AppLauncher(headless=args.headless, livestream=args.livestream)
# -- Option 3: Pass the settings as a dictionary
app_launcher = AppLauncher(vars(args))
# -- Option 4: Pass no settings
app_launcher = AppLauncher()

# obtain the launched app
simulation_app = app_launcher.app

Simulation App Launcher#

class omni.isaac.lab.app.AppLauncher[source]#

A utility class to launch Isaac Sim application based on command-line arguments and environment variables.

The class resolves the simulation app settings that appear through environments variables, command-line arguments (CLI) or as input keyword arguments. Based on these settings, it launches the simulation app and configures the extensions to load (as a part of post-launch setup).

The input arguments provided to the class are given higher priority than the values set from the corresponding environment variables. This provides flexibility to deal with different users’ preferences.

Note

Explicitly defined arguments are only given priority when their value is set to something outside their default configuration. For example, the livestream argument is -1 by default. It only overrides the LIVESTREAM environment variable when livestream argument is set to a value >-1. In other words, if livestream=-1, then the value from the environment variable LIVESTREAM is used.

Methods:

`__init__`([launcher_args])	Create a SimulationApp instance based on the input settings.
`add_app_launcher_args`(parser)	Utility function to configure AppLauncher arguments with an existing argument parser object.

Attributes:

app

The launched SimulationApp.

__init__(launcher_args: Namespace | dict | None = None, **kwargs)[source]#

Create a SimulationApp instance based on the input settings.

Parameters:

launcher_args – Input arguments to parse using the AppLauncher and set into the SimulationApp. Defaults to None, which is equivalent to passing an empty dictionary. A detailed description of the possible arguments is available in the SimulationApp documentation.
**kwargs – Additional keyword arguments that will be merged into launcher_args. They serve as a convenience for those who want to pass some arguments using the argparse interface and others directly into the AppLauncher. Duplicated arguments with the launcher_args will raise a ValueError.

Raises:

ValueError – If there are common/duplicated arguments between launcher_args and kwargs.
ValueError – If combination of launcher_args and kwargs are missing the necessary arguments that are needed by the AppLauncher to resolve the desired app configuration.
ValueError – If incompatible or undefined values are assigned to relevant environment values, such as LIVESTREAM.

property app: omni.isaac.kit.SimulationApp#: The launched SimulationApp.

static add_app_launcher_args(parser: ArgumentParser) → None[source]#

Utility function to configure AppLauncher arguments with an existing argument parser object.

This function takes an argparse.ArgumentParser object and does some sanity checking on the existing arguments for ingestion by the SimulationApp. It then appends custom command-line arguments relevant to the SimulationApp to the input argparse.ArgumentParser instance. This allows overriding the environment variables using command-line arguments.

Currently, it adds the following parameters to the argparser object:

headless (bool): If True, the app will be launched in headless (no-gui) mode. The values map the same as that for the HEADLESS environment variable. If False, then headless mode is determined by the HEADLESS environment variable.
livestream (int): If one of {1, 2}, then livestreaming and headless mode is enabled. The values map the same as that for the LIVESTREAM environment variable. If -1, then livestreaming is determined by the LIVESTREAM environment variable. Valid options are:
- 0: Disabled
- 1: Native
- 2: WebRTC
enable_cameras (bool): If True, the app will enable camera sensors and render them, even when in headless mode. This flag must be set to True if the environments contains any camera sensors. The values map the same as that for the ENABLE_CAMERAS environment variable. If False, then enable_cameras mode is determined by the ENABLE_CAMERAS environment variable.
device (str): The device to run the simulation on. Valid options are:
- cpu: Use CPU.
- cuda: Use GPU with device ID 0.
- cuda:N: Use GPU, where N is the device ID. For example, “cuda:0”.
experience (str): The experience file to load when launching the SimulationApp. If a relative path is provided, it is resolved relative to the apps folder in Isaac Sim and Isaac Lab (in that order).

If provided as an empty string, the experience file is determined based on the command-line flags:
- If headless and enable_cameras are True, the experience file is set to isaaclab.python.headless.rendering.kit.
- If headless is False and enable_cameras is True, the experience file is set to isaaclab.python.rendering.kit.
- If headless and enable_cameras are False, the experience file is set to isaaclab.python.kit.
- If headless is True and enable_cameras is False, the experience file is set to isaaclab.python.headless.kit.
kit_args (str): Optional command line arguments to be passed to Omniverse Kit directly. Arguments should be combined into a single string separated by space. Example usage: –kit_args “–ext-folder=/path/to/ext1 –ext-folder=/path/to/ext2”

Parameters:: parser – An argument parser instance to be extended with the AppLauncher specific options.