Update README.md

README.md

@@ -3,6 +3,69 @@
 
 The `MSCKF_VIO` package is a stereo version of MSCKF. The software takes in synchronized stereo images and IMU messages and generates real-time 6DOF pose estimation of the IMU frame.
 
+## Original repository
+This repository is a modified version of [`MSCKF_VIO`](https://github.com/KumarRobotics/msckf_vio). We facilitate the installation process and the use of Docker.
+
+## Docker support
+
+In order to facilitate the installation process, the system is wrapped up using Docker.
+We provide scripts to create a Docker image, build the system and run it in a Docker container. 
+
+### Dependencies 
+* Docker
+* ROS
+* [`pose_listener`](https://github.com/CIFASIS/pose_listener) (if you use `run_rosario_sequence.sh`, see below)
+
+### Building the system
+Run:
+```
+./run.sh -b
+```
+
+This command creates a Docker image, installs all the dependencies and builds the system. The resulting image contains a version of the system ready to be run.
+
+### Running the system in VIS mode
+If you are not interested in making changes in the source code, you should run the system in VIS mode. Run:
+```
+./run.sh -v
+```
+The system is launched in a Docker container based on the previously built image. By default, this command executes a launch file which is configured to run the Rosario dataset. If you want to run your own dataset, **write a launch file and placed it in the `launch/` folder**. Configuration files must be placed in the `config/` folder. Then, run the script with the option `-l <LAUNCH_FILE_NAME>`. For example, if you are testing EuRoC, write `euroc_dataset.launch`, move it into `launch/` and type:
+```
+./run.sh -v -l euroc_dataset.launch
+```
+Making changes in launch/configuration files in the host is possible because these folders are mounted into the Docker container. It is not necessary to access the container through a bash shell to modify these files.
+
+See below for information about input data and visualization.
+
+### Running the system in DEV mode
+DEV mode allows developers to make changes in the source code, recompile the system and run it with the modifications. To do this, the whole repository is mounted in a container. Run:
+```
+./run.sh -d
+```
+This opens a bash shell in a docker container. You can edit source files in the host and after that you can use this shell to recompile the system. When the compilation process finishes, you can run the method using `roslaunch`.
+
+See below for information about input data and visualization.
+
+### Input data and visualization
+
+At this point, the system is waiting for input data. Either you can run `rosbag play` or you can use `run_rosario_sequence.sh`.
+If you choose the latter, open a second terminal and run:
+```
+./run_rosario_sequence.sh -o <OUTPUT_TRAJECTORY_FILE> <ROSBAG_FILE>
+```
+In contrast to what `run.sh` does, `run_rosario_sequence.sh` executes commands in the host (you can modify it to use a Docker container). 
+
+`ROSBAG_FILE` is played using `rosbag`. Also, make sure you have cloned and built `pose_listener` in your catkin workspace. Default path for the workspace is `${HOME}/catkin_ws`, set `CATKIN_WS_DIR` if the workspace is somewhere else (e.g.: `export CATKIN_WS_DIR=$HOME/foo_catkin_ws`). `pose_listener` saves the estimated trajectory in `<OUTPUT_TRAJECTORY_FILE>` (use absolute path). You can edit `run_rosario_sequence.sh` if you prefer to save the trajectory using your own methods. Additionally, `run_rosario_sequence.sh` launches `rviz` to display visual information during the execution of the system.
+
+Alternatively, if you are not interested in development but in testing or visualization, instead of running `run.sh` and `run_rosario_sequence.sh` in two different terminals, you can just run:
+```
+./run_rosario_sequence.sh -r -o <OUTPUT_TRAJECTORY_FILE> <ROSBAG_FILE>
+```
+This launches a Docker container and executes the default launch file (see `LAUNCH_FILE` in `run.sh`). After that, the bagfile is played and `rviz` and `pose_listener` are launched. Add `-b` if you want to turn off the visualization.
+
+
+# Original README
+
 The software is tested on Ubuntu 16.04 with ROS Kinetic.
 
 Video: [https://www.youtube.com/watch?v=jxfJFgzmNSw&t](https://www.youtube.com/watch?v=jxfJFgzmNSw&t=3s)<br/>
@@ -20,22 +83,6 @@ Most of the dependencies are standard including `Eigen`, `OpenCV`, and `Boost`.
 sudo apt-get install libsuitesparse-dev
 ```
 
-## Docker support
-1. Clone the repository.
-1. Build image:
-   ```
-   make image
-   ```
-1. Open shell in a docker container:
-   ```
-   make shell
-   ```
-1. Write your own launch file and run `msckf_vio`. For example:
-   ```
-   roslaunch msckf_vio msckf_vio_rosario.launch
-   ```
-1. Open another terminal and run `rosbag play <BAG_FILE>` in the host. Finally, `rviz` can be executed in the host too.
-
 ## Compling
 The software is a standard catkin package. Make sure the package is on `ROS_PACKAGE_PATH` after cloning the package to your workspace. And the normal procedure for compiling a catkin package should work.