isaaclab.app

isaaclab.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.
`LoadingScreen`	Staged progress display that owns the console while a run starts up.
`Scan`	Signals gathered from one walk of the config tree (see `scan()`).

Functions

`launch_simulation`(cfg[, launcher_args])	Context manager that launches the appropriate simulation runtime for cfg.
`make_physics_cfg`(physics_cfg_str)	Build a physics config for the requested backend.
`report_activity`(activity)	Report what the startup path is doing right now.
`scan`(cfg[, launcher_args])	Walk cfg once, collecting all launch signals and applying `--physics`.

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 WebRTC Livestream extension over public networks. This allows users to connect through the WebRTC Client using the WebRTC protocol.
- LIVESTREAM=2 enables streaming via the WebRTC Livestream extension over private and local networks. This allows users to connect through the WebRTC Client 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.
Public IP Address: When using the environment variable LIVESTREAM={1,2}, set the PUBLIC_IP envvar to define the public IP address endpoint for livestreaming remotely.

Camera and offscreen rendering support is enabled automatically. No environment variable or command-line option is required for camera tasks.

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

export LIVESTREAM=2
# run the python script
uv run --extra isaacsim python scripts/demos/quadrupeds.py

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

LIVESTREAM=2 uv run --extra isaacsim python scripts/demos/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 argparse

from isaaclab.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 isaaclab.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.

The ISAACLAB_FABRIC_USE_GPU_INTEROP environment variable optionally overrides the /physics/fabricUseGPUInterop Kit setting. Set it to 1 or 0 to enable or disable the setting. When unset, Kit’s configured default is preserved.

Methods:

`sync_visualizer_cli_settings_to_carb`(...)	Write visualizer CLI selection and `--max_visible_envs` to carb settings.
`__init__`([launcher_args])	Create a SimulationApp instance based on the input settings.
`is_available`()	Return whether the full Isaac Sim runtime is importable, i.e. Kit can be launched.
`has_gui`()	Return whether the resolved app state has an interactive GUI.
`add_app_launcher_args`(parser)	Utility function to configure AppLauncher arguments with an existing argument parser object.

Attributes:

`app`	The launched SimulationApp.
`has_window`	Whether a local window exists that can render UI and receive input.

static sync_visualizer_cli_settings_to_carb(launcher_args: dict) → None[source]#

Write visualizer CLI selection and --max_visible_envs to carb settings.

Callers may set visualizer_explicit / visualizer_disable_all when those values were resolved elsewhere (e.g. AppLauncher strips flags from launcher_args). Otherwise disable_all is inferred from "none" in visualizer.

Also used when Kit is skipped (see isaaclab.app.sim_launcher).

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

ImportError – If the full Isaac Sim runtime is unavailable.
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: isaacsim.SimulationApp#: The launched SimulationApp.

classmethod is_available() → bool[source]#

Return whether the full Isaac Sim runtime is importable, i.e. Kit can be launched.

This reports launchability, not running state: it is True in any process with a full Isaac Sim installation, before and after Kit starts. Use has_kit() to check whether Kit is currently running.

classmethod has_gui() → bool[source]#

Return whether the resolved app state has an interactive GUI.

True when the launch resolved to a local window, a livestream, or an XR session. AppLauncher publishes this as the /isaaclab/has_gui setting during initialization, so the value is False before any launcher has run in the process.

property has_window: bool#

Whether a local window exists that can render UI and receive input.

True when a windowed visualizer was requested, or when livestreaming, which renders a window and forwards input from the remote client. Use this rather than has_gui() to decide whether local UI-driven features such as keyboard bindings are available: livestreaming runs the host headless yet still presents an interactive window, while XR without an explicit windowed visualizer does not open a local window.

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:

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: WebRTC over public network
- 2: WebRTC over local/private network
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 selected from the resolved visualizer and XR settings. Rendering support is available by default, including in headless execution.
deterministic (bool): Publishes /isaaclab/render/deterministic for reproducible rendering. Does not change how the default experience file is chosen.
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” A single Kit argument works in both the space-separated and the =-attached form (e.g. --kit_args "--ext-folder=/path/to/ext1" or --kit_args=--ext-folder=/path/to/ext1). Isaac Lab experiences use one renderer GPU by default. Applications that need single-process multi-GPU rendering can override the renderer.multiGpu settings through this argument.
visualizer (str): Visualizer backends to enable. Valid options are:
- rerun: Use Rerun visualizer.
- newton_gl: Use Newton GL visualizer.
- newton_rtx: Use Newton RTX path-tracer visualizer (experimental).
- viser: Use Viser visualizer.
- kit: Use Omniverse Kit visualizer.
- none: Disable all visualizers explicitly.
- Multiple visualizers can be specified as a comma-delimited list: --viz rerun,newton_gl,viser.
Deprecated since version Use: newton_gl instead of newton.
max_visible_envs (int | None): Optional global override for partial visualization by capping how many environments are shown in the visualizers. More partial visualization configuration fields are available in the VisualizerCfg class.

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

Simulation Launcher#

isaaclab.app.launch_simulation(cfg, launcher_args: Namespace | dict | None = None) → Generator[PhysicsCfg | None, None, None][source]#

Context manager that launches the appropriate simulation runtime for cfg.

Walks the config tree once (resolving --physics, validating the physics/renderer/visualizer combination, and deciding whether Isaac Sim Kit is needed), then launches AppLauncher for Kit-based backends (closed on exit) or does nothing for kitless ones. Cameras are auto-enabled for Kit-renderer sensors.

Yields the resolved physics config, so a script can pass a bare placeholder and pick the backend from the command line:

with launch_simulation(PhysicsCfg(), args_cli) as physics_cfg:
    sim = SimulationContext(SimulationCfg(physics=physics_cfg))

Callers that do not need the value simply omit as.

Parameters:

cfg¶ – Config tree to scan for backend, renderer, and sensor requirements.
launcher_args¶ –
Parsed launcher arguments, typically the script’s args_cli. Besides the arguments added by add_launcher_args(), the following keys are read when a script contributes them:
- physics: Backend selector applied to every physics config in cfg, see make_physics_cfg().
- require_kit: Whether the caller needs Kit for a reason cfg cannot express, e.g. a tool that reaches a Kit-only extension API. This is additive – it can only turn a kitless launch into a Kit one, never the reverse, so a config that already needs Kit still launches it when the key is absent or False.

isaaclab.app.make_physics_cfg(physics_cfg_str: str) → PhysicsCfg[source]#

Build a physics config for the requested backend.

Parameters:: physics_cfg_str¶ – Backend selector: "physx", "isaacsim_physx", "newton_mjwarp", "newton_vbd", or "ovphysx". The "physx" selector is automatic: it resolves to Isaac Sim PhysX when Kit is required, and to OvPhysX otherwise.
Returns:: A new physics config instance for the requested backend.
Raises:: ValueError – If physics_cfg_str does not name a known backend.

isaaclab.app.scan(cfg, launcher_args: Namespace | dict | None = None) → Scan[source]#

Walk cfg once, collecting all launch signals and applying --physics.

When the physics key is present in launcher_args, every physics config is replaced by the requested backend (see make_physics_cfg()): nested configs in place, a root config via Scan.effective_cfg (it cannot be mutated in place). Automatic PhysX configurations and RTX renderer placeholders (renderer_type="auto_rtx") are also resolved at this stage using the full launcher_args context.

class isaaclab.app.Scan[source]#

Signals gathered from one walk of the config tree (see scan()).

Every field starts as a plain snapshot computed during that single walk. Automatic PhysX preset selections and RTX placeholders are also recorded so launch-time resolution can update the physics- and renderer-related fields without traversing the config tree again. needs_kit is the headline launch decision after automatic selections are resolved: a Kit-renderer camera or Isaac Sim PhysX requires Kit (the launcher additionally forces Kit when --visualizer kit is requested).

Methods:

__init__(resolved_physics_cfg, ...)

__init__(resolved_physics_cfg: PhysicsCfg | None, effective_cfg: Any, visualizer_intent: dict[str, bool], has_ovrtx: bool, has_kit_camera: bool, has_kit_physics: bool, has_kitless_physics: bool, has_ovphysx_physics: bool, needs_kit: bool) → None#