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.

Creation

Syntax

tfTree = rostf

trtree = ros.TransformationTree(node)

Description

tfTree = rostf creates a ROS TransformationTree object.

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.

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

This property is read-only.

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.

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. Specify the IP address.

rosinit('192.168.17.129')

Initializing global node /matlab_global_node_20832 with NodeURI http://192.168.17.1:55526/

Create a transformation tree. Use the AvailableFrames property to see the transformation frames available. These transformations were specified separately prior to connecting to the network.

tree = rostf;
pause(1);
tree.AvailableFrames

ans = 36×1 cell array
    {'base_footprint'            }
    {'base_link'                 }
    {'camera_depth_frame'        }
    {'camera_depth_optical_frame'}
    {'camera_link'               }
    {'camera_rgb_frame'          }
    {'camera_rgb_optical_frame'  }
    {'caster_back_link'          }
    {'caster_front_link'         }
    {'cliff_sensor_front_link'   }
    {'cliff_sensor_left_link'    }
    {'cliff_sensor_right_link'   }
    {'gyro_link'                 }
    {'mount_asus_xtion_pro_link' }
    {'odom'                      }
    {'plate_bottom_link'         }
    {'plate_middle_link'         }
    {'plate_top_link'            }
    {'pole_bottom_0_link'        }
    {'pole_bottom_1_link'        }
    {'pole_bottom_2_link'        }
    {'pole_bottom_3_link'        }
    {'pole_bottom_4_link'        }
    {'pole_bottom_5_link'        }
    {'pole_kinect_0_link'        }
    {'pole_kinect_1_link'        }
    {'pole_middle_0_link'        }
    {'pole_middle_1_link'        }
    {'pole_middle_2_link'        }
    {'pole_middle_3_link'        }
      ⋮

Disconnect from the ROS network.

rosshutdown

Shutting down global node /matlab_global_node_20832 with NodeURI http://192.168.17.1:55526/

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

Initializing ROS master on http://bat584804glnxa64:34635/.
Initializing global node /matlab_global_node_99362 with NodeURI http://bat584804glnxa64:37503/

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

Using Master URI http://localhost:34635 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);
pause(1)

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

frames = tftree.AvailableFrames

frames = 3x1 cell array
    {'camera_center' }
    {'mounting_point'}
    {'robot_base'    }

updateTime = tftree.LastUpdateTime

updateTime = 
  ROS Time with properties:

     Sec: 1.5805e+09
    Nsec: 886000000

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');
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 = 
  ROS PointStamped message with properties:

    MessageType: 'geometry_msgs/PointStamped'
         Header: [1x1 Header]
          Point: [1x1 Point]

  Use showdetails to show the contents of the message

Display the transformed point coordinates.

tfpt.Point

ans = 
  ROS Point message with properties:

    MessageType: 'geometry_msgs/Point'
              X: 1.2000
              Y: 1.5000
              Z: -2.5000

  Use showdetails to show the contents of the message

Clear ROS node. Shut down ROS master.

clear('node')
rosshutdown

Shutting down global node /matlab_global_node_99362 with NodeURI http://bat584804glnxa64:37503/
Shutting down ROS master on http://bat584804glnxa64:34635/.