Implement SDFormat 1.8 Interface API

include/sdf/CMakeLists.txt

@@ -23,6 +23,12 @@ set (headers
   Gui.hh
   Heightmap.hh
   Imu.hh
+  InterfaceElements.hh
+  InterfaceFrame.hh
+  InterfaceJoint.hh
+  InterfaceLink.hh
+  InterfaceModel.hh
+  InterfaceModelPoseGraph.hh
   Joint.hh
   JointAxis.hh
   Lidar.hh

include/sdf/InterfaceElements.hh

@@ -0,0 +1,125 @@
+/*
+ * Copyright 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.
+ *
+ */
+#ifndef SDF_INTERFACE_ELEMENTS_HH_
+#define SDF_INTERFACE_ELEMENTS_HH_
+
+#include <string>
+#include <memory>
+
+#include <ignition/math/Pose3.hh>
+
+#include "sdf/Element.hh"
+#include "sdf/InterfaceModel.hh"
+#include "sdf/Types.hh"
+
+#include "sdf/sdf_config.h"
+#include "sdf/system_util.hh"
+
+namespace sdf
+{
+inline namespace SDF_VERSION_NAMESPACE
+{
+/// \brief Contains the necessary information about an included model file
+/// for custom model parsers to be able to find the file and parse it.
+struct SDFORMAT_VISIBLE NestedInclude
+{
+  /// \brief Provides the URI as specified in `//include/uri`. This may or may
+  /// not end with a file extension (it will not end with an extension if it
+  /// refers to a model package).
+  std::string uri;
+
+  /// \brief Provides the *resolved* absolute file path from the URI.
+  /// It is recommended to use this in `CustomModelParser` when checking
+  /// predicates on filenames -- however, the predicates should generally only
+  /// check the file extension.
+  std::string resolvedFileName;
+
+  /// \brief Name of the parent entity in absolute hierarchy.
+  /// Example: if the interface model's name is
+  /// `top_model::middle_model::my_new_model`, the absoluteParentName would be
+  /// `top_model::middle_model`. If the parent entity is the world, this would
+  /// be an empty string.
+  std::string absoluteParentName;
+
+  /// \brief Name relative to immediate parent as specified in
+  /// `//include/name`. This is nullopt if `//include/name` is not set. Then the
+  /// name of the model must be determined by the custom model parser from the
+  /// included model file.
+  /// Example: `my_new_model`
+  std::optional<std::string> localModelName;
+
+  /// \brief Whether the model is static as defined by `//include/static`. This
+  /// is nullopt if `//include/static` is not set.
+  std::optional<bool> isStatic;
+
+  /// \brief The raw pose as specified in //include/pose. This is nullopt if
+  /// `//include/pose` is not set.
+  std::optional<ignition::math::Pose3d> includeRawPose;
+
+  /// \brief The relative-to frame of the pose as specified in
+  /// `//include/pose/@relative_to`. This is nullopt if
+  /// `//include/pose/@relative_to` is not set.
+  std::optional<std::string> includePoseRelativeTo;
+
+  /// \brief The placement frame as specified in `//include/placement_frame`.
+  /// This is nullopt if `//include/placement_frame` is is not set.
+  std::optional<std::string> placementFrame;
+
+  /// This is the `//include` element. This can be used to pass custom elements
+  /// and attributes to the custom model parser.
+  sdf::ElementPtr includeElement;
+};
+
+/// Defines a custom model parser.
+///
+/// Every custom model parser should define it's own way of (quickly)
+/// determining if it should parse a model. This should generally be done by
+/// looking at the file extension of `include.resolvedFileName`, and
+/// returning nullptr if it doesn't match a given criteria.
+///
+/// Custom model parsers are visited in the *reverse* of how they are defined.
+/// The latest parser gains precedence.
+///
+/// Custom model parsers are *never* checked if resolved file extension ends
+/// with `*.sdf` or `*.world`.
+/// If libsdformat encounters a `*.urdf` file, it will first check custom
+/// parser. If no custom parser is found, it will then convert the URDF XML to
+/// SDFormat XML, and parse it as an SDFormat file.
+///
+/// \param[in] include The parsed //include information from which this model
+///   should be parsed.
+/// \param[out] errors Errors encountered during custom parsing.
+///   If any errors are reported, this must return nullptr.
+/// \return An optional ModelInterface.
+///   * If not nullptr, the returned model interface is incorporated into the
+///     existing model and its frames are exposed through the frame graph.
+///   * If nullptr and no errors are reported, then libsdformat should
+///     continue testing out other custom parsers registered under the same
+///     extension (e.g. a parser for `.yaml`, which may cover many different
+///     schemas).
+///
+/// If an exception is raised by this callback, libsdformat will *not* try to
+/// intercept the exception.
+///
+/// To see an example implementation, please refer to
+/// test/integration/interface_api.cc
+using CustomModelParser =
+    std::function<sdf::InterfaceModelPtr(const sdf::NestedInclude &, Errors &)>;
+}
+}
+
+#endif

include/sdf/InterfaceFrame.hh

@@ -0,0 +1,65 @@
+/*
+ * Copyright 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.
+ *
+ */
+
+#ifndef SDF_INTERFACE_FRAME_HH_
+#define SDF_INTERFACE_FRAME_HH_
+
+#include <string>
+
+#include <ignition/math/Pose3.hh>
+#include <ignition/utils/ImplPtr.hh>
+
+#include "sdf/sdf_config.h"
+#include "sdf/system_util.hh"
+
+namespace sdf
+{
+inline namespace SDF_VERSION_NAMESPACE
+{
+/// \brief Interface element representing an explicit frame
+class SDFORMAT_VISIBLE InterfaceFrame
+{
+  /// \brief Constructor
+  /// \param[in] _name The *local* name.
+  /// \param[in] _attachedTo Name of the attached-to frame. This cannot be an
+  /// empty string. If the frame is attached to the model frame, this must be
+  /// "__model__" . The (implicit or explicit) frame must exist in the scope of
+  /// this frame.
+  /// \param[in] _pose The pose of the frame relative to the attached-to frame.
+  public: InterfaceFrame(const std::string &_name,
+      const std::string &_attachedTo, const ignition::math::Pose3d &_pose);
+
+  /// \brief Get the name of the frame.
+  /// \return Local name of the frame.
+  public: const std::string &Name() const;
+
+  /// \brief Get the name of the coordinate frame to which this frame is
+  /// attached.
+  /// \return The name of the attached-to frame.
+  public: const std::string &AttachedTo() const;
+
+  /// \brief Get the pose of this frame relative to the attached-to frame.
+  /// \return The pose of this frame in the attached-to frame.
+  public: const ignition::math::Pose3d &PoseInAttachedToFrame() const;
+
+  /// \brief Private data pointer.
+  IGN_UTILS_IMPL_PTR(dataPtr)
+};
+}
+}
+
+#endif

include/sdf/InterfaceJoint.hh

@@ -0,0 +1,61 @@
+/*
+ * Copyright 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.
+ *
+ */
+
+#ifndef SDF_INTERFACE_JOINT_HH_
+#define SDF_INTERFACE_JOINT_HH_
+
+#include <string>
+
+#include <ignition/math/Pose3.hh>
+#include <ignition/utils/ImplPtr.hh>
+
+#include "sdf/sdf_config.h"
+#include "sdf/system_util.hh"
+
+namespace sdf
+{
+inline namespace SDF_VERSION_NAMESPACE
+{
+/// \brief Interface element representing a Joint
+class SDFORMAT_VISIBLE InterfaceJoint
+{
+  /// \brief Constructor
+  /// \param[in] name The *local* name.
+  /// \param[in] _childName Name of the child link or frame.
+  /// \param[in] _pose The pose of the joint relative to the child frame.
+  public: InterfaceJoint(const std::string &_name,
+      const std::string &_childName, const ignition::math::Pose3d &_pose);
+
+  /// \brief Get the name of the joint.
+  /// \return Local name of the joint.
+  public: const std::string &Name() const;
+
+  /// \brief Get the name of the joint's child.
+  /// \return The name of the joint's child link or frame.
+  public: const std::string &ChildName() const;
+
+  /// \brief Get the pose of this joint in the child frame.
+  /// \return The pose of this joint in the child frame.
+  public: const ignition::math::Pose3d &PoseInChildFrame() const;
+
+  /// \brief Private data pointer.
+  IGN_UTILS_IMPL_PTR(dataPtr)
+};
+}
+}
+
+#endif

include/sdf/InterfaceLink.hh

@@ -0,0 +1,56 @@
+/*
+ * Copyright 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.
+ *
+ */
+
+#ifndef SDF_INTERFACE_LINK_HH_
+#define SDF_INTERFACE_LINK_HH_
+
+#include <string>
+
+#include <ignition/math/Pose3.hh>
+#include <ignition/utils/ImplPtr.hh>
+
+#include "sdf/sdf_config.h"
+#include "sdf/system_util.hh"
+
+namespace sdf
+{
+inline namespace SDF_VERSION_NAMESPACE
+{
+/// \brief Interface element representing a Link
+class SDFORMAT_VISIBLE InterfaceLink
+{
+  /// \brief Constructor
+  /// \param[in] name The *local* name.
+  /// \param[in] _pose The pose of the link relative to model frame.
+  public: InterfaceLink(
+              const std::string &_name, const ignition::math::Pose3d &_pose);
+
+  /// \brief Get the name of the link.
+  /// \return Local name of the link.
+  public: const std::string &Name() const;
+
+  /// \brief Get the pose of this link in the parent model frame.
+  /// \return The pose of this link in the parent model frame.
+  public: const ignition::math::Pose3d &PoseInModelFrame() const;
+
+  /// \brief Private data pointer.
+  IGN_UTILS_IMPL_PTR(dataPtr)
+};
+}
+}
+
+#endif