addSubtree

Add subtree to robot

Syntax

addSubtree(robot,bodyname,subtreerobot)

addSubtree(___,ReplaceBase=MODE)

Description

addSubtree(robot,bodyname,subtreerobot) attaches the robot model, newSubtree, to an existing robot model, robot, at the body specified by bodyname. The subtree base is not added as a body.

addSubtree(___,ReplaceBase=MODE) replaces the current base of the subtree with bodyname when MODE is set to true. MODE is true by default.

Examples

Modify a Robot Rigid Body Tree Model

Make changes to an existing rigidBodyTree object. You can get replace joints, bodies and subtrees in the rigid body tree.

Load an ABB IRB-120T manipulator from the Robotics System Toolbox™ loadrobot. It is specified as a rigidBodyTree object.

manipulator = loadrobot("abbIrb120T");

View the robot with show and read the details of the robot using showdetails.

show(manipulator);

showdetails(manipulator)

--------------------
Robot: (8 bodies)

 Idx     Body Name            Joint Name            Joint Type     Parent Name(Idx)   Children Name(s)
 ---     ---------            ----------            ----------     ----------------   ----------------
   1          base        base_link-base                 fixed         base_link(0)   
   2        link_1               joint_1              revolute         base_link(0)   link_2(3)  
   3        link_2               joint_2              revolute            link_1(2)   link_3(4)  
   4        link_3               joint_3              revolute            link_2(3)   link_4(5)  
   5        link_4               joint_4              revolute            link_3(4)   link_5(6)  
   6        link_5               joint_5              revolute            link_4(5)   link_6(7)  
   7        link_6               joint_6              revolute            link_5(6)   tool0(8)  
   8         tool0          joint6-tool0                 fixed            link_6(7)   
--------------------

Get a specific body to inspect the properties. The only child of the link_3 body is the link_4 body. You can copy a specific body as well.

body3 = getBody(manipulator,"link_3");
childBody = body3.Children{1}

childBody = 
  rigidBody with properties:

            Name: 'link_4'
           Joint: [1x1 rigidBodyJoint]
            Mass: 1.3280
    CenterOfMass: [0.2247 1.5000e-04 4.1000e-04]
         Inertia: [0.0028 0.0711 0.0723 1.3052e-05 -1.3878e-04 -6.6037e-05]
          Parent: [1x1 rigidBody]
        Children: {[1x1 rigidBody]}
         Visuals: {'Mesh Filename link_4.stl'}
      Collisions: {'Mesh Filename link_4.stl'}

body3Copy = copy(body3);

Replace the joint on the link_3 body. You must create a new Joint object and use replaceJoint to ensure the downstream body geometry is unaffected. Call setFixedTransform if necessary to define a transform between the bodies instead of with the default identity matrices.

newJoint = rigidBodyJoint("prismatic");
replaceJoint(manipulator,"link_3",newJoint);

showdetails(manipulator)

--------------------
Robot: (8 bodies)

 Idx     Body Name            Joint Name            Joint Type     Parent Name(Idx)   Children Name(s)
 ---     ---------            ----------            ----------     ----------------   ----------------
   1          base        base_link-base                 fixed         base_link(0)   
   2        link_1               joint_1              revolute         base_link(0)   link_2(3)  
   3        link_2               joint_2              revolute            link_1(2)   link_3(4)  
   4        link_3             prismatic                 fixed            link_2(3)   link_4(5)  
   5        link_4               joint_4              revolute            link_3(4)   link_5(6)  
   6        link_5               joint_5              revolute            link_4(5)   link_6(7)  
   7        link_6               joint_6              revolute            link_5(6)   tool0(8)  
   8         tool0          joint6-tool0                 fixed            link_6(7)   
--------------------

Remove an entire body and get the resulting subtree using removeBody. The removed body is included in the subtree.

subtree = removeBody(manipulator,"link_4")

subtree = 
  rigidBodyTree with properties:

     NumBodies: 4
        Bodies: {[1x1 rigidBody]  [1x1 rigidBody]  [1x1 rigidBody]  [1x1 rigidBody]}
          Base: [1x1 rigidBody]
     BodyNames: {'link_4'  'link_5'  'link_6'  'tool0'}
      BaseName: 'link_3'
       Gravity: [0 0 0]
    DataFormat: 'struct'

show(subtree);

Remove the modified link_3 body. Add the original copied link_3 body to the link_2 body, followed by the returned subtree. The robot model remains the same. See a detailed comparison through showdetails.

removeBody(manipulator,"link_3");
addBody(manipulator,body3Copy,"link_2")
addSubtree(manipulator,"link_3",subtree)

showdetails(manipulator)

--------------------
Robot: (8 bodies)

 Idx     Body Name            Joint Name            Joint Type     Parent Name(Idx)   Children Name(s)
 ---     ---------            ----------            ----------     ----------------   ----------------
   1          base        base_link-base                 fixed         base_link(0)   
   2        link_1               joint_1              revolute         base_link(0)   link_2(3)  
   3        link_2               joint_2              revolute            link_1(2)   link_3(4)  
   4        link_3               joint_3              revolute            link_2(3)   link_4(5)  
   5        link_4               joint_4              revolute            link_3(4)   link_5(6)  
   6        link_5               joint_5              revolute            link_4(5)   link_6(7)  
   7        link_6               joint_6              revolute            link_5(6)   tool0(8)  
   8         tool0          joint6-tool0                 fixed            link_6(7)   
--------------------

Attach a Gripper to a Rigid Body Tree Manipulator Model

Load the UR10 robot manipulator from the Robotics System Toolbox™ loadrobot. It is specified as a rigidBodyTree object.

ur10 = loadrobot("universalUR10");

Load the Robotiq 2F-85 gripper to attach it to the manipulator arm.

gripper = loadrobot("robotiq2F85");

Attach the gripper to the end of the UR10 arm.

addSubtree(ur10, 'tool0', gripper, ReplaceBase=false);

View the robot with show and read the details of the robot using showdetails to view the modified joint of the rigidBodyTree object.

show(ur10)

ans = 
  Axes (Primary) with properties:

             XLim: [-1.5000 1.5000]
             YLim: [-1.5000 1.5000]
           XScale: 'linear'
           YScale: 'linear'
    GridLineStyle: '-'
         Position: [0.1300 0.1100 0.7750 0.8150]
            Units: 'normalized'

  Use GET to show all properties

showdetails(ur10)

--------------------
Robot: (21 bodies)

 Idx                      Body Name                            Joint Name                            Joint Type                      Parent Name(Idx)   Children Name(s)
 ---                      ---------                            ----------                            ----------                      ----------------   ----------------
   1                      base_link                           world_joint                                 fixed                              world(0)   base(2)  shoulder_link(3)  
   2                           base            base_link-base_fixed_joint                                 fixed                          base_link(1)   
   3                  shoulder_link                    shoulder_pan_joint                              revolute                          base_link(1)   upper_arm_link(4)  
   4                 upper_arm_link                   shoulder_lift_joint                              revolute                      shoulder_link(3)   forearm_link(5)  
   5                   forearm_link                           elbow_joint                              revolute                     upper_arm_link(4)   wrist_1_link(6)  
   6                   wrist_1_link                         wrist_1_joint                              revolute                       forearm_link(5)   wrist_2_link(7)  
   7                   wrist_2_link                         wrist_2_joint                              revolute                       wrist_1_link(6)   wrist_3_link(8)  
   8                   wrist_3_link                         wrist_3_joint                              revolute                       wrist_2_link(7)   ee_link(9)  tool0(10)  
   9                        ee_link                        ee_fixed_joint                                 fixed                       wrist_3_link(8)   
  10                          tool0        wrist_3_link-tool0_fixed_joint                                 fixed                       wrist_3_link(8)   robotiq_arg2f_base_link(11)  
  11        robotiq_arg2f_base_link           robotiq_arg2f_base_link_jnt                                 fixed                             tool0(10)   left_outer_knuckle(12)  left_inner_knuckle(16)  right_inner_knuckle(17)  right_outer_knuckle(18)  
  12             left_outer_knuckle                          finger_joint                              revolute           robotiq_arg2f_base_link(11)   left_outer_finger(13)  
  13              left_outer_finger               left_outer_finger_joint                                 fixed                left_outer_knuckle(12)   left_inner_finger(14)  
  14              left_inner_finger               left_inner_finger_joint                              revolute                 left_outer_finger(13)   left_inner_finger_pad(15)  
  15          left_inner_finger_pad           left_inner_finger_pad_joint                                 fixed                 left_inner_finger(14)   
  16             left_inner_knuckle              left_inner_knuckle_joint                              revolute           robotiq_arg2f_base_link(11)   
  17            right_inner_knuckle             right_inner_knuckle_joint                              revolute           robotiq_arg2f_base_link(11)   
  18            right_outer_knuckle             right_outer_knuckle_joint                              revolute           robotiq_arg2f_base_link(11)   right_outer_finger(19)  
  19             right_outer_finger              right_outer_finger_joint                                 fixed               right_outer_knuckle(18)   right_inner_finger(20)  
  20             right_inner_finger              right_inner_finger_joint                              revolute                right_outer_finger(19)   right_inner_finger_pad(21)  
  21         right_inner_finger_pad          right_inner_finger_pad_joint                                 fixed                right_inner_finger(20)   
--------------------

Input Arguments

robot — Robot model

RigidBodyTree object

Robot model, specified as a rigidBodyTree object.

bodyname — Parent body name

string scalar | character vector

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

Data Types: char | string

subtreerobot — Subtree robot model

rigidBodyTree object

Subtree robot model, specified as a rigidBodyTree object.

ReplaceBase — Replace current subtree base

true (default) | false

Replaces the current base of the subtree with bodyname when MODE is specified as true. The default value of MODE is set to true.

Data Types: logical

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

When creating the rigidBodyTree object, use the syntax that specifies the MaxNumBodies as an upper bound for adding bodies to the robot model. You must also specify the DataFormat property as a name-value pair. For example:

robot = rigidBodyTree("MaxNumBodies",15,"DataFormat","row")

To minimize data usage, limit the upper bound to a number close to the expected number of bodies in the model. All data formats are supported for code generation. To use the dynamics functions, the data format must be set to "row" or "column".

The show and showdetails functions do not support code generation.

Version History

Introduced in R2016b

R2022b: ReplaceBase name-value argument

Use ReplaceBase name-value argument to replace the current base of the subtree with bodyname.