{"id":30110326,"url":"https://github.com/leggedrobotics/nav-suite","last_synced_at":"2025-08-12T06:02:50.231Z","repository":{"id":308521064,"uuid":"1032642307","full_name":"leggedrobotics/nav-suite","owner":"leggedrobotics","description":"Navigation Suite for IsaacLab","archived":false,"fork":false,"pushed_at":"2025-08-06T12:01:28.000Z","size":10554,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-06T12:11:21.385Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leggedrobotics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-05T15:49:16.000Z","updated_at":"2025-08-06T10:20:26.000Z","dependencies_parsed_at":"2025-08-06T12:21:30.933Z","dependency_job_id":null,"html_url":"https://github.com/leggedrobotics/nav-suite","commit_stats":null,"previous_names":["leggedrobotics/nav-suite"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/leggedrobotics/nav-suite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggedrobotics%2Fnav-suite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggedrobotics%2Fnav-suite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggedrobotics%2Fnav-suite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggedrobotics%2Fnav-suite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leggedrobotics","download_url":"https://codeload.github.com/leggedrobotics/nav-suite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggedrobotics%2Fnav-suite/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269677518,"owners_count":24457858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-10T04:44:32.908Z","updated_at":"2025-08-10T04:44:37.877Z","avatar_url":"https://github.com/leggedrobotics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Isaac Navigation Suite\n\n[![IsaacSim](https://img.shields.io/badge/IsaacSim-4.5.0-silver.svg)](https://docs.omniverse.nvidia.com/isaacsim/latest/overview.html)\n[![Isaac Lab](https://img.shields.io/badge/IsaacLab-2.1.1-silver)](https://isaac-sim.github.io/IsaacLab)\n[![Python](https://img.shields.io/badge/python-3.10-blue.svg)](https://docs.python.org/3/whatsnew/3.10.html)\n[![Linux platform](https://img.shields.io/badge/platform-linux--64-orange.svg)](https://releases.ubuntu.com/24.04/)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)](https://pre-commit.com/)\n[![License](https://img.shields.io/badge/license-Apache--2.0-yellow.svg)](https://opensource.org/license/apache-2-0)\n\n\n\u003ctable style=\"border-collapse:collapse;border:none;width:100%;\"\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"text-align:center;border:none;\"\u003e\n      \u003cstrong\u003eData Generation\u003c/strong\u003e\u003cbr/\u003e\n      \u003cimg src=\"docs/source/_static/overview/data_gen.png\" alt=\"Data Generation\" width=\"250\"/\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"text-align:center;border:none;\"\u003e\n      \u003cstrong\u003eTraversability Analysis\u003c/strong\u003e\u003cbr/\u003e\n      \u003cimg src=\"docs/source/_static/overview/trav_analysis.png\" alt=\"Traversability Analysis\" width=\"250\"/\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"text-align:center;border:none;\"\u003e\n      \u003cstrong\u003ePolicy Learning\u003c/strong\u003e\u003cbr/\u003e\n      \u003cimg src=\"docs/source/_static/overview/policy_learning.png\" alt=\"Policy Learning\" width=\"250\"/\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\n**Isaac Navigation Suite** is a framework for robotic navigation task. It is meant to unify navigation-relevant environments,\ndata-sampling approaches, typical RL terms and a benchmarking environment. Currently, the suite includes two extensions:\n\n## Table of Contents\n- [nav_suite Extension](#nav_suite-extension)\n- [nav_tasks Extension](#nav_tasks-extension)\n- [Installation](#installation)\n- [Usage and Examples](#usage)\n- [Citing](#citing)\n- [License](#license)\n- [Support](#support)\n\n\n## `nav_suite` Extension\n\nThis extension lets you load realistic terrains complete with rich semantic annotations, run fast traversability analysis, and render large batches of multi-modal data. It exposes three core modules:\n\n  - **Environment Importer** – load Matterport, Unreal/Carla, generated or USD terrains and expose all geometric / semantic domains\u0026nbsp;→ [Details](exts/nav_suite/docs/README.md#environment-importer)\n  - **Data Collectors** – sample trajectories, viewpoints and render multi-modal data from any imported world\u0026nbsp;→ [Details](exts/nav_suite/docs/README.md#data-collectors)\n  - **Terrain Analysis** – build traversability height-maps and graphs for path planning and curriculum tasks\u0026nbsp;→ [Details](exts/nav_suite/docs/README.md#traversabilty-analysis)\n\n## `nav_tasks` Extension\n\nThis extension provides a comprehensive library of reusable MDP terms—usable in reinforcement-learning pipelines and in unsupervised or supervised navigation objectives—and ships with an example PPO training setup.\n\n\n### MDP Components\n\n#### Goal Commands\n\n- **GoalCommand:** Samples goal positions using terrain analysis, ensuring feasibility and diversity.\n- **ConsecutiveGoalCommand:** Generates a sequence of terrain-aware goals, resampling as each is reached.\n- **FixGoalCommand:** Provides fixed goal positions.\n\n#### Reward Terms\n\n- **near_goal_stability:** Rewards stability and low velocity near the goal.\n- **near_goal_angle:** Rewards correct heading at the goal.\n- **backwards_movement / lateral_movement:** Encourage or penalize specific movement directions.\n- **SteppedProgressTerm:** Discrete reward for progress toward the goal.\n- **AverageEpisodeVelocityTerm:** Rewards average velocity upon reaching the goal.\n\n#### Terminations \u0026 Events\n\n- **At Goal:** Ends episode when the agent reaches the goal.\n- **Timeouts:** Proportional to goal distance.\n- **StayedAtGoal:** Ensures the agent remains at the goal for a set time.\n- **Reset Events:** Use terrain analysis to place the robot at feasible spawn points.\n\n### Example RL Training\n\nTo start training a example navigation policy, use:\n\n```bash\npython -m isaaclab.train --task NavTasks-DepthImgNavigation-PPO-Anymal-D-TRAIN\n```\n\n**Demo Recording**\n\nVisualizations of the trained policy in action with an example reward curve for the policy trained in rough terrain:\n\n\u003cdiv style=\"display: flex; justify-content: space-between;\"\u003e\n    \u003cimg src=\"exts/nav_tasks/docs/videos/rl-video-step-16000.gif\" width=\"32%\"/\u003e\n    \u003cimg src=\"exts/nav_tasks/docs/videos/rl-video-step-32000.gif\" width=\"32%\"/\u003e\n    \u003cimg src=\"exts/nav_tasks/docs/figures/wandb_example_training_mean_reward.png\" width=\"32%\"/\u003e\n\u003c/div\u003e\n\n\n## Installation\n\n1. Install IsaacLab following the [IsaacLab installation guide](https://isaac-sim.github.io/IsaacLab/main/source/setup/installation/index.html).\n2. Clone this repo and install the extensions. Note that the nav_suite has been tested with ``IsaacLab v2.1.1``  (last checked commit 19b24c7). We try to be in sync with the latest IsaacLab version, but minor issues can occur. \\\n  NOTE: Please use an IsaacLab version where [PR77](https://github.com/leggedrobotics/IsaacLab-Internal/pull/77) have been merged, they contain changes necessary to run the scripts successfully.\n\n```bash\ngit clone git@github.com:isaac-sim/IsaacLab.git\ngit clone git@github.com:leggedrobotics/isaac-nav-suite.git\ncd \u003cpath-to-your-isaaclab-repo\u003e\ngit checkout v2.1.1\n\n./isaaclab.sh -p -m pip install -e \u003cpath-to-your-nav-suite-repo\u003e/exts/nav_suite\n./isaaclab.sh -p -m pip install -e \u003cpath-to-your-nav-suite-repo\u003e/exts/nav_tasks\n```\n\n3. Some files of the ``nav_suite`` are located on git lfs (such as policies or terrains). Please install git lfs following the [Installation Guide](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage) and then pull the files.\n\n```bash\ncd \u003cpath-to-your-nav-suite-repo\u003e\ngit lfs pull\n```\n\n\n### Docker and Cluster Installation\n\n1. Get the IsaacLab docker, following the description [Docker Guide](https://isaac-sim.github.io/IsaacLab/source/deployment/docker.html).\n2. Add the nav-suite as a submodule to the IsaacLab repo.\n\n  ```bash\n  cd \u003cpath-to-your-isaaclab-repo\u003e\n  git submodule add git@github.com:leggedrobotics/isaac-nav-suite.git\n  git submodule update --init --recursive\n  ```\n\n3. Create symlinks to the extensions. Make sure that these are relative in order to be included in the docker image.\n\n  ```bash\n  cd \u003cpath-to-your-isaaclab-repo\u003e/source\n  ln -s ../../isaac-nav-suite/exts/nav_suite .\n  ln -s ../../isaac-nav-suite/exts/nav_tasks .\n  ```\n\n4. Bin the extension into your docker container to reflect changes inside the docker on your host. To do so add the\n   following lines to the `docker/docker-compose.yaml` file:\n\n    ```yaml\n    - type: bind\n      source: ../isaac-nav-suite\n      target: ${DOCKER_ISAACLAB_PATH}/isaac-nav-suite\n    ```\n\n4. Rebuild your docker image to install the additional extensions and let the bind take effect.\n\n  ```bash\n  cd \u003cpath-to-your-isaaclab-repo\u003e\n  ./docker/container.py start\n  ```\n\n## Usage\n\n### Download Example Environments\n\nThe suite comes with some example environments. Carla that can be downloaded using the following link [Carla (Unreal Engine)](https://drive.google.com/file/d/1vOf1Fp6CGtBdLWZ2Q3r0tkYQLQHM7Y0A/view?usp=sharing). To download Matterport datasets, please refer to the [Matterport3D](https://niessner.github.io/Matterport/) website.\nThe NVIDIA Warehouse environment is already included in the repo.\n\nThe downloaded environments should be extracted to\n`\u003cpath-to-your-nav-suite-repo\u003e/exts/nav_suite/data/[matterport, unreal/town01]`. The paths in the scripts are\nalready set to these directories.\n\n\n### Workflow\n\nStandalone scripts can be used to customize the functionalities and easily integrate different parts of the extensions for your own projects.\nHere we provide a set of examples that demonstrate how to use the different parts:\n\n- ``nav_suite``\n  -  ``importer``\n      - [Import a Matterport3D Environment](scripts/nav_suite/terrains/matterport_import.py)\n      - [Import a Carla (Unreal Engine) Environment](scripts/nav_suite/terrains/carla_import.py)\n      - [Import the Nvidia Warehouse Environment](scripts/nav_suite/terrains/warehouse_import.py)\n  - ``collector``\n      - [Sample Trajectories from Matterport](scripts/nav_suite/collector/matterport_trajectory_sampling.py)\n      - [Sample Viewpoints and Render Images from Carla (Unreal Engine)](scripts/nav_suite/collector/carla_viewpoint_sampling.py)\n\n## Citing\n\nThe current version was developed as part of the ViPlanner ([Paper](https://arxiv.org/abs/2310.00982) | [Code](https://github.com/leggedrobotics/viplanner)) and perceptive forward dynamcis model ([Paper](https://arxiv.org/abs/2504.19322) | [Webpage](https://leggedrobotics.github.io/fdm.github.io/)).\n\nWe are currently preparaing a workshop paper submission. Up to that point, if you use this code in a scientific\npublication, please cite the following [paper](https://arxiv.org/abs/2310.00982) if you use the Matterport related implementations:\n```\n@article{roth2023viplanner,\n  title     ={ViPlanner: Visual Semantic Imperative Learning for Local Navigation},\n  author    ={Pascal Roth and Julian Nubert and Fan Yang and Mayank Mittal and Marco Hutter},\n  journal   = {2024 IEEE International Conference on Robotics and Automation (ICRA)},\n  year      = {2023},\n  month     = {May},\n}\n```\n\nor [paper](https://arxiv.org/abs/2504.19322) for the rest of the code:\n\n```\n@inproceedings{roth2025fdm,\n  title={Learned Perceptive Forward Dynamics Model for Safe and Platform-aware Robotic Navigation},\n  author={Roth, Pascal and Frey, Jonas and Cadena, Cesar and Hutter, Marco},\n  booktitle={Robotics: Science and Systems (RSS 2025)},\n  year={2025}\n}\n```\n\n## License\n\nThe repository is released under [Apache 2.0](LICENSE). The license files of its dependencies and assets are present in the [`docs/licenses`](docs/licenses) directory.\n\n\n## Support\nThis repository contains research code, except that it changes often, and any fitness for a particular purpose is disclaimed.\n\n* Please use GitHub [Discussions](https://github.com/leggedrobotics/nav-suite/discussions) for discussing ideas, asking questions, and requests for new features.\n* Github [Issues](https://github.com/leggedrobotics/nav-suite/issues) should only be used to track executable pieces of work with a definite scope and a clear deliverable. These can be fixing bugs, documentation issues, new features, or general updates.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleggedrobotics%2Fnav-suite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleggedrobotics%2Fnav-suite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleggedrobotics%2Fnav-suite/lists"}