Clarifies Isaac Lab ecosystem and installation steps in documentation (#1338)

kellyguo11 · web-flow · commit 9d6594b4b360 · 2024-11-17T08:13:36.000-05:00
# Description This change adds a new page highlighting the Isaac Lab ecosystem and relationship with Omniverse and Isaac Sim. It also clarifies the installation steps with recommendations on when each installation approach should be used. ## Type of change - This change requires a documentation update ## Checklist - [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.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 - [ ] I have added my name to the `CONTRIBUTORS.md` or my name already exists there
diff --git a/docs/index.rst b/docs/index.rst
@@ -74,7 +74,9 @@ Table of Contents
    :maxdepth: 2
    :caption: Getting Started
 
+   source/setup/ecosystem
    source/setup/installation/index
+   source/setup/installation/cloud_installation
    source/setup/faq
 
 .. toctree::
diff --git a/docs/source/_static/setup/ecosystem-dark.jpg b/docs/source/_static/setup/ecosystem-dark.jpg
diff --git a/docs/source/_static/setup/ecosystem-light.jpg b/docs/source/_static/setup/ecosystem-light.jpg
diff --git a/docs/source/_static/setup/verify_install.jpg b/docs/source/_static/setup/verify_install.jpg
diff --git a/docs/source/overview/core-concepts/actuators.rst b/docs/source/overview/core-concepts/actuators.rst
@@ -74,4 +74,4 @@ The following figure shows the actuator groups for a legged mobile manipulator:
 .. seealso::
 
     We provide implementations for various explicit actuator models. These are detailed in
-    `omni.isaac.lab.actuators <../api/lab/omni.isaac.lab.actuators.html>`_ sub-package.
+    `omni.isaac.lab.actuators <../../api/lab/omni.isaac.lab.actuators.html>`_ sub-package.
diff --git a/docs/source/overview/core-concepts/index.rst b/docs/source/overview/core-concepts/index.rst
@@ -9,5 +9,3 @@ This section we introduce core concepts in Isaac Lab.
 
   task_workflows
   actuators
-
-# motion_generators
diff --git a/docs/source/overview/developer-guide/template.rst b/docs/source/overview/developer-guide/template.rst
@@ -22,4 +22,36 @@ This template serves three distinct use cases:
   features and improvements in Isaac Lab.
 
 
-To get started, please follow the instructions in the `extension template repository <https://github.com/isaac-sim/IsaacLabExtensionTemplate>`_.
+Installation
+------------
+
+Install Isaac Lab by following the `installation guide <../../setup/installation/index.html>`_. We recommend using the conda installation as it simplifies calling Python scripts from the terminal.
+
+Clone the extension template repository separately from the Isaac Lab installation (i.e. outside the IsaacLab directory):
+
+.. code:: bash
+
+	# Option 1: HTTPS
+	git clone https://github.com/isaac-sim/IsaacLabExtensionTemplate.git
+
+	# Option 2: SSH
+	git clone git@github.com:isaac-sim/IsaacLabExtensionTemplate.git
+
+Throughout the repository, the name ``ext_template`` only serves as an example and we provide a script to rename all the references to it automatically:
+
+.. code:: bash
+
+	# Enter the repository
+	cd IsaacLabExtensionTemplate
+
+	# Rename all occurrences of ext_template (in files/directories) to your_fancy_extension_name
+	python scripts/rename_template.py your_fancy_extension_name
+
+Using a python interpreter that has Isaac Lab installed, install the library:
+
+.. code:: bash
+
+	python -m pip install -e exts/ext_template
+
+
+For more details, please follow the instructions in the `extension template repository <https://github.com/isaac-sim/IsaacLabExtensionTemplate>`_.
diff --git a/docs/source/setup/ecosystem.rst b/docs/source/setup/ecosystem.rst
@@ -0,0 +1,32 @@
+Isaac Lab Ecosystem
+===================
+
+Isaac Lab is built on top of Isaac Sim to provide a unified and flexible framework
+for robot learning that exploits latest simulation technologies. It is designed to be modular and extensible,
+and aims to simplify common workflows in robotics research (such as RL, learning from demonstrations, and
+motion planning). While it includes some pre-built environments, sensors, and tasks, its main goal is to
+provide an open-sourced, unified, and easy-to-use interface for developing and testing custom environments
+and robot learning algorithms.
+
+Working with Isaac Lab requires the installation of Isaac Sim, which is packaged with core robotics tools
+that Isaac Lab depends on, including URDF and MJCF importers, simulation managers, and ROS features. Isaac
+Sim also builds on top of the Nvidia Omniverse platform, leveraging advanced physics simulation from PhysX,
+photorealistic rendering technologies, and Universal Scene Description (USD) for scene creation.
+
+Isaac Lab not only inherits the capabilities of Isaac Sim, but also adds a number
+of new features that pertain to robot learning research. For example, including actuator dynamics in the
+simulation, procedural terrain generation, and support to collect data from human demonstrations.
+
+.. image:: ../_static/setup/ecosystem-light.jpg
+    :class: only-light
+    :align: center
+    :alt: The Isaac Lab, Isaac Sim, and Nvidia Omniverse ecosystem
+
+.. image:: ../_static/setup/ecosystem-dark.jpg
+    :class: only-dark
+    :align: center
+    :alt: The Isaac Lab, Isaac Sim, and Nvidia Omniverse ecosystem
+
+
+For a detailed explanation of Nvidia's development journey of robot learning frameworks, please visit
+the `FAQ page <faq.html>`_.
diff --git a/docs/source/setup/installation/binaries_installation.rst b/docs/source/setup/installation/binaries_installation.rst
@@ -407,8 +407,14 @@ top of the repository:
 
 
 The above command should launch the simulator and display a window with a black
-ground plane. You can exit the script by pressing ``Ctrl+C`` on your terminal.
+viewport. You can exit the script by pressing ``Ctrl+C`` on your terminal.
 On Windows machines, please terminate the process from Command Prompt using
 ``Ctrl+Break`` or ``Ctrl+fn+B``.
 
+.. figure:: ../../_static/setup/verify_install.jpg
+    :align: center
+    :figwidth: 100%
+    :alt: Simulator with a black window.
+
+
 If you see this, then the installation was successful! |:tada:|
diff --git a/docs/source/setup/installation/index.rst b/docs/source/setup/installation/index.rst
@@ -1,5 +1,5 @@
-Installation Guide
-===================
+Local Installation
+==================
 
 .. image:: https://img.shields.io/badge/IsaacSim-4.2.0-silver.svg
    :target: https://developer.nvidia.com/isaac-sim
@@ -31,14 +31,9 @@ Installation Guide
     For the full list of system requirements for Isaac Sim, please refer to the
     `Isaac Sim system requirements <https://docs.omniverse.nvidia.com/isaacsim/latest/installation/requirements.html#system-requirements>`_.
 
-As an experimental feature since Isaac Sim 4.0 release, Isaac Sim can also be installed through pip.
-This simplifies the installation
-process by avoiding the need to download the Omniverse Launcher and installing Isaac Sim through
-the launcher. Therefore, there are two ways to install Isaac Lab:
 
 .. toctree::
     :maxdepth: 2
 
-    Option 1: Installation using Isaac Sim pip <pip_installation>
-    Option 2: Installation using Isaac Sim binaries <binaries_installation>
-    cloud_installation
+    Pip installation (recommended for Ubuntu 22.04 and Windows) <pip_installation>
+    Binary installation (recommended for Ubuntu 20.04) <binaries_installation>
diff --git a/docs/source/setup/installation/pip_installation.rst b/docs/source/setup/installation/pip_installation.rst
@@ -88,7 +88,14 @@ compatibility issues with some Linux distributions. If you encounter any issues,
       pip install --upgrade pip
 
 
--  Then, install the Isaac Sim packages necessary for running Isaac Lab:
+-  Then, install the Isaac Sim package
+
+   .. code-block:: bash
+
+      pip install isaacsim==4.2.0.2 --extra-index-url https://pypi.nvidia.com
+
+
+- To install a minimal set of packages for running Isaac Lab only, the following command can be used. Note that you cannot run ``isaacsim`` with this.
 
    .. code-block:: bash
 
@@ -310,8 +317,15 @@ top of the repository:
 
 
 The above command should launch the simulator and display a window with a black
-ground plane. You can exit the script by pressing ``Ctrl+C`` on your terminal.
+viewport as shown below. You can exit the script by pressing ``Ctrl+C`` on your terminal.
 On Windows machines, please terminate the process from Command Prompt using
 ``Ctrl+Break`` or ``Ctrl+fn+B``.
 
+
+.. figure:: ../../_static/setup/verify_install.jpg
+    :align: center
+    :figwidth: 100%
+    :alt: Simulator with a black window.
+
+
 If you see this, then the installation was successful! |:tada:|
diff --git a/source/standalone/tutorials/00_sim/log_time.py b/source/standalone/tutorials/00_sim/log_time.py
@@ -40,12 +40,14 @@
 def main():
     """Main function."""
     # Specify that the logs must be in logs/docker_tutorial
-    log_dir_path = os.path.join("logs", "docker_tutorial")
+    log_dir_path = os.path.join("logs")
+    if not os.path.isdir(log_dir_path):
+        os.mkdir(log_dir_path)
     # In the container, the absolute path will be
     # /workspace/isaaclab/logs/docker_tutorial, because
     # all python execution is done through /workspace/isaaclab/isaaclab.sh
     # and the calling process' path will be /workspace/isaaclab
-    log_dir_path = os.path.abspath(log_dir_path)
+    log_dir_path = os.path.abspath(os.path.join(log_dir_path, "docker_tutorial"))
     if not os.path.isdir(log_dir_path):
         os.mkdir(log_dir_path)
     print(f"[INFO] Logging experiment to directory: {log_dir_path}")
