Description

Rmagine is a library for fast and accurate simulation of range sensors in large 3D environments using ray tracing. These simulations can also run on embedded devices mounted on a robot. Rmagine has been specifically developed to:

• perform multiple sensor simulations simultaneously and in real time
• distribute computations across devices (CPU, GPU, RTX, …)
• keep data local to the device performing the computation
• minimize graphical overhead (off-screen rendering)
• support runtime-critical tasks

| Spherical, pinhole, or fully customizable models | Query multiple attributes at intersections | |:----:|:----:| | | |

Installation and Usage

Minimal instructions for installing the Rmagine library on your system:

Dependencies

Rmagine depends on TBB, Boost, Eigen, Assimp, and CMake. Install them as follows:

Build and Install

Rmagine can be built either with a standard CMake workflow or by placing it directly into your ROS workspace.

For more advanced options and detailed instructions, visit the Wiki.

Example

This example demonstrates how to simulate ranges for 100 Velodyne VLP-16 sensors using the Embree backend.
First, include the following headers:

```c++ // Map handling

include

// Sensor models

include

// Predefined sensor models (e.g. VLP-16)

include

// Simulators

include

namespace rm = rmagine; ```

The following code loads the map "my_mesh.ply" and simulates 100 Velodyne VLP-16 scans from predefined poses. Hits and ranges are selected as intersection attributes:

```c++ // Load a map from disk std::string pathtomesh = "mymesh.ply"; rm::EmbreeMapPtr map = rm::importembreemap(pathto_mesh);

// Define a sensor model // Here we use the predefined VLP-16 sensor model rm::SphericalModel sensormodel = rm::vlp16900();

// Construct a simulator, set sensor model and map rm::SphereSimulatorEmbree sim; sim.setModel(sensor_model); sim.setMap(map);

// Create 100 transformations between base and map (robot poses) rm::Memory Tbm(100); for(size_t i = 0; i < Tbm.size(); i++) { rm::Transform T = rm::Transform::Identity(); T.t = {2.0, 0.0, 0.0}; // Position (2, 0, 0) rm::EulerAngles e = {0.0, 0.0, 1.0}; // Orientation (0, 0, 1) radians T.R.set(e); // Euler angles internally converted to quaternion Tbm[i] = T; }

// Add desired attributes at intersections // Optimized at compile time // Possible attributes (rmagine/simulation/SimulationResults.hpp): // - Hits // - Ranges // - Points // - Normals // - FaceIds // - GeomIds // - ObjectIds using ResultT = rm::Bundle< rm::Hitsrm::RAM, rm::Rangesrm::RAM

; // To query all attributes at once, use 'rm::IntAttrAll' instead of 'ResultT'

ResultT result = sim.simulate(Tbm); // result.hits, result.ranges contain the resulting attribute buffers std::cout << "First ray’s range: " << result.ranges[0] << std::endl;

// Slice the results for the scan at pose 5 auto ranges5 = result.ranges(5 * sensormodel.size(), 6 * sensormodel.size()); std::cout << "First ray’s range of the fifth scan: " << ranges5[0] << std::endl; ```

More detailed examples explaining each step and how to customize them are available in the Wiki.
Additional examples can be found here: https://github.com/amock/rmagine_examples.

Citation

Please reference the following paper when using the Rmagine library in your scientific work:

bib @inproceedings{mock2023rmagine, title={Rmagine: 3D Range Sensor Simulation in Polygonal Maps via Ray Tracing for Embedded Hardware on Mobile Robots}, author={Mock, Alexander and Wiemann, Thomas and Hertzberg, Joachim}, booktitle={IEEE International Conference on Robotics and Automation (ICRA)}, year={2023}, doi={10.1109/ICRA48891.2023.10161388} }

The paper is available on IEEE Xplore and as a preprint on arXiv.

Rmagine-Accelerated Applications

• rmagine_viewer
• rmaginegazeboplugins
• RMCL
• radarays_ros

Contributions

We welcome contributions of all kinds: issues, pull requests, and feedback. Feel free to help us improve this open-source project.
If you would like to enhance the documentation, whether by fixing typos or adding examples, please submit issues or pull requests at https://github.com/uos/rmagine_docs.

Maintainment

Maintainers: - Alexander Mock (Osnabrück University)

Contact the people listed above if you want and feel capable to help maintaining this piece of open-source software.