Skip to content

Latest commit

 

History

History
257 lines (209 loc) · 10.3 KB

README.md

File metadata and controls

257 lines (209 loc) · 10.3 KB
Raw

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:

  • Point cloud computation using hardware-accelerated raytracing (Nvidia OptiX)
  • High performance (~4x improvement over gpu_lidar sensor from Gazebo)
  • Multiple LiDAR pattern configuration methods, including importing a pattern from a binary file
  • Realistic presets of the most popular LiDARs

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:

  • do_ignore_entities_in_lidar_link - if enabled, all entities attached to the same <link> as lidar will be ignored from raycasting. It could be useful when a visual representation of the sensor is added. (optional, default: true)
    Note: It has been noticed that when the lidar link is chained to another link with a joint component, the entity tree is simplified and the parent link becomes the lidar link. In such case, the whole robot could be ignored from raycasting. Yet to be resolved.

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:

  • range - the minimum and maximum range that the hits will be registered (in meters).

  • update_rate - the frequency at which the lidar will perform raycasting (in Hz).

  • topic - topic on which pointcloud message (gz::msgs::PointCloudPacked) will be published. A second topic with the /world postfix will also be created for visualization purposes.

  • frame - frame_id for point cloud message header.

  • update_on_paused_sim - determines whether the lidar is active when the simulation is paused (optional, default: false).

  • pattern_<type> - definition of the lidar firing pattern. Each type has different parameters described below.

Pattern types:

  • pattern_uniform
    An analog to the gpu_lidar configuration (angles in radians).

    <pattern_uniform>
    <horizontal>
        <samples>1800</samples>
        <min_angle>-3.14159</min_angle>
        <max_angle>3.14159</max_angle>
    </horizontal>
    <vertical>
        <samples>128</samples>
        <min_angle>-0.436332</min_angle>
        <max_angle>0.261799</max_angle>
    </vertical>
</pattern_uniform>

  • pattern_custom
    channels attribute defines the angular position of lidar channels (angles in radians). Horizontal samples are uniformly distributed.

    <pattern_custom channels="0.69 -0.69 0.26 -0.26">
    <horizontal>
        <samples>3600</samples>
        <min_angle>-3.14159</min_angle>
        <max_angle>3.14159</max_angle>
    </horizontal>
</pattern_custom>

  • pattern_preset
    We have prepared several lidar presets. You can type in the name of a LiDAR to use its pattern (all available patterns are shown below).

    <pattern_preset>Alpha Prime</pattern_preset>
<pattern_preset>Puck</pattern_preset>
<pattern_preset>Ultra Puck</pattern_preset>
<pattern_preset>OS1 64</pattern_preset>
<pattern_preset>Pandar64</pattern_preset>
<pattern_preset>Pandar40P</pattern_preset>

    Note: Before launching the simulation it is required to set RGL_PATTERNS_DIR environment variable with the path to pattern presets directory (lidar_patterns from repository).

    # For example
export RGL_PATTERNS_DIR=`pwd`/lidar_patterns

  • pattern_preset_path
    If you wish so, You can create your own preset by providing a binary file with the structure below repeated as many times as you fancy. Please note that an absolute path is required.

    /**
 * Row-major matrix with 3 rows and 4 columns of 32-bit floats.
 */
typedef struct
{
	float value[3][4];
} rgl_mat3x4f;
    <pattern_preset_path>/home/some1/your-preset.mat3x4f</pattern_preset_path>

  • pattern_lidar2d
    Almost the same as pattern_uniform but only has the horizontal element and publishes a LaserScan message instead of a point cloud

    <pattern_lidar2d>
    <horizontal>
        <samples>1800</samples>
        <min_angle>-3.14159</min_angle>
        <max_angle>3.14159</max_angle>
    </horizontal>
</pattern_lidar2d>

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.