isaaclab_physx.app

isaaclab_physx.app#

Sub-package for launching and managing the Kit application process.

Classes

KitLauncher

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

KitStageBackend

Attach the simulation stage to Kit's USD context, where Kit extensions discover it.

KitStageBackendCfg

Kit USD-context attachment; the stage is borrowed from the active simulation.

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 isaaclab demo zoo --physics isaacsim_physx --viz kit

Alternatively, set the environment variable inline for a single invocation:

LIVESTREAM=2 uv run --extra isaacsim isaaclab demo zoo --physics isaacsim_physx --viz kit

export LIVESTREAM=2
# run the python script
LD_PRELOAD=/lib/aarch64-linux-gnu/libgomp.so.1 uv run --extra isaacsim isaaclab demo zoo --physics isaacsim_physx --viz kit

Alternatively, set the environment variable inline for a single invocation:

LIVESTREAM=2 LD_PRELOAD=/lib/aarch64-linux-gnu/libgomp.so.1 uv run --extra isaacsim isaaclab demo zoo --physics isaacsim_physx --viz kit

Note

Direct Python commands that import Isaac Sim on aarch64 require the LD_PRELOAD=/lib/aarch64-linux-gnu/libgomp.so.1 prefix shown above. See Automatic setup with uv (recommended).

Warning

Livestreaming is not currently supported or validated on DGX Spark. See the Installation for the current list of features not yet validated on this platform.

In Command Prompt:

set LIVESTREAM=2
uv run --extra isaacsim isaaclab demo zoo --physics isaacsim_physx --viz kit

In PowerShell:

$env:LIVESTREAM = "2"
uv run --extra isaacsim isaaclab demo zoo --physics isaacsim_physx --viz kit

Note

The POSIX inline VAR=value <command> prefix form used on Linux (for example LIVESTREAM=2 uv run ...) has no Windows equivalent; use one of the two forms above instead.

Overriding the environment variables#

Scripts do not construct the KitLauncher themselves. launch_simulation() constructs it when the resolved configuration needs Isaac Sim / Kit, and passes it the launcher arguments. Arguments that are not at their default values override the environment variables. They can be passed as an argparse.Namespace or as a dictionary:

import argparse

from isaaclab.app import add_launcher_args, launch_simulation

parser = argparse.ArgumentParser()
# add your own arguments
# ....
# add the launcher arguments for the command line
add_launcher_args(parser)
args = parser.parse_args()

# -- Option 1: pass the parsed arguments
with launch_simulation(env_cfg, args):
    ...
# -- Option 2: pass the settings as a dictionary
with launch_simulation(env_cfg, {"livestream": 2, "enable_cameras": True}):
    ...

Kit Launcher#

class isaaclab_physx.app.KitLauncher[source]#

Bases: SimulationLauncher

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:

__init__([launcher_args])

Create a SimulationApp instance based on the input settings.

close([exit_code])

Close the Kit app this launcher started; Kit fast shutdown exits with exit_code.

is_available()

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

add_launcher_args(parser)

Utility function to configure KitLauncher arguments with an existing argument parser object.
__init__(launcher_args: Namespace | dict | None = None)[source]#

Create a SimulationApp instance based on the input settings.

Parameters:

launcher_args – Launcher arguments, as normalized by launch_simulation(). Defaults to None, which is equivalent to passing an empty dictionary. Keys named like SimulationApp config fields (e.g. width) are forwarded to it.

Raises:

  • SystemExit – If the full Isaac Sim runtime is unavailable.

  • ValueError – If incompatible or undefined values are assigned to relevant environment values, such as HEADLESS.

close(exit_code: int = 0) → None[source]#

Close the Kit app this launcher started; Kit fast shutdown exits with exit_code.

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.

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

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

This function appends the 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 KitLauncher specific options.

Kit Stage#

class isaaclab_physx.app.KitStageBackend[source]#

Attach the simulation stage to Kit’s USD context, where Kit extensions discover it.

Kit extensions such as PhysX views, articulations, and the viewport read the stage of the USD context rather than Isaac Lab’s current stage.

Methods:

__init__(cfg)

close()

Close the stage of Kit's USD context.
__init__(cfg: KitStageBackendCfg)[source]#
close() → None[source]#

Close the stage of Kit’s USD context.

The simulation closes backends before it clears the stage cache; clearing the cache first makes Kit fail with “Removal of UsdStage from cache failed” and can hang teardown.

class isaaclab_physx.app.KitStageBackendCfg[source]#

Bases: BackendCfg

Kit USD-context attachment; the stage is borrowed from the active simulation.

Classes:

class_type

alias of KitStageBackend

Methods:

__init__([class_type])

class_type#

alias of KitStageBackend

__init__(class_type: type = <class 'isaaclab_physx.app.kit_stage.KitStageBackend'>, *, stage: pxr.Usd.Stage) → None#