|
| 1 | +.. _project-structure: |
| 2 | + |
| 3 | + |
| 4 | +Project Structure |
| 5 | +================= |
| 6 | + |
| 7 | +There are four nested structures you need to be aware of when working in the direct workflow with an Isaac Lab template |
| 8 | +project: the **Project**, the **Extension**, the **Modules**, and the **Task**. |
| 9 | + |
| 10 | +.. figure:: ../../_static/setup/walkthrough_project_setup.svg |
| 11 | + :align: center |
| 12 | + :figwidth: 100% |
| 13 | + :alt: The structure of the isaac lab template project. |
| 14 | + |
| 15 | +The **Project** is the root directory of the generated template. It contains the source and scripts directories, as well as |
| 16 | +a ``README.md`` file. When we created the template, we named the project *IsaacLabTutorial* and this defined the root directory |
| 17 | +of a git repository. If you examine the project root with hidden files visible you will see a number of files defining |
| 18 | +the behavior of the project with respect to git. The ``scripts`` directory contains the ``train.py`` and ``play.py`` scripts for the |
| 19 | +various RL libraries you chose when generating the template, while the source directory contains the python packages for the project. |
| 20 | + |
| 21 | +The **Extension** is the name of the python package we installed via pip. By default, the template generates a project |
| 22 | +with a single extension of the same name. A project can have multiple extensions, and so they are kept in a common ``source`` |
| 23 | +directory. Traditional python packages are defined by the presence of a ``pyproject.toml`` file that describes the package |
| 24 | +metadata, but packages using Isaac Lab must also be Isaac Sim extensions and so require a ``config`` directory and an accompanying |
| 25 | +``extension.toml`` file that describes the metadata needed by the Isaac Sim extension manager. Finally, because the template |
| 26 | +is intended to be installed via pip, it needs a ``setup.py`` file to complete the setup procedure using the ``extension.toml`` |
| 27 | +config. A project can have multiple extensions, as evidenced by the Isaac Lab repository itself! |
| 28 | + |
| 29 | +The **Modules** are what actually gets loaded by Isaac Lab to run training (the meat of the code). By default, the template |
| 30 | +generates an extension with a single module that is named the same as the project. The structure of the various sub-modules |
| 31 | +in the extension is what determines the ``entry_point`` for an environment in Isaac Lab. This is why our template project needed |
| 32 | +to be installed before we could call ``train.py``: the path to the necessary components to run the task needed to be exposed |
| 33 | +to python for Isaac Lab to find them. |
| 34 | + |
| 35 | +Finally, the **Task** is the heart of the direct workflow. By default, the template generates a single task with the same name |
| 36 | +as the project. The environment and configuration files are stored here, as well as placeholder, RL library dependent ``agents``. |
| 37 | +Critically, note the contents of the ``__init__.py``! Specifically, the ``gym.register`` function needs to be called at least once |
| 38 | +before an environment and task can be used with the Isaac Lab ``train.py`` and ``play.py`` scripts. |
| 39 | +This function should be included in one of the module ``__init__.py`` files so it is called at installation. The path to |
| 40 | +this init file is what defines the entry point for the task! |
| 41 | + |
| 42 | +For the template, ``gym.register`` is called within ``isaac_lab_tutorial/source/isaac_lab_tutorial/isaac_lab_tutorial/tasks/direct/isaac_lab_tutorial/__init__.py``. |
| 43 | +The repeated name is a consequence of needing default names for the template, but now we can see the structure of the project. |
| 44 | +**Project**/source/**Extension**/**Module**/tasks/direct/**Task**/__init__.py |
0 commit comments