Ask Your Question

tf2 Documentation Needs Work

asked 2018-05-30 07:01:00 -0600

vschmidt gravatar image

As we get ramped up on our own ROS environment, we've found the tf2 implementation extremely hard to understand. So this is a bit of a plea for folks who understand it well, to improve the tutorials, provide implementations of complete tf2 framework doing useful things, and a more up-front explanation of how it is implemented, why it is implemented that way and meant to work.

Let me say at the outset, this is meant to be wholly constructive. The amount of work that has gone into these packages and their documentation is extraordinary and we are wholly thankful for all of it. When we have a better understanding, we'll be in a better place to make contributions ourselves. But until then, we're asking for some help.

The concepts of reference frames in general, the REPs for ROS conventions, and the need for them is clear enough.

The rub is in exactly how one implements tf2 to provide utility in transforming a point, pose, vector, or arrays of any of these, between any two arbitrary reference frames quickly and seamlessly.

The basic tutorials here provide a nice gentle introduction to the mechanics. But I think the broadcaster example is confusing to first-time users in that it does not clearly introduce the tf2 library along the lines of the other turtle_sim tutorials. For example, rather than creating a transform from a pose message with little explanation as to why, it might be clearer, to set the problem up a bit first. Explain that turtle1 will be driven around using key-board commands and its location will be calculating using odometery and reported as a Pose message in the odom frame. Then, the broadcaster is implemented explicitly to define the transform between the odom and base_link frames.

The Listener is also confusing. The spawning of a new turtle simulation deserves some comment, as it is not done in most of the other tutorials. Also, the process does not explicitly define the reference frame for the position of turtle2. Given that this is a tf2 tutorial, doing so would make things more clear. Finally, although it is not part of the "listening", because this is somewhat of a contrived example, some discussion of why one is listening to the published transform and creating Twist messages from the result. Driving one turtle based on the pose of another through broadcast of a transform is just not a model that most, if anyone, would ever use, and for first timers it needs some comment.

Finally, what is perhaps most confusing and frustrating is that the tutorial doesn't actually provide an example of how to transform a Pose, Vector, Point or anything else having a reference frame into its equivalent in another reference frame. Since this is the whole point of the tf2 package it is a HUGE omission. Understanding how to do this, how to optimize it for large data sets, how to troubleshoot it - all important pieces.

There are some other ... (more)

edit retag flag offensive close merge delete


I agree that the documentation needs work. People who started with tf can figure out most things, but I guess starting right away with tf2 is challenging. For the Python part, it would already help to have real auto-generated docs, e.g. on .

Nicolas gravatar image Nicolas  ( 2019-11-20 03:47:52 -0600 )edit

The infrastructure to generate the documentation would appear to all be there.

The quickest way to move this forward would be for more community contributions to add content.

gvdhoorn gravatar image gvdhoorn  ( 2019-11-20 06:26:43 -0600 )edit

1 Answer

Sort by ยป oldest newest most voted

answered 2018-05-30 13:07:52 -0600

tfoote gravatar image

Thanks for all the feedback. There's definitely always space for improvement in the documentation and tutorials. You have a bunch of good ideas for how to improve them. If you'd like to extend the tutorials that would be great. Adding some more background information is always good to do.

And for the tutorials on how to transform datatypes that would probably make sense to be added in an additional tutorial in the series for both Python and C++.

Here's some answers to your more specific design questions.

Clearly the various back-ends provide other functionality that is useful. What does one back-end do that another does not? Why would I want to chose one over another?

The most common reason to choose one backend over another is that you're integrating a codebase that's already using one of the the backends. And it's designed to be extendable to a custom backend if you have another implementation that you're using.

It is hard to understand why, having created a geometry_msgs/PoseStamped, upon which the rest of ROS common libraries depends, should one have to convert it to a tf2_geometry_msg/PoseStamped, or further into some other library's message type. All this data type conversion seems hugely inefficient and largely unnecessary unless you want to support all those other libraries (which most people probably don't need and can implement themselves if they do). Why was the choice made to completely redefine the geometry messages within tf2 rather than reusing the already defined ones and creating this incompatibility with the rest of ROS?

It's not necessary to convert any datatypes. With the templated API and the multiple available backends the user never needs to explicitly convert. (Note that there is no tf2_geometry_msgs datatypes.) The geometry_msgs datatypes are just messages, and consequently do not have any methods etc that are available. The tf2 datatypes that I think you are referring to are an integrated linear math backend that's used internally and can be used by the user, but is designed to not be needed for the users code. And it's recommended to use one of the full linear math libraries instead.

edit flag offensive delete link more

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Question Tools



Asked: 2018-05-30 07:01:00 -0600

Seen: 113 times

Last updated: May 30 '18