transform

Transform message entities into target coordinate frame

Since R2023a

Syntax

tfentity = transform(tftree,targetframe,entity)

tfentity = transform(tftree,targetframe,entity,"msgtime")

tfentity = transform(tftree,targetframe,entity,sourcetime)

Description

tfentity = transform(tftree,targetframe,entity) retrieves the latest transformation that takes data from the coordinate frame of theentity to the targetframe. The transformation is then applied to the data in entity. entity is a ROS 2 message of a specific type and the transformed message is returned in tfentity. An error is displayed if the transformation does not exist.

tfentity = transform(tftree,targetframe,entity,"msgtime") uses the timestamp in the header of message entity as source time to retrieve and apply the transformation.

tfentity = transform(tftree,targetframe,entity,sourcetime) uses the time sourcetime to retrieve and apply the transformation to the message entity.

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.

entity — Initial message entity

"struct"

Initial message entity, specified as a structure which represents ros2message. This function determines the type of the input message entity and apply the appropriate transformation method.

Supported messages are:

• geometry_msgs/PointStamped

• geometry_msgs/PoseStamped

• geometry_msgs/QuaternionStamped

• geometry_msgs/Vector3Stamped

• sensor_msgs/PointCloud2

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, sourcetime is the ROS 2 simulation time published on the /clock topic. If you set the use_sim_time ROS 2 parameter to true, sourcetime returns the system time.

Data Types: struct | scalar

Output Arguments

tfentity — Transformed entity

"struct"

Transformed entity, returned as a structure that represents ros2message.

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