Creates a tutorial on AppLauncher parameters (#262)

# Description

Adds a tutorial explaining how to use the AppLauncher class and
corresponding script. Also slightly modifies AppLauncher by removing -1
from the list of argument choices for --livestream and --ros, as these
are options used internally and which should never be entered by a user.

Fixes #229 (partially)

## Type of change

- New feature (non-breaking change which adds functionality)

## Checklist

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./orbit.sh --format`
- [ ] 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

docs/index.rst

@@ -50,6 +50,7 @@ For more information about the framework, please refer to the `paper <https://ar
 
    source/tutorials/00_sim/empty
    source/tutorials/00_sim/prims
+   source/tutorials/00_sim/applauncher
    source/tutorials/00_sim/docker
    source/tutorials/01_assets/articulation
    source/tutorials/01_assets/rigid_object

docs/source/tutorials/00_sim/applauncher.rst

+Launching Isaac Sim from AppLauncher
+==============================
+
+.. currentmodule:: omni.isaac.orbit
+
+In this tutorial, we will learn how to use the :class:`app.AppLauncher` class to configure the simulator using
+CLI arguments and environment variables (envars). As a specific example in this tutorial, we will be demonstrating
+how to use :class:`~app.AppLauncher` to enable livestreaming and configure :class:`omni.isaac.kit.SimulationApp` while also specifying user-provided options.
+
+Motivation
+----------
+
+:class:`~app.AppLauncher` is a wrapper for :class:`~omni.isaac.kit.SimulationApp`, intended to simplify configuration.
+: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.
+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. :class:`~app.AppLauncher` presents an interface that can handle these extensions and startup options
+in a portable manner across a variety of Orbit 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 :class:`~omni.isaac.kit.SimulationApp`.
+
+
+The Code
+~~~~~~~~
+
+The tutorial corresponds to the ``applauncher.py`` script in the ``orbit/source/standalone/tutorials/00_sim`` directory.
+
+.. dropdown:: :fa:`eye,mr-1` Code for ``applauncher.py``
+
+   .. literalinclude:: ../../../../source/standalone/tutorials/00_sim/applauncher.py
+      :language: python
+      :emphasize-lines: 17-41
+      :linenos:
+
+The Code Explained
+~~~~~~~~~~~~~~~~~~
+
+:class:`~app.AppLauncher` is designed to be compatible with custom CLI args that users need for their own scripts,
+while still providing a portable CLI interface. A standard :class:`argparse.ArgumentParser` is instantiated
+and given the script-specific ``--size`` argument, as well as the arguments ``--height`` and ``--width`` to be ingested by :class:`~omni.isaac.kit.SimulationApp`.
+The argument ``--size`` is not used by :class:`~app.AppLauncher`, but will merge seamlessly with the :class:`~app.AppLauncher`
+interface. In-script arguments can be merged with the :class:`~app.AppLauncher` interface via the :meth:`~app.AppLauncher.add_app_launcher_args()` method,
+which will return a modified :class:`~argparse.ArgumentParser` with the :class:`~app.AppLauncher` arguments appended. This can then be processed
+into an :class:`argparse.Namespace` using the standard :meth:`~argparse.ArgumentParser.parse_args()` method and passed directly to :class:`~app.AppLauncher` for instantiation.
+This illustrates only one of several ways of passing arguments to :class:`~app.AppLauncher`, please consult its documentation page to see further options.
+
+.. literalinclude::  ../../../../source/standalone/tutorials/00_sim/applauncher.py
+   :language: python
+   :start-at: import argparse
+   :end-at: simulation_app = app_launcher.app
+
+To illustrate this process, we can pass the ``--help`` argument and see the combined outputs of our custom arguments and
+those from :class:`~app.AppLauncher`.
+
+.. code-block:: console
+
+   ./orbit.sh -p source/standalone/tutorials/00_sim/applauncher.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: applauncher.py [-h] [--size SIZE] [--width WIDTH] [--height HEIGHT] [--headless] [--livestream {0,1,2,3}] [--ros {0,1,2}]
+                        [--offscreen_render]
+
+   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,3}
+                           Force enable livestreaming. Mapping corresponds to that for the `LIVESTREAM` environment variable.
+   --ros {0,1,2}         Enable ROS middleware. Mapping corresponds to that for the `ROS_ENABLED` environment variable
+   --offscreen_render    Enable offscreen rendering when running without a GUI.
+
+This readout details the ``--size``, ``--height``, and ``--width`` arguments defined in the script directly, as well as the :class:`~app.AppLauncher` arguments.
+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,
+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`.
+Please refer to the `specification`_ for such arguments for more examples.
+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
+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,
+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
+will demonstrate below.
+
+
+These arguments can be used with any script that starts the simulation using :class:`~app.AppLauncher`, with one exception, ``--offscreen-render``.
+The :class:`omni.isaac.orbit.sim.SimulationContext`  class controls many aspects of simulation execution, including the rendering pipeline. This makes it required when we
+want to use the ``--offscreen_render`` argument, because ``--offscreen_render`` pipeline depends on behavior within :class:`~omni.isaac.orbit.sim.SimulationContext`.
+For more information on the ``--offscreen-render`` flag, please see the :class:`~app.AppLauncher` API doc.
+
+
+.. literalinclude::  ../../../../source/standalone/tutorials/00_sim/applauncher.py
+   :language: python
+   :start-at: def main():
+   :end-at: sim = sim_utils.SimulationContext(sim_cfg)
+
+The Code Execution
+~~~~~~~~~~~~~~~~~~
+
+We will now run the example script:
+
+.. code-block:: console
+
+   LIVESTREAM=1 ./orbit.sh -p source/standalone/tutorials/00_sim/applauncher.py --size 0.5
+
+This will spawn a 0.5m\ :sup:`3` 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`_. The process can be killed by pressing ``Ctrl+C`` in the launching terminal.
+
+
+Now we will look at how :class:`~app.AppLauncher` handles conflicting commands:
+
+.. code-block:: console
+
+   export LIVESTREAM=0
+   ./orbit.sh -p source/standalone/tutorials/00_sim/applauncher.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 :class:`~omni.isaac.kit.SimulationApp` through :class:`~app.AppLauncher`:
+
+.. code-block:: console
+
+   export LIVESTREAM=1
+   ./orbit.sh -p source/standalone/tutorials/00_sim/applauncher.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.
+
+.. _specification: https://docs.omniverse.nvidia.com/py/isaacsim/source/extensions/omni.isaac.kit/docs/index.html#omni.isaac.kit.SimulationApp.DEFAULT_LAUNCHER_CONFIG
+.. _Native Livestreaming: https://docs.omniverse.nvidia.com/isaacsim/latest/installation/manual_livestream_clients.html#omniverse-streaming-client

source/extensions/omni.isaac.orbit/omni/isaac/orbit/app.py

@@ -305,14 +305,14 @@ class AppLauncher:
             "--livestream",
             type=int,
             default=AppLauncher._APPLAUNCHER_CFG_INFO["livestream"][1],
-            choices={-1, 0, 1, 2, 3},
+            choices={0, 1, 2, 3},
             help="Force enable livestreaming. Mapping corresponds to that for the `LIVESTREAM` environment variable.",
         )
         arg_group.add_argument(
             "--ros",
             type=int,
             default=AppLauncher._APPLAUNCHER_CFG_INFO["ros"][1],
-            choices={-1, 0, 1, 2},
+            choices={0, 1, 2},
             help="Enable ROS middleware. Mapping corresponds to that for the `ROS_ENABLED` environment variable",
         )
         arg_group.add_argument(

source/standalone/tutorials/00_sim/applauncher.py

+# Copyright (c) 2022-2023, The ORBIT Project Developers.
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+This script demonstrates how to run IsaacSim via the AppLauncher
+
+.. code-block:: bash
+
+    # Usage
+    ./orbit.sh -p source/standalone/tutorials/00_sim/applauncher.py
+
+"""
+
+from __future__ import annotations
+
+"""Launch Isaac Sim Simulator first."""
+import argparse
+
+from omni.isaac.orbit.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
+
+"""Rest everything follows."""
+
+import traceback
+
+import carb
+import omni.isaac.core.utils.prims as prim_utils
+
+import omni.isaac.orbit.sim as sim_utils
+
+
+def design_scene():
+    """Designs the scene by spawning ground plane, light, objects and meshes from usd files."""
+    # Ground-plane
+    cfg_ground = sim_utils.GroundPlaneCfg()
+    cfg_ground.func("/World/defaultGroundPlane", cfg_ground)
+
+    # spawn distant light
+    cfg_light_distant = sim_utils.DistantLightCfg(
+        intensity=3000.0,
+        color=(0.75, 0.75, 0.75),
+    )
+    cfg_light_distant.func("/World/lightDistant", cfg_light_distant, translation=(1, 0, 10))
+
+    # create a new xform prim for all objects to be spawned under
+    prim_utils.create_prim("/World/Objects", "Xform")
+    # spawn a cuboid
+    cfg_cuboid = sim_utils.CuboidCfg(
+        size=[args_cli.size] * 3,
+        visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(1.0, 1.0, 1.0)),
+    )
+    # Spawn cuboid, altering translation on the z-axis to scale to its size
+    cfg_cuboid.func("/World/Objects/Cuboid1", cfg_cuboid, translation=(0.0, 0.0, args_cli.size / 2))
+
+
+def main():
+    """Main function."""
+
+    # Initialize the simulation context
+    sim_cfg = sim_utils.SimulationCfg(dt=0.01, substeps=1)
+    sim = sim_utils.SimulationContext(sim_cfg)
+    # Set main camera
+    sim.set_camera_view([2.0, 0.0, 2.5], [-0.5, 0.0, 0.5])
+
+    # Design scene by adding assets to it
+    design_scene()
+
+    # Play the simulator
+    sim.reset()
+    # Now we are ready!
+    print("[INFO]: Setup complete...")
+
+    # Simulate physics
+    while simulation_app.is_running():
+        # perform step
+        sim.step()
+
+
+if __name__ == "__main__":
+    try:
+        # run the main execution
+        main()
+    except Exception as err:
+        carb.log_error(err)
+        carb.log_error(traceback.format_exc())
+        raise
+    finally:
+        # close sim app
+        simulation_app.close()