Update the tf2 documentation (#638)

* include documentation folder

update API links to latest

change docs folder

move Doxyfile and update sphinx template

update conf file

* Remove unnecessary docs subdirectory.

We are going to make all of the changes in the existing
pages.

* Fixes to the Doxygen comments in the tf2 header files.

* Addition of the architecture to the front page.

* Add in a Doxyfile for tf2.

Signed-off-by: Chris Lalancette <[email protected]>
Co-authored-by: kurshakuz <[email protected]>

tf2/Doxyfile

@@ -1,7 +1,7 @@
 # All settings not listed here will use the Doxygen default values.
 
 PROJECT_NAME           = "tf2"
-PROJECT_NUMBER         = master
+PROJECT_NUMBER         = rolling
 PROJECT_BRIEF          = "tf2 maintains the relationship between coordinate frames in a tree \
 structure buffered in time, and lets the user transform points, vectors, etc between any two \
 coordinate frames at any desired point in time."
@@ -19,9 +19,5 @@ ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
 PREDEFINED             += TF2_PUBLIC=
-
-# Tag files that do not exist will produce a warning and cross-project linking will not work.
-TAGFILES += "../../../../doxygen_tag_files/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"
-# Consider changing "latest" to the version you want to reference (e.g. beta1 or 1.0.0)
-TAGFILES += "../../../../doxygen_tag_files/rcutils.tag=http://docs.ros2.org/latest/api/rcutils/"
-GENERATE_TAGFILE = "../../../../doxygen_tag_files/tf2.tag"
+PREDEFINED             += TF2SIMD_FORCE_INLINE=
+PREDEFINED             += ATTRIBUTE_ALIGNED16(class)=

tf2/include/tf2/buffer_core.h

@@ -96,12 +96,11 @@ class BufferCore : public BufferCoreInterface
   static const uint32_t MAX_GRAPH_DEPTH = 1000UL;
 
   /** Constructor
-   * \param interpolating Whether to interpolate, if this is false the closest value will be returned
    * \param cache_time How long to keep a history of transforms in nanoseconds
    *
    */
   TF2_PUBLIC
-  explicit BufferCore(tf2::Duration cache_time_ = BUFFER_CORE_DEFAULT_CACHE_TIME);
+  explicit BufferCore(tf2::Duration cache_time = BUFFER_CORE_DEFAULT_CACHE_TIME);
 
   TF2_PUBLIC
   virtual ~BufferCore(void);
@@ -242,6 +241,7 @@ class BufferCore : public BufferCoreInterface
 
   /**@brief Fill the parent of a frame.
    * @param frame_id The frame id of the frame in question
+   * @param time The timepoint of the frame in question
    * @param parent The reference to the string to fill the parent
    * Returns true unless "NO_PARENT" */
   TF2_PUBLIC
@@ -371,7 +371,7 @@ class BufferCore : public BufferCoreInterface
     const std::string & fixed_frame, tf2::Transform & transform, TimePoint & time_out) const;
 
   /** \brief An accessor to get a frame.
-   * \param frame_number The frameID of the desired Reference Frame
+   * \param c_frame_id The frameID of the desired Reference Frame
    */
   TimeCacheInterfacePtr getFrame(CompactFrameID c_frame_id) const;
 
@@ -397,8 +397,8 @@ class BufferCore : public BufferCoreInterface
     *   the current function and argument name being validated
     * \param frame_id name of the tf frame to validate
     * \return The CompactFrameID of the existing frame.
-    * \raises InvalidArgumentException if the frame_id string has an invalid format
-    * \raises LookupException if frame_id did not exist
+    * \throws InvalidArgumentException if the frame_id string has an invalid format
+    * \throws LookupException if frame_id did not exist
     */
   CompactFrameID validateFrameId(
     const char * function_name_arg,

tf2/include/tf2/convert.h

@@ -110,7 +110,7 @@ std::string getFrameId(const tf2::Stamped<P> & t)
  *
  * An implementation for WithCovarianceStamped<P> datatypes.
  *
- * \param[in] c The data input.
+ * \param[in] t The data input.
  * \return The covariance matrix associated with the data.
  */
 template<class P>
@@ -135,7 +135,7 @@ B toMsg(const A & a);
  * \param b the object to convert to
  */
 template<typename A, typename B>
-void fromMsg(const A &, B & b);
+void fromMsg(const A & a, B & b);
 
 /**\brief Function that converts any type to any type (messages or not).
  * Matching toMsg and from Msg conversion functions need to exist.

tf2/include/tf2/utils.h

@@ -41,7 +41,7 @@ void getEulerYPR(const A & a, double & yaw, double & pitch, double & roll)
  * This function is a specialization of getEulerYPR and is useful for its
  * wide-spread use in navigation
  * \param a the object to get data from (it represents a rotation/quaternion)
- * \param yaw yaw
+ * \return yaw
  */
 template<class A>
 double getYaw(const A & a)

tf2/mainpage.dox

@@ -1,36 +1,195 @@
 /**
 \mainpage
-\htmlinclude manifest.html
 
-\b tf2 is the second generation of the tf library.
+``tf2`` is the second generation of the tf library.
 
-This library implements the interface defined by tf2::BufferCore.
+This library implements the interface defined by `tf2::BufferCore`.
 
 There is also a Python wrapper with the same API that class this library using CPython bindings.
 
-\section codeapi Code API
+Some tutorials are available at <A HREF="http://docs.ros.org/en/rolling/Tutorials/Intermediate/Tf2/Tf2-Main.html">https://docs.ros.org/</A>.
 
-The main interface is through the tf2::BufferCore interface.
+\section architecture Architecture
 
-It uses the exceptions in exceptions.h and the Stamped datatype
-in transform_datatypes.h.
+``tf2`` is a transform library designed to provide implementation of interface that keeps track of multiple coordinate frames over time.
+``tf2`` maintains the relationship between coordinate frames in a tree structure buffered in time, and lets the user transform data between any two coordinate frames at any desired point in time.
+The high level goal is to allow developers and users not to have to worry about which coordinate frame any specific data is stored in.
 
-\section conversions Conversion Interface
+\subsection main-interface Main Interface
 
-tf2 offers a templated conversion interface for external libraries to specify conversions between
-tf2-specific data types and user-defined data types. Various templated functions in tf2_ros use the
-conversion interface to apply transformations from the tf server to these custom datatypes.
+The main interface is through the `tf2::BufferCore` interface.
+
+It uses the exceptions in tf2/exceptions.h and the `tf2::Stamped` datatype in tf2/transform_datatypes.h.
+
+\subsection conversion-interface Conversion Interface
+
+tf2 offers a templated conversion interface for external libraries to specify conversions between ``tf2``-specific data types and user-defined data types.
+Various templated functions in ``tf2_ros`` use the conversion interface to apply transformations from the tf server to these custom datatypes.
 
 The conversion interface is defined in tf2/convert.h.
 
-Some packages that implement this interface:
+\subsection buffer-core-relations Buffer Core: Record and lookup relations between frames
+
+The ``tf2`` library implements the interface defined by `tf2::BufferCore`.
+This class and all classes derived from it are responsible for providing coordinate transforms between any two frames in a system.
+This class provides a simple interface to allow recording and lookup of relationships between arbitrary frames of the system.
+
+``tf2`` assumes that there is a tree of coordinate frame transforms which define the relationship between all coordinate frames.
+After transformation relationships are supplied, query specifiyng target frame, source frame, and time point can be used to obtain required data.
+``tf2`` will take care of all the intermediate transfromation steps for specific queries.
+
+Additionally, ``tf2`` features data interpolation.
+The probability that a specific query would be at the same timestamp of all the frames in the system is very unlikely in an asynchronous system with nanosecond precision.
+Therefore, for any given query it can be expected that data is interpolated.
+
+It should be noted that buffer implicitly limits the maximum cache size of 10s by default as defined by the `tf2::TIMECACHE_DEFAULT_MAX_STORAGE_TIME` and it cannot interpolate outside of the cache history.
+Thus there is a risk of incurring extrapolation limits based on specific system.
+
+\subsubsection buffer-core-methods Buffer Core Methods
+
+The `tf2::BufferCore` class contains useful methods to update the existing tf buffer.
+
+- `tf2::BufferCore::clear`
+
+  - This method clears all data in the buffer.
+
+- `tf2::BufferCore::setTransform`
+
+  - This method will add `geometry_msgs::msg::TransformStamped` information to the tf data structure.
+
+- `tf2::BufferCore::lookupTransform`
+
+  - This method returns the transform between two frames by frame ID.
+  - Possible exceptions are `tf2::LookupException`, `tf2::ConnectivityException`, `tf2::ExtrapolationException`, or `tf2::InvalidArgumentException`.
+
+- `tf2::BufferCore::canTransform`
+
+  - This method tests if a transform is possible.
+
+- `tf2::BufferCore::getAllFrameNames`
+
+  - This method returns all frames that exist in the system.
+
+- `tf2::BufferCore::allFramesAsYAML`
+
+  - This method allows to see what frames have been cached in yaml format and is useful for debugging tools.
+
+- `tf2::BufferCore::allFramesAsString`
+
+  - This method allows to see what frames have been cached and is useful for debugging.
+
+\subsection supported-datatypes Supported Datatypes
+
+``tf2`` implements templated datatype support.
+This allows the core packages to have minimal dependencies and there be packages which add support for converting to and from different datatypes as well as transforming those data types.
+``tf2`` does have an internal datatypes which are based on bullet's LinearMath library.
+However it's recommended to use a fully supported math datatype which best supports your application.
+``tf2`` conversion methods also support converting between and transforming between multiple different datatypes too.
+
+At it's core ``tf2`` relies on the `tf2::Stamped` data types which can be conveniently correlated to ROS 2 messages which have a `std_msgs::msg::Header`.
+
+\subsubsection data-type-support-packages Data Type Support Packages
+
+These packages provide methods to allow ``tf2`` to work natively with data types of any external library.
+Most are either C++ or Python specific.
 
 - tf2_bullet
+
+  - ``tf2`` methods to work with bullet datatypes natively in C++.
+
 - tf2_eigen
+
+  - ``tf2`` methods to work with Eigen datatypes natively in C++.
+
 - tf2_geometry_msgs
+
+  - ``tf2`` methods to work with `geometry_msgs` datatypes natively in C++ or Python.
+
 - tf2_kdl
+
+  - ``tf2`` methods to work with kdl datatypes natively in C++ or Python.
+
 - tf2_sensor_msgs
 
-Some tutorials are available at <A HREF="https://docs.ros.org/en/rolling/Tutorials/tf2.html">https://docs.ros.org/</A>.
+  - ``tf2`` methods to work with sensor_msgs datatypes natively in C++ or Python.
+
+\subsection coordinate-frame-conventions Coordinate Frame Conventions
+
+An important part of using ``tf2`` is to use standard conventions for coordinate frames.
+There are several sources of conventions for using coordinate frames.
+
+- Units, orientation conventions, chirality, rotation representations, and covariance representations are covered in <a href=https://www.ros.org/reps/rep-0103.html>REP 103</a>.
+
+- Standard names for mobile base coordinate frames are covered in <a href=https://www.ros.org/reps/rep-0105.html>REP 105</a>.
+
+- Standard coordinate frames for Humanoid Robots are in <a href=https://www.ros.org/reps/rep-0120.html>REP 120</a>.
+
+\subsection geometry Geometry
+
+``tf2`` provides basic geometry data types, such as
+
+  - `tf2::Vector3`
+
+  - `tf2::Matrix3x3`
+
+  - `tf2::Quaternion`
+
+  - `tf2::Transform`
+
+These data types support linear algebra operations between each other.
+
+\subsection high-level-design High level Design
+
+- A distributed system:
+
+  - Purpose: No bottle neck process and all processes are one step away for minimal latency.
+  - Implementation: Everything is broadcast and reassembled at end consumer points.
+    There can be multiple data sources for tf information.
+    Data is not required to be synchronized by using interpolation, so data can arrive out of order.
+
+- Only transform data between coordinate frames at the time of use:
+
+  - Purpose: Efficiency, both computational, bandwidth, and simplicity.
+  - Implementation: Transform data between given frames only when required.
+
+- Support queries on data which are timestamped at times other than the current time:
+
+  - Purpose: Handle data processing lag gracefully.
+  - Implementation: Interface class stores all transform data in memory and traverses tree on request.
+
+- Only have to know the name of the coordinate frame to work with data:
+
+  - Purpose: Ease of use for users/developers.
+  - Implementation: Use string ``frame_ids`` as unique identifiers.
+
+- The system doesn't need to know about the configuration before hand and can handle reconfiguring on the fly:
+
+  - Purpose: Generic system for any configuration.
+  - Implementation: Use directed tree structure.
+    It allows fast traversal (order ``n`` where ``n`` is the depth of the tree) when evaluating a transform.
+    It can be reconfigured simply by redefining a link.
+    It does not require any structure verification or maintenance of the data structure, except for maintaining a sorted linked list of data for each link.
+
+- Core is ROS agnostic:
+
+  - Purpose: Code reuse.
+  - Implementation: Core library is C++ class.
+    A second class provides ROS interface and instantiates the core library.
+
+- Thread Safe Interface:
+
+  - Purpose: Can be used in a multithreaded program.
+  - Implementation: Mutexes around data storage for each frame.
+    Mutexes around ``frame_id`` lookup map.
+    Each are individually locked and unlocked, neither can block the other.
+
+- Native Datatype Interfaces:
+
+  - Purpose: Users can interact with ``tf2_ros`` in their native datatypes, the conversion is handled implicitly by the library.
+  - Implementation: There is a `tf2::convert` templated method that converts from type A to type B using the geometry_msgs types as the common factor.
+
+  And as long as any datatype provides the methods ``msgType toMsg(datatype)`` and ``fromMsg(msgType, datatype)`` it can be automatically converted to any other datatype with the same methods defined and a matching ``msgType``.
+  All ``tf2_ros`` interfaces can then be called with native type in and native type out.
+  Note, the native type in and out do not need to match.
 
 */