tf2 is the second generation of the tf library.

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.

Some tutorials are available at https://docs.ros.org/.

Architecture

tf2 is a transform library designed to provide implementation of the 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.

Main Interface

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.

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.

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 transformation 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.

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.

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.

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++.

File truncated at 100 lines see the full file

Changelog for package tf2

0.45.5 (2025-12-16)

• static function to crate quaternions directly from rotation added (#881)
• Expose Doxygen output in tf2, showing former Doxygen front page also as README.md (#871)
• Move author tags to file brief (#870)
• Modernize conf.py files to only include modified Copyright, eliminati… (#865)
• Contributors: Markus Bader, R Kent James

0.45.4 (2025-11-28)

• Fix various documentation errors in tf2 (#857)
• Contributors: R Kent James

0.45.3 (2025-11-24)

• Disable TAGFILES in rosdoc2 to separate namespace tf2 documentation into packages (#856)
• Fix REP url locations (#847)
• Contributors: R Kent James, Tim Clephas

0.45.2 (2025-11-07)

• Adding explicit handling for normalization of zero-quaternions (#839)
• Cleanup TF2 dependencies (#843)
• Contributors: Chris Lalancette, Simon Jusner

0.45.1 (2025-10-17)

0.45.0 (2025-08-27)

• Added tf2 documentation to docs.ros.org (#671)
• Contributors: Alejandro Hernández Cordero

0.44.0 (2025-07-29)

• Add RPY quaternion constructor (#806)
• Contributors: Alireza Moayyedi

0.43.1 (2025-07-18)

0.43.0 (2025-07-01)

0.42.2 (2025-06-19)

• Default initialize TransformStorage's frame_id_ and child_frame_id_ with UINT32_MAX (#783)
• Contributors: Andreas

0.42.1 (2025-05-14)

• Removed deprecated headers tf2 (#789)
• Contributors: Alejandro Hernández Cordero

0.42.0 (2025-04-25)

0.41.0 (2025-04-25)

• Add isnan support (#780)
• Overflow Issue in durationFromSec() Function when Handling Extremely Large or Small Values (#785)
• Do not clobber callback handles when cancelling pending transformable requests (#779)
• Uniform cmake min version (#764)
• Contributors: Michael Carlstrom, Timo Röhling, cramke, mosfet80

0.40.1 (2025-01-15)

• Remove many extra conversions from Matrix3x3 to Quaternion (#741) Co-authored-by: jmachowinski <<jmachowinski@users.noreply.github.com>> Co-authored-by: Katherine Scott <<katherineAScott@gmail.com>>
• Cleanup deprecation warnings. (#744) The deprecation warnings were not printing out properly on GCC, at least; it would warn that #warning was not standard, and it would also not print out the actual warning. Also "deprecated" was spelled wrong. Fix all of these issues here.
• Contributors: Chris Lalancette, kyle-basis

0.40.0 (2024-12-20)

File truncated at 100 lines see the full file