updateFrame

Update frame in rigid body

Since R2025a

Syntax

updateFrame(rb,existingFrameName,Name=Value)

Description

updateFrame(rb,existingFrameName,Name=Value) updates the frame name, parent frame name and the rigid body associated with the frame using different name-value arguments. Updating a frame also updates any visual or collision geometries and any rigid bodies attached to it.

Examples

Work with Frames in Rigid Body Robot Model

This example showcases how to manage frames within a rigid body, covering operations such as adding, removing, and updating frames, as well as retrieving transforms between them.

Create a rigid body robot model and display initial frame information.

A rigid body can contain multiple frames used to define coordinate systems for attaching sensors, tools, or other components.

rb = rigidBody('rb');
rbFrame = frameinfo(rb, 'rb')

rbFrame = struct with fields:
              Name: 'rb'
    RigidTransform: [4×4 double]
       ParentFrame: ''
       ChildFrames: {1×0 cell}

Add a new frame named test to the rigid body rb, defining its position with a translation relative to the root frame rb.

addFrame(rb, 'test', 'rb', trvec2tform([1 2 3]));

Next, add another frame, test1, which is positioned relative to the newly added frame test using a combination of translation and rotation.

Each frame is defined by its name, parent frame, and rigid transform.

addFrame(rb, 'test1', 'test', trvec2tform([1 2 3]));

Display information about these added frames to verify their properties and confirm their placement within the rigid body.

testFrame = frameinfo(rb, 'test1')

testFrame = struct with fields:
              Name: 'test1'
    RigidTransform: [4×4 double]
       ParentFrame: 'test'
       ChildFrames: {1×0 cell}

You can also remove frames, which updates the frame tree to maintain its kinematic structure. Remove the frame test and observe its effect on test1 frame.

% Remove frame 'test'
removeFrame(rb, 'test');

% Check updated frame information for 'test1'
frameAfterRemove = frameinfo(rb, 'test1')

frameAfterRemove = struct with fields:
              Name: 'test1'
    RigidTransform: [4×4 double]
       ParentFrame: 'rb'
       ChildFrames: {1×0 cell}

Now, modify existing frames by updating their properties, such as the name, parent frame, or rigid transform.

First, rename test1 frame to test2.

updateFrame(rb, 'test1', 'Name', 'test2');

Add a new frame test3 and update test2 to use it as the parent frame.

addFrame(rb, 'test3', 'rb', trvec2tform([1 1 1]));
updateFrame(rb, 'test2', 'ParentFrame', 'test3', ...
    'RigidTransform', trvec2tform([1 2 3]));

Display updated frame information.

frameAfterUpdate = frameinfo(rb, 'test2')

frameAfterUpdate = struct with fields:
              Name: 'test2'
    RigidTransform: [4×4 double]
       ParentFrame: 'test3'
       ChildFrames: {1×0 cell}

Input Arguments

rb — Rigid body

rigidBody object

Rigid body, specified as a rigidBody object.

existingFrameName — Original name of frame

string scalar | character vector

Original name of frame to be updated in the rigid body, specified as a string scalar or character vector.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: rb.updateFrame("test1", Name="test2")

Name — Updated name of frame

string scalar | character vector

Updated name of frame in the rigid body, specified as a string scalar or character vector.

Data Types: char | string

ParentName — Name of parent frame

string scalar | character vector

Name of the parent frame, specified as a string scalar or character vector.

Data Types: char | string

RigidTransform — Rigid body transform of frame

4-by-4 matrix

Rigid body transform of the frame to be updated, specified as a 4-by-4 matrix.

Data Types: double

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2025a