[Citadel] Update tutorials (gazebosim#204)

Signed-off-by: claireyywang <22240514+claireyywang@users.noreply.github.com> Signed-off-by: anindex <an.thai.le97@gmail.com> Co-authored-by: anindex <an.thai.le97@gmail.com> Co-authored-by: Louise Poubel <louise@openrobotics.org> Co-authored-by: Claire Wang <22240514+claireyywang@users.noreply.github.com> Co-authored-by: Steve Peters <scpeters@openrobotics.org>
scpeters · May 3, 2021 · 966b7ec · 966b7ec
1 parent 671ee8c
commit 966b7ec
Show file tree

Hide file tree

Showing 27 changed files with 592 additions and 413 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -110,3 +110,5 @@ ign_create_docs(
     "${IGNITION-PLUGIN_DOXYGEN_TAGFILE} = ${IGNITION-PLUGIN_API_URL}"
     "${IGNITION-MATH_DOXYGEN_TAGFILE} = ${IGNITION-MATH_API_URL}"
   )
+
+file(COPY ${CMAKE_SOURCE_DIR}/tutorials/img/ DESTINATION ${CMAKE_BINARY_DIR}/doxygen/html/img/)
diff --git a/examples/hello_world_loader/hello_world_loader.cc b/examples/hello_world_loader/hello_world_loader.cc
@@ -15,6 +15,8 @@
  *
 */
 
+////////////////////////////////////////////////////////////////////
+//! [include statements]
 #include <iostream>
 
 #include <ignition/plugin/Loader.hh>
@@ -28,7 +30,10 @@
 using Features = ignition::physics::FeatureList<
     ignition::physics::GetEngineInfo
 >;
+//! [include statements]
 
+////////////////////////////////////////////////////////////////////
+//! [main]
 int main(int argc, char **argv)
 {
   // User should provide path to plugin library
@@ -62,3 +67,4 @@ int main(int argc, char **argv)
     std::cout << "  engine name: " << engine->GetName() << std::endl;
   }
 }
+//! [main]
diff --git a/examples/hello_world_plugin/HelloWorldPlugin.cc b/examples/hello_world_plugin/HelloWorldPlugin.cc
@@ -15,18 +15,26 @@
  *
 */
 
+////////////////////////////////////////////////////////////
+//! [include statements]
 #include <ignition/physics/FeatureList.hh>
 #include <ignition/physics/FeaturePolicy.hh>
 #include <ignition/physics/GetEntities.hh>
 #include <ignition/physics/Register.hh>
+//! [include statements]
 
 namespace mock
 {
+  ////////////////////////////////////////////////////////
+  //! [feature list]
   // List of all features that this plugin will implement
   struct HelloWorldFeatureList : ignition::physics::FeatureList<
       ignition::physics::GetEngineInfo
   > { };
+  //! [feature list]
 
+  ////////////////////////////////////////////////////////
+  //! [implementation]
   // The plugin class, which implements a 3D policy
   class HelloWorldPlugin
       : public ignition::physics::Implements3d<HelloWorldFeatureList>
@@ -52,10 +60,14 @@ namespace mock
 
     std::string engineName;
   };
+  //! [implementation]
 
+  ////////////////////////////////////////////////////////
+  //! [register]
   // Register plugin
   IGN_PHYSICS_ADD_PLUGIN(
       HelloWorldPlugin,
       ignition::physics::FeaturePolicy3d,
       HelloWorldFeatureList)
+  //! [register]
 }
diff --git a/examples/simple_plugin/CMakeLists.txt b/examples/simple_plugin/CMakeLists.txt
@@ -0,0 +1,20 @@
+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)
+
+add_library(SimplePlugin SHARED plugin.cc EntityManagementFeatures.cc)
+target_link_libraries(SimplePlugin
+  PRIVATE
+    ignition-physics${IGN_PHYSICS_VER}::ignition-physics${IGN_PHYSICS_VER})
+
+add_executable(PluginTest EntityManagementFeatures_TEST.cc)
+target_link_libraries(PluginTest
+  ignition-plugin${IGN_PLUGIN_VER}::loader
+  ignition-physics${IGN_PHYSICS_VER}::ignition-physics${IGN_PHYSICS_VER})
+
+target_compile_definitions(PluginTest PRIVATE
+  "simple_plugin_LIB=\"$<TARGET_FILE:SimplePlugin>\"")
diff --git a/examples/simple_plugin/EntityManagementFeatures.cc b/examples/simple_plugin/EntityManagementFeatures.cc
@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2021 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+#include <string>
+#include "EntityManagementFeatures.hh"
+
+using namespace ignition;
+using namespace physics;
+using namespace simpleplugin;
+
+/////////////////////////////////////////////////
+Identity EntityManagementFeatures::ConstructEmptyWorld(
+  const Identity &, const std::string &_name)
+{
+  // Generate dummy identity
+  return this->GenerateIdentity(0);
+}
diff --git a/examples/simple_plugin/EntityManagementFeatures.hh b/examples/simple_plugin/EntityManagementFeatures.hh
@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2021 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+//! [basic include]
+#include <string>
+#include <ignition/physics/Implements.hh>
+//! [basic include]
+
+//! [include feature]
+#include <ignition/physics/ConstructEmpty.hh>
+
+namespace ignition {
+namespace physics {
+namespace simpleplugin {
+
+struct EntityManagementFeatureList : FeatureList<
+  ConstructEmptyWorldFeature
+> { };
+
+//! [include feature]
+
+//! [override feature]
+class EntityManagementFeatures :
+  public virtual Implements3d<EntityManagementFeatureList>
+{
+  /// \brief Construct an empty dummy world.
+  /// \param[in] _engineID Identity for the engine.
+  /// \param[in] _name Name of the world.
+  public: Identity ConstructEmptyWorld(
+    const Identity &_engineID, const std::string &_name) override;
+};
+
+}
+}
+}
+//! [override feature]
diff --git a/examples/simple_plugin/EntityManagementFeatures_TEST.cc b/examples/simple_plugin/EntityManagementFeatures_TEST.cc
@@ -0,0 +1,60 @@
+/*
+ * Copyright (C) 2021 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+#include <iostream>
+
+#include <ignition/plugin/Loader.hh>
+#include <ignition/physics/RequestEngine.hh>
+#include "EntityManagementFeatures.hh"
+
+// Simple executable that loads the simple plugin and constructs a world.
+
+struct TestFeatureList : ignition::physics::FeatureList<
+  ignition::physics::simpleplugin::EntityManagementFeatureList
+> { };
+
+int main(int argc, char *argv[])
+{
+  // Load the custom plugin
+  ignition::plugin::Loader loader;
+  loader.LoadLib(simple_plugin_LIB);
+
+  auto simplePlugin =
+    loader.Instantiate("ignition::physics::simpleplugin::Plugin");
+
+  // Get the engine pointer
+  auto engine =
+      ignition::physics::RequestEngine3d<TestFeatureList>::From(simplePlugin);
+
+  if (nullptr == engine)
+  {
+    std::cerr << "Something went wrong, the engine is null" << std::endl;
+    return -1;
+  }
+
+  auto world = engine->ConstructEmptyWorld("empty world");
+
+  if (nullptr == world)
+  {
+    std::cerr << "Failed to create empty world" << std::endl;
+    return -1;
+  }
+
+  std::cout << "Created empty world!" << std::endl;
+
+  return 0;
+}
diff --git a/examples/simple_plugin/plugin.cc b/examples/simple_plugin/plugin.cc
@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) 2021 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+#include <ignition/physics/FeatureList.hh>
+#include <ignition/physics/FeaturePolicy.hh>
+#include <ignition/physics/Register.hh>
+
+#include "EntityManagementFeatures.hh"
+
+namespace ignition {
+namespace physics {
+namespace simpleplugin {
+
+  struct SimplePluginFeatures : FeatureList<
+    EntityManagementFeatureList
+  > { };
+
+  class Plugin :
+    public virtual EntityManagementFeatures,
+    public virtual Implements3d<SimplePluginFeatures>
+  {
+    using Identity = ignition::physics::Identity;
+    public: Identity InitiateEngine(std::size_t /*_engineID*/) override
+    {
+      return this->GenerateIdentity(0);
+    }
+  };
+
+  IGN_PHYSICS_ADD_PLUGIN(Plugin, FeaturePolicy3d, SimplePluginFeatures)
+
+}
+}
+}
diff --git a/include/ignition/physics/ConstructEmpty.hh b/include/ignition/physics/ConstructEmpty.hh
@@ -26,6 +26,7 @@ namespace ignition {
 namespace physics {
 
 /////////////////////////////////////////////////
+//! [ConstructEmptyWorld]
 /// \brief This feature constructs an empty world and return its pointer
 /// from the current physics engine in use.
 class ConstructEmptyWorldFeature : public virtual Feature
@@ -48,6 +49,7 @@ class ConstructEmptyWorldFeature : public virtual Feature
         const Identity &_engineID, const std::string &_name) = 0;
   };
 };
+//! [ConstructEmptyWorld]
 
 /////////////////////////////////////////////////
 /// \brief This feature constructs an empty model and return its pointer

diff --git a/tutorials.md.in b/tutorials.md.in
@@ -9,11 +9,11 @@ Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively.
 
 1. \subpage introduction "Introduction"
 2. \subpage installation "Installation"
-3. \subpage physicsplugin "Understanding the Physics Plugin"
-4. \subpage switchphysicsengines "Switching physics engines"
-5. \subpage pluginloading "Loading a Physics Plugin"
+3. \subpage physicsplugin "Understanding the physics plugin"
+4. \subpage physicsengine "Use different physics engines"
+5. \subpage pluginloading "Loading physics plugins"
 6. \subpage physicsconcepts "Ignition Physics simulation concepts"
-7. \subpage createphysicsplugin "Implement a physics plugin"
+7. \subpage createphysicsplugin "Implement a physics feature"
 8. \subpage createcustomfeature "Implement a custom feature"
 9. \subpage setupphysicsenginetpe "Use custom engine with Ignition Physics"
 

diff --git a/tutorials/01_intro.md b/tutorials/01_intro.md
@@ -20,17 +20,15 @@ Ignition Physics extensibility and modularity.
 For a big picture of the Ignition Physics operation in Ignition ecosystem, see
 the abstract diagram below:
 
-<img src="https://user-images.githubusercontent.com/18066876/94801505-6bbf6980-03e6-11eb-97e5-e5f0dc68229f.png"/>
+@image html img/ign-libraries.png
 
 In general, `ign-gazebo` is the main simulation library, in which its
 functionalities are powered by many component libraries.
 For example, its graphical drawing is supported by `ign-rendering` or simulated
 sensors that are defined and implemented in `ign-sensors`.
 In particular, this library `ign-physics` provides an abstract interface to
 physics engines, which simulates dynamic transformations and interactions of
-objects in `ign-gazebo`.
-The communication between these libraries at runtime is provided by
-`ign-transport` and `ign-msgs`.
+objects in `ign-gazebo`. The libraries are connected by C++ code.
 
 Ignition Physics uses a plugin architecture where each physics engine is
 implemented as a plugin that can be loaded at runtime.
@@ -64,15 +62,17 @@ to \ref physicsplugin
 ### Features logs
 
 **Ignition Physics 1.x**
+
 - Initial release
 - Define base concepts: Entity, FeaturePolicy, Feature and FeatureList.
 - Add features for `dartsim` physics engines (more detail in \ref physicsplugin).
 - Add RequestFeatures API for casting the features of an entity to a new feature set when possible.
 - Enforce joint effort limit in `dartsim-plugin`.
 
 **Ignition Physics 2.x**
-- Support sdformat 1.7 frame semantics.
-- Support compiling against dart 6.9.
+
+- Support SDFormat 1.7 frame semantics.
+- Support compiling against DART 6.9.
 - Trivial Physics Engine (TPE)- partial implementation
 - Add features for TPE physics engines (more detail in \ref physicsplugin).
 - Extend contact data with force, normal, and penetration depth.