Tf Transforms

There are two methods for looking up tf2 transforms.

Component

The TfTransform component can be used to subscribe to transforms between two frames.

TfTransform {
  id: tfTransform
  active: true // This is the default, if false no updates will be received
  sourceFrame: "turtle1"
  targetFrame: "world"
}

It provides a valid property that indicates if a valid transform has been received. If it is valid, it contains a transform property with the stamped transform geometry_msgs/msg/TransformStamped and for convenience also a translation and a rotation property which refer to the translation and rotation in the transform.

Using the rate property, you can also change the maximum rate at which the transform is updated.

Static

You can also use the TfTransformListener singleton to look up transforms if you just need it once.

Button {
  text: "Look Up"
  onClicked: {
    var transformStamped = TfTransformListener.lookUpTransform(inputTargetFrame.text, inputSourceFrame.text)
    if (!transformStamped.valid)
    {
      transformResult.text = "Transform from '" + inputSourceFrame.text + "' to '" + inputTargetFrame.text + "' was not valid!\n" +
                              "Exception: " + transformStamped.exception + "\nMessage: " + transformStamped.message
      return
    }
    transformResult.text = "Position:\n" + printVector3(transformStamped.transform.translation) + "\nOrientation:\n" + printRotation(transformStamped.transform.rotation)
  }
}

Use the provided Ros2.now() static methods to look up at specific time points. For the latest, you can pass new Date(0). Be aware that in JavaScript durations are given in milliseconds.

Warning

Be aware that canLookUp can return a boolean value or a string error message. You should explicitly test for that since strings are truthy, too.

Namespaced

The global TfTransformListener singleton follows the design of tf2_ros::TransformListener and therefore always subscribes to /tf and /tf_static. For multi-robot setups where each robot publishes its own tf tree under a namespace (<namespace>/tf and <namespace>/tf_static), use the TfBuffer component. Each instance owns its own tf buffer fed from the topics under the configured namespace and exposes the same canTransform / lookUpTransform API as the singleton.

TfBuffer {
  id: robot1Buffer
  ns: "/robot1" // subscribes to /robot1/tf and /robot1/tf_static
}

TfBuffer {
  id: robot2Buffer
  ns: "/robot2" // subscribes to /robot2/tf and /robot2/tf_static
}

TfTransform {
  buffer: robot1Buffer
  sourceFrame: "base_link"
  targetFrame: "map"
}

An empty ns (the default) subscribes to /tf and /tf_static and therefore behaves like the global singleton path.

Passing an instance to a TfTransform via its buffer property sources transforms from that buffer instead of the global singleton. Leaving buffer unset (the default) keeps the existing behavior of using the global TfTransformListener.

The same lookUpTransform / canTransform methods that are available on the TfTransformListener singleton can also be called directly on a TfBuffer instance. Additionally, you can query the authority that provided the transform for a frame using getFrameAuthority(frame_id).

Frame Queries

Both the TfTransformListener singleton and TfBuffer instances expose methods for querying individual frames or the entire frame tree. Each frame is represented by a TfFrameInfo value object with the following properties:

  • frameId — the frame ID string

  • parentId — the parent frame ID (empty for root frames)

  • authority — the node name that publishes the transform for this frame

  • translation — a map {x, y, z} of the translation from parent to frame

  • rotation — a quaternion map {w, x, y, z} from parent to frame

  • isStatic — true if the transform was received on /tf_static

  • children — a list of direct child frame IDs

  • frequency — the publishing rate in Hz (computed over a 5-second window)

// Query a single frame
var frame = TfTransformListener.getFrame("base_link")
if (frame) {
    console.log("Parent:", frame.parentId)
    console.log("Authority:", frame.authority)
    console.log("Frequency:", frame.frequency.toFixed(1), "Hz")
    console.log("Children:", frame.children)
}

// Enumerate all frames
var allFrames = TfTransformListener.getAllFrames()
for (var i = 0; i < allFrames.length; ++i) {
    var f = allFrames[i]
    console.log(f.frameId, "->", f.parentId)
}

// Get the age of a transform in seconds
var age = TfTransformListener.getTransformAge("base_link")
if (age >= 0)
    console.log("Transform age:", age.toFixed(3), "s")

The same methods are available on TfBuffer instances:

TfBuffer {
    id: robotBuffer
    ns: "/robot1"
}

// ...
var frame = robotBuffer.getFrame("base_link")
var all = robotBuffer.getAllFrames()
var age = robotBuffer.getTransformAge("base_link")

API

class TfTransformListenerWrapper : public QObject

A wrapper around the TfTransformListener singleton to allow the QML engine to create and destroy it.

Public Functions

void initialize()

Initializes the TfTransformListener singleton if not already initialized. This will be done automatically the first time you use any of the other methods, so calling this is optional but may be used to initialize earlier such that transforms are available when needed. Creating a TfTransform object will also initialize the singleton.

QVariant canTransform(const QString &target_frame, const QString &source_frame, const QDateTime &time, double timeout = 0) const

Checks if a transform is possible. Returns true if possible, otherwise either false or if available a message why the transform failed.

Parameters:

  • target_frame – The frame into which to transform.

  • source_frame – The frame from which to transform.

  • time – The time at which to transform in seconds.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

True if the transform is possible, otherwise an error message (string) if available, false if not.

QVariant canTransform(const QString &target_frame, const QString &source_frame, const Time &time = Time(rclcpp::Time(0)), double timeout = 0) const

Checks if a transform is possible. Returns true if possible, otherwise either false or if available a message why the transform failed.

Parameters:

  • target_frame – The frame into which to transform.

  • source_frame – The frame from which to transform.

  • time – The time at which to transform in seconds.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

True if the transform is possible, otherwise an error message (string) if available, false if not.

QVariant canTransform(const QString &target_frame, const QDateTime &target_time, const QString &source_frame, const QDateTime &source_time, const QString &fixed_frame, double timeout = 0) const

Checks if a transform is possible. Returns true if possible, otherwise either false or if available a message why the transform failed.

Parameters:

  • target_frame – The frame into which to transform.

  • target_time – The time into which to transform.

  • source_frame – The frame from which to transform.

  • source_time – The time from which to transform.

  • fixed_frame – The frame in which to treat the transform as constant in time.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

True if the transform is possible, otherwise an error message (string) if available, false if not.

QVariant canTransform(const QString &target_frame, const Time &target_time, const QString &source_frame, const Time &source_time, const QString &fixed_frame, double timeout = 0) const

Checks if a transform is possible. Returns true if possible, otherwise either false or if available a message why the transform failed.

Parameters:

  • target_frame – The frame into which to transform.

  • target_time – The time into which to transform.

  • source_frame – The frame from which to transform.

  • source_time – The time from which to transform.

  • fixed_frame – The frame in which to treat the transform as constant in time.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

True if the transform is possible, otherwise an error message (string) if available, false if not.

QVariantMap lookUpTransform(const QString &target_frame, const QString &source_frame, const QDateTime &time, double timeout = 0)

Get the transform between two frames by frame id.

Parameters:

  • target_frame – The frame to which the data should be transformed.

  • source_frame – The frame where the data originated.

  • time – The time at which the value of the transform is desired. Set to 0 for latest.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

A map containing a boolean valid field. If valid is true it also contains the transform. If valid is false, it might contain more information, e.g., an exception field with the name of the exception and a message field containing more information about the reason of failure.

QVariantMap lookUpTransform(const QString &target_frame, const QString &source_frame, const Time &time = Time(rclcpp::Time(0)), double timeout = 0)

Get the transform between two frames by frame id.

Parameters:

  • target_frame – The frame to which the data should be transformed.

  • source_frame – The frame where the data originated.

  • time – The time at which the value of the transform is desired. Set to 0 for latest.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

A map containing a boolean valid field. If valid is true it also contains the transform. If valid is false, it might contain more information, e.g., an exception field with the name of the exception and a message field containing more information about the reason of failure.

QVariantMap lookUpTransform(const QString &target_frame, const QDateTime &target_time, const QString &source_frame, const QDateTime &source_time, const QString &fixed_frame, double timeout = 0)

Get the transform between two frames by frame id.

Parameters:

  • target_frame – The frame to which the data should be transformed.

  • target_time – The time to which the data should be transformed. Set to 0 for latest.

  • source_frame – The frame where the data originated.

  • source_time – The time at which the source_frame should be evaluated. Set to 0 for latest.

  • fixed_frame – The frame in which to assume the transform is constant in time.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

A map containing a boolean valid field. If valid is true it also contains the transform. If valid is false, it might contain more information, e.g., an exception field with the name of the exception and a message field containing more information about the reason of failure.

QVariantMap lookUpTransform(const QString &target_frame, const Time &target_time, const QString &source_frame, const Time &source_time, const QString &fixed_frame, double timeout = 0)

Get the transform between two frames by frame id.

Parameters:

  • target_frame – The frame to which the data should be transformed.

  • target_time – The time to which the data should be transformed. Set to 0 for latest.

  • source_frame – The frame where the data originated.

  • source_time – The time at which the source_frame should be evaluated. Set to 0 for latest.

  • fixed_frame – The frame in which to assume the transform is constant in time.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

A map containing a boolean valid field. If valid is true it also contains the transform. If valid is false, it might contain more information, e.g., an exception field with the name of the exception and a message field containing more information about the reason of failure.

QString getFrameAuthority(const QString &frame_id) const

Returns the authority (node name) that provided the latest transform for the given frame.

Parameters:

frame_id – The frame ID to look up.

Returns:

The node name of the authority, or an empty string if not found.

QVariant getFrame(const QString &frame_id) const

Returns information about a single frame.

Parameters:

frame_id – The frame ID to look up.

Returns:

A TfFrameInfo wrapped in QVariant, or an invalid QVariant if the frame is not known.

QVariantList getAllFrames() const

Returns information about all known frames.

Returns:

A list of TfFrameInfo objects for every frame in the buffer.

double getTransformAge(const QString &frame_id) const

Returns the age of the latest transform for the given frame.

The age is computed as the difference between the current ROS time and the timestamp of the most recent transform received for the frame.

Parameters:

frame_id – The frame ID to look up.

Returns:

The age in seconds, or -1.0 if the frame is not known or has no parent.

class TfBuffer : public QObjectRos2

A tf buffer that subscribes to a (optionally namespaced) tf topic pair.

Unlike the global TfTransformListener (which is backed by tf2_ros::TransformListener and can therefore only listen on /tf and /tf_static), this element subscribes directly to <namespace>/tf and <namespace>/tf_static on the shared plugin node and feeds the received transforms into its own tf2_ros::Buffer. This enables multi-robot setups where each robot publishes its own tf tree under a namespace.

Provides the same canTransform/lookUpTransform QML API as the global Ros2.TfTransformListener. Instances can be passed to TfTransform via its buffer property.

Public Functions

tf2_ros::Buffer *buffer()

Non-QML accessor used by TfTransform. May return nullptr until ROS2 is initialized.

QVariant canTransform(const QString &target_frame, const QString &source_frame, const rclcpp::Time &time, double timeout = 0) const

Checks if a transform is possible. Returns true if possible, otherwise either false or if available a message why the transform failed.

Parameters:

  • target_frame – The frame into which to transform.

  • source_frame – The frame from which to transform.

  • time – The time at which to transform in seconds.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

True if the transform is possible, otherwise an error message (string) if available, false if not.

QVariant canTransform(const QString &target_frame, const rclcpp::Time &target_time, const QString &source_frame, const rclcpp::Time &source_time, const QString &fixed_frame, double timeout = 0) const

Checks if a transform is possible. Returns true if possible, otherwise either false or if available a message why the transform failed.

Parameters:

  • target_frame – The frame into which to transform.

  • target_time – The time into which to transform.

  • source_frame – The frame from which to transform.

  • source_time – The time from which to transform.

  • fixed_frame – The frame in which to treat the transform as constant in time.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

True if the transform is possible, otherwise an error message (string) if available, false if not.

QVariantMap lookUpTransform(const QString &target_frame, const QString &source_frame, const rclcpp::Time &time, double timeout = 0) const

Get the transform between two frames by frame id.

Parameters:

  • target_frame – The frame to which the data should be transformed.

  • source_frame – The frame where the data originated.

  • time – The time at which the value of the transform is desired. Set to 0 for latest.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

A map containing a boolean valid field. If valid is true it also contains the transform. If valid is false, it might contain more information, e.g., an exception field with the name of the exception and a message field containing more information about the reason of failure.

QVariantMap lookUpTransform(const QString &target_frame, const rclcpp::Time &target_time, const QString &source_frame, const rclcpp::Time &source_time, const QString &fixed_frame, double timeout = 0) const

Get the transform between two frames by frame id.

Parameters:

  • target_frame – The frame to which the data should be transformed.

  • target_time – The time to which the data should be transformed. Set to 0 for latest.

  • source_frame – The frame where the data originated.

  • source_time – The time at which the source_frame should be evaluated. Set to 0 for latest.

  • fixed_frame – The frame in which to assume the transform is constant in time.

  • timeout – How long to block before failing in milliseconds. Set to 0 for no timeout.

Returns:

A map containing a boolean valid field. If valid is true it also contains the transform. If valid is false, it might contain more information, e.g., an exception field with the name of the exception and a message field containing more information about the reason of failure.

QString getFrameAuthority(const QString &frame_id) const

Returns the authority (node name) that provided the latest transform for the given frame.

In TF, the authority for a frame is defined as the node that publishes the transform where the frame is the child_frame_id.

Parameters:

frame_id – The frame ID to look up.

Returns:

The node name of the authority, or an empty string if not found.

QVariant getFrame(const QString &frame_id) const

Returns information about a single frame.

Parameters:

frame_id – The frame ID to look up.

Returns:

A TfFrameInfo wrapped in QVariant, or an invalid QVariant if the frame is not known.

QVariantList getAllFrames() const

Returns information about all known frames.

Returns:

A list of TfFrameInfo objects for every frame in the buffer.

double getTransformAge(const QString &frame_id) const

Returns the age of the latest transform for the given frame.

The age is computed as the difference between the current ROS time and the timestamp of the most recent transform received for the frame.

Parameters:

frame_id – The frame ID to look up.

Returns:

The age in seconds, or -1.0 if the frame is not known or has no parent.

Properties

QML_ELEMENT QString ns

The ROS2 namespace whose /tf and /tf_static topics this buffer subscribes to. An empty namespace (default) subscribes to /tf and /tf_static, equivalent to the global TfTransformListener.

class TfFrameInfo

Properties

QString frameId

The frame ID of this frame.

QString parentId

The parent frame ID, or empty string if this is a root frame.

QString authority

The authority (node name) that provided the latest transform for this frame.

QVariantMap translation

The translation from parent to this frame as a map with x, y, z fields.

QVariantMap rotation

The rotation from parent to this frame as a quaternion map with w, x, y, z fields.

bool isStatic

Whether the transform was received on the static topic (/tf_static).

QStringList children

The list of direct child frame IDs.

double frequency

The publishing frequency in Hz, computed from a sliding window of recent messages.

class TfTransform : public QObject

Represents a tf transform between source and target frame.

Properties

QString sourceFrame

The source frame of the tf transform, i.e., the frame where the data originated.

QString targetFrame

The target frame of the tf transform, i.e., the frame to which the data should be transformed.

bool enabled

Whether this tf transform is enabled, i.e., receiving transform updates.

QVariantMap transform

The last received transform as a geometry_msgs/msg/TransformStamped with an added boolean valid field and optional error fields. See TfTransformListener::lookUpTransform

QVariantMap message

An alias for transform.

QVariant translation

The translation part of the tf transform as a vector with x, y, z fields. Zero if no valid transform available (yet).

QVariant rotation

The rotation part of the tf transform as a quaternion with w, x, y, z fields. Identity if no valid transform available (yet).

qreal rate

The maximum rate in Hz at which tf updates are processed and emitted as changed signals. Default: 60 Note: The rate can not exceed 1000. Setting to 0 will disable updates.

bool valid

Whether the current transform, i.e., the fields message, translation and rotation are valid.

qml6_ros2_plugin::TfBuffer * buffer

Optional TfBuffer instance providing the tf buffer. If unset (default), the global TfTransformListener singleton is used. When set, transforms are sourced from the given buffer, allowing TfTransform to follow a namespaced tf tree.