diff --git a/dartsim/include/ignition/physics/dartsim/World.hh b/dartsim/include/ignition/physics/dartsim/World.hh index 9d7fcebbb..c1eb6c957 100644 --- a/dartsim/include/ignition/physics/dartsim/World.hh +++ b/dartsim/include/ignition/physics/dartsim/World.hh @@ -45,6 +45,7 @@ class RetrieveWorld : public virtual Feature }; ///////////////////////////////////////////////// +//! [feature template] template dart::simulation::WorldPtr RetrieveWorld::World ::GetDartsimWorld() @@ -52,6 +53,7 @@ dart::simulation::WorldPtr RetrieveWorld::World return this->template Interface() ->GetDartsimWorld(this->identity); } +//! [feature template] } } diff --git a/dartsim/src/CustomFeatures.cc b/dartsim/src/CustomFeatures.cc index 0df54efc1..183b9bfbc 100644 --- a/dartsim/src/CustomFeatures.cc +++ b/dartsim/src/CustomFeatures.cc @@ -22,11 +22,13 @@ namespace physics { namespace dartsim { ///////////////////////////////////////////////// +//! [implementation] dart::simulation::WorldPtr CustomFeatures::GetDartsimWorld( const Identity &_worldID) { return this->worlds.at(_worldID); } +//! [implementation] } } diff --git a/dartsim/src/CustomFeatures.hh b/dartsim/src/CustomFeatures.hh index 16c9d9f88..84cba25fb 100644 --- a/dartsim/src/CustomFeatures.hh +++ b/dartsim/src/CustomFeatures.hh @@ -28,9 +28,11 @@ namespace ignition { namespace physics { namespace dartsim { +//! [add to list] using CustomFeatureList = FeatureList< RetrieveWorld >; +//! [add to list] class CustomFeatures : public virtual Base, diff --git a/tutorials/05_plugin_loading.md b/tutorials/05_plugin_loading.md index 8760efaf7..aeab06648 100644 --- a/tutorials/05_plugin_loading.md +++ b/tutorials/05_plugin_loading.md @@ -13,11 +13,11 @@ plugin using \ref ignition::physics "Ignition Physics" API. ## Prerequisites - \ref installation "Installation" -- \ref physicsplugin "Understand physics plugin" +- \ref physicsplugin "Understanding the physics plugin" ## Write a simple loader -We will use a simplified physics plugin example for this tutorial. Source code can be found at [ign-physics2/examples](https://github.com/ignitionrobotics/ign-physics/tree/ign-physics3/examples/hello_world_loader) folder. +-We will use a simplified physics plugin example for this tutorial. Source code can be found at [ign-physics/examples](https://github.com/ignitionrobotics/ign-physics/tree/ign-physics2/examples/hello_world_loader) folder. First, create a workspace for the example plugin loader. @@ -41,7 +41,7 @@ be used in our code. After the `std` C++ libraries are the `Loader.hh` and and plugin pointers. Next includes from \ref ignition::physics are the tools for retrieving \ref ignition::physics::Feature "Feature" and \ref ignition::physics::Entity "Entity" from physics plugins (please refer to -\ref physicsplugin "Understand Physics Plugin" tutorial for their +\ref physicsplugin "Understanding the physics plugin" tutorial for their design concepts). \snippet examples/hello_world_loader/hello_world_loader.cc include statements @@ -55,8 +55,7 @@ available in the path using @ref ignition::plugin::Loader::Instantiate member function. Then for each instantiated plugin, using @ref ignition::physics::RequestEngine3d::From, it will request an engine implementing a \ref ignition::physics::FeaturePolicy "FeaturePolicy" (3D - in this case). -. + in this case). \snippet examples/hello_world_loader/hello_world_loader.cc main diff --git a/tutorials/06-physics-simulation-concepts.md b/tutorials/06-physics-simulation-concepts.md index dc0531151..3ccf6e7a3 100644 --- a/tutorials/06-physics-simulation-concepts.md +++ b/tutorials/06-physics-simulation-concepts.md @@ -26,7 +26,7 @@ For a comprehensive tutorial for constructing your robot model from SDFormat, re In this tutorial, we will show how to manipulate and visualize some physics aspects using demos on Ignition Gazebo. -All demos can be found in [ign-gazebo3/examples/worlds](https://github.com/ignitionrobotics/ign-gazebo/blob/ign-gazebo3/examples/worlds/) folder. +All demos can be found in [ign-gazebo/examples/worlds](https://github.com/ignitionrobotics/ign-gazebo/blob/ign-gazebo3/examples/worlds/) folder. ### Differential drive @@ -53,7 +53,7 @@ ign gazebo velocity_control.sdf --physics-engine ignition-physics-tpe-plugin # s ``` To control the car movement, in a separate terminal window, we publish a -\ref ignition::msgs::Twist "Twist" message using Ignition Transport library: +Twist message using Ignition Transport library: ```bash ign topic -t "/model/vehicle_blue/cmd_vel" -m ignition.msgs.Twist -p "linear: {x: 1.0}, angular: {z: 0.5}" @@ -65,7 +65,7 @@ This command tells the car to move in its coordinate frame with velocity second in Z-axis. Note that the mechanism to move the car is different depending on the used physics -engine, see \ref physicsengine "Use different physics engine" for details on how to change physics engine used by simulation. +engine, see \ref physicsengine "Use different physics engines" for details on how to change physics engine used by simulation. Dartsim moves the car by applying force on the joints, whereas TPE directly set velocity on the model. @@ -76,7 +76,7 @@ select the drop-down list `Pose`. Moreover, we could also read the model links' poses relative to their parent link by selecting the corresponding link on the model tree: -@image html img/diff_drive_link.gif +@image html img/diff_drive_link.gif width=100% Note that using the model tree as shown in the above gif, we can view the parameters and properties such as `visual` or `collision` of each link or joint @@ -89,7 +89,7 @@ Ignition Gazebo also simulates realistic collision effect. While the `vehicle_bl car is moving in a circle, we can move the `vehicle_green` to be on `vehicle_blue`'s upcoming path. The blue car will then push the green car in the following demo. -@image html img/diff_drive_collision.gif +@image html img/diff_drive_collision.gif width=100% To see where these collision parameters are set in SDFormat and how it works, please see this [SDFormat tutorial](http://sdformat.org/tutorials?tut=spec_shapes&cat=specification&). @@ -110,7 +110,7 @@ ign gazebo lift_drag.sdf ``` To see how the rotor lifts the cube due to wind force pressure, in a separate terminal window, we can publish a -\ref ignition::msgs::Double "Double" message represeting the torque (Nm) applying to +Double message represeting the torque (Nm) applying to the rotor rod axis: ```bash @@ -126,7 +126,7 @@ ign topic -t "/model/lift_drag_demo_model/joint/rod_1_joint/cmd_force" -m igniti You will see the cube drops due to no lift force from support torque on the rod, and the blades will stop after some time due to friction. -@image html img/lift_drag_torque.gif +@image html img/lift_drag_torque.gif width=100% Several simulation features come into effect in this demo. The lift and drag force is computed by taking the wind pressure, mass of the cude, and gravity into account, and the resulting force is exerted on multiple joints. Dartsim is used to power this demo. @@ -153,7 +153,7 @@ ign gazebo buoyancy.sdf After pressing the Play button, demo will run as below: -@image html img/buoyancy.gif +@image html img/buoyancy.gif width=100% The buoyancy concept is implemented by simulating fluid density and applying the force on the object in the fluid @@ -180,7 +180,7 @@ After pressing the Play button, you will see that the pendulum will oscillate ar its main revolute joint forever due to lack of friction (it is undeclared in the SDFormat file). -@image html img/pendulum.gif +@image html img/pendulum.gif width=100% The oscillation period or the max angular speed of the joint will change if we modify the inertia of the rods. According to the demo below, @@ -205,7 +205,7 @@ ign gazebo multicopter_velocity_control.sdf ``` To control the multicopter to ascend and hover, in a separate terminal window, send a -\ref ignition::msgs::Twist "Twist" message to command the `X3` multicopter +Twist message to command the `X3` multicopter ascending 0.1 m.s as follow: ```bash @@ -218,7 +218,7 @@ then hovering: ign topic -t "/X3/gazebo/command/twist" -m ignition.msgs.Twist -p " " ``` -@image html img/hover.gif +@image html img/hover.gif width=100% Do the same for the `X4` multicopter. After pressing the Play button, you will see both of the multicopters will ascend, this demonstrates how the physics engine diff --git a/tutorials/07-implementing-a-physics-plugin.md b/tutorials/07-implementing-a-physics-plugin.md index 80f29990b..95f9bd8a4 100644 --- a/tutorials/07-implementing-a-physics-plugin.md +++ b/tutorials/07-implementing-a-physics-plugin.md @@ -7,8 +7,8 @@ This tutorial shows how to develop a simple plugin that implements a ## Prerequisites - \ref installation "Installation" -- \ref physicsplugin "Understand physics plugin" -- \ref loadplugin "Load physics plugin" +- \ref physicsplugin "Understanding the physics plugin" +- \ref pluginloading "Loading physics plugins" ## Write a simple physics plugin @@ -44,7 +44,7 @@ Next, we use a dummy namespace `mock` and list all the features we would like to The plugin will be able to return its physics engine metadata. We will now implement our plugin class named `HelloWorldPlugin` -using the defined \ref ignition::physics::FeatureList `FeatureList` above. +using the defined \ref ignition::physics::FeatureList "FeatureList" above. The class is inherited from \ref ignition::physics::Implements3d "Implements3d" to declare that the plugin's `HelloWorldFeatureList` will be in the 3D coordinate system. @@ -53,11 +53,11 @@ coordinate system. Because we are not using a real physics engines, a dummy physics engines is defined inside member function `InitiateEngine` by simply setting the `engineName` to `HelloWorld`, -and returning the engine object using \ref ignition::physics::Identity. Then, we +and returning the engine object using `Identity`. Then, we define the metadata getters `GetEngineIndex` and `GetEngineName` for the feature \ref ignition::physics::GetEngineInfo "GetEngineInfo" (please look into corresponding public member functions defined in the subclasses). A list of other -pre-defined features are can be found in the [`GetEntities` FeatureList](https://ignitionrobotics.org/api/physics/2.0/GetEntities_8hh.html). +pre-defined features can be found in the [`GetEntities` FeatureList](https://ignitionrobotics.org/api/physics/2.0/GetEntities_8hh.html). Finally, we only have to register our plugin in Ignition Physics as a physics engine by: @@ -76,7 +76,7 @@ plugin provides, i.e. `HelloWorldFeatureList` Now create a file named `CMakeLists.txt` with your favorite editor and add these lines for finding `ign-plugin` and `ign-physics` dependencies for the Citadel release: -\snippet examples/hello_world_plugin/CMakeLists.txt +\include examples/hello_world_plugin/CMakeLists.txt ## Build and run @@ -104,7 +104,7 @@ and `HelloWorldPlugin.dll` on Windows. ### Test loading the plugin on Linux -Please first follow the \ref loadplugin "Load physics plugin" tutorial +Please first follow the \ref pluginloading "Loading physics plugins" tutorial to create a simple loader. Then we test our plugin using the loader as follow: ```bash diff --git a/tutorials/08-implementing-a-custom-feature.md b/tutorials/08-implementing-a-custom-feature.md index 4c2677e0d..03d06ca9d 100644 --- a/tutorials/08-implementing-a-custom-feature.md +++ b/tutorials/08-implementing-a-custom-feature.md @@ -3,13 +3,13 @@ ## Prerequisites - \ref installation "Installation" -- \ref physicsplugin "Understand physics plugin" -- \ref loadplugin "Load physics plugin" -- \ref implementfeature "Implement physics feature" +- \ref physicsplugin "Understanding the physics plugin" +- \ref pluginloading "Loading physics plugins" +- \ref createphysicsplugin "Implement a physics feature" ## Implement a custom feature in DART plugin -In the last \ref implementfeature "Implement physics feature" tutorial, we +In the last \ref createphysicsplugin "Implement a physics feature" tutorial, we know how to implement a dummy physics engine as a plugin and load it using \ref ignition::physics "Ignition Physics API". In this tutorial, we will look deeper into the structure of a physics engine plugin, for example, the available @@ -36,8 +36,7 @@ ign-physics └── CMakeLists.txt CMake build script. ``` -As shown above, there are two physics engines available (more detail -in \ref physicsplugin "Physics plugin tutorial"): +As shown above, there are two physics engines available: - **DART**: `ignition-physics-dartsim-plugin`. - **TPE**: `ignition-physics-tpe-plugin`. @@ -60,8 +59,7 @@ functionality of the external physics engine can be defined as a header in be added in a \ref ignition::physics::FeatureList "FeatureList" and implemented its functionalities in `src` folder. -The `dartsim` plugin's \ref ignition::physics::FeatureList "FeatureList" could be -found in \ref physicsplugin "Understand physics plugin" tutorial. +See the \ref physicsplugin "Understanding the physics plugin" tutorial for details on physics engines. ### Plugin and feature requirements @@ -137,7 +135,7 @@ will not run at the same time when requested. With the requirements and restrictions above, we first need to define a feature template for the custom feature. In this case, this feature will be responsible for retrieving world pointer from the physics engine. The template is placed in [World.hh](https://github.com/ignitionrobotics/ign-physics/blob/ign-physics2/dartsim/include/ignition/physics/dartsim/World.hh): -\snippet dartsim/include/ignition/physcis/dartsim/World.hh +\snippet dartsim/include/ignition/physics/dartsim/World.hh feature template The `RetrieveWorld` feature retrieves world pointer from physics engine, so we will use the `World` entity inherited @@ -174,7 +172,7 @@ implement the `RetrieveWorld` feature function using Dartsim API. After defining the feature template, we can add it to a custom \ref ignition::physics::FeatureList "FeatureList": -\snippet dartsim/src/CustomFeatures.hh +\snippet dartsim/src/CustomFeatures.hh add to list The custom feature `RetrieveWorld` is added to `CustomFeatureList`, other custom features could also be added here. @@ -188,7 +186,7 @@ custom feature with \ref ignition::physics::FeaturePolicy3d "FeaturePolicy3d" We will then implement the actual function with Dartsim API in [CustomFeatures.cc](https://github.com/ignitionrobotics/ign-physics/blob/ign-physics2/dartsim/src/CustomFeatures.cc) to override the member function declared in the custom feature header file: -\snippet dartsim/src/CustomFeatures.cc +\snippet dartsim/src/CustomFeatures.cc implementation Here, we implement the behavior of `GetDartsimWorld` with Dartsim API to return the world pointer from `EntityStorage` object storing world pointers of `dartsim` in @@ -197,8 +195,8 @@ world pointer from `EntityStorage` object storing world pointers of `dartsim` in In the end, we add the implemented `CustomFeatures` "FeatureList" together with other \ref ignition::physics::FeatureList "FeatureList" to final `DartsimFeatures` "FeatureList" as in [dartsim/src/plugin.cc](https://github.com/ignitionrobotics/ign-physics/blob/ign-physics2/dartsim/src/plugin.cc) -(please see \ref implementfeature "Implement physics feature" for -registering the plugin to Ignition Physics). +(please see the \ref createphysicsplugin "Implement a physics feature" tutorial +for registering the plugin to Ignition Physics). The folder structure is shown below: