Main Content

rostf

Receive, send, and apply ROS transformations

Since R2019b

Description

Calling the rostf function creates a ROS TransformationTree object, which allows you to access the tf coordinate transformations that are shared on the ROS network. You can receive transformations and apply them to different entities. You can also send transformations and share them with the rest of the ROS network.

ROS uses the tf transform library to keep track of the relationship between multiple coordinate frames. The relative transformations between these coordinate frames are maintained in a tree structure. Querying this tree lets you transform entities like poses and points between any two coordinate frames. To access available frames, use the syntax:

tfTree.AvailableFrames

Use the ros.TransformationTree syntax when connecting to a specific ROS node, otherwise use rostf to create the transformation tree.

Note

In a future release, ROS Toolbox will use message structures instead of objects for ROS messages.

To use message structures now, set the "DataFormat" name-value argument to "struct". For more information, see ROS Message Structures.

Creation

Description

example

tfTree = rostf creates a ROS TransformationTree object.

tfTree = rostf("DataFormat","struct") uses message structures instead of objects. For more information, see ROS Message Structures.

example

trtree = ros.TransformationTree(node) creates a ROS transformation tree object handle that the transformation tree is attached to. The node is the node connected to the ROS network that publishes transformations.

tfTree = ros.TransformationTree(node,"DataFormat","struct") uses message structures instead of objects. For more information, see ROS Message Structures.

Properties

expand all

This property is read-only.

List of all available coordinate frames, specified as a cell array. This list of available frames updates if new transformations are received by the transformation tree object.

Example: {'camera_center';'mounting_point';'robot_base'}

Data Types: cell

This property is read-only.

Time when the last transform was received, specified as a ROS Time object.

Length of time transformations are buffered, specified as a scalar in seconds. If you change the buffer time from the current value, the transformation tree and all transformations are reinitialized. You must wait for the entire buffer time to be completed to get a fully buffered transformation tree.

Message format, specified as "object" or "struct". You must set this property on creation using the name-value input. For more information, see ROS Message Structures.

Object Functions

waitForTransformWait until a transformation is available
getTransformRetrieve transformation between two coordinate frames
transformTransform message entities into target coordinate frame
sendTransformSend transformation to ROS network

Examples

collapse all

Connect to a ROS network and create a transformation tree.

Connect to a ROS network. Create a node. Use the example helper function to publish transformation data.

rosinit
Launching ROS Core...
Done in 0.62039 seconds.
Initializing ROS master on http://172.29.206.170:52526.
Initializing global node /matlab_global_node_49358 with NodeURI http://dcc598343glnxa64:42077/ and MasterURI http://localhost:52526.
node = ros.Node('/testTf');
Using Master URI http://localhost:52526 from the global node to connect to the ROS master.
exampleHelperROSStartTfPublisher

Create a transformation tree. Use structures as the ROS message data format. Use the AvailableFrames property to see the transformation frames available. These transformations were specified separately prior to connecting to the network.

tree = rostf('DataFormat','struct');
pause(1);
tree.AvailableFrames
ans = 3x1 cell
    {'camera_center' }
    {'mounting_point'}
    {'robot_base'    }

Disconnect from the ROS network.

rosshutdown
Shutting down global node /matlab_global_node_49358 with NodeURI http://dcc598343glnxa64:42077/ and MasterURI http://localhost:52526.
Shutting down ROS master on http://172.29.206.170:52526.

Create a ROS transformation tree. You can then view or use transformation information for different coordinate frames setup in the ROS network.

Start ROS network and broadcast sample transformation data.

rosinit
Launching ROS Core...
Done in 0.61261 seconds.
Initializing ROS master on http://172.29.205.152:57727.
Initializing global node /matlab_global_node_97787 with NodeURI http://dcc591245glnxa64:33187/ and MasterURI http://localhost:57727.
node = ros.Node('/testTf');
Using Master URI http://localhost:57727 from the global node to connect to the ROS master.
exampleHelperROSStartTfPublisher

Retrieve the TransformationTree object. Pause to wait for tftree to update.

tftree = ros.TransformationTree(node,'DataFormat','struct');
pause(1)

View available coordinate frames and the time when they were last received.

frames = tftree.AvailableFrames
frames = 3x1 cell
    {'camera_center' }
    {'mounting_point'}
    {'robot_base'    }

updateTime = tftree.LastUpdateTime
updateTime = struct with fields:
     Sec: 1707800080
    Nsec: 843502918

Wait for the transform between two frames, 'camera_center' and 'robot_base'. This will wait until the transformation is valid and block all other operations. A time out of 5 seconds is also given.

waitForTransform(tftree,'robot_base','camera_center',5)

Define a point in the camera's coordinate frame

pt = rosmessage('geometry_msgs/PointStamped','DataFormat','struct');
pt.Header.FrameId = 'camera_center';
pt.Point.X = 3;
pt.Point.Y = 1.5;
pt.Point.Z = 0.2;

Transform the point into the 'base_link' frame.

tfpt = transform(tftree, 'robot_base', pt)
tfpt = struct with fields:
    MessageType: 'geometry_msgs/PointStamped'
         Header: [1x1 struct]
          Point: [1x1 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

Clear ROS node. Shut down ROS master.

clear('node')
rosshutdown
Shutting down global node /matlab_global_node_97787 with NodeURI http://dcc591245glnxa64:33187/ and MasterURI http://localhost:57727.
Shutting down ROS master on http://172.29.205.152:57727.

Limitations

  • In ROS Noetic, multiple coordinate frames with redundant timestamp cannot be published.

Extended Capabilities

Version History

Introduced in R2019b

expand all