geometricJacobian

Geometric Jacobian for robot configuration

Syntax

jacobian = geometricJacobian(robot,configuration,endeffectorframe)

jacobian = geometricJacobian(___,referenceframe)

Description

jacobian = geometricJacobian(robot,configuration,endeffectorframe) computes the geometric Jacobian relative to the base for the specified end-effector frame and configuration for the robot model.

jacobian = geometricJacobian(___,referenceframe) computes the geometric Jacobian for the end-effector frame with respect to the specified reference frame.

Examples

Geometric Jacobian for Robot Configuration

Calculate the geometric Jacobian for a specific end effector and configuration of a robot.

Load a PUMA 560 robot from the Robotics System Toolbox™ loadrobot, specified as a rigidBodyTree object.

puma = loadrobot("puma560");

Calculate the geometric Jacobian of body "link7" on the Puma robot for a random configuration.

geoJacob = geometricJacobian(puma,randomConfiguration(puma),"link7")

geoJacob = 6×6

   -0.0000   -0.5752   -0.5752   -0.4266   -0.7683   -0.5213
    0.0000    0.8180    0.8180   -0.3000   -0.3776    0.8377
    1.0000   -0.0000   -0.0000    0.8533   -0.5168    0.1629
    0.1696    0.0823    0.3087   -0.0407    0.0198         0
   -0.5577    0.0578    0.2171   -0.0200    0.0210         0
    0.0000    0.5538    0.2224   -0.0274   -0.0448         0

Input Arguments

robot — Robot model

rigidBodyTree object

Robot model, specified as a rigidBodyTree object.

configuration — Robot configuration

vector | structure

Robot configuration, specified as a vector of joint positions or a structure with joint names and positions for all the bodies in the robot model. You can generate a configuration using homeConfiguration(robot), randomConfiguration(robot), or by specifying your own joint positions in a structure. To use the vector form of configuration, set the DataFormat property for robot to either "row" or "column".

endeffectorframe — End-effector frame name

string scalar | character vector

End-effector frame name, specified as a string scalar or character vector. The end-effector frame can be any frame or body in the robot model.

Data Types: char | string

referenceframe — Reference frame name

BaseName of rigidBodyTree object | string scalar | character vector

Reference frame name, specified as a string scalar or character vector. The reference frame can be any frame or body in the robot model.

By default, the reference frame is set to the same value as the BaseName property of the rigidBodyTree object.

Data Types: char | string

Output Arguments

jacobian — Geometric Jacobian

6-by-n matrix

Geometric Jacobian of the end effector with the specified configuration, returned as a 6-by-n matrix, where n is the number of degrees of freedom of the robot. The Jacobian J maps the joint-space velocity to the end-effector velocity, relative to the base-coordinate frame. The end-effector velocity equals:

$$V_{EE}=\left[\begin{array}{c}{\omega }_x\\ {\omega }_y\\ {\omega }_z\\ v_x\\ v_y\\ v_z\end{array}\right]=J\dot{q}=J\left[\begin{array}{c}{\dot{q}}_1\\ ⋮\\ {\dot{q}}_n\end{array}\right]$$

ω is the angular velocity, υ is the linear velocity, and is the joint-space velocity.

By default, the geometric Jacobian is relative to the base-coordinate frame (J = J_base). If you specify a different reference frame using the referenceframe argument, the geometricJacobian function transforms the Jacobian to the coordinate system of the reference frame:

$$J=J_{ref}=\left[\begin{array}{cc}{R}_{base}^{ref}& 0_{3x3}\\ 0_{3x3}& R_{ref}^{base}\end{array}\right]J_{base}$$

$$R_{base}^{ref}$$ and $$R_{ref}^{base}$$ are SO(3) rotation matrices that relate the orientations of the base coordinate frame and the reference frame.

More About

Dynamics Properties

When working with robot dynamics, specify the information for individual bodies of your manipulator robot using these properties of the rigidBody objects:

• Mass — Mass of the rigid body in kilograms.

• CenterOfMass — Center of mass position of the rigid body, specified as a vector of the form [x y z]. The vector describes the location of the center of mass of the rigid body, relative to the body frame, in meters. The centerOfMass object function uses these rigid body property values when computing the center of mass of a robot.

• Inertia — Inertia of the rigid body, specified as a vector of the form [Ixx Iyy Izz Iyz Ixz Ixy]. The vector is relative to the body frame in kilogram square meters. The inertia tensor is a positive definite matrix of the form:

  

  The first three elements of the Inertia vector are the moment of inertia, which are the diagonal elements of the inertia tensor. The last three elements are the product of inertia, which are the off-diagonal elements of the inertia tensor.

For information related to the entire manipulator robot model, specify these rigidBodyTree object properties:

• Gravity — Gravitational acceleration experienced by the robot, specified as an [x y z] vector in m/s². By default, there is no gravitational acceleration.

• DataFormat — The input and output data format for the kinematics and dynamics functions, specified as "struct", "row", or "column".

Dynamics Equations

Manipulator rigid body dynamics are governed by this equation:

$$\frac{d}{dt}\left[\begin{array}{c}q\\ \dot{q}\end{array}\right]=\left[\begin{array}{c}\dot{q}\\ M{(q)}^{-1}\left(-C(q,\dot{q})\dot{q}-G(q)-J{(q)}^T{f}_{Ext}+\tau \right)\end{array}\right]$$

also written as:

$$M(q)\ddot{q}=-C(q,\dot{q})\dot{q}-G(q)-J{(q)}^T{f}_{Ext}+\tau$$

where:

• $$M(q)$$ — is a joint-space mass matrix based on the current robot configuration. Calculate this matrix by using the massMatrix object function.

• $$C(q,\dot{q})$$ — are the Coriolis terms, which are multiplied by $$\dot{q}$$ to calculate the velocity product. Calculate the velocity product by using by the velocityProduct object function.

• $$G(q)$$ — is the gravity torques and forces required for all joints to maintain their positions in the specified gravity Gravity. Calculate the gravity torque by using the gravityTorque object function.

• $$J(q)$$ — is the geometric Jacobian for the specified joint configuration. Calculate the geometric Jacobian by using the geometricJacobian object function.

• $$f_{Ext}$$ — is a matrix of the external forces applied to the rigid body. Generate external forces by using the externalForce object function.

• $$\tau$$ — are the joint torques and forces applied directly as a vector to each joint.

• $$q,\dot{q},\ddot{q}$$ — are the joint configuration, joint velocities, and joint accelerations, respectively, as individual vectors. For revolute joints, specify values in radians, rad/s, and rad/s², respectively. For prismatic joints, specify in meters, m/s, and m/s².

To compute the dynamics directly, use the forwardDynamics object function. The function calculates the joint accelerations for the specified combinations of the above inputs.

To achieve a certain set of motions, use the inverseDynamics object function. The function calculates the joint torques required to achieve the specified configuration, velocities, accelerations, and external forces.

References

[1] Featherstone, Roy. Rigid Body Dynamics Algorithms. Springer US, 2008. DOI.org (Crossref), doi:10.1007/978-1-4899-7560-7.

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

R2026a: Specify reference frame name in geometricJacobian method

You can now use the geometricJacobian object function to calculate the geometric Jacobian in any reference frame. By default, the reference frame is set to the base of the rigid body tree.

R2025a: Integrate frame name in geometricJacobian method

The geometricJacobian method now accepts either a body name or frame name in its input argument, for which it computes the geometric Jacobian.

R2024a: Static memory allocation support

geometricJacobian now supports code generation with disabled dynamic memory allocation. For more information about disabling dynamic memory allocation, see Control Dynamic Memory Allocation in Generated Code (MATLAB Coder).