"Use custom engine with Ignition Physics"

Prerequisites

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

How to adapt a physics engine as a plugin in Ignition Physics

In the last Implement a physics plugin tutorial, we know how to implement a dummy physics engine as a plugin and load it using Ignition Physics API. In Implement a custom feature tutorial, we know how to define and implement a custom feature in an existing DART physics plugin. This tutorial will explain step-by-step how to use any physics engine with Ignition Physics. We will use TPE as an example for this tutorial.

General structure of a physics plugin

As described in Implement a custom feature tutorial, the plugin folder is placed just below the top-level folder of ign-physics. In general, any physics plugin folder will have the following structure, which is commented in detail:

tpe
├── lib                              Main physics engine implementation.
│    ├── src
│    ├── CMakeLists.txt              CMake build script for physics engine implementation.
├── plugin                           Main implementation of the plugin features interfacing the physics engines API
│    ├── src
│    |     ├── plugin.cc             Main file for the plugin declaration and plugin registering.
│    |     ├── <FEATURES>.hh         The FeatureList header file.
│    |     ├── <FEATURES>.cc         Implementation of the FeatureList, which adapts to functions implemented in lib used in the FeatureList.
│    |     ├── <FEATURES_TEST>.cc    Test cases for the FeatureList.
│    ├── worlds                      Example SDF files for testing plugin functionalities.
│    ├── CMakeLists.txt              CMake build script for the plugin features.
└── CMakeLists.txt                   CMake build script for the plugin.

Note that the lib folder is optionally placed inside the physics plugin folder depending on the design target, we can link the external physics engine library in CMakeLists.txt of the plugin, assuming the physics engine library is already installed. In our case, TPE is natively developed inside Ignition Physics and hence the lib folder.

We declare and implement the FeatureList interfacing with the physics engine API inside plugin\src folder (please see Implement a custom feature for the plugin feature requirements). Depending on design target, a FeatureList is generally a packing of related Features. For example in TPE's EntityManagementFeatures , there are GetEngineInfo, GetWorldFromEngine, etc. features defined in the "FeatureList" structure for entity management purpose.

Conventionally, a FeatureList can be implemented as:

• <FEATURES>.hh for the "FeatureList" declaration.
• <FEATURES>.cc for the "FeatureList" implementation corresponding to each of the Features member functions, using the physics engine API to realize the feature behavior. For a list of common pre-defined features in Ignition Physics, please refer to Understanding the Physics Plugin tutorial.
• <FEATURES_TEST>.cc for unit tests of the "FeatureList".

Main plugin.cc file

In this tutorial, we will show how to construct a simple simulation world using TPE physics engine. For this purpose, we will implement the pre-defined ConstructEmptyWorldFeature and include this feature into an empty FeatureList named EntityManagementFeatureList defined in EntityManagementFeatures.hh. We first include the EntityManagementFeatureList in plugin.cc main file and register the example TPE physics plugin as follow:

#include <ignition/physics/Register.hh>

#include "Base.hh"

#include "EntityManagementFeatures.hh"

namespace ignition {
namespace physics {
namespace tpeplugin {

struct TpePluginFeatures : FeatureList<
  EntityManagementFeatureList
> { };

class Plugin :
  public virtual Implements3d<TpePluginFeatures>,
  public virtual Base,
  public virtual EntityManagementFeatures { };

IGN_PHYSICS_ADD_PLUGIN(Plugin, FeaturePolicy3d, TpePluginFeatures)

}
}
}

In general, there are 3 steps for plugin.cc:

• Define the final FeatureList including all required "FeatureLists". In TPE case, it is TpePluginFeatures.
• Define an empty class inherited all "FeatureLists" class, Base class (optionally depending on software design) and Implements class implementing FeaturePolicy 2D or 3D and different scalar type.
• Register the physics plugin using IGN_PHYSICS_ADD_PLUGIN macro (See Implement a physics plugin for more detail).

Implement a feature using TPE's API

Now we assume that we have not implemented any Feature for TPE. In the plugin folder, we will create two files EntityManagementFeatures.hh and EntityManagementFeatures.cc to implement ConstructEmptyWorldFeature in EntityManagementFeatures "FeatureList". The unit test for this feature is also worth implemented in EntityManagement_TEST.cc. Please download the example CMakeLists.txt and Base.hh into plugin folder by:

wget https://raw.githubusercontent.com/ignitionrobotics/ign-physics/main/tpe/plugin/CMakeLists.txt -P <path-to-ign-physics>/tpe/plugin/
wget https://raw.githubusercontent.com/ignitionrobotics/ign-physics/main/tpe/plugin/src/Base.hh -P <path-to-ign-physics>/tpe/plugin/src

Now the folder structure looks like this:

tpe
├── lib
├── plugin
│    ├── src
│    |     ├── plugin.cc
│    |     ├── Base.hh
│    |     ├── EntityManagementFeatures.hh
│    |     ├── EntityManagementFeatures.cc
│    |     ├── EntityManagement_TEST.cc
│    ├── CMakeLists.txt
└── CMakeLists.txt

Basically, ConstructEmptyWorldFeature has a subclass Engine defining ConstructEmptyWorld member function. The feature implementation is shown as below:

EntityManagementFeatures.hh:

#ifndef IGNITION_PHYSICS_TPE_PLUGIN_SRC_GETENTITIESFEATURE_HH_
#define IGNITION_PHYSICS_TPE_PLUGIN_SRC_GETENTITIESFEATURE_HH_

#include <string>
#include <ignition/physics/ConstructEmpty.hh>
#include <ignition/physics/Shape.hh>
#include <ignition/physics/GetEntities.hh>
#include <ignition/physics/RemoveEntities.hh>
#include <ignition/physics/Implements.hh>

#include "Base.hh" // optionally depending on software design

namespace ignition {
namespace physics {
namespace tpeplugin {

struct EntityManagementFeatureList : FeatureList<
  ConstructEmptyWorldFeature
> { };

class EntityManagementFeatures :
  public virtual Base,
  public virtual Implements3d<EntityManagementFeatureList>
{
  // ----- Construct empty entities -----
  public: Identity ConstructEmptyWorld(
    const Identity &_engineID, const std::string &_name) override;
};

}
}
}

#endif

Together with other (if existing) Features, the ConstructEmptyWorldFeature is included in EntityManagementFeatureList "FeatureList" to declare the related features for entity management purpose.

The EntityManagementFeatures "FeatureList" here inherits from:

• (optionally) Base class for foundation metadata definitions of Models, Joints, Links, and Shapes objects of TPE to provide easy access to tpelib structures in the TPE library. Note that we mention Base class here for completeness, Base class is not necessarily needed if there is a straightforward way to interface external physics engine class objects with ign-physics class objects.
• Implements3d for implementing the custom feature with FeaturePolicy3d ("FeaturePolicy" of 3 dimensions and scalar type double).

EntityManagementFeatures.cc:

#include <string>
#include "EntityManagementFeatures.hh"

using namespace ignition;
using namespace physics;
using namespace tpeplugin;

Identity EntityManagementFeatures::ConstructEmptyWorld(
  const Identity &, const std::string &_name)
{
  auto world = std::make_shared<tpelib::World>();
  world->SetName(_name);
  return this->AddWorld(world);
}

Here we show the overriding of ConstructEmptyWorld member function of ConstructEmptyWorldFeature, this is where we use the physics engine API to implement this member function. We simply instantiate World object, set the world name and call AddWorld function which was defined in Base.hh.

EntityManagement_TEST.cc:

Simple unit tests are good practice for sanity checks. While we won't go into detail, here is an example to test our new ConstructEmptyWorldFeature:

#include <gtest/gtest.h>
#include <ignition/plugin/Loader.hh>
#include <ignition/physics/RequestEngine.hh>
#include "EntityManagementFeatures.hh"

struct TestFeatureList : ignition::physics::FeatureList<
  ignition::physics::tpeplugin::EntityManagementFeatureList
> { };

TEST(EntityManagement_TEST, ConstructEmptyWorld)
{
  ignition::plugin::Loader loader;
  loader.LoadLib(tpe_plugin_LIB);

  ignition::plugin::PluginPtr tpe_plugin =
    loader.Instantiate("ignition::physics::tpeplugin::Plugin");

  auto engine =
      ignition::physics::RequestEngine3d<TestFeatureList>::From(tpe_plugin);
  auto world = engine->ConstructEmptyWorld("empty world");
  ASSERT_NE(nullptr, world);
}

int main(int argc, char *argv[])
{
  ::testing::InitGoogleTest(&argc, argv);
  return RUN_ALL_TESTS();
}

Please take a look at EntityManagement_TEST.cc for more comprehensive unit tests.

Build the custom physics plugin

Please follow the previous tutorial Installation to build ign-physics from source again for our new feature to be compiled.

Now we can load the new physics plugin named ignition-physics-tpe-plugin to test it on Ignition Gazebo by following this Switching physics engines tutorial.

Prerequisites

• Installation
• Understand physics plugin
• Use different physics engines
• Load physics plugin
• Implement custom feature

How to interface with physics engine

In the previous Implement custom feature tutorial, we walked through how to define and implement a custom feature using an already supported physics engine. This tutorial will explain step-by-step how to interface with any physics engine using Ignition Physics. We will use TPE as an example in this tutorial.

Structure of a physics plugin

Depending on what physics engine you would like to use, the folder structure could be slightly different from what's shown below. Here's the plugin folder structure of TPE, within the Ignition Physics library.

ign-physics
├── tpe
│   ├── plugin                           Implementation of the plugin features interfacing the physics engines API
│   │    ├── src
│   │    |     ├── plugin.cc             Main file for the plugin declaration and plugin registering.
│   │    |     ├── <FEATURES>.hh         The FeatureList header file.
│   │    |     ├── <FEATURES>.cc         Implementation of the FeatureList using physics engine API
│   │    |     └── <FEATURES_TEST>.cc    Tests
│   │    └── CMakeLists.txt              CMake build script for the plugin features.
│   └── CMakeLists.txt                   CMake build script for the plugin.
└── CMakeList.txt                        CMake build script for Ignition Physics library.

We link the external physics engine library in CMakeLists.txt of the plugin, assuming the physics engine library is already installed. In our case, TPE is placed inside Ignition Physics and hence there is a lib folder under tpe.

We declare and implement the FeatureList interfacing with the physics engine API inside plugin/src folder (please see Implement custom feature for the plugin feature requirements). Depending on design target, a FeatureList is generally a packing of related Features. For example in TPE's EntityManagementFeatures , there are GetEngineInfo, GetWorldFromEngine, etc. features defined in the "FeatureList" structure for entity management purpose.

Conventionally, a FeatureList can be implemented as:

• <FEATURES>.hh for the "FeatureList" declaration.
• <FEATURES>.cc for the "FeatureList" implementation corresponding to each of the Features member functions, using the physics engine API to realize the feature behavior. For a list of common pre-defined features in Ignition Physics, please refer to Understand physics plugin tutorial.
• <FEATURES_TEST>.cc for unit tests of the "FeatureList".

Next, we will use a simplified TPE plugin example to explain important components needed to interface with any physics engine. All code examples used below can be downloaded from examples under the simple_plugin folder:

simple_plugin
├── CMakeLists.txt
├── plugin.cc
├── EntityManagementFeatures.hh
├── EntityManagementFeatures.cc
└── EntityManagementFeatures_TEST.cc

plugin.cc

In this tutorial, we will show how to construct a simple simulation world using TPE physics engine. For this purpose, we will implement the pre-defined ConstructEmptyWorldFeature and include this feature into an empty FeatureList named EntityManagementFeatureList defined in EntityManagementFeatures.hh. We first include the EntityManagementFeatureList in plugin.cc main file and register the example TPE physics plugin as follow:

Those are 3 things needed to be specified in plugin.cc:

• Define the conclusive FeatureList including all required "FeatureLists" and Base class. In TPE case, it is TpePluginFeatures.
• Define the dimension of the simulation, ex. Implements class implementing FeaturePolicy 2D or 3D and different scalar type.
• Register the physics plugin using IGN_PHYSICS_ADD_PLUGIN macro (See Implement physics plugin for more detail).

Implement features with physics engine's API

Now we would like to implement the EntityManagementFeatures. In the simple_plugin folder, we will create two files EntityManagementFeatures.hh and EntityManagementFeatures.cc to implement a single feature ConstructEmptyWorldFeature in EntityManagementFeatures "FeatureList" using TPE API from tpe/lib in Ignition Physics library.

Before we dive into the feature implementation, we need to understand how the features are defined.

The ConstructEmptyWorldFeature is declared in a function template file ign-physics/include/ignition/physics/ConstructEmpty.hh.

Ignition Physics library uses function templates to specify features that accept generic types. The use of templates makes it easier to implement features using different physics engine APIs, without having to repeat the entire code for a function.

The ConstructEmptyWorldFeature example here is implemented with TPE API, but a similar feature can also be implemented using DART API.

In this case, we are implementing a feature that is already defined by Ignition Physics, thus we do not need to write our own template function, and can just include the template in our header file.

But first, let's include the basics:

#include <string>
#include <ignition/physics/Implements.hh>

Then, we include the specific feature template file and add it to the feature list:

#include <ignition/physics/ConstructEmpty.hh>

namespace ignition {
namespace physics {
namespace simpleplugin {

struct EntityManagementFeatureList : FeatureList<
  ConstructEmptyWorldFeature
> { };

We also need to declare the feature function in the header file, but since the function is already declared in the template file we just included, we need to override the generic declaration instead:

class EntityManagementFeatures :
  public virtual Implements3d<EntityManagementFeatureList>
{
  public: Identity ConstructEmptyWorld(
    const Identity &_engineID, const std::string &_name) override;
};

}
}
}

The EntityManagementFeatures "FeatureList" here inherits from:

• (optionally) Base class for foundation metadata definitions of Models, Joints, Links, and Shapes objects of TPE to provide easy access to tpelib structures in the TPE library.
• Implements3d for implementing the custom feature with FeaturePolicy3d ("FeaturePolicy" of 3 dimensions and scalar type double).

Then we can go ahead with the implementation of ConstructEmptyWorldFeature:

Here we show the overriding of ConstructEmptyWorld member function of ConstructEmptyWorldFeature, this is where we use the physics engine API to implement this member function. We simply instantiate World object, set the world name and call AddWorld function which was defined in Base.hh.

Simple unit tests are good practice for sanity checks. While we won't go into detail, here is an example to test our new ConstructEmptyWorldFeature:

To get a more comprehensive view of how EntityManagementFeatures are constructed in TPE and Dartsim, feel free to take a look here:

• Dartsim: EntityManagementFeatures.hh and EntityManagementFeatures.cc
• TPE: EntityManagementFeatures.hh and EntityManagementFeatures.cc

Load and test

Please follow the previous tutorial Installation to build ign-physics from source again for our new feature to be compiled.

Now we can load the new physics plugin named ignition-physics-tpe-plugin to test it on Ignition Gazebo by following this Use different physics engines tutorial.