transform

Transform message entities into target coordinate frame

Syntax

tfentity = transform(tftree,targetframe,entity)
tfentity = transform(tftree,targetframe,entity,"msgtime")
tfentity = transform(tftree,targetframe,entity,sourcetime)

Description

example

tfentity = transform(tftree,targetframe,entity) retrieves the latest transformation between targetframe and the coordinate frame of entity and applies it to entity, a ROS message of a specific type. tftree is the full transformation tree containing known transformations between entities. If the transformation from entity to targetframe does not exist, MATLAB® throws an error.

tfentity = transform(tftree,targetframe,entity,"msgtime") uses the timestamp in the header of the message, entity, as the source time to retrieve and apply the transformation.

tfentity = transform(tftree,targetframe,entity,sourcetime) uses the given source time to retrieve and apply the transformation to the message, entity.

Examples

collapse all

This example shows how to set up a ROS transformation tree and transform frames based on this 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.203.129';
rosinit(ipaddress)
tftree = rostf;
pause(1)
Initializing global node /matlab_global_node_60416 with NodeURI http://192.168.203.1:53781/

Look at the available frames on the transformation tree.

tftree.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'        }
    {'pole_top_0_link'           }
    {'pole_top_1_link'           }
    {'pole_top_2_link'           }
    {'pole_top_3_link'           }
    {'wheel_left_link'           }
    {'wheel_right_link'          }

Check if the desired transformation is available now. 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. getTransform 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 could 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 saved from before.

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_60416 with NodeURI http://192.168.203.1:53781/

This example shows how to access time-buffered transformations on the ROS network. Access transformations for specific times and modify the BufferTime property based on your desired times.

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

ipaddress = '192.168.203.129';
rosinit(ipaddress)
tftree = rostf;
pause(2);
Initializing global node /matlab_global_node_29163 with NodeURI http://192.168.203.1:53691/

Get the transformation from 1 second ago.

desiredTime = rostime('now') - 1;
tform = getTransform(tftree,'base_link','camera_link',desiredTime);

The transformation buffer time is 10 seconds by default. Modify the BufferTime property of the transformation tree to increase the buffer time and wait for that buffer to fill.

tftree.BufferTime = 15;
pause(15);

Get the transformation from 12 seconds ago.

desiredTime = rostime('now') - 12;
tform = getTransform(tftree,'base_link','camera_link',desiredTime);

You can also get transformations at a time in the future. getTransform will wait until the transformation is available. You can also specify a timeout to error out if no transformation is found. This example waits 5 seconds for the transformation at 3 seconds from now to be available.

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

Shut down the ROS network.

rosshutdown
Shutting down global node /matlab_global_node_29163 with NodeURI http://192.168.203.1:53691/

Input Arguments

collapse all

ROS transformation tree, specified as a TransformationTree object handle. You can create a transformation tree by calling the rostf function.

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

Initial message entity, specified as a Message object handle.

Supported messages are:

  • geometry_msgs/PointStamped

  • geometry_msgs/PoseStamped

  • geometry_msgs/QuaternionStamped

  • geometry_msgs/Vector3Stamped

  • sensor_msgs/PointCloud2

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

Output Arguments

collapse all

Transformed entity, returned as a Message object handle.

Introduced in R2015a