{"id":18621494,"url":"https://github.com/ethz-asl/cvae_exploration_planning","last_synced_at":"2025-11-04T05:03:42.845Z","repository":{"id":38261093,"uuid":"503735089","full_name":"ethz-asl/cvae_exploration_planning","owner":"ethz-asl","description":"Learning informed sampling distributions and information gains for efficient exploration planning.","archived":false,"fork":false,"pushed_at":"2022-11-09T16:05:53.000Z","size":12463,"stargazers_count":40,"open_issues_count":0,"forks_count":9,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-05-03T16:21:31.859Z","etag":null,"topics":["cvae","distribution-learning","exploration","information-gain","informed-distribution","learning","planning","sampling"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethz-asl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-06-15T11:24:10.000Z","updated_at":"2024-03-27T10:58:26.000Z","dependencies_parsed_at":"2023-01-21T22:16:24.274Z","dependency_job_id":null,"html_url":"https://github.com/ethz-asl/cvae_exploration_planning","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethz-asl%2Fcvae_exploration_planning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethz-asl%2Fcvae_exploration_planning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethz-asl%2Fcvae_exploration_planning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethz-asl%2Fcvae_exploration_planning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethz-asl","download_url":"https://codeload.github.com/ethz-asl/cvae_exploration_planning/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223455090,"owners_count":17147848,"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","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":["cvae","distribution-learning","exploration","information-gain","informed-distribution","learning","planning","sampling"],"created_at":"2024-11-07T04:12:01.932Z","updated_at":"2025-11-04T05:03:42.770Z","avatar_url":"https://github.com/ethz-asl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cvae_exploration_planning\n**CVAE Exploration Planning** proposes a new approach to local exploration planning by combining learning and the sampling-based planning paradigm! This package provides an open-source implementation of the simulator, datasets, models, and planners presented in our paper on learning sampling-based local exploration.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"100%\" src=\"https://user-images.githubusercontent.com/36043993/176672800-24e26425-ae9b-4df9-98f3-70b71d3cd2c7.gif\"\u003e\n\u003c/p\u003e\n\n# Table of Contents\n**Credits**\n* [Paper and Video](#Paper-and-Video)\n\n**Setup**\n* [Dependencies](#Dependencies)\n* [Installation](#Installation)\n* [Data Repository](#Data-Repository)\n\n**Examples**\n* [Training the CVAE Model](#Training-the-CVAE-Model)\n* [Training the CNN Model](#Training-the-CNN-Model)\n* [Evaluating a Planner](#Evaluating-a-Planner)\n* [Using the simulator](#Using-the-simulator)\n\n**Additional Information**\n* [Project Overview](#Project-Overview)\n\n\n# Credits\n## Paper and Video\nIf you find this package useful for your research, please consider citing our paper:\n\n* Lukas Schmid, Chao Ni, Yuliang Zhong, Roland Siegwart, and Olov Andersson, \"**Fast and Compute-efficient Sampling-based Local Exploration Planning via Distribution Learning**\", in *IEEE Robotics and Automation Letters*, vol. 7, no. 3, pp. 7810-7817, July 2022 [ [IEEE](https://ieeexplore.ieee.org/document/9807401) | [ArXiv](https://arxiv.org/abs/2202.13715) | [Video](https://www.youtube.com/watch?v=Hj5yI8VtlXk) | [Project Page](https://chaofiber.github.io/cvae_exploration_planning/) ]\n  ```bibtex\n  @ARTICLE{Schmid22Fast,\n    title={Fast and Compute-efficient Sampling-based Local Exploration Planning via Distribution Learning},\n    author={L. {Schmid} and C. {Ni} and Y. {Zhong} and and R. {Siegwart} and O. {Andersson}},\n    journal={IEEE Robotics and Automation Letters},\n    year={2022},\n    volume={7},\n    number={3},\n    pages={7810-7817},\n    doi={10.1109/LRA.2022.3186511}}\n  }\n  ```\n  \nFor a short overview of our approach check out our video on youtube:\n\n[\u003cimg src=\"https://user-images.githubusercontent.com/36043993/191530807-1432b5c9-318a-4028-aedf-2b9cd5c82322.png\" alt=\"youtube video\"\u003e](https://www.youtube.com/watch?v=Hj5yI8VtlXk)\n  \n# Setup\nWe recommend using a virtual environment to run this project. We provide setup instructions using [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html) on Ubuntu.\n\n**Note on versioning:** This repository was developed and tested using `Ubuntu 20.04` with `Python 3.8` and `Torch 1.7`. Other versions should also work.\n\n## Dependencies\n\n* Install [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html) and setup a virtual environment: \n  ```bash \n  conda create --name cvae \n  conda activate cvae\n  ```\n\n* Use conda to install [PyTorch](https://pytorch.org/) for your [cuda version](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html): \n  ```bash\n  export MY_CUDA_VERSION='11.6' # Replace with your version. \n  conda install pytorch torchvision torchaudio cudatoolkit=$MY_CUDA_VERSION -c pytorch\n  ```\n\n* Install other dependencies: \n  ```bash\n  pip install -r requirements.txt\n  ```\n\n## Installation\n\n* Setup the destination where to isntall the project:\n  ```bash\n  export MY_CVAE_ROOT='/home/$USER/cvae_exploration_workspace' # Replace with your path.\n  makedir -p $MY_CVAE_ROOT\n  cd $MY_CVAE_ROOT\n  ```\n\n* Download the repository, we recommend using [SSH Keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#about-ssh-key-generation) or alternatively via HTTPS:\n  ```bash\n  git clone git@github.com:ethz-asl/cvae_exploration_planning.git # SSH\n  git clone https://github.com/ethz-asl/cvae_exploration_planning.git # HTTPS\n  cd cvae_exploration_planning\n  ```\n\n* Add the project folder to your python path:\n  ```bash\n  export PYTHONPATH=\"${MY_CVAE_ROOT}/:${PYTHONPATH}\"\n  ```\n\n* You are now ready to go!\n\n## Data Repository\n\nAll our data is available on the [ETHZ ASL Dataserver](https://projects.asl.ethz.ch/datasets/doku.php?id=cvae_exploration_planning).\nYou can download all files needed to train and run our models and planners easily:\n* Setup a data folder (this path is used by default):\n  ```\n  cd $MY_CVAE_ROOT/cvae_exploration_planning\n  mkdir data\n  ```\n* Download the data used to train the CVAE models: \n  ```\n  wget http://robotics.ethz.ch/~asl-datasets/2022_CVAE_Exploration_Planning/CVAE_dataset.npy -P data\n  ```\n* Download the data used to train the CNN models: \n  ```\n  wget http://robotics.ethz.ch/~asl-datasets/2022_CVAE_Exploration_Planning/CNN_dataset.npy -P data\n  ```\n* Download the worlds used in our experiments: \n  ```\n  wget http://robotics.ethz.ch/~asl-datasets/2022_CVAE_Exploration_Planning/test_worlds.zip\n  unzip -j test_worlds.zip -d experiments/worlds\n  rm test_worlds.zip\n  ```\n\n# Examples\n\n## Training the CVAE model\nTo train the original CVAE model, make sure you [downloaded the CVAE dataset](Data-Repository), then run:\n\n```\ncd learning \npython train_cvae.py\n```\n\nThe model will start training, and periodically save the intermediate model in `learning/policies/\u003cstart_time\u003e` and training information in `learning/runs/\u003cstart_time\u003e`.\n\nSee `learning/config_cvae.yaml` for tunable parameters. For example, to jointly train the gain estimator (+GJ in the paper), set `x_dim` to 4 and the last dimension of the network output will be the predicted gain. \n\n## Training the CNN model\n\nTo train the CNN based gain estimator of the two-stage model, make sure you [downloaded the CNN dataset](Data-Repository), then run:\n```\ncd learning \npython train_cnn.py \n```\n\nThe model will start training and write intermediate and final models as well as a performance evaluation to `learning/runs/\u003cstart_time\u003e`.\n\nSee `learning/config_cnn.yaml` for tunable parameters.\n\n## Evaluating a Planner\nWe provide a script to run and evaluate any planner. First, set the worlds, planners, numbers of runs, numbers of sampels, and other experiment details in `experiments/config.yaml`. Then conduct the experiments by running:\n\n```\ncd experiments\npython evaluate.py\n```\n\nThis will run the planners in the simulator for all specified experiments and store the results in `epxeriments/results/\u003cstart_time\u003e`. Afterwards the stored data is evaluated and exploration progress curves are plotted.\n\n![Example_performance](https://user-images.githubusercontent.com/36043993/176662115-fb589d43-242c-4712-8308-962a0d98dae2.png)\n\nExample performance on the demo_maze for N=5.\n\n\n## Using the simulator\nThe simulator used to generate data and evaluate the approaches is a fully functional 2D exploration simulator. We provide a demo showcasing how some of the main features of the simulator can be used and visualized. Start the demo by running:\n\n```\ncd simulator\npython demo.py\n```\n\nThe demo will first display the complete randomly generated world and start pose. Then enter '1' in the terminal to let the robot explore the simulated world using a bseline planner. If it gets stuck in a local minimum a global planner will reset it.\n\n![Simulator](https://user-images.githubusercontent.com/36043993/176603370-3dd3727d-7f65-4e35-80ba-f8419fd58516.png)\n\nRandomly generated world (left) and robot moving around (right, orange to red pose arrows).\n\nTo generate different world files for experiments, run the world explorer:\n```\ncd experiments\npython explore_worlds.py\n```\n\n# Additional Information\n## Project Overview\nThe files in this repository are structured as follows:\n\n```bash\n├── data  # ---------------- # Local directory for training data.\n│   ├── CNN_dataset.npy      # Provided downloadable data.\n│   └── CVAE_dataset.npy\n├── experiments  # --------- # Package to run experiments.\n│   ├── config.yaml          # Which experiments to run.\n│   ├── evaluate.py          # Run and evaluate planners.\n│   ├── explore_worlds.py    # Interactively create new world files.\n│   ├── models               # Provided pre-trained models.\n│   ├── results              # Local directory for experiment outputs.\n│   └── worlds               # Local directory to store wo\n├── learning  # ------------ # Package to define and train models.\n│   ├── config_cnn.yaml      # Configurations to train CVAE/CNN models.\n│   ├── config_cvae.yaml\n│   ├── data.py              # Data processing tools.\n│   ├── model.py             # Network model definitions.\n│   ├── runs                 # Local directory for training output.\n│   ├── train_cnn.py         # Scripts to train the CVAE/CNN models.\n│   ├── train_cvae.py\n│   └── util.py              # Utility tools for networks.\n├── planning  # ------------ # Package that contains all planners.\n│   ├── baseline_nbvp.py     # Python implementation of RH-NBVP.\n│   ├── baseline_planner.py  # Uniform sampling-based local planner.\n│   ├── global_planner.py    # Frontier-based global planner.\n│   ├── policy_planner.py    # Local planners using our models.\n│   └── rrt_star.py          # RRT* for global path verification.\n└── simulator  # ----------- # Package that contains the simulator.\n    ├── config.py            # Config definition for entire simulator.\n    ├── demo.py              # Example on how to use some interfaces.\n    ├── robot.py             # Code for capabilities of the robot.\n    ├── simulator.py         # Main interface combining all components.\n    └── world.py             # Procedural world generation.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethz-asl%2Fcvae_exploration_planning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethz-asl%2Fcvae_exploration_planning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethz-asl%2Fcvae_exploration_planning/lists"}