Deep-dive into AppLauncher#
In this tutorial, we will dive into the app.AppLauncher
class to configure the simulator using
CLI arguments and environment variables (envars). Particularly, we will demonstrate how to use
AppLauncher
to enable livestreaming and configure the omni.isaac.kit.SimulationApp
instance it wraps, while also allowing user-provided options.
The AppLauncher
is a wrapper for SimulationApp
to simplify
its configuration. The SimulationApp
has many extensions that must be
loaded to enable different capabilities, and some of these extensions are order- and inter-dependent.
Additionally, there are startup options such as headless
which must be set at instantiation time,
and which have an implied relationship with some extensions, e.g. the livestreaming extensions.
The AppLauncher
presents an interface that can handle these extensions and startup
options in a portable manner across a variety of use cases. To achieve this, we offer CLI and envar
flags which can be merged with user-defined CLI args, while passing forward arguments intended
for SimulationApp
.
The Code#
The tutorial corresponds to the launch_app.py
script in the
source/standalone/tutorials/00_sim
directory.
Code for launch_app.py
1# Copyright (c) 2022-2024, The Isaac Lab Project Developers.
2# All rights reserved.
3#
4# SPDX-License-Identifier: BSD-3-Clause
5
6"""
7This script demonstrates how to run IsaacSim via the AppLauncher
8
9.. code-block:: bash
10
11 # Usage
12 ./isaaclab.sh -p source/standalone/tutorials/00_sim/launch_app.py
13
14"""
15
16"""Launch Isaac Sim Simulator first."""
17
18
19import argparse
20
21from omni.isaac.lab.app import AppLauncher
22
23# create argparser
24parser = argparse.ArgumentParser(description="Tutorial on running IsaacSim via the AppLauncher.")
25parser.add_argument("--size", type=float, default=1.0, help="Side-length of cuboid")
26# SimulationApp arguments https://docs.omniverse.nvidia.com/py/isaacsim/source/extensions/omni.isaac.kit/docs/index.html?highlight=simulationapp#omni.isaac.kit.SimulationApp
27parser.add_argument(
28 "--width", type=int, default=1280, help="Width of the viewport and generated images. Defaults to 1280"
29)
30parser.add_argument(
31 "--height", type=int, default=720, help="Height of the viewport and generated images. Defaults to 720"
32)
33
34# append AppLauncher cli args
35AppLauncher.add_app_launcher_args(parser)
36# parse the arguments
37args_cli = parser.parse_args()
38# launch omniverse app
39app_launcher = AppLauncher(args_cli)
40simulation_app = app_launcher.app
41
42"""Rest everything follows."""
43
44import omni.isaac.lab.sim as sim_utils
45
46
47def design_scene():
48 """Designs the scene by spawning ground plane, light, objects and meshes from usd files."""
49 # Ground-plane
50 cfg_ground = sim_utils.GroundPlaneCfg()
51 cfg_ground.func("/World/defaultGroundPlane", cfg_ground)
52
53 # spawn distant light
54 cfg_light_distant = sim_utils.DistantLightCfg(
55 intensity=3000.0,
56 color=(0.75, 0.75, 0.75),
57 )
58 cfg_light_distant.func("/World/lightDistant", cfg_light_distant, translation=(1, 0, 10))
59
60 # spawn a cuboid
61 cfg_cuboid = sim_utils.CuboidCfg(
62 size=[args_cli.size] * 3,
63 visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(1.0, 1.0, 1.0)),
64 )
65 # Spawn cuboid, altering translation on the z-axis to scale to its size
66 cfg_cuboid.func("/World/Object", cfg_cuboid, translation=(0.0, 0.0, args_cli.size / 2))
67
68
69def main():
70 """Main function."""
71
72 # Initialize the simulation context
73 sim_cfg = sim_utils.SimulationCfg(dt=0.01, device=args_cli.device)
74 sim = sim_utils.SimulationContext(sim_cfg)
75 # Set main camera
76 sim.set_camera_view([2.0, 0.0, 2.5], [-0.5, 0.0, 0.5])
77
78 # Design scene by adding assets to it
79 design_scene()
80
81 # Play the simulator
82 sim.reset()
83 # Now we are ready!
84 print("[INFO]: Setup complete...")
85
86 # Simulate physics
87 while simulation_app.is_running():
88 # perform step
89 sim.step()
90
91
92if __name__ == "__main__":
93 # run the main function
94 main()
95 # close sim app
96 simulation_app.close()
The Code Explained#
Adding arguments to the argparser#
AppLauncher
is designed to be compatible with custom CLI args that users need for
their own scripts, while still providing a portable CLI interface.
In this tutorial, a standard argparse.ArgumentParser
is instantiated and given the
script-specific --size
argument, as well as the arguments --height
and --width
.
The latter are ingested by SimulationApp
.
The argument --size
is not used by AppLauncher
, but will merge seamlessly
with the AppLauncher
interface. In-script arguments can be merged with the
AppLauncher
interface via the add_app_launcher_args()
method,
which will return a modified ArgumentParser
with the AppLauncher
arguments appended. This can then be processed into an argparse.Namespace
using the
standard argparse.ArgumentParser.parse_args()
method and passed directly to
AppLauncher
for instantiation.
import argparse
from omni.isaac.lab.app import AppLauncher
# create argparser
parser = argparse.ArgumentParser(description="Tutorial on running IsaacSim via the AppLauncher.")
parser.add_argument("--size", type=float, default=1.0, help="Side-length of cuboid")
# SimulationApp arguments https://docs.omniverse.nvidia.com/py/isaacsim/source/extensions/omni.isaac.kit/docs/index.html?highlight=simulationapp#omni.isaac.kit.SimulationApp
parser.add_argument(
"--width", type=int, default=1280, help="Width of the viewport and generated images. Defaults to 1280"
)
parser.add_argument(
"--height", type=int, default=720, help="Height of the viewport and generated images. Defaults to 720"
)
# append AppLauncher cli args
AppLauncher.add_app_launcher_args(parser)
# parse the arguments
args_cli = parser.parse_args()
# launch omniverse app
app_launcher = AppLauncher(args_cli)
simulation_app = app_launcher.app
The above only illustrates only one of several ways of passing arguments to AppLauncher
.
Please consult its documentation page to see further options.
Understanding the output of –help#
While executing the script, we can pass the --help
argument and see the combined outputs of the
custom arguments and those from AppLauncher
.
./isaaclab.sh -p source/standalone/tutorials/00_sim/launch_app.py --help
[INFO] Using python from: /isaac-sim/python.sh
[INFO][AppLauncher]: The argument 'width' will be used to configure the SimulationApp.
[INFO][AppLauncher]: The argument 'height' will be used to configure the SimulationApp.
usage: launch_app.py [-h] [--size SIZE] [--width WIDTH] [--height HEIGHT] [--headless] [--livestream {0,1,2}]
[--enable_cameras] [--verbose] [--experience EXPERIENCE]
Tutorial on running IsaacSim via the AppLauncher.
options:
-h, --help show this help message and exit
--size SIZE Side-length of cuboid
--width WIDTH Width of the viewport and generated images. Defaults to 1280
--height HEIGHT Height of the viewport and generated images. Defaults to 720
app_launcher arguments:
--headless Force display off at all times.
--livestream {0,1,2}
Force enable livestreaming. Mapping corresponds to that for the "LIVESTREAM" environment variable.
--enable_cameras Enable cameras when running without a GUI.
--verbose Enable verbose terminal logging from the SimulationApp.
--experience EXPERIENCE
The experience file to load when launching the SimulationApp.
* If an empty string is provided, the experience file is determined based on the headless flag.
* If a relative path is provided, it is resolved relative to the `apps` folder in Isaac Sim and
Isaac Lab (in that order).
This readout details the --size
, --height
, and --width
arguments defined in the script directly,
as well as the AppLauncher
arguments.
The [INFO]
messages preceding the help output also reads out which of these arguments are going
to be interpreted as arguments to the SimulationApp
instance which the
AppLauncher
class wraps. In this case, it is --height
and --width
. These
are classified as such because they match the name and type of an argument which can be processed
by SimulationApp
. Please refer to the specification for such arguments
for more examples.
Using environment variables#
As noted in the help message, the AppLauncher
arguments (--livestream
, --headless
)
have corresponding environment variables (envar) as well. These are detailed in omni.isaac.lab.app
documentation. Providing any of these arguments through CLI is equivalent to running the script in a shell
environment where the corresponding envar is set.
The support for AppLauncher
envars are simply a convenience to provide session-persistent
configurations, and can be set in the user’s ${HOME}/.bashrc
for persistent settings between sessions.
In the case where these arguments are provided from the CLI, they will override their corresponding envar,
as we will demonstrate later in this tutorial.
These arguments can be used with any script that starts the simulation using AppLauncher
,
with one exception, --enable_cameras
. This setting sets the rendering pipeline to use the
offscreen renderer. However, this setting is only compatible with the omni.isaac.lab.sim.SimulationContext
.
It will not work with Isaac Sim’s omni.isaac.core.simulation_context.SimulationContext
class.
For more information on this flag, please see the AppLauncher
API documentation.
The Code Execution#
We will now run the example script:
LIVESTREAM=1 ./isaaclab.sh -p source/standalone/tutorials/00_sim/launch_app.py --size 0.5
This will spawn a 0.5m3 volume cuboid in the simulation. No GUI will appear, equivalent
to if we had passed the --headless
flag because headlessness is implied by our LIVESTREAM
envar. If a visualization is desired, we could get one via Isaac’s Native Livestreaming. Streaming
is currently the only supported method of visualization from within the container. The
process can be killed by pressing Ctrl+C
in the launching terminal.
Now, let’s look at how AppLauncher
handles conflicting commands:
LIVESTREAM=0 ./isaaclab.sh -p source/standalone/tutorials/00_sim/launch_app.py --size 0.5 --livestream 1
This will cause the same behavior as in the previous run, because although we have set LIVESTREAM=0
in our envars, CLI args such as --livestream
take precedence in determining behavior. The process can
be killed by pressing Ctrl+C
in the launching terminal.
Finally, we will examine passing arguments to SimulationApp
through
AppLauncher
:
LIVESTREAM=1 ./isaaclab.sh -p source/standalone/tutorials/00_sim/launch_app.py --size 0.5 --width 1920 --height 1080
This will cause the same behavior as before, but now the viewport will be rendered at 1920x1080p resolution.
This can be useful when we want to gather high-resolution video, or we can specify a lower resolution if we
want our simulation to be more performant. The process can be killed by pressing Ctrl+C
in the launching
terminal.