addFrame

Add frame name to rigid body

Since R2025a

Syntax

addFrame(rb,name,parentname,tform)

addFrame(rb,name,parentname,rotation,translation)

Description

addFrame(rb,name,parentname,tform) adds a frame with name name on the parent frame with name parentname on the rigid body. The added frame is transformed by transformation tform from the frame.

addFrame(rb,name,parentname,rotation,translation) adds a frame name to the rigid body. The added frame is transformed by rotation and translation from the parentname frame.

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.

name — Name of frame to be added

string scalar | character vector

Name of the frame to be added to the rigid body, specified as a string scalar or character vector.

Data Types: char | string

parentname — Parent body name or frame name

string scalar | character vector

Parent body name or frame name, specified as a string scalar or character vector. This parent body or frame must already exist in the robot model. The new body is attached to this parent body.

Data Types: char | string

tform — Transformation matrix of the frame to be added

4-by-4 matrix

Transformation matrix describing the relative transformation of the frame to be added with respect to the parent frame on the rigid body, specified as a 4-by-4 matrix.

Data Types: double

rotation — Rotation matrix of frame to be added

rotation matrix | quaternion

Rotation matrix describing the relative rotation of the frame to be added with respect to the parent frame on the rigid body, specified as a rotation matrix or quaternion.

Data Types: double

translation — Translation of added frame with respect to parent frame

1-by-3 vector

Translation of added frame with respect to parent frame, specified as a 1-by-3 vector.

Data Types: double

Extended Capabilities

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

Version History

Introduced in R2025a