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:
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:
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:
Now the folder structure looks like this:
Basically, ConstructEmptyWorldFeature has a subclass Engine defining ConstructEmptyWorld
member function. The feature implementation is shown as below:
EntityManagementFeatures.hh:
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 withign-physics
class objects. - Implements3d for implementing the custom feature with FeaturePolicy3d ("FeaturePolicy" of 3 dimensions and scalar type
double
).
EntityManagementFeatures.cc:
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:
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.