Main Content

transform

Transform message entities into target coordinate frame

Since R2019b

collapse all in page

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. The tftree is the full transformation tree containing known transformations between entities. If the transformation from entity to targetframe does not exist, MATLAB® produces 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

Open Live Script

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/
Open Live Script

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.17.129';
rosinit(ipaddress,11311)
Initializing global node /matlab_global_node_78006 with NodeURI http://192.168.17.1:56344/

tftree = rostf;
pause(2);

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. The getTransform function will wait until the transformation is available. You can also specify a timeout to error 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_78006 with NodeURI http://192.168.17.1:56344/

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 an 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.

Extended Capabilities

Version History

Introduced in R2019b

See Also

|