Main Content

getTransform

Return the transformation between two coordinate frames

Since R2023a

collapse all in page

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.

example

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

collapse all

Open Live Script

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

collapse all

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

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

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

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

collapse all

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

Version History

Introduced in R2023a

See Also

| | |

Topics