rostf

Receive, send, and apply ROS transformations

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

Syntax

tfTree = rostf

tfTree = rostf("DataFormat","struct")

trtree = ros.TransformationTree(node)

tfTree = ros.TransformationTree(node,"DataFormat","struct")

Description

tfTree = rostf creates a ROS TransformationTree object.

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

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

AvailableFrames — List of all available coordinate frames

cell array

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

LastUpdateTime — Time when the last transform was received

ROS Time object

This property is read-only.

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

BufferTime — Length of time transformations are buffered

10 (default) | scalar

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.

DataFormat — Message format

"object" (default) | "struct"

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

waitForTransform	Wait until a transformation is available
getTransform	Retrieve transformation between two coordinate frames
transform	Transform message entities into target coordinate frame
sendTransform	Send transformation to ROS network

Examples

Create a ROS Transformation Tree

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.35847 seconds.
Initializing ROS master on http://172.29.209.26:55750.
Initializing global node /matlab_global_node_93409 with NodeURI http://dcc245873glnxa64:43797/ and MasterURI http://localhost:55750.

node = ros.Node('/testTf');

Using Master URI http://localhost:55750 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_93409 with NodeURI http://dcc245873glnxa64:43797/ and MasterURI http://localhost:55750.
Shutting down ROS master on http://172.29.209.26:55750.

Use TransformationTree Object

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.85572 seconds.
Initializing ROS master on http://172.29.217.10:59188.
Initializing global node /matlab_global_node_99038 with NodeURI http://dcc138007glnxa64:32779/ and MasterURI http://localhost:59188.

node = ros.Node('/testTf');

Using Master URI http://localhost:59188 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: 1669473845
    Nsec: 615637086

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_99038 with NodeURI http://dcc138007glnxa64:32779/ and MasterURI http://localhost:59188.
Shutting down ROS master on http://172.29.217.10:59188.

Limitations

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

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.

• Usage in MATLAB Function block is not supported.

Version History

Introduced in R2019b

R2021a: ROS Message Structures

You can now create messages as structures with fields matching the message object properties. Using structures typically improves performance of creating, updating, and using ROS messages, but message fields are no longer validated when set. Message types and corresponding field values from the structures are validated when sent across the network.

To use ROS messages as structures, use the "DataFormat" name-value argument when creating your publishers, subscribers, or other ROS objects. Any messages generated from these objects will utilize structures.

pub = rospublisher("/scan","sensor_msgs/LaserScan","DataFormat","struct")
msg = rosmessage(pub)

You can also create messages as structures directly, but make sure to specify the data format as "struct" for the publisher, subscriber, or other ROS objects as well. ROS objects still use message objects by default.

msg = rosmessage("/scan","sensor_msgs/LaserScan","DataFormat","struct")
...
pub = rospublisher("/scan","sensor_msgs/LaserScan","DataFormat","struct")

In a future release, ROS messages will use structures by default and ROS message objects will be removed.

For more information, see Improve Performance of ROS Using Message Structures.