Gazebo Physics

API Reference

2.6.2
Plugin Loading

This tutorial shows how to create an executable that loads physics engine plugins on Ubuntu, according to the desired feature list.

Overview

Physics Plugin integrates external physics engines into the Ignition Physics. It allows users to select from multiple supported physics engines based on their simulation needs. This tutorial will describe how to load a compiled physics plugin using Ignition Physics API.

Prerequisites

Write a simple loader

-We will use a simplified physics plugin example for this tutorial. Source code can be found at ign-physics/examples folder.

First, create a workspace for the example plugin loader.

cd ~
mkdir -p ~/hello_world_loader/build
cd hello_world_loader

Then download the example loader into your current directory by:

wget https://raw.githubusercontent.com/ignitionrobotics/ign-physics/ign-physics2/examples/hello_world_loader/hello_world_loader.cc

Examine the code

At the top of the file hello_world_loader.cc, we include the headers that will be used in our code. After the std C++ libraries are the Loader.hh and PluginPtr.hh, which provides main functionalities for loading physics plugins and plugin pointers. Next includes from ignition::physics are the tools for retrieving Feature and Entity from physics plugins (please refer to Understanding the physics plugin tutorial for their design concepts).

#include <iostream>
#include <gz/plugin/Loader.hh>
#include <gz/plugin/PluginPtr.hh>
// The features that an engine must have to be loaded by this loader.
>;

Next, in the main function, the loader requires users to provide a path for desired plugins to be loaded. The plugin names are retrieved by ignition::plugin::Loader::LoadLib member function.

Assuming the correct path, our loader will instantiate all plugins that are available in the path using ignition::plugin::Loader::Instantiate member function. Then for each instantiated plugin, using ignition::physics::RequestEngine3d<Features>::From, it will request an engine implementing a FeaturePolicy (3D in this case).

int main(int argc, char **argv)
{
// User should provide path to plugin library
if (argc <= 1)
{
std::cerr << "Please provide the path to an engine plugin." << std::endl;
return 1;
}
std::string pluginPath = argv[1];
auto plugins = pl.LoadLib(pluginPath);
// Look for 3d plugins
if (pluginNames.empty())
{
std::cerr << "No plugins with required features found in "
<< pluginPath
}
for (const std::string &name : pluginNames)
{
std::cout << "Testing plugin: " << name << std::endl;
std::cout << " engine name: " << engine->GetName() << std::endl;
}
}

Setup CMakeLists.txt for CMake build

Now create a file named CMakeLists.txt with your favorite editor and add these lines for finding ign-plugin and ign-physics dependencies in Citadel release. After that, add the executable pointing to our file and add linking library so that cmake can compile it.

cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
project(ign-physics-hello-world-loader)
set(IGN_PLUGIN_VER 1)
find_package(ignition-plugin${IGN_PLUGIN_VER} 1.1 REQUIRED COMPONENTS all)
set(IGN_PHYSICS_VER 2)
find_package(ignition-physics${IGN_PHYSICS_VER} REQUIRED)
add_executable(hello_world_loader hello_world_loader.cc)
target_link_libraries(hello_world_loader
ignition-plugin${IGN_PLUGIN_VER}::loader
ignition-physics${IGN_PHYSICS_VER}::ignition-physics${IGN_PHYSICS_VER})

If you find CMake syntax difficult to understand, take a look at the official tutorial here.

Build and run

Compile the loader

Your current loader folder should look like this

$ ls ~/hello_world_loader
CMakeLists.txt hello_world_loader.cc build

Now you can build the loader by:

cd build
cmake ..
make

This will generate the hello_world_loader executable under build folder. This loader will load any plugin that implements the GetEngineInfo feature, and print the engine name.

Load existing plugins

For example, if you have the Ignition Physics plugin for DART compiled, find where it is installed with (you may need administrative rights: sudo on Linux platform):

find / | grep libignition-physics-dartsim-plugin.so

You may find more than one file. Choose one of them, and load it with the loader by:

./hello_world_loader <path_to>/libignition-physics-dartsim-plugin.so

And you'll see the engine info:

Testing plugin: ignition::physics::dartsim::Plugin
engine name: dartsim-6.10.0

At the time of writing, Ignition Physics is shipped with DART and TPE physics plugins installed. Following the above steps, you can load TPE by the library name libignition-physics-tpe-plugin.so or other custom plugins by their corresponding names.

STL class.
This feature retrieves the physics engine name in use.
Definition: gz/physics/GetEntities.hh:31
static EnginePtrType From(const PtrT &_pimpl, const std::size_t _engineID=0)
Get an Engine from the given physics plugin.
Use a FeatureList to aggregate a list of Features.
Definition: gz/physics/FeatureList.hh:51
std::unordered_set< std::string > LoadLib(const std::string &_pathToLibrary)
static std::set< std::string > From(const LoaderT &_loader)
Find a set of plugins that satisfy the requested list of features.
T endl(T... args)
PluginPtr Instantiate(const std::string &_pluginNameOrAlias) const