Skip to content

K
KincoActuatorIsaacLab
Unverified Commit 8b590c1a authored by Mayank Mittal's avatar Mayank Mittal Committed by GitHub
Browse files
Options

Details installation section in documentation (#3442) 

# Description

It was getting confusing with the table of content on which installation
instruction to follow when. This MR takes a stab at writing clearer
documentation for users. I hope this helps with new users coming to
Isaac Lab.

## Type of change

- Documentation update

## Screenshots

<img width="553" height="865" alt="image"
src="https://github.com/user-attachments/assets/b2b8c71c-8aa4-4911-8efb-25bc894e3a00"
/>

## Checklist

- [x] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [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
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there
parent 137106d3
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 686 additions and 136 deletions
README.md
View file @ 8b590c1a
......@@ -37,92 +37,6 @@ Isaac Lab offers a comprehensive set of tools and environments designed to facil
## Getting Started
### Getting Started with Open-Source Isaac Sim
Isaac Sim is now open source and available on GitHub!
For detailed Isaac Sim installation instructions, please refer to
[Isaac Sim README](https://github.com/isaac-sim/IsaacSim?tab=readme-ov-file#quick-start).
1. Clone Isaac Sim
```
git clone https://github.com/isaac-sim/IsaacSim.git
```
2. Build Isaac Sim
```
cd IsaacSim
./build.sh
```
On Windows, please use `build.bat` instead.
3. Clone Isaac Lab
```
cd ..
git clone https://github.com/isaac-sim/IsaacLab.git
cd isaaclab
```
4. Set up symlink in Isaac Lab
Linux:
```
ln -s ../IsaacSim/_build/linux-x86_64/release _isaac_sim
```
Windows:
```
mklink /D _isaac_sim ..\IsaacSim\_build\windows-x86_64\release
```
5. Install Isaac Lab
Linux:
```
./isaaclab.sh -i
```
Windows:
```
isaaclab.bat -i
```
6. [Optional] Set up a virtual python environment (e.g. for Conda)
Linux:
```
source _isaac_sim/setup_conda_env.sh
```
Windows:
```
_isaac_sim\setup_python_env.bat
```
7. Train!
Linux:
```
./isaaclab.sh -p scripts/reinforcement_learning/skrl/train.py --task Isaac-Ant-v0 --headless
```
Windows:
```
isaaclab.bat -p scripts\reinforcement_learning\skrl\train.py --task Isaac-Ant-v0 --headless
```
### Documentation
Our [documentation page](https://isaac-sim.github.io/IsaacLab) provides everything you need to get started, including
......
docs/conf.py
View file @ 8b590c1a
......@@ -96,6 +96,8 @@ nitpick_ignore_regex = [
(r"py:.*", r"trimesh.*"), # we don't have intersphinx mapping for trimesh
]
# emoji style
sphinxemoji_style = "twemoji" # options: "twemoji" or "unicode"
# put type hints inside the signature instead of the description (easier to maintain)
autodoc_typehints = "signature"
# autodoc_typehints_format = "fully-qualified"
......
docs/source/setup/installation/asset_caching.rst
View file @ 8b590c1a
......@@ -8,7 +8,7 @@ In some cases, it is possible that asset loading times can be long when assets a
If you run into cases where assets take a few minutes to load for each run,
we recommend enabling asset caching following the below steps.
First, launch the Isaac Sim app:
First, launch the Isaac Sim application:
.. tab-set::
:sync-group: os
......@@ -27,25 +27,32 @@ First, launch the Isaac Sim app:
isaaclab.bat -s
On the top right of the Isaac Sim app, there will be an icon labelled ``CACHE:``.
There may be a message indicating ``HUB NOT DETECTED`` or ``NEW VERSION DETECTED``.
On the top right of the Isaac Lab or Isaac Sim app, look for the icon labeled ``CACHE:``.
You may see a message such as ``HUB NOT DETECTED`` or ``NEW VERSION DETECTED``.
Click the message to enable `Hub <https://docs.omniverse.nvidia.com/utilities/latest/cache/hub-workstation.html>`_.
Hub automatically manages local caching for Isaac Lab assets, so subsequent runs will use cached files instead of
downloading from AWS each time.
.. figure:: ../../_static/setup/asset_caching.jpg
:align: center
:figwidth: 100%
:alt: Simulator with cache messaging.
Click on the message, which will enable `Hub <https://docs.omniverse.nvidia.com/utilities/latest/cache/hub-workstation.html>`_
for asset caching. Once enabled, Hub will run automatically each time an Isaac Lab or Isaac Sim instance is run.
Hub provides better control and management of cached assets, making workflows faster and more reliable, especially
in environments with limited or intermittent internet access.
Note that for the first run, assets will still need to be pulled from the cloud, which could lead to longer loading times.
However, subsequent runs that use the same assets will be able to use the cached files from Hub.
Hub will provide better control for caching of assets used in Isaac Lab.
.. note::
The first time you run Isaac Lab, assets will still need to be pulled from the cloud, which could lead
to longer loading times. Once cached, loading times will be significantly reduced on subsequent runs.
Nucleus
-------
Prior to Isaac Sim 4.5, assets were accessible from the Omniverse Nucleus server and through setting up a local Nucleus server.
Although from Isaac Sim 4.5, we have deprecated the use of Omniverse Nucleus and the Omniverse Launcher, any existing instances
or setups of local Nucleus instances should still work. We recommend keeping existing setups if a local Nucleus server
was previously already set up.
Before Isaac Sim 4.5, assets were accessed via the Omniverse Nucleus server, including setups with local Nucleus instances.
.. warning::
Starting with Isaac Sim 4.5, the Omniverse Nucleus server and Omniverse Launcher are deprecated.
Existing Nucleus setups will continue to work, so if you have a local Nucleus server already configured,
you may continue to use it.
docs/source/setup/installation/binaries_installation.rst
View file @ 8b590c1a
......@@ -3,7 +3,7 @@
Installation using Isaac Sim Binaries
=====================================
Isaac Lab requires Isaac Sim. This tutorial installs Isaac Sim first from binaries, then Isaac Lab from source code.
Isaac Lab requires Isaac Sim. This tutorial installs Isaac Sim first from its binaries, then Isaac Lab from source code.
Installing Isaac Sim
--------------------
......@@ -15,7 +15,8 @@ Please follow the Isaac Sim
`documentation <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/install_workstation.html>`__
to install the latest Isaac Sim release.
From Isaac Sim 4.5 release, Isaac Sim binaries can be `downloaded <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/download.html#download-isaac-sim-short>`_ directly as a zip file.
From Isaac Sim 4.5 release, Isaac Sim binaries can be `downloaded <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/download.html#download-isaac-sim-short>`_
directly as a zip file.
To check the minimum system requirements, refer to the documentation
`here <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/requirements.html>`__.
......@@ -485,7 +486,7 @@ and ``source _isaac_sim/setup_conda_env.sh`` has been executed (for uv as well).
Train a robot!
~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~
You can now use Isaac Lab to train a robot through Reinforcement Learning! The quickest way to use Isaac Lab is through the predefined workflows using one of our **Batteries-included** robot tasks. Execute the following command to quickly train an ant to walk!
We recommend adding ``--headless`` for faster training.
......
docs/source/setup/installation/index.rst
View file @ 8b590c1a
......@@ -19,6 +19,11 @@ Local Installation
:target: https://www.microsoft.com/en-ca/windows/windows-11
:alt: Windows 11
Isaac Lab installation is available for Windows and Linux. Since it is built on top of Isaac Sim,
it is required to install Isaac Sim before installing Isaac Lab. This guide explains the
recommended installation methods for both Isaac Sim and Isaac Lab.
.. caution::
We have dropped support for Isaac Sim versions 4.2.0 and below. We recommend using the latest
......@@ -27,44 +32,121 @@ Local Installation
For more information, please refer to the
`Isaac Sim release notes <https://docs.isaacsim.omniverse.nvidia.com/latest/overview/release_notes.html#>`__.
.. note::
We recommend system requirements with at least 32GB RAM and 16GB VRAM for Isaac Lab.
For workflows with rendering enabled, additional VRAM may be required.
For the full list of system requirements for Isaac Sim, please refer to the
`Isaac Sim system requirements <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/requirements.html#system-requirements>`_.
System Requirements
-------------------
General Requirements
~~~~~~~~~~~~~~~~~~~~
- **RAM:** 32 GB or more
- **GPU VRAM:** 16 GB or more (additional VRAM may be required for rendering workflows)
- **OS:** Ubuntu 22.04 (Linux x64) or Windows 11 (x64)
For detailed requirements, see the
`Isaac Sim system requirements <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/requirements.html#system-requirements>`_.
Driver Requirements
~~~~~~~~~~~~~~~~~~~
Drivers other than those recommended on `Omniverse Technical Requirements <https://docs.omniverse.nvidia.com/materials-and-rendering/latest/common/technical-requirements.html>`_
may work but have not been validated against all Omniverse tests.
- Use the **latest NVIDIA production branch driver**.
- On Linux, version ``535.216.01`` or later is recommended, especially when upgrading to
**Ubuntu 22.04.5 with kernel 6.8.0-48-generic** or newer.
- If you are using a new GPU or encounter driver issues, install the latest production branch
driver from the `Unix Driver Archive <https://www.nvidia.com/en-us/drivers/unix/>`_
using the ``.run`` installer.
Troubleshooting
~~~~~~~~~~~~~~~
Please refer to the `Linux Troubleshooting <https://docs.omniverse.nvidia.com/dev-guide/latest/linux-troubleshooting.html>`_
to resolve installation issues in Linux.
Quick Start (Recommended)
-------------------------
For most users, the simplest and fastest way to install Isaac Lab is by following the
:doc:`pip_installation` guide.
This method will install Isaac Sim via pip and Isaac Lab through its source code.
If you are new to Isaac Lab, start here.
Choosing an Installation Method
-------------------------------
Different workflows require different installation methods.
Use this table to decide:
+-------------------+------------------------------+------------------------------+---------------------------+------------+
| Method | Isaac Sim | Isaac Lab | Best For | Difficulty |
+===================+==============================+==============================+===========================+============+
| **Recommended** | |:package:| pip install | |:floppy_disk:| source (git) | Beginners, standard use | Easy |
+-------------------+------------------------------+------------------------------+---------------------------+------------+
| Binary + Source | |:inbox_tray:| binary | |:floppy_disk:| source (git) | Users preferring binary | Easy |
| | download | | install of Isaac Sim | |
+-------------------+------------------------------+------------------------------+---------------------------+------------+
| Full Source Build | |:floppy_disk:| source (git) | |:floppy_disk:| source (git) | Developers modifying both | Advanced |
+-------------------+------------------------------+------------------------------+---------------------------+------------+
| Pip Only | |:package:| pip install | |:package:| pip install | External extensions only | Special |
| | | | (no training/examples) | case |
+-------------------+------------------------------+------------------------------+---------------------------+------------+
Next Steps
----------
Once you've reviewed the installation methods, continue with the guide that matches your workflow:
- |:smiley:| :doc:`pip_installation`
- Install Isaac Sim via pip and Isaac Lab from source.
- Best for beginners and most users.
- :doc:`binaries_installation`
- Install Isaac Sim from its binary package (website download).
- Install Isaac Lab from its source code.
- Choose this if you prefer not to use pip for Isaac Sim (for instance, on Ubuntu 20.04).
For details on driver requirements, please see the `Technical Requirements <https://docs.omniverse.nvidia.com/materials-and-rendering/latest/common/technical-requirements.html>`_ guide
- :doc:`source_installation`
* See `Linux Troubleshooting <https://docs.omniverse.nvidia.com/dev-guide/latest/linux-troubleshooting.html>`_ to resolve driver installation issues in linux
* If you are on a new GPU or are experiencing issues with the current drivers, we recommend installing the **latest production branch version** drivers from the `Unix Driver Archive <https://www.nvidia.com/en-us/drivers/unix/>`_ using the ``.run`` installer on Linux.
* NVIDIA driver version ``535.216.01`` or later is recommended when upgrading to **Ubuntu 22.04.5 kernel 6.8.0-48-generic** or later
- Build Isaac Sim from source.
- Install Isaac Lab from its source code.
- Recommended only if you plan to modify Isaac Sim itself.
- :doc:`isaaclab_pip_installation`
Isaac Lab is built on top of the Isaac Sim platform. Therefore, it is required to first install Isaac Sim
before using Isaac Lab.
- Install Isaac Sim and Isaac Lab as pip packages.
- Best for advanced users building **external extensions** with custom runner scripts.
- Note: This does **not** include training or example scripts.
Both Isaac Sim and Isaac Lab provide two ways of installation:
either through binary download/source file, or through Python's package installer ``pip``.
The method of installation may depend on the use case and the level of customization desired from users.
For example, installing Isaac Sim from pip will be a simpler process than installing it from binaries,
but the source code will then only be accessible through the installed source package and not through the direct binary download.
Asset Caching
-------------
Similarly, installing Isaac Lab through pip is only recommended for workflows that use external launch scripts outside of Isaac Lab.
The Isaac Lab pip packages only provide the core framework extensions for Isaac Lab and does not include any of the
standalone training, inferencing, and example scripts. Therefore, this workflow is recommended for projects that are
built as external extensions outside of Isaac Lab, which utilizes user-defined runner scripts.
Isaac Lab assets are hosted on **AWS S3 cloud storage**. Loading times can vary
depending on your **network connection** and **geographical location**, and in some cases,
assets may take several minutes to load for each run. To improve performance or support
**offline workflows**, we recommend enabling **asset caching**.
We recommend using Isaac Sim pip installation for a simplified installation experience.
- Cached assets are stored locally, reducing repeated downloads.
- This is especially useful if you have a slow or intermittent internet connection,
or if your deployment environment is offline.
For users getting started with Isaac Lab, we recommend installing Isaac Lab by cloning the repo.
Please follow the steps :doc:`asset_caching` to enable asset caching and speed up your workflow.
.. toctree::
:maxdepth: 2
:hidden:
Pip installation (recommended) <pip_installation>
Binary installation <binaries_installation>
Advanced installation (Isaac Lab pip) <isaaclab_pip_installation>
Asset caching <asset_caching>
pip_installation
binaries_installation
source_installation
isaaclab_pip_installation
asset_caching
docs/source/setup/installation/isaaclab_pip_installation.rst
View file @ 8b590c1a
......@@ -187,14 +187,17 @@ To run a user-defined script for Isaac Lab, simply run
Generating VS Code Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Due to the structure resulting from the installation, VS Code IntelliSense (code completion, parameter info and member lists, etc.) will not work by default.
To set it up (define the search paths for import resolution, the path to the default Python interpreter, and other settings), for a given workspace folder, run the following command:
Due to the structure resulting from the installation, VS Code IntelliSense (code completion, parameter info
and member lists, etc.) will not work by default. To set it up (define the search paths for import resolution,
the path to the default Python interpreter, and other settings), for a given workspace folder,
run the following command:
.. code-block:: bash
.. code-block:: bash
python -m isaaclab --generate-vscode-settings
python -m isaaclab --generate-vscode-settings
.. warning::
The command will generate a ``.vscode/settings.json`` file in the workspace folder.
If the file already exists, it will be overwritten (a confirmation prompt will be shown first).
.. warning::
The command will generate a ``.vscode/settings.json`` file in the workspace folder.
If the file already exists, it will be overwritten (a confirmation prompt will be shown first).
docs/source/setup/installation/pip_installation.rst
View file @ 8b590c1a
.. _isaaclab-pip-installation:
Installation using Isaac Sim pip
Installation using Isaac Sim Pip
================================
Isaac Lab requires Isaac Sim. This tutorial first installs Isaac Sim from pip, then Isaac Lab from source code.
......@@ -371,7 +371,7 @@ On Windows machines, please terminate the process from Command Prompt using
If you see this, then the installation was successful! |:tada:|
Train a robot!
~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~
You can now use Isaac Lab to train a robot through Reinforcement Learning! The quickest way to use Isaac Lab is through the predefined workflows using one of our **Batteries-included** robot tasks. Execute the following command to quickly train an ant to walk!
We recommend adding ``--headless`` for faster training.
......
docs/source/setup/installation/source_installation.rst 0 → 100644
View file @ 8b590c1a
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment