Main Content

transform

Transform message entities into target coordinate frame

Since R2023a

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.

example

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

collapse all

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

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

collapse all

Transformed entity, returned as a structure that represents ros2message.

Extended Capabilities

Version History

Introduced in R2023a