Update wiki

3D-OpenGL-Rendering-Engine.md

@@ -0,0 +1,32 @@
+Rendering engine based on pure OpenGL code, that can simulate simple 3D scenes, including the possibility to simulate dynamic objects moving in the scene.
+
+## Run
+
+Run the simulator as follows (do not forget to set the absolute paths in `opengl.conf`):
+
+    roslaunch esim_ros esim.launch config:=cfg/opengl.conf
+
+To visualize the output of the simulator, you can open `rviz` (from a new terminal) as follows:
+
+    roscd esim_visualization
+    rviz -d cfg/esim.rviz
+
+You can also open `rqt` for more visualizations, as follows:
+
+    roscd esim_visualization
+    rqt --perspective-file cfg/esim.perspective
+
+## Scenes
+
+[Assimp](http://www.assimp.org/) is used to read a 3D object used as scene, for example an .obj file.
+Use `--render_scene` to specify the path to some object.
+
+### Blender
+
+Theoretically, Blender-files are supported by Assimp, but are loaded somehow incorrectly.
+Better export your scene as a .obj file. Make sure of the following things:
+
+- Materials must have UV maps defined for textures (In Textures: Mapping: Coordinates select 'UV').
+- Choose 'Z Up' and 'Y forward' when exporting as .obj
+- Make sure 'include UVs' and 'write materials' are enabled when exporting.
+- Make sure 'Path Mode' is set to 'Copy' (this will export and copy the texture files to the same folder as the .obj file)

Home.md

@@ -8,8 +8,8 @@ Below is a table summarizing the different rendering engines available to date,
 
 |                   | Dimension          | IMU | Moving Objects | Camera Distortion | Simulation speed |
 |-------------------|--------------------|-----|----------------|-------------------|------------------|
-| [MultiObjects2D](https://github.com/uzh-rpg/rpg_event_camera_simulator/wiki/Multi-Objects-2D-renderer)    | 2D                 | No  | Yes            | No                |  ***             |
-| [PanoramicRenderer](https://github.com/uzh-rpg/rpg_event_camera_simulator/wiki/Panoramic-Renderer) | 2D (rotation only) | Yes | No             | Yes               | ****             |
-|  [PlanarRenderer](https://github.com/uzh-rpg/rpg_event_camera_simulator/wiki/Planar-Renderer)   | 2.5D (planar)      | Yes | No             | Yes               | ****             |
-| [OpenGLRenderer](https://github.com/uzh-rpg/rpg_event_camera_simulator/wiki/3D-OpenGL-Rendering-Engine)    | 3D                 | Yes | Yes            | No                | *****            |
-| [UnrealCVRenderer](https://github.com/uzh-rpg/rpg_event_camera_simulator/wiki/Photorealistic-Rendering-Engine-based-on-Unreal-Engine)  | 3D                 | Yes | No             | No                | *                |
+| [MultiObjects2D](https://github.com/uzh-rpg/rpg_esim/wiki/Multi-Objects-2D-renderer)    | 2D                 | No  | Yes            | No                |  ***             |
+| [PanoramicRenderer](https://github.com/uzh-rpg/rpg_esim/wiki/Panoramic-Renderer) | 2D (rotation only) | Yes | No             | Yes               | ****             |
+|  [PlanarRenderer](https://github.com/uzh-rpg/rpg_esim/wiki/Planar-Renderer)   | 2.5D (planar)      | Yes | No             | Yes               | ****             |
+| [OpenGLRenderer](https://github.com/uzh-rpg/rpg_esim/wiki/3D-OpenGL-Rendering-Engine)    | 3D                 | Yes | Yes            | No                | *****            |
+| [UnrealCVRenderer](https://github.com/uzh-rpg/rpg_esim/wiki/Photorealistic-Rendering-Engine-based-on-Unreal-Engine)  | 3D                 | Yes | No             | No                | *                |

Installation-(ROS-Melodic).md

@@ -0,0 +1,15 @@
+We recommend to use ROS Kinetic with this simulator. However, ROS Kinetic is not supported on Ubuntu distributions > 16.04 LTS. In this case we recommend to upgrade ROS to Melodic, because we experienced library conflicts and similar bugs when the Ubuntu version is not in sync with what's recommended by ROS.
+
+This page collects information on how to install the simulator on a newer ROS version (Melodic in combination with GCC 7.x).
+
+## Catkin Configuration
+```
+catkin config --extend /opt/ros/melodic --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=-Wno-int-in-bool-context
+```
+## Hector Trajectory Server
+The hector trajectory server package is not available for ros melodic. But we can manually compile it together with the other dependencies. Download the packages from [their Github Repository](https://github.com/tu-darmstadt-ros-pkg/hector_slam) and put them in the source directory, next to rpg_esim (`sim_ws/src`). The packages are detected `catkin` during a regular compilation process.
+
+Required Packages:
+ - hector_map_tools
+ - hector_nav_msgs
+ - hector_trajectory_server

Installation.md

@@ -0,0 +1,69 @@
+---
+:grey_exclamation: **NOTE:**
+Please read [this guide](https://github.com/uzh-rpg/rpg_esim/wiki/Installation-(ROS-Melodic)) if you have to use ROS Melodic.
+
+---
+We recommend to create a new catkin workspace specifically for the simulator as follows:
+    
+    mkdir -p ~/sim_ws/src && cd ~/sim_ws
+    catkin init
+    catkin config --extend /opt/ros/kinetic --cmake-args -DCMAKE_BUILD_TYPE=Release
+
+Install `vcstools` if you do not have it already:
+
+    sudo apt-get install python-vcstool
+
+Clone this repository and run `vcstools`:
+
+    cd src/
+    git clone git@github.com:uzh-rpg/rpg_esim.git
+    vcs-import < rpg_esim/dependencies.yaml
+
+Install `pcl_ros`:
+
+    sudo apt-get install ros-kinetic-pcl-ros
+
+Install `glfw`:
+
+    sudo apt-get install libglfw3 libglfw3-dev
+
+Install `glm`:
+
+    sudo apt-get install libglm-dev
+
+Optionally install the trajectory server:
+
+    sudo apt-get install ros-kinetic-hector-trajectory-server
+
+Disable the packages that are not needed:
+
+    cd ze_oss
+    touch imp_3rdparty_cuda_toolkit/CATKIN_IGNORE \
+          imp_app_pangolin_example/CATKIN_IGNORE \
+          imp_benchmark_aligned_allocator/CATKIN_IGNORE \
+          imp_bridge_pangolin/CATKIN_IGNORE \
+          imp_cu_core/CATKIN_IGNORE \
+          imp_cu_correspondence/CATKIN_IGNORE \
+          imp_cu_imgproc/CATKIN_IGNORE \
+          imp_ros_rof_denoising/CATKIN_IGNORE \
+          imp_tools_cmd/CATKIN_IGNORE \
+          ze_data_provider/CATKIN_IGNORE \
+          ze_geometry/CATKIN_IGNORE \
+          ze_imu/CATKIN_IGNORE \
+          ze_trajectory_analysis/CATKIN_IGNORE
+
+
+Build the `event_camera_simulator` node:
+
+    catkin build esim_ros
+
+Make an alias for your workspace so you can source it easily next time.
+
+    printf "#!/bin/bash\n\nsource ~/sim_ws/devel/setup.bash" >> ~/setupeventsim.sh
+    chmod +x ~/setupeventsim.sh
+
+In your `.bashrc` file, add the following line:
+
+    alias ssim='source ~/setupeventsim.sh'
+
+From now on, typing `ssim` in a terminal will initialize the simulator workspace (you need to run `bash` first if you want to try this right after editing the `.bashrc` file.

Multi-Objects-2D-renderer.md

@@ -0,0 +1,27 @@
+A simple 2D rendering engine that simulates several 2D objects moving over a planar background.
+
+## Example
+
+To run the example:
+
+    roslaunch esim_ros esim.launch config:=cfg/multi_objects.conf
+
+You should get a result similar to [this video](https://youtu.be/Yre8iS2LqPc).
+
+## Format of a `scene` file
+
+The configuration of this rendering engine can be set through a `scene` file (example [here](https://github.com/uzh-rpg/rpg_esim/blob/master/event_camera_simulator/imp/imp_multi_objects_2d/scenes/example.scene)).
+
+A scene file with N layers has the following structure:
+
+    width height tmax (s)
+    <layer 1>
+    <layer 2>
+    ...
+    <layer N>
+
+where each layer line has the format:
+
+    path_to_image median_filter_size gaussian_blur_sigma theta0 theta1 x0 x1 y0 y1 sx0 sx1 sy0 sy1
+
+describing which image should be used for the layer, how much preprocessing should be applied to it, and the parameters of the affine transformation it will undergo between t=0 and t=tmax

Panoramic-Renderer.md

@@ -0,0 +1,17 @@
+Rendering engine that simulate camera rotation provided a panoramic map of the scene in equirectangular format (such as [this one](https://github.com/uzh-rpg/rpg_esim/blob/master/event_camera_simulator/imp/imp_panorama_renderer/textures/bicycle_parking.jpg) for example).
+
+## Run
+
+Run the simulator as follows (do not forget to set the absolute paths in `panorama.conf`):
+
+    roslaunch esim_ros esim.launch config:=cfg/panorama.conf
+
+To visualize the output of the simulator, you can open `rviz` (from a new terminal) as follows:
+
+    roscd esim_visualization
+    rviz -d cfg/esim.rviz
+
+You can also open `rqt` for more visualizations, as follows:
+
+    roscd esim_visualization
+    rqt --perspective-file cfg/esim.perspective

Photorealistic-Rendering-Engine-based-on-Unreal-Engine.md

@@ -0,0 +1,26 @@
+Photorealistic rendering engine based on [Unreal Engine](https://www.unrealengine.com), using the [UnrealCV](https://github.com/unrealcv/unrealcv) project.
+
+## Preparation
+
+You need first to set up an UnrealCV plugin, or simply download one from the [Model Zoo](http://docs.unrealcv.org/en/latest/reference/model_zoo.html). We recommend to start first with the `RealisticRendering` model.
+
+Before running the simulator, you need to launch the UnrealCV server as follows:
+
+    cd <path_to_the_unrealcv_server_code>
+    ./LinuxNoEditor/playground.sh
+
+## Run
+
+Once an UnrealCV server is running, you can run the simulator as follows:
+
+    roslaunch esim_ros esim.launch config:=cfg/unrealcv.conf
+
+To visualize the output of the simulator, you can open `rviz` (from a new terminal) as follows:
+
+    roscd esim_visualization
+    rviz -d cfg/esim.rviz
+
+You can also open `rqt` for more visualizations, as follows:
+
+    roscd esim_visualization
+    rqt --perspective-file cfg/esim.perspective

Planar-Renderer.md

@@ -0,0 +1,17 @@
+Rendering engine that simulates a 3D camera motion in a planar scene (one plane with texture attached to it).
+
+## Run
+
+Run the simulator as follows (do not forget to set the absolute paths in `example.conf`):
+
+    roslaunch esim_ros esim.launch config:=cfg/example.conf
+
+To visualize the output of the simulator, you can open `rviz` (from a new terminal) as follows:
+
+    roscd esim_visualization
+    rviz -d cfg/esim.rviz
+
+You can also open `rqt` for more visualizations, as follows:
+
+    roscd esim_visualization
+    rqt --perspective-file cfg/esim.perspective

Tests.md

@@ -0,0 +1,9 @@
+The test suite requires a data folder `esim_test_data`. Before running any test, it is necessary to export the path to the test data folder as follows (you can add this line to the `setupeventsim.sh` script created previously):
+
+    export ESIM_TEST_DATA_PATH=~/sim_ws/src/event_camera_simulator/event_camera_simulator/esim_test_data/
+
+### Running the tests
+
+    ssim
+    roscd
+    catkin run_tests esim_common