New example: get an ECM snapshot from an external program (#859)

Signed-off-by: Louise Poubel <louise@openrobotics.org>

examples/standalone/external_ecm/CMakeLists.txt

@@ -0,0 +1,8 @@
+cmake_minimum_required(VERSION 3.10.2 FATAL_ERROR)
+
+find_package(ignition-gazebo3 REQUIRED)
+
+add_executable(external_ecm external_ecm.cc)
+target_link_libraries(external_ecm
+  ignition-gazebo3::core)
+

examples/standalone/external_ecm/README.md

@@ -0,0 +1,93 @@
+# External ECM
+
+Example showing how to get a snapshot of all entities and components in a
+running simulation from an external program using the state message.
+
+## Build
+
+From the root of the `ign-gazebo` repository, do the following to build the example:
+
+~~~
+cd ign-gazebo/examples/standalone/external_ecm
+mkdir build
+cd build
+cmake ..
+make
+~~~
+
+This will generate the `external_ecm` executable under `build`.
+
+## Run
+
+Start a simulation, for example:
+
+    ign gazebo shapes.sdf
+
+On another terminal, run the `external_ecm` executable, passing the name of the
+running world you want to inspect:
+
+  cd ign-gazebo/examples/standalone/external_ecm
+  ./external_ecm shapes
+
+You should see something like this:
+
+```
+$ ./external_ecm shapes
+
+Requesting state for world [shapes] on service [/world/shapes/state]...
+
+Entity [1]
+  - Name: shapes
+  - Parent:
+Entity [4]
+  - Name: ground_plane
+  - Parent: shapes [1]
+Entity [5]
+  - Name: link
+  - Parent: ground_plane [4]
+Entity [6]
+  - Name: visual
+  - Parent: link [5]
+Entity [7]
+  - Name: collision
+  - Parent: link [5]
+Entity [8]
+  - Name: box
+  - Parent: shapes [1]
+Entity [9]
+  - Name: box_link
+  - Parent: box [8]
+Entity [10]
+  - Name: box_visual
+  - Parent: box_link [9]
+Entity [11]
+  - Name: box_collision
+  - Parent: box_link [9]
+Entity [12]
+  - Name: cylinder
+  - Parent: shapes [1]
+Entity [13]
+  - Name: cylinder_link
+  - Parent: cylinder [12]
+Entity [14]
+  - Name: cylinder_visual
+  - Parent: cylinder_link [13]
+Entity [15]
+  - Name: cylinder_collision
+  - Parent: cylinder_link [13]
+Entity [16]
+  - Name: sphere
+  - Parent: shapes [1]
+Entity [17]
+  - Name: sphere_link
+  - Parent: sphere [16]
+Entity [18]
+  - Name: sphere_visual
+  - Parent: sphere_link [17]
+Entity [19]
+  - Name: sphere_collision
+  - Parent: sphere_link [17]
+Entity [20]
+  - Name: sun
+  - Parent: shapes [1]
+```

examples/standalone/external_ecm/external_ecm.cc

@@ -0,0 +1,98 @@
+/*
+ * 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/gazebo/EntityComponentManager.hh>
+#include <ignition/gazebo/components/Name.hh>
+#include <ignition/gazebo/components/ParentEntity.hh>
+#include <ignition/msgs/serialized.pb.h>
+#include <ignition/transport/Node.hh>
+
+//////////////////////////////////////////////////
+int main(int argc, char **argv)
+{
+  if (argc < 2)
+  {
+    std::cout << "Usage: `./external_ecm <world name>`" << std::endl;
+    return -1;
+  }
+
+  // Get arguments
+  std::string world = argv[1];
+
+  // Create a transport node.
+  ignition::transport::Node node;
+
+  bool executed{false};
+  bool result{false};
+  unsigned int timeout{5000};
+  std::string service{"/world/" + world + "/state"};
+
+  std::cout << std::endl << "Requesting state for world [" << world
+            << "] on service [" << service << "]..." << std::endl << std::endl;
+
+  // Request and block
+  ignition::msgs::SerializedStepMap res;
+  executed = node.Request(service, timeout, res, result);
+
+  if (!executed)
+  {
+    std::cerr << std::endl << "Service call to [" << service << "] timed out"
+              << std::endl;
+    return -1;
+  }
+
+  if (!result)
+  {
+    std::cerr << std::endl << "Service call to [" << service << "] failed"
+              << std::endl;
+    return -1;
+  }
+
+  // Instantiate an ECM and populate with data from message
+  ignition::gazebo::EntityComponentManager ecm;
+  ecm.SetState(res.state());
+
+  // Print some information
+  ecm.Each<ignition::gazebo::components::Name>(
+      [&](const ignition::gazebo::Entity &_entity,
+          const ignition::gazebo::components::Name *_name) -> bool
+  {
+    auto parentComp =
+        ecm.Component<ignition::gazebo::components::ParentEntity>(_entity);
+
+    std::string parentInfo;
+    if (parentComp)
+    {
+      auto parentNameComp =
+          ecm.Component<ignition::gazebo::components::Name>(
+          parentComp->Data());
+
+      if (parentNameComp)
+      {
+        parentInfo += parentNameComp->Data() + " ";
+      }
+      parentInfo += "[" + std::to_string(parentComp->Data()) + "]";
+    }
+
+    std::cout << "Entity [" << _entity << "]" << std::endl
+              << "  - Name: " << _name->Data() << std::endl
+              << "  - Parent: " << parentInfo << std::endl;
+
+    return true;
+  });
+}