rigidBodyJoint
Create a joint
Description
The rigidBodyJoint
objects defines how a rigid body moves relative to
an attachment point. In a tree-structured robot, a joint always belongs to a specific
rigid body, and each rigid body has one joint.
The rigidBodyJoint
object can describe joints of various types. When
building a rigid body tree structure with rigidBodyTree
, you must assign the Joint
object to a
rigid body using the rigidBody
class.
The different joint types supported are:
fixed
— Fixed joint that prevents relative motion between two bodies.revolute
— Single degree of freedom (DOF) joint that rotates around a given axis. Also called a pin or hinge joint.prismatic
— Single DOF joint that slides along a given axis. Also called a sliding joint.floating
— Six DOF joint that enables any translation and rotation.
Each joint type has different properties with different dimensions, depending on its defined geometry.
Creation
Description
Input Arguments
jname
— Joint name
string scalar | character vector
Joint name, specified as a string scalar or character vector. The joint name must be unique to access it off the rigid body tree.
Example: "elbow_right"
Data Types: char
| string
jtype
— Joint type
"fixed"
(default) | string scalar | character vector
Joint type, specified as a string scalar or character vector. The joint type predefines certain properties when creating the joint.
The different joint types supported are:
"fixed"
— Fixed joint that prevents relative motion between two bodies."revolute"
— Single degree of freedom (DOF) joint that rotates around a given axis. Also called a pin or hinge joint."prismatic"
— Single DOF joint that slides along a given axis. Also called a sliding joint."floating"
— Six DOF joint that enables free translation and rotation.
Example: "prismatic"
Data Types: char
| string
Properties
Type
— Joint type
"fixed"
(default) | string scalar | character vector
This property is read-only.
Joint type, returned as a string scalar or character vector. The joint type predefines certain properties when creating the joint.
The different joint types supported are:
"fixed"
— Fixed joint that prevents relative motion between two bodies."revolute"
— Single degree of freedom (DOF) joint that rotates around a given axis. Also called a pin or hinge joint."prismatic"
— Single DOF joint that slides along a given axis. Also called a sliding joint."floating"
— Six DOF joint that enables free translation and rotation.
If the rigid body that contains this joint is added to a robot model, the
joint type must be changed by replacing the joint using replaceJoint
.
Example: "prismatic"
Data Types: char
| string
Name
— Joint name
string scalar | character vector
Joint name, returned as a string scalar or character vector. The joint
name must be unique to access it off the rigid body tree. If the rigid body
that contains this joint is added to a robot model, the joint name must be
changed by replacing the joint using replaceJoint
.
Example: "elbow_right"
Data Types: char
| string
PositionLimits
— Position limits of joint
two-element row vector | 7-by-2 matrix
Position limits of the joint, specified as a two-element row vector of
[min max]
values or as a 7-by-2 matrix of
[min max]
values depending on the type of
joint:
fixed
—[NaN NaN]
(default). A fixed joint has no joint limits. Bodies remain fixed between each other.revolute
—[-pi pi]
(default). The limits define the angle of rotation around the axis in radians.prismatic
—[-0.5 0.5]
(default). The limits define the linear motion along the axis in meters.floating
—[NaN(4,2); repmat([-5 5],3,1)]
(default). The rotation, represented as a quaternion, has no joint limits. Each row of the position limits defines the linear motion along the x-,y-, and z-axes, respectively.
Example: [-pi/2 pi/2]
HomePosition
— Home position of joint
scalar | seven-element row vector
Home position of joint, specified as a scalar or seven-element row vector
depending on your joint type. The home position must fall in the range set
by PositionLimits
. This property is used by homeConfiguration
to
generate the predefined home configuration for an entire rigid body
tree.
Depending on the joint type, the home position has a different definition.
fixed
—0
(default). A fixed joint has no relevant home position.revolute
—0
(default). A revolute joint has a home position defined by the angle of rotation around the joint axis in radians.prismatic
—0
(default). A prismatic joint has a home position defined by the linear motion along the joint axis in meters.floating
—[1 0 0 0 0 0 0]
(default). A floating joint has a home position defined by an identity quaternion and xyz-position.
Example: pi/2
radians for a revolute
joint
JointAxis
— Axis of motion for joint
[NaN
NaN
NaN
] (default) | three-element unit vector
Axis of motion for joint, specified as a three-element unit vector. The vector can be any direction in 3-D space in local coordinates.
Depending on the joint type, the joint axis has a different definition.
fixed
— A fixed joint has no relevant axis of motion.revolute
— A revolute joint rotates the body in the plane perpendicular to the joint axis.prismatic
— A prismatic joint moves the body in a linear motion along the joint axis direction.floating
— A floating joint rotates the body freely in space. You cannot set theJointAxis
property for the floating joint.
Example: [1 0 0]
for motion around the
x-axis for a revolute
joint
JointToParentTransform
— Fixed transform from joint to parent frame
eye(4)
(default) | 4-by-4 homogeneous transform matrix
This property is read-only.
Fixed transform from joint to parent frame, returned as a 4-by-4 homogeneous transform matrix. The transform converts the coordinates of points in the joint predecessor frame to the parent body frame.
Example: eye(4)
ChildToJointTransform
— Fixed transform from child body to joint frame
eye(4)
(default) | 4-by-4 homogeneous transform matrix
This property is read-only.
Fixed transform from child body to joint frame, returned as a 4-by-4 homogeneous transform matrix. The transform converts the coordinates of points in the child body frame to the joint successor frame.
Example: eye(4)
Object Functions
copy | Create copy of joint |
setFixedTransform | Set fixed transform properties of joint |
Examples
Attach Rigid Body and Joint to Rigid Body Tree
Add a rigid body and corresponding joint to a rigid body tree. Each rigidBody
object contains a rigidBodyJoint
object and must be added to the rigidBodyTree
using addBody
.
Create a rigid body tree.
rbtree = rigidBodyTree;
Create a rigid body with a unique name.
body1 = rigidBody('b1');
Create a revolute joint. By default, the rigidBody
object comes with a fixed joint. Replace the joint by assigning a new rigidBodyJoint
object to the body1.Joint
property.
jnt1 = rigidBodyJoint('jnt1','revolute'); body1.Joint = jnt1;
Add the rigid body to the tree. Specify the body name that you are attaching the rigid body to. Because this is the first body, use the base name of the tree.
basename = rbtree.BaseName; addBody(rbtree,body1,basename)
Use showdetails
on the tree to confirm the rigid body and joint were added properly.
showdetails(rbtree)
-------------------- Robot: (1 bodies) Idx Body Name Joint Name Joint Type Parent Name(Idx) Children Name(s) --- --------- ---------- ---------- ---------------- ---------------- 1 b1 jnt1 revolute base(0) --------------------
Build Manipulator Robot Using Denavit-Hartenberg Parameters
Use the Denavit-Hartenberg (DH) parameters of the Puma560® robot to build a robot. Each rigid body is added one at a time, with the child-to-parent transform specified by the joint object.
The DH parameters define the geometry of the robot with relation to how each rigid body is attached to its parent. For convenience, setup the parameters for the Puma560 robot in a matrix [1]. The Puma robot is a serial chain manipulator. The DH parameters are relative to the previous row in the matrix, corresponding to the previous joint attachment.
dhparams = [0 pi/2 0 0; 0.4318 0 0 0 0.0203 -pi/2 0.15005 0; 0 pi/2 0.4318 0; 0 -pi/2 0 0; 0 0 0 0];
Create a rigid body tree object to build the robot.
robot = rigidBodyTree;
Create the first rigid body and add it to the robot. To add a rigid body:
Create a
rigidBody
object and give it a unique name.Create a
rigidBodyJoint
object and give it a unique name.Use
setFixedTransform
to specify the body-to-body transformation using DH parameters. The last element of the DH parameters,theta
, is ignored because the angle is dependent on the joint position.Call
addBody
to attach the first body joint to the base frame of the robot.
body1 = rigidBody('body1'); jnt1 = rigidBodyJoint('jnt1','revolute'); setFixedTransform(jnt1,dhparams(1,:),'dh'); body1.Joint = jnt1; addBody(robot,body1,'base')
Create and add other rigid bodies to the robot. Specify the previous body name when calling addBody
to attach it. Each fixed transform is relative to the previous joint coordinate frame.
body2 = rigidBody('body2'); jnt2 = rigidBodyJoint('jnt2','revolute'); body3 = rigidBody('body3'); jnt3 = rigidBodyJoint('jnt3','revolute'); body4 = rigidBody('body4'); jnt4 = rigidBodyJoint('jnt4','revolute'); body5 = rigidBody('body5'); jnt5 = rigidBodyJoint('jnt5','revolute'); body6 = rigidBody('body6'); jnt6 = rigidBodyJoint('jnt6','revolute'); setFixedTransform(jnt2,dhparams(2,:),'dh'); setFixedTransform(jnt3,dhparams(3,:),'dh'); setFixedTransform(jnt4,dhparams(4,:),'dh'); setFixedTransform(jnt5,dhparams(5,:),'dh'); setFixedTransform(jnt6,dhparams(6,:),'dh'); body2.Joint = jnt2; body3.Joint = jnt3; body4.Joint = jnt4; body5.Joint = jnt5; body6.Joint = jnt6; addBody(robot,body2,'body1') addBody(robot,body3,'body2') addBody(robot,body4,'body3') addBody(robot,body5,'body4') addBody(robot,body6,'body5')
Verify that your robot was built properly by using the showdetails
or show
function. showdetails
lists all the bodies in the MATLAB® command window. show
displays the robot with a given configuration (home by default). Calls to axis
modify the axis limits and hide the axis labels.
showdetails(robot)
-------------------- Robot: (6 bodies) Idx Body Name Joint Name Joint Type Parent Name(Idx) Children Name(s) --- --------- ---------- ---------- ---------------- ---------------- 1 body1 jnt1 revolute base(0) body2(2) 2 body2 jnt2 revolute body1(1) body3(3) 3 body3 jnt3 revolute body2(2) body4(4) 4 body4 jnt4 revolute body3(3) body5(5) 5 body5 jnt5 revolute body4(4) body6(6) 6 body6 jnt6 revolute body5(5) --------------------
show(robot);
axis([-0.5,0.5,-0.5,0.5,-0.5,0.5])
axis off
References
[1] Corke, P. I., and B. Armstrong-Helouvry. “A Search for Consensus among Model Parameters Reported for the PUMA 560 Robot.” Proceedings of the 1994 IEEE International Conference on Robotics and Automation, IEEE Computer. Soc. Press, 1994, pp. 1608–13. DOI.org (Crossref), doi:10.1109/ROBOT.1994.351360.
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)
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}
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)
Remove an entire body and get the resulting subtree using removeBody
. The removed body is included in the subtree.
subtree = removeBody(manipulator,"link_4")
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)
Model Floating-Base Robot Using Floating Joint
This example shows how to model a floating robot as a rigid body tree using a floating joint, represented by a rigidBodyJoint
of type "floating"
, at the fixed base. Use this approach for most applications such as forward kinematics and dynamics. However, if you need to use inverse kinematics solvers or motion models for a robot with a floating base, you cannot use the "floating"
joint. To model a floating-base robot for inverse kinematics or motion models, see Inverse Kinematics for Robots with Floating Base.
First create a fixed base as an empty rigid body tree. Then, create a rigid body and add a rigid body joint of type "floating"
to the rigid body.
rbt = rigidBodyTree(DataFormat="row"); floatingBaseBody = rigidBody("floatingBase"); floatingBaseBody.Joint = rigidBodyJoint("j1","floating");
Add the rigid body to the fixed-base rigid body tree. Now the rigid body and the fixed base are joined at the floating joint, enabling free translation and rotation in and along the xyz-axes.
addBody(rbt,floatingBaseBody,rbt.BaseName);
Load the rigid body tree model of the ABB IRB 120 robotic arm and add the loaded rigid body tree to the floating-base rigid body tree. Change the name of the BaseName
property of the floating base rigid body tree to 'world'
to avoid name conflicts. This name conflict is due to both rigid body trees using the default base name, 'base_link'
.
abbirb = loadrobot("abbIrb120",DataFormat="row"); rbt.BaseName = 'world'; addSubtree(rbt,"floatingBase",abbirb,ReplaceBase=false);
To demonstrate that the rigid body tree can both freely translate and rotate in space, visualize the base of the robotic arm at the xyz-coordinate [-1.1, 0.2, 0.3]
with an orientation of [0 pi/2 pi/3]
in the fixed base frame.
baseOrientation = eul2quat([0 pi/3 pi/3]); % ZYX Euler rotation order
basePosition = [-1.1 0.2 0.3];
floatingRBTConfig = [baseOrientation,basePosition,homeConfiguration(abbirb)]
floatingRBTConfig = 1×13
0.7500 0.4330 0.4330 -0.2500 -1.1000 0.2000 0.3000 0 0 0 0 0 0
show(rbt,floatingRBTConfig); axis equal title(["Robot Joint Configuration With Base", "at Desired Position and Orientation"])
Now you can use this floating base robot for applications such as forward kinematics and dynamics. As previously mentioned, you cannot model a floating-base robot in this way if you plan to use inverseKinematics
or do motion planning for it. Attempting to do so causes an error from the inverse kinematics function. To model a floating robot for inverse kinematics and motion planning, see Inverse Kinematics for Robots with Floating Base.
Limitations
These objects and functions do not support rigid body trees that contain
"floating"
joints:These blocks do not support rigid body trees that contain
"floating"
joints:The Inverse Kinematics Designer does not support rigid body trees that contain
"floating"
joints.Simscape™ Multibody™ does not support importing rigid body trees that contain floating joints.
For more information about these limitations and how to model a floating-base robot for use with these objects, functions, and blocks, see Inverse Kinematics for Robots with Floating Base.
References
[1] Craig, John J. Introduction to Robotics: Mechanics and Control. Reading, MA: Addison-Wesley, 1989.
[2] Siciliano, Bruno. Robotics: Modelling, Planning and Control. London: Springer, 2009.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Version History
Introduced in R2016bR2024a: Floating Joint Support
The rigidBodyJoint
object now supports the floating joint type.
This enables you to model robots with floating bases for dynamics, forward
kinematics, and motion planning.
R2019b: rigidBodyJoint
was renamed
The rigidBodyJoint
object was renamed from
robotics.Joint
. Use rigidBodyJoint
for all
object creation.
MATLAB-Befehl
Sie haben auf einen Link geklickt, der diesem MATLAB-Befehl entspricht:
Führen Sie den Befehl durch Eingabe in das MATLAB-Befehlsfenster aus. Webbrowser unterstützen keine MATLAB-Befehle.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)