You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Puts the AppLauncher tutorial later in the series (isaac-sim#341)
# Description
Currently, the very first tutorial for users is the app launcher. This
might be a bit overwhelming to start with. This MR iterates over the app
launcher tutorial and puts it later in the part 1 of the tutorials.
## Type of change
- This change requires a documentation update
## Checklist
- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./orbit.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there
In this tutorial, we will dive into the :class:`app.AppLauncher` class to configure the simulator using
7
-
CLI arguments and environment variables (envars). Particularly, we will demonstrate how to use:class:`~app.AppLauncher`
8
-
to enable livestreaming and configure the :class:`omni.isaac.kit.SimulationApp` instance it wraps,
9
-
while also allowing user-provided options.
7
+
CLI arguments and environment variables (envars). Particularly, we will demonstrate how to use
8
+
:class:`~app.AppLauncher` to enable livestreaming and configure the :class:`omni.isaac.kit.SimulationApp`
9
+
instance it wraps, while also allowing user-provided options.
10
10
11
-
Motivation
12
-
----------
13
-
14
-
The :class:`~app.AppLauncher` is a wrapper for :class:`~omni.isaac.kit.SimulationApp` to simplify its configuration.
15
-
The :class:`~omni.isaac.kit.SimulationApp` has many extensions that must be loaded to enable different capabilities, and some of these extensions are order- and inter-dependent.
16
-
Additionally, there are startup options such as ``headless`` which must be set at instantiation time, and which have an implied relationship with
17
-
some extensions, e.g. the livestreaming extensions. The :class:`~app.AppLauncher` presents an interface that can handle these extensions and startup options
18
-
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,
19
-
while passing forward arguments intended for :class:`~omni.isaac.kit.SimulationApp`.
11
+
The :class:`~app.AppLauncher` is a wrapper for :class:`~omni.isaac.kit.SimulationApp` to simplify
12
+
its configuration. The :class:`~omni.isaac.kit.SimulationApp` has many extensions that must be
13
+
loaded to enable different capabilities, and some of these extensions are order- and inter-dependent.
14
+
Additionally, there are startup options such as ``headless`` which must be set at instantiation time,
15
+
and which have an implied relationship with some extensions, e.g. the livestreaming extensions.
16
+
The :class:`~app.AppLauncher` presents an interface that can handle these extensions and startup
17
+
options in a portable manner across a variety of use cases. To achieve this, we offer CLI and envar
18
+
flags which can be merged with user-defined CLI args, while passing forward arguments intended
19
+
for :class:`~omni.isaac.kit.SimulationApp`.
20
20
21
21
22
22
The Code
23
-
~~~~~~~~
23
+
--------
24
24
25
-
The tutorial corresponds to the ``launch_app.py`` script in the ``orbit/source/standalone/tutorials/00_sim`` directory.
25
+
The tutorial corresponds to the ``launch_app.py`` script in the
:class:`~app.AppLauncher` is designed to be compatible with custom CLI args that users need for
43
+
their own scripts, while still providing a portable CLI interface.
37
44
38
-
:class:`~app.AppLauncher` is designed to be compatible with custom CLI args that users need for their own scripts,
39
-
while still providing a portable CLI interface. In this tutorial, a standard :class:`argparse.ArgumentParser` is instantiated
40
-
and given the script-specific ``--size`` argument, as well as the arguments ``--height`` and ``--width``. The latter
41
-
are ingested by :class:`~omni.isaac.kit.SimulationApp`.
45
+
In this tutorial, a standard :class:`argparse.ArgumentParser` is instantiated and given the
46
+
script-specific ``--size`` argument, as well as the arguments ``--height`` and ``--width``.
47
+
The latter are ingested by :class:`~omni.isaac.kit.SimulationApp`.
42
48
43
-
The argument ``--size`` is not used by :class:`~app.AppLauncher`, but will merge seamlessly with the :class:`~app.AppLauncher`
44
-
interface. In-script arguments can be merged with the :class:`~app.AppLauncher` interface via the :meth:`~app.AppLauncher.add_app_launcher_args` method,
45
-
which will return a modified :class:`~argparse.ArgumentParser` with the :class:`~app.AppLauncher` arguments appended. This can then be processed
46
-
into an :class:`argparse.Namespace` using the standard :meth:`argparse.ArgumentParser.parse_args` method and passed directly to :class:`~app.AppLauncher` for instantiation.
47
-
This illustrates only one of several ways of passing arguments to :class:`~app.AppLauncher`, please consult its documentation page to see further options.
49
+
The argument ``--size`` is not used by :class:`~app.AppLauncher`, but will merge seamlessly
50
+
with the :class:`~app.AppLauncher` interface. In-script arguments can be merged with the
51
+
:class:`~app.AppLauncher` interface via the :meth:`~app.AppLauncher.add_app_launcher_args` method,
52
+
which will return a modified :class:`~argparse.ArgumentParser` with the :class:`~app.AppLauncher`
53
+
arguments appended. This can then be processed into an :class:`argparse.Namespace` using the
54
+
standard :meth:`argparse.ArgumentParser.parse_args` method and passed directly to
To illustrate this process, we can pass the ``--help`` argument and see the combined outputs of our custom arguments and
55
-
those from :class:`~app.AppLauncher`.
62
+
The above only illustrates only one of several ways of passing arguments to :class:`~app.AppLauncher`.
63
+
Please consult its documentation page to see further options.
64
+
65
+
Understanding the output of --help
66
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
67
+
68
+
While executing the script, we can pass the ``--help`` argument and see the combined outputs of the
69
+
custom arguments and those from :class:`~app.AppLauncher`.
56
70
57
71
.. code-block:: console
58
72
@@ -79,27 +93,38 @@ those from :class:`~app.AppLauncher`.
79
93
--ros {0,1,2} Enable ROS middleware. Mapping corresponds to that for the "ROS_ENABLED" environment variable
80
94
--offscreen_render Enable offscreen rendering when running without a GUI.
81
95
82
-
This readout details the ``--size``, ``--height``, and ``--width`` arguments defined in the script directly, as well as the :class:`~app.AppLauncher` arguments.
83
-
An ``[INFO]`` message preceding the help output also reads out which of these arguments are going to be interpreted as arguments to the :class:`~omni.isaac.kit.SimulationApp` instance which :class:`~app.AppLauncher` wraps,
84
-
in this instance ``--height`` and ``--width``. These are classified as such because they match the name and type of an argument which can be processed by :class:`~omni.isaac.kit.SimulationApp`.
85
-
Please refer to the `specification`_ for such arguments for more examples.
86
-
As noted in the help message, the :class:`~app.AppLauncher` arguments correspond to the envars described in :mod:`omni.isaac.orbit.app`. Providing any of these arguments is equivalent to
87
-
running the script in a shell environment where the corresponding envar is set- :class:`~app.AppLauncher` envars are simply a convenience to provide session-persistent configurations,
88
-
and can be set in the user's ``.bashrc`` for persistent settings between sessions. In the case where these arguments are provided, they will override their corresponding envar, as we
89
-
will demonstrate below.
96
+
This readout details the ``--size``, ``--height``, and ``--width`` arguments defined in the script directly,
97
+
as well as the :class:`~app.AppLauncher` arguments.
90
98
91
-
These arguments can be used with any script that starts the simulation using :class:`~app.AppLauncher`, with one exception, ``--offscreen_render``.
92
-
The :class:`omni.isaac.orbit.sim.SimulationContext` class controls many aspects of simulation execution, including the rendering pipeline. This makes it required when we
93
-
want to use the ``--offscreen_render`` argument, because ``--offscreen_render`` pipeline depends on behavior within :class:`~omni.isaac.orbit.sim.SimulationContext`.
94
-
For more information on the ``--offscreen_render`` flag, please see the :class:`~app.AppLauncher` API doc.
99
+
The ``[INFO]`` messages preceding the help output also reads out which of these arguments are going
100
+
to be interpreted as arguments to the :class:`~omni.isaac.kit.SimulationApp` instance which the
101
+
:class:`~app.AppLauncher` class wraps. In this case, it is ``--height`` and ``--width``. These
102
+
are classified as such because they match the name and type of an argument which can be processed
103
+
by :class:`~omni.isaac.kit.SimulationApp`. Please refer to the `specification`_ for such arguments
104
+
for more examples.
105
+
106
+
Using environment variables
107
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
108
+
109
+
As noted in the help message, the :class:`~app.AppLauncher` arguments (``--livestream``, ``--ros``)
110
+
have corresponding environment variables (envar) as well. These are detailed in :mod:`omni.isaac.orbit.app`
111
+
documentation. Providing any of these arguments through CLI is equivalent to running the script in a shell
112
+
environment where the corresponding envar is set.
113
+
114
+
The support for :class:`~app.AppLauncher` envars are simply a convenience to provide session-persistent
115
+
configurations, and can be set in the user's ``${HOME}/.bashrc`` for persistent settings between sessions.
116
+
In the case where these arguments are provided from the CLI, they will override their corresponding envar,
117
+
as we will demonstrate later in this tutorial.
118
+
119
+
These arguments can be used with any script that starts the simulation using :class:`~app.AppLauncher`,
120
+
with one exception, ``--offscreen_render``. This setting is sets the rendering pipeline to use the
121
+
offscreen renderer. However, this setting is only compatible with the :class:`omni.isaac.orbit.sim.SimulationContext`.
122
+
It will not work with Isaac Sim's :class:`omni.isaac.core.simulation_context.SimulationContext` class.
123
+
For more information on this flag, please see the :class:`~app.AppLauncher` API documentation.
This will spawn a 0.5m\ :sup:`3` volume cuboid in the simulation. No GUI will appear, equivalent
111
-
to if we had passed the ``--headless`` flag because headlessness is implied by our ``LIVESTREAM`` envar. If a
112
-
visualization is desired, we could get one via Isaac's `Native Livestreaming`_. The process can be killed by pressing ``Ctrl+C`` in the launching terminal.
136
+
to if we had passed the ``--headless`` flag because headlessness is implied by our ``LIVESTREAM``
137
+
envar. If a visualization is desired, we could get one via Isaac's `Native Livestreaming`_. The
138
+
process can be killed by pressing ``Ctrl+C`` in the launching terminal.
113
139
114
140
115
-
Now we will look at how :class:`~app.AppLauncher` handles conflicting commands:
141
+
Now, let's look at how :class:`~app.AppLauncher` handles conflicting commands:
116
142
117
143
.. code-block:: console
118
144
@@ -123,7 +149,8 @@ This will cause the same behavior as in the previous run, because although we ha
123
149
in our envars, CLI args such as ``--livestream`` take precedence in determining behavior. The process can
124
150
be killed by pressing ``Ctrl+C`` in the launching terminal.
125
151
126
-
Finally, we will examine passing arguments to :class:`~omni.isaac.kit.SimulationApp` through :class:`~app.AppLauncher`:
152
+
Finally, we will examine passing arguments to :class:`~omni.isaac.kit.SimulationApp` through
153
+
:class:`~app.AppLauncher`:
127
154
128
155
.. code-block:: console
129
156
@@ -132,7 +159,9 @@ Finally, we will examine passing arguments to :class:`~omni.isaac.kit.Simulation
132
159
133
160
This will cause the same behavior as before, but now the viewport will be rendered at 1920x1080p resolution.
134
161
This can be useful when we want to gather high-resolution video, or we can specify a lower resolution if we
135
-
want our simulation to be more performant. The process can be killed by pressing ``Ctrl+C`` in the launching terminal.
162
+
want our simulation to be more performant. The process can be killed by pressing ``Ctrl+C`` in the launching
0 commit comments