search

RobotecAI / RGLGazeboPlugin

Other
61 stars 11 forks source link

readme

RGL Gazebo Plugin

RGL Gazebo Plugin Logo

About the project

RGL Gazebo Plugin has been created by Robotec.AI to bring Robotec GPU Lidar to Gazebo.

Key features:

Requirements:

Installation:

Using pre-built libraries

  1. Download libraries from release.
  2. Make RGL plugins visible to Gazebo:
    • Move libraries to the plugin's directories. 
      # If Gazebo installed from apt:
cp libRobotecGPULidar.so /usr/lib/x86_64-linux-gnu/ign-gazebo-6/plugins/
cp libRGLServerPluginInstance.so /usr/lib/x86_64-linux-gnu/ign-gazebo-6/plugins/
cp libRGLServerPluginManager.so /usr/lib/x86_64-linux-gnu/ign-gazebo-6/plugins/
cp libRGLVisualize.so /usr/lib/x86_64-linux-gnu/ign-gazebo-6/plugins/gui/
    • Or set environment variables: 
      # Assuming that libraries:
# libRGLServerPluginInstance.so, libRGLServerPluginManager.so and libRobotecGPULidar.so
# are located in RGLServerPlugin directory,
# and libRGLVisualize.so in RGLGuiPlugin.
export GZ_SIM_SYSTEM_PLUGIN_PATH=`pwd`/RGLServerPlugin:$GZ_SIM_SYSTEM_PLUGIN_PATH
export GZ_GUI_PLUGIN_PATH=`pwd`/RGLGuiPlugin:$GZ_GUI_PLUGIN_PATH

      Building from source

Docker

docker build \
   --target=exporter \
   --output=install .

Manual

mkdir build
cd build
cmake ..
make -j
make install
cd ..
export GZ_SIM_SYSTEM_PLUGIN_PATH=`pwd`/install/RGLServerPlugin:$GZ_SIM_SYSTEM_PLUGIN_PATH
export GZ_GUI_PLUGIN_PATH=`pwd`/install/RGLVisualize:$GZ_GUI_PLUGIN_PATH

Using custom build of RobotecGPULidar

By default, the RGLGazebPlugin downloads RobotecGPULidar binaries from the official release. To use your own build of RobotecGPULidar, set the following CMake variables when configuring the project:

# RGL_CUSTOM_LIBRARY_PATH - Path to the custom RobotecGPULidar library build
# RGL_CUSTOM_API_HEADER_PATH - Path to the include directory with API headers compatible with the custom library build
#                              (`include` directory of `RobotecGPULidar` project)
# Example:
cmake \
  -DRGL_CUSTOM_LIBRARY_PATH="$HOME/RobotecGPULidar/build/lib/libRobotecGPULidar.so" \
  -DRGL_CUSTOM_API_HEADER_PATH="$HOME/RobotecGPULidar/include" \
  ..

Demo:

Launch the prepared simulation from test_world directory:

gz sim sonoma_with_rgl.sdf
  1. Start the simulation by pressing play
  2. The lidar hits should be visible in the GUI
  3. You can control the car using the Teleop plugin (preferably changing the steering to the keyboard and upping the speed to 15)

The second sample world (rgl_playground.sdf) contains all supported object types with this plugin. Since the pattern_type is configured as pattern_preset, it is required to set RGL_PATTERNS_DIR environment variable before running the simulation:

# From the top-level directory of this repository
export RGL_PATTERNS_DIR=`pwd`/lidar_patterns
gz sim test_world/rgl_playground.sdf

Using the plugin:

RGLServerPlugin contains two plugins: RGLServerPluginManager and RGLServerPluginInstance. For the plugin to work properly, we need to include both.

How to include RGLServerPluginManager in your sdf:

<plugin name='rgl::RGLServerPluginManager' filename='RGLServerPluginManager'>
    <do_ignore_entities_in_lidar_link>true</do_ignore_entities_in_lidar_link>
</plugin>

Parameters description:

This is a global plugin and should be included only once per sdf, preferably inside the world entity. RGLServerPluginManager is responsible for synchronizing the scene between Gazebo and GPU (CUDA). At the moment manager handles all primitive geometry types (Box, Capsule, Cylinder, Ellipsoid, Sphere), planes, meshes and submeshes.

How to include RGLServerPluginInstance in your sdf:

Inside the link entity in your model, add a custom sensor:

<sensor name="UniqueSensorName" type="custom">
  <plugin filename="RGLServerPluginInstance" name="rgl::RGLServerPluginInstance">
    <range>
        <min>0</min>
        <max>100</max>
    </range>
    <update_rate>10</update_rate>
    <update_on_paused_sim>false</update_on_paused_sim>
    <topic>rgl_lidar</topic>
    <frame>RGLLidar</frame>
    <pattern_preset>Alpha Prime</pattern_preset>
  </plugin>
</sensor>

Parameters description:

Pattern types:

How to visualize in Gazebo

To enable non-uniform point clouds visualization in Gazebo Fortress that are produced by RGLServerPlugin, we port PointCloud gui plugin from Gazebo Garden and create RGLVisualize. It reimplements the minimal functionality of receiving PointCloudPacked messages (in a world coordinate frame) and rendering them in the scene.

After starting the simulation:

  1. Add RGLVisualize gui plugin.
  2. Select topic with /world postfix.

Level of detail

At Robotec.AI we care about every little detail of our product, so our presets mimic the patterns exactly. We take into account the fact that in many lidars, the lasers are staggered (not positioned exactly one above another), like in the Ultra Puck according to the manual, page 118.

Ultra Puck one horizontal step pattern RGL digital twin

Ray pattern comparison

RGL uniform pattern gpu_lidar uniform pattern

Acknowledgements

The project benefited from significant contributions and support of Dexory. Features such as LaserScan publishing and Laser Retro as well as update to the newest RGL version were possible thanks to their dedication to the open source community.