📚 Backward incompatibility: `mrs_lib::Transformer` API changes, please README

[matemat13]

This change is of interest to all users of the mrs_lib::Transformer class. If you don't use it, you can safely ignore this message.

Summary of changes

The mrs_lib pull request #37 redefines the API of the mrs_lib::Transformer helper class to be more clear to newcomers and more general. It doesn't remove any functionality, but most of the special features like automatic prefixing of frames or default frame name deduction are now disabled by default so that it behaves in a more expectable manner.

Refactoring guide

General changes

• The transformSingle(to_frame, what) methods' signature was changed to transformSingle(what, to_frame) (switched the order of parameters) to be in line with the mnemonic "transform a single thing - what, to where".
• To be consistent with the previous change, the signature of the transform(tf, what) method was also changed to transform(what, tf).
• The transformHeaderless(tf, what) was removed. The case of variables without a header member is now handled natively by the regular transform(what, tf) method using template meta-programming. So just use transform(what, tf) for everything.
• The resolveFrameName(frame) was renamed to resolveFrame(frame) to be consistent in nomenclature with the rest of the class.
• The method setCurrentLatLon(lat, lon) was renamed to setLatLon(lat, lon).
• A new variant of the constructor with ros::NodeHandle as a parameter is now provided. You can use it to make sure that the topics are subscribed using your node handle.
• The Transformer(node_name, uav_name) constructor is now removed (see below).
• The getTransform() method overloads now return an std::optional<geometry_msgs::TransformStamped> instead (see below).

Default prefixing of frame name with a namespace

Originally, you could specify the uav_name in the Transformer(node_name, uav_name) constructor. This constructor was removed. Instead of uav_name, you can now specify the default prefix anytime using the setDefaultPrefix(prefix) method. You can clear the default prefix by calling this method with an empty string (nothing will be prefixed).

By default, the prefix is not set. If the default prefix is set and it is not empty, it will be prefixed to any frame name not starting with the prefix. Otherwise, the frame name will be unchanged.

Default frame name

The functionality originally called setCurrentControlFrame(frame) is now renamed to setDefaultFrameName(frame) to be more general, since the "current control frame" doesn't make sense in many applications.

If any frame name supplied to the Transformer is an empty string, the default frame name will be used instead (no further prefix will be applied to it).

Retrying transformation lookup with newest timestamp

In the original implementation, if the lookup of a transformation with the specified timestamp failed, it was automatically retried with ros::Time(0) as the timestamp, telling the transformation buffer to look for the newest available transformation irregardless of its timestamp. However, in many applications, this is not the desired behaviour, which is why it's now disabled by default. To re-enable this behaviour, use the retryLookupNewest(true) method (call with false to disable again).

You can now also specify a timeout duration for the lookup operation using the lookupTimeout(duration) method.

mrs_lib::TransformStamped

The mrs_lib::TransformStamped class has been removed and now simply the geometry_msgs::TransformStamped class is used instead. For convenience, static methods

• mrs_lib::Transformer::inverse(tf),
• mrs_lib::Transformer::frame_from(tf),
• and mrs_lib::Transformer::frame_to(tf)

are provided that implement the functionality originally provided by mrs_lib::TransformStamped.