canTransform

Verify if transformation is available

Syntax

isAvailable = canTransform(tftree,targetframe,sourceframe)

isAvailable = canTransform(tftree,targetframe,sourceframe,sourcetime)

isAvailable = canTransform(bagSel,targetframe,sourceframe)

isAvailable = canTransform(bagSel,targetframe,sourceframe,sourcetime)

isAvailable = canTransform(bagreader,targetframe,sourceframe)

isAvailable = canTransform(bagreader,targetframe,sourceframe,sourcetime)

Description

TransformationTree Object

isAvailable = canTransform(tftree,targetframe,sourceframe) verifies if a transformation between the source frame and target frame is available at the current time in tftree. Create the tftree object using rostf, which requires a connection to a ROS network.

isAvailable = canTransform(tftree,targetframe,sourceframe,sourcetime) verifies if a transformation is available for the source time. If sourcetime is outside the buffer window, the function returns false.

BagSelection Object

isAvailable = canTransform(bagSel,targetframe,sourceframe) verifies if a transformation is available in a rosbag in bagSel. To get the bagSel input, load a rosbag using rosbag.

isAvailable = canTransform(bagSel,targetframe,sourceframe,sourcetime) verifies if a transformation is available in a rosbag for the source time. If sourcetime is outside the buffer window, the function returns false.

rosbagreader Object

isAvailable = canTransform(bagreader,targetframe,sourceframe) verifies if a transformation is available in a rosbag in bagreader.

isAvailable = canTransform(bagreader,targetframe,sourceframe,sourcetime) verifies if a transformation is available in a rosbag for the source time. If sourcetime is outside the buffer window, the function returns false.

Examples

Send a Transformation to ROS Network

This example shows how to create a transformation and send it over the ROS network.

Create a ROS transformation tree. Use rosinit to connect a ROS network. Replace ipaddress with your ROS network address.

rosinit;

Launching ROS Core...
....Done in 4.1192 seconds.
Initializing ROS master on http://192.168.125.1:56090.
Initializing global node /matlab_global_node_16894 with NodeURI http://HYD-KVENNAPU:63122/

tftree = rostf;
pause(2)

Verify the transformation you want to send over the network does not already exist. The canTransform function returns false if the transformation is not immediately available.

canTransform(tftree,'new_frame','base_link')

ans = logical
   0

Create a TransformStamped message. Populate the message fields with the transformation information.

tform = rosmessage('geometry_msgs/TransformStamped');
tform.ChildFrameId = 'new_frame';
tform.Header.FrameId = 'base_link';
tform.Transform.Translation.X = 0.5;
tform.Transform.Rotation.X = 0.5;
tform.Transform.Rotation.Y = 0.5;
tform.Transform.Rotation.Z = 0.5;
tform.Transform.Rotation.W = 0.5;

Send the transformation over the ROS network.

sendTransform(tftree,tform)

Verify the transformation is now on the ROS network.

canTransform(tftree,'new_frame','base_link')

ans = logical
   1

Shut down the ROS network.

rosshutdown

Shutting down global node /matlab_global_node_16894 with NodeURI http://HYD-KVENNAPU:63122/
Shutting down ROS master on http://192.168.125.1:56090.

Get ROS Transformations and Apply to ROS Messages

This example shows how to set up a ROS transformation tree and transform frames based on transformation tree information. It uses time-buffered transformations to access transformations at different times.

Create a ROS transformation tree. Use rosinit to connect to a ROS network. Replace ipaddress with your ROS network address.

ipaddress = '192.168.17.129';
rosinit(ipaddress,11311)

Initializing global node /matlab_global_node_14346 with NodeURI http://192.168.17.1:56312/

tftree = rostf;
pause(1)

Look at the available frames on the transformation tree.

tftree.AvailableFrames

ans = 36×1 cell
    {'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'        }
      ⋮

Check if the desired transformation is now available. For this example, check for the transformation from 'camera_link' to 'base_link'.

canTransform(tftree,'base_link','camera_link')

ans = logical
   1

Get the transformation for 3 seconds from now. The getTransform function will wait until the transformation becomes available with the specified timeout.

desiredTime = rostime('now') + 3;
tform = getTransform(tftree,'base_link','camera_link',...
                     desiredTime,'Timeout',5);

Create a ROS message to transform. Messages can also be retrieved off the ROS network.

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

Transform the ROS message to the 'base_link' frame using the desired time previously saved.

tfpt = transform(tftree,'base_link',pt,desiredTime);

Optional: You can also use apply with the stored tform to apply this transformation to the pt message.

tfpt2 = apply(tform,pt);

Shut down the ROS network.

rosshutdown

Shutting down global node /matlab_global_node_14346 with NodeURI http://192.168.17.1:56312/

Get Transformations from rosbag File

Get transformations from rosbag (.bag) files by loading the rosbag and checking the available frames. From these frames, use getTransform to query the transformation between two coordinate frames.

Load the rosbag.

bag = rosbag('ros_turtlesim.bag');

Get a list of available frames.

frames = bag.AvailableFrames;

Get the latest transformation between two coordinate frames.

tf = getTransform(bag,'world',frames{1});

Check for a transformation available at a specific time and retrieve the transformation. Use canTransform to check if the transformation is available. Specify the time using rostime.

tfTime = rostime(bag.StartTime + 1);
if (canTransform(bag,'world',frames{1},tfTime))
    tf2 = getTransform(bag,'world',frames{1},tfTime);
end

Get Transformations from rosbag File Using rosbagreader Object

Get transformations from rosbag (.bag) files by loading the rosbag and checking the available frames. From these frames, use getTransform to query the transformation between two coordinate frames.

Load the rosbag.

bagMsgs = rosbagreader("ros_turtlesim.bag")

bagMsgs = 
  rosbagreader with properties:

           FilePath: '/tmp/Bdoc25b_2988451_749882/tp673d749e/ros-ex81142742/ros_turtlesim.bag'
          StartTime: 1.5040e+09
            EndTime: 1.5040e+09
        NumMessages: 6089
    AvailableTopics: [6×3 table]
    AvailableFrames: {2×1 cell}
        MessageList: [6089×4 table]

Get a list of available frames.

frames = bagMsgs.AvailableFrames

frames = 2×1 cell
    {'turtle1'}
    {'world'  }

Get the latest transformation between two coordinate frames.

tf = getTransform(bagMsgs,'world',frames{1})

tf = 
  ROS TransformStamped message with properties:

     MessageType: 'geometry_msgs/TransformStamped'
          Header: [1×1 Header]
       Transform: [1×1 Transform]
    ChildFrameId: 'turtle1'

  Use showdetails to show the contents of the message

Check for a transformation available at a specific time and retrieve the transformation. Use canTransform to check if the transformation is available. Specify the time using rostime.

tfTime = rostime(bagMsgs.StartTime + 1);
if (canTransform(bagMsgs,'world',frames{1},tfTime))
    tf2 = getTransform(bagMsgs,'world',frames{1},tfTime);
end

Input Arguments

tftree — ROS transformation tree

TransformationTree object

ROS transformation tree, specified as a TransformationTree object. Create a transformation tree by calling the rostf function.

bagSel — Selection of rosbag messages

BagSelection object

Selection of rosbag messages, specified as a BagSelection object. To create a selection of rosbag messages, use rosbag.

bagreader — Index of messages in rosbag

rosbagreader object

Index of the messages in the rosbag, specified as a rosbagreader object.

targetframe — Target coordinate frame

string scalar | character vector

Target coordinate frame, specified as a string scalar or character vector. You can view the frames available for transformation by calling tftree.AvailableFrames or bagSel.AvailableFrames.

sourceframe — Initial coordinate frame

string scalar | character vector

Initial coordinate frame, specified as a string scalar or character vector. You can view the available frames for transformation by calling tftree.AvailableFrames or bagSel.AvailableFrames.

sourcetime — ROS or system time

scalar | Time object handle

ROS or system time, specified as a scalar or Time object handle. The scalar input is converted to a Time object using rostime.

Output Arguments

isAvailable — Indicator if transform exists

boolean

Indicator if transform exists, returned as a boolean. The function returns false if:

• sourcetime is outside the buffer window for a tftree object.

• sourcetime is outside the time of the bagSel or bagreader object.

• sourcetime is in the future.

• The transformation is not published yet.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Supported only for the syntaxes with TransformationTree object as input.

• Supported only for the Build Type, Executable.

• Usage in MATLAB Function block is not supported.

Version History

Introduced in R2019b