updateFrame

Update frame in rigid body

Since R2025a

collapse all in page

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.

example

Examples

collapse all

Open Live Script

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

collapse all

Rigid body, specified as a rigidBody object.

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

collapse all

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")

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

Data Types: char | string

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

Data Types: char | string

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

Data Types: double

Extended Capabilities

expand all

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

Version History

Introduced in R2025a

See Also

| | | |