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.
Credits
Setup
Examples
Additional Information
If you find this package useful for your research, please consider citing our paper:
- 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 | ArXiv | Video | Project Page ]
@ARTICLE{Schmid22Fast, title={Fast and Compute-efficient Sampling-based Local Exploration Planning via Distribution Learning}, author={L. {Schmid} and C. {Ni} and Y. {Zhong} and and R. {Siegwart} and O. {Andersson}}, journal={IEEE Robotics and Automation Letters}, year={2022}, volume={7}, number={3}, pages={7810-7817}, doi={10.1109/LRA.2022.3186511}} }
For a short overview of our approach check out our video on youtube:
We recommend using a virtual environment to run this project. We provide setup instructions using conda on Ubuntu.
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.
-
Install conda and setup a virtual environment:
conda create --name cvae conda activate cvae
-
Use conda to install PyTorch for your cuda version:
export MY_CUDA_VERSION='11.6' # Replace with your version. conda install pytorch torchvision torchaudio cudatoolkit=$MY_CUDA_VERSION -c pytorch
-
Install other dependencies:
pip install -r requirements.txt
-
Setup the destination where to isntall the project:
export MY_CVAE_ROOT='/home/$USER/cvae_exploration_workspace' # Replace with your path. makedir -p $MY_CVAE_ROOT cd $MY_CVAE_ROOT
-
Download the repository, we recommend using SSH Keys or alternatively via HTTPS:
git clone [email protected]:ethz-asl/cvae_exploration_planning.git # SSH git clone https://github.com/ethz-asl/cvae_exploration_planning.git # HTTPS cd cvae_exploration_planning
-
Add the project folder to your python path:
export PYTHONPATH="${MY_CVAE_ROOT}/:${PYTHONPATH}"
-
You are now ready to go!
All our data is available on the ETHZ ASL Dataserver. You can download all files needed to train and run our models and planners easily:
- Setup a data folder (this path is used by default):
cd $MY_CVAE_ROOT/cvae_exploration_planning mkdir data - Download the data used to train the CVAE models:
wget http://robotics.ethz.ch/~asl-datasets/2022_CVAE_Exploration_Planning/CVAE_dataset.npy -P data - Download the data used to train the CNN models:
wget http://robotics.ethz.ch/~asl-datasets/2022_CVAE_Exploration_Planning/CNN_dataset.npy -P data - Download the worlds used in our experiments:
wget http://robotics.ethz.ch/~asl-datasets/2022_CVAE_Exploration_Planning/test_worlds.zip unzip -j test_worlds.zip -d experiments/worlds rm test_worlds.zip
To train the original CVAE model, make sure you downloaded the CVAE dataset, then run:
cd learning
python train_cvae.py
The model will start training, and periodically save the intermediate model in learning/policies/<start_time> and training information in learning/runs/<start_time>.
See 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.
To train the CNN based gain estimator of the two-stage model, make sure you downloaded the CNN dataset, then run:
cd learning
python train_cnn.py
The model will start training and write intermediate and final models as well as a performance evaluation to learning/runs/<start_time>.
See learning/config_cnn.yaml for tunable parameters.
We 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:
cd experiments
python evaluate.py
This will run the planners in the simulator for all specified experiments and store the results in epxeriments/results/<start_time>. Afterwards the stored data is evaluated and exploration progress curves are plotted.
Example performance on the demo_maze for N=5.
The 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:
cd simulator
python demo.py
The 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.
Randomly generated world (left) and robot moving around (right, orange to red pose arrows).
To generate different world files for experiments, run the world explorer:
cd experiments
python explore_worlds.py
The files in this repository are structured as follows:
├── data # ---------------- # Local directory for training data.
│ ├── CNN_dataset.npy # Provided downloadable data.
│ └── CVAE_dataset.npy
├── experiments # --------- # Package to run experiments.
│ ├── config.yaml # Which experiments to run.
│ ├── evaluate.py # Run and evaluate planners.
│ ├── explore_worlds.py # Interactively create new world files.
│ ├── models # Provided pre-trained models.
│ ├── results # Local directory for experiment outputs.
│ └── worlds # Local directory to store wo
├── learning # ------------ # Package to define and train models.
│ ├── config_cnn.yaml # Configurations to train CVAE/CNN models.
│ ├── config_cvae.yaml
│ ├── data.py # Data processing tools.
│ ├── model.py # Network model definitions.
│ ├── runs # Local directory for training output.
│ ├── train_cnn.py # Scripts to train the CVAE/CNN models.
│ ├── train_cvae.py
│ └── util.py # Utility tools for networks.
├── planning # ------------ # Package that contains all planners.
│ ├── baseline_nbvp.py # Python implementation of RH-NBVP.
│ ├── baseline_planner.py # Uniform sampling-based local planner.
│ ├── global_planner.py # Frontier-based global planner.
│ ├── policy_planner.py # Local planners using our models.
│ └── rrt_star.py # RRT* for global path verification.
└── simulator # ----------- # Package that contains the simulator.
├── config.py # Config definition for entire simulator.
├── demo.py # Example on how to use some interfaces.
├── robot.py # Code for capabilities of the robot.
├── simulator.py # Main interface combining all components.
└── world.py # Procedural world generation.