getTransform

Return the transformation between two coordinate frames

Since R2023a

Syntax

tf = getTransform(tftree,targetframe,sourceframe)

tf = getTransform(tftree,targetframe,sourceframe,sourcetime)

tf = getTransform(tftree,targetframe,sourceframe,Timeout=timeout)

Description

tf = getTransform(tftree,targetframe,sourceframe) gets and returns the latest known transformation between two coordinate frames. tf represents the transformation that takes coordinates in the sourceframe into the corresponding coordinates in the targetframe. The returned transformation tf is empty if it does not exist in the tree.

tf = getTransform(tftree,targetframe,sourceframe,sourcetime) returns the transformation at the time sourcetime. An error is displayed if the transformation at that time is not available.

tf = getTransform(tftree,targetframe,sourceframe,Timeout=timeout) specifies a timeout period in seconds, to wait until the transformation between two coordinates frames is available. Use timeout as Inf to wait indefinitely. If the transformation does not become available in the timeout period, MATLAB^® displays an error. Use this syntax with any of the input arguments in previous syntaxes.

Examples

Create a ROS 2 Transformation Tree

This example assumes that a ROS 2 node publishes transformations between robot_base and camera_center. For example, a real or simulated TurtleBot would do that.

Create a ROS 2 node on domain ID 25. Use the example helper function to publish transformation data.

node = ros2node("/matlabNode",25);
exampleHelperROS2StartTfPublisher

Retrieve the transformation tree object.

tftree = ros2tf(node);
pause(1)

Use the AvailableFrames property to see the transformation frames available. These transformations were specified separately prior to connecting to the network.

frames = tftree.AvailableFrames

frames = 3×1 cell
    {'camera_center' }
    {'mounting_point'}
    {'robot_base'    }

Use the LastUpdateTime property to see the time when the last transformation was received.

updateTime = tftree.LastUpdateTime

updateTime = struct with fields:
    MessageType: 'builtin_interfaces/Time'
            sec: 1670925404
        nanosec: 440832800

Wait for the transformation that takes data from camera_center to robot_base. It waits for the transformation to be valid within 5 seconds.

getTransform(tftree,'robot_base','camera_center', Timeout=5)

ans = struct with fields:
       MessageType: 'geometry_msgs/TransformStamped'
            header: [1×1 struct]
    child_frame_id: 'camera_center'
         transform: [1×1 struct]

Define a point [3 1.5 0.2] in the camera's coordinate frame.

pt = ros2message('geometry_msgs/PointStamped');
pt.header.frame_id = 'camera_center';
pt.point.x = 3;
pt.point.y = 1.5;
pt.point.z = 0.2;

The transformation is now available, so transform the point into the robot_base frame.

tfpt = transform(tftree,'robot_base',pt)

tfpt = struct with fields:
    MessageType: 'geometry_msgs/PointStamped'
         header: [1×1 struct]
          point: [1×1 struct]

Display the transformed point coordinates.

tfpt.point

ans = struct with fields:
    MessageType: 'geometry_msgs/Point'
              x: 1.2000
              y: 1.5000
              z: -2.5000

Stop the example transformation publisher.

exampleHelperROS2StopTfPublisher

Clear the node.

clear('node')

Input Arguments

tftree — ROS 2 transformation tree

ros2tf object handle

ROS 2 transformation tree, specified as ros2tf object handle. You can create a ROS 2 transformation tree by using the ros2tf object.

targetframe — Target coordinate frame

string scalar | character vector

Target coordinate frame, specified as a string scalar or character vector. You can view the available frames for transformation by calling tftree.AvailableFrames.

sourceframe — Initial coordinate frame

string scalar | character vector

Initial coordinate frame, specified as a string scalar or character vector. You can view the available frames for transformation using tftree.AvailableFrames.

sourcetime — ROS 2 or system time

struct | scalar

ROS 2 or system time, specified as a scalar or structure that resembles ros2time. The scalar input is converted into structure using ros2time. By default, the sourcetime returns the system time. If you set the use_sim_time ROS 2 parameter to true, the sourcetime returns the ROS 2 simulation time published on the /clock topic.

Data Types: struct | scalar

Timeout — Timeout period

0 (default) | numeric scalar in seconds

Timeout for receiving the transform, specified as a numeric scalar in seconds. If the transformation does not become available, MATLAB displays an error, but continues running the current program.

Output Arguments

tf — Transformation between coordinate frames

struct

Transformation between coordinate frames, returned as a structure that represents geometry_msgs/TransformStamped. Transformations are structured as a 3-D translation (three-element vector) and a 3-D rotation (quaternion).

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Supported only for the Build Type, Executable.

• Accessing the last update time from the ros2tf object using its LastUpdateTime property is not supported when you are generating code using MATLAB Coder™.

• Usage of the function inside MATLAB Function block in Simulink^® is not supported.

Version History

Introduced in R2023a