This repository serves as a template for building projects or extensions based on Orbit. It allows you to develop in an isolated environment, outside of the core Orbit repository. Furthermore, this template serves three use cases:
-
Python Package Can be installed into Isaac Sim's Python environment, making it suitable for users who want to integrate their extension to
Orbit
as a python package. -
Project Template Ensures access to
Isaac Sim
andOrbit
functionalities, which can be used as a project template. -
Omniverse Extension Can be used as an Omniverse extension, ideal for projects that leverage the Omniverse platform's graphical user interface.
Key Features:
Isolation
Work outside the core Orbit repository, ensuring that your development efforts remain self-contained.Flexibility
This template is set up to allow your code to be run as an extension in Omniverse.
Keywords: extension, template, orbit
The source code is released under a BSD 3-Clause license.
Author: The ORBIT Project Developers
Affiliation: The AI Institute
Maintainer: Nico Burger, nburger@theaiinstitute.com
Depending on the use case defined above, follow the instructions to set up your extension template. Start with the Basic Setup, which is required for either use case.
This template depends on Isaac Sim and Orbit. For detailed instructions on how to install these dependencies, please refer to the installation guide.
Decide on a name for your project or extension. This guide will refer to this name as <your_extension_name>
.
-
Create a new repository based off this template here. Name your forked repository using the following convention:
"orbit.<your_extension_name>"
. -
Clone your forked repository to a location outside the orbit repository.
git clone <your_repository_url>
-
To tailor this template to your needs, customize the settings in
config/extension.toml
andsetup.py
by completing the sections marked with TODO. -
Rename your source folder.
cd orbit.<your_extension_name>
mv orbit/ext_template orbit/<your_extension_name>
- Define the following environment variable to specify the path to your Orbit installation:
# Set the ORBIT_PATH environment variable to point to your Orbit installation directory
export ORBIT_PATH=<your_orbit_path>
Although using a virtual environment is optional, we recommend using conda
(detailed instructions here). If you decide on using Isaac Sim's bundled Python, you can skip these steps.
- If you haven't already: create and activate your
conda
environment, followed by installing extensions inside Orbit:
# Create conda environment
${ORBIT_PATH}/orbit.sh --conda
# Activate conda environment
conda activate orbit
# Install all Orbit extensions in orbit/source/extensions
${ORBIT_PATH}/orbit.sh --install
- Set your
conda
environment as the default interpreter in VSCode by opening the command palette (Ctrl+Shift+P
), choosingPython: Select Interpreter
and selecting yourconda
environment.
Once you are in the virtual environment, you do not need to use ${ORBIT_PATH}/orbit.sh -p
to run python scripts. You can use the default python executable in your environment by running python
or python3
. However, for the rest of the documentation, we will assume that you are using ${ORBIT_PATH}/orbit.sh -p
to run python scripts.
To setup the IDE, please follow these instructions:
- Open the
orbit.<your_extension_template>
directory on Visual Studio Code IDE - Run VSCode Tasks, by pressing
Ctrl+Shift+P
, selectingTasks: Run Task
and running thesetup_python_env
in the drop down menu. When running this task, you will be prompted to add the absolute path to your Orbit installation.
If everything executes correctly, it should create a file .python.env in the .vscode directory. The file contains the python paths to all the extensions provided by Isaac Sim and Omniverse. This helps in indexing all the python modules for intelligent suggestions while writing code.
From within this repository, install your extension as a Python package to the Isaac Sim Python executable.
${ORBIT_PATH}/orbit.sh -p -m pip install --upgrade pip
${ORBIT_PATH}/orbit.sh -p -m pip install -e .
To enable your extension, follow these steps:
-
Add the search path of your repository to the extension manager:
- Navigate to the extension manager using
Window
->Extensions
. - Click on the Hamburger Icon (☰), then go to
Settings
. - In the
Extension Search Paths
, enter the path that goes up to your repository's location without actually including the repository's own directory. For example, if your repository is located at/home/code/orbit.ext_template
, you should add/home/code
as the search path. - If not already present, in the
Extension Search Paths
, enter the path that leads to your local Orbit directory. For example:/home/orbit/source/extensions
- Click on the Hamburger Icon (☰), then click
Refresh
.
- Navigate to the extension manager using
-
Search and enable your extension:
- Find your extension under the
Third Party
category. - Toggle it to enable your extension.
- Find your extension under the
Import your python package within Isaac Sim
and Orbit
using:
import orbit.<your_extension_name>
We provide an example for training and playing a policy for ANYmal on flat terrain. Install RSL_RL outside of the orbit repository, e.g. home/code/rsl_rl
.
git clone https://github.com/leggedrobotics/rsl_rl.git
cd rsl_rl
${ORBIT_PATH}/orbit.sh -p -m pip install -e .
Train a policy.
cd <path_to_your_extension>
${ORBIT_PATH}/orbit.sh -p scripts/rsl_rl/train.py --task Template-Velocity-Flat-Anymal-D-v0 --num_envs 4096 --headless
Play the trained policy.
${ORBIT_PATH}/orbit.sh -p scripts/rsl_rl/play.py --task Template-Velocity-Flat-Anymal-D-Play-v0 --num_envs 16
We provide an example UI extension that will load upon enabling your extension defined in orbit/ext_template/ui_extension_example.py
. For more information on UI extensions, enable and check out the source code of the omni.isaac.ui_template
extension and refer to the introduction on Isaac Sim Workflows 1.2.3. GUI.
Pre-committing involves using a framework to automate the process of enforcing code quality standards before code is actually committed to a version control system, like Git. This process involves setting up hooks that run automated checks, such as code formatting, linting (checking for programming errors, bugs, stylistic errors, and suspicious constructs), and running tests. If these checks pass, the commit is allowed; if not, the commit is blocked until the issues are resolved. This ensures that all code committed to the repository adheres to the defined quality standards, leading to a cleaner, more maintainable codebase. To do so, we use the pre-commit module. Install the module using:
pip install pre-commit
Run the pre-commit with:
pre-commit run --all-files
You are all set and no longer need the template instructions
-
The
orbit/ext_template
andscripts/rsl_rl
directories act as a reference template for your convenience. Delete them if no longer required. -
When ready, use this
README.md
as a template and customize where appropriate.
We are currently working on a docker and cluster setup for this template. In the meanwhile, please refer to the current setup provided in the Orbit documentation.
When running within a docker container, the following error has been encountered: ModuleNotFoundError: No module named 'orbit'
. To mitigate, please comment out the docker specific environment definitions in .vscode/launch.json
and run the following:
echo -e "\nexport PYTHONPATH=\$PYTHONPATH:/workspace/orbit.<your_extension_name>" >> ~/.bashrc
source ~/.bashrc
Please report bugs and request features using the Issue Tracker.