Ignition Physics

API Reference

2.3.0
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

In the previous tutorial Installation, you have installed the Ignition Physics corresponding to the desired Ignition release.

Write a simple loader

Please create a folder for the loader first:

cd ~
mkdir -p ~/simple_loader/build
cd simple_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).

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.

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);

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).

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 building (Version: Citadel, ign-physics2)

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:

cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
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)

After that, add the executable pointing to our file and add linking library so that cmake can compile it:

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})

For a comprehensive CMake tutorial, please take a look here.

Build and run

Compile the loader

Your current loader folder should look like this:

$ ls ~/simple_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.