From 04e783573713640d72f593702cbbd0e8e203e648 Mon Sep 17 00:00:00 2001 From: Henri Rebecq Date: Mon, 29 Oct 2018 17:58:36 +0100 Subject: [PATCH] Update wiki --- 3D-OpenGL-Rendering-Engine.md | 32 +++++++++ Home.md | 10 +-- Installation-(ROS-Melodic).md | 15 ++++ Installation.md | 69 +++++++++++++++++++ Multi-Objects-2D-renderer.md | 27 ++++++++ Panoramic-Renderer.md | 17 +++++ ...Rendering-Engine-based-on-Unreal-Engine.md | 26 +++++++ Planar-Renderer.md | 17 +++++ Tests.md | 9 +++ 9 files changed, 217 insertions(+), 5 deletions(-) create mode 100644 3D-OpenGL-Rendering-Engine.md create mode 100644 Installation-(ROS-Melodic).md create mode 100644 Installation.md create mode 100644 Multi-Objects-2D-renderer.md create mode 100644 Panoramic-Renderer.md create mode 100644 Photorealistic-Rendering-Engine-based-on-Unreal-Engine.md create mode 100644 Planar-Renderer.md create mode 100644 Tests.md diff --git a/3D-OpenGL-Rendering-Engine.md b/3D-OpenGL-Rendering-Engine.md new file mode 100644 index 0000000..30213c5 --- /dev/null +++ b/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) diff --git a/Home.md b/Home.md index 17de6dc..ae1fbd4 100644 --- a/Home.md +++ b/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 | * | \ No newline at end of file +| [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 | * | diff --git a/Installation-(ROS-Melodic).md b/Installation-(ROS-Melodic).md new file mode 100644 index 0000000..2578e22 --- /dev/null +++ b/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 diff --git a/Installation.md b/Installation.md new file mode 100644 index 0000000..0ba35b8 --- /dev/null +++ b/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. diff --git a/Multi-Objects-2D-renderer.md b/Multi-Objects-2D-renderer.md new file mode 100644 index 0000000..fd9c567 --- /dev/null +++ b/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) + + + ... + + +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 diff --git a/Panoramic-Renderer.md b/Panoramic-Renderer.md new file mode 100644 index 0000000..40287db --- /dev/null +++ b/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 diff --git a/Photorealistic-Rendering-Engine-based-on-Unreal-Engine.md b/Photorealistic-Rendering-Engine-based-on-Unreal-Engine.md new file mode 100644 index 0000000..054de96 --- /dev/null +++ b/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 + ./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 \ No newline at end of file diff --git a/Planar-Renderer.md b/Planar-Renderer.md new file mode 100644 index 0000000..797322f --- /dev/null +++ b/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 \ No newline at end of file diff --git a/Tests.md b/Tests.md new file mode 100644 index 0000000..c6836dd --- /dev/null +++ b/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