en fr

# Quaternions

Quaternion functions support scalar and arrays of quaternions. Basic arithmetic operators and functions are overloaded to support expressions with the same syntax as for numbers and matrices.

Quaternions are numbers similar to complex numbers, but with four components instead of two. The unit imaginary parts are named i, j, and k. A quaternion can be written w+ix+jy+kz. The following relationships hold:

i^2 = j^2 = k^2 = ijk = -1

It follows that the product of two quaternions is not commutative; for instance, ij=k but ji=-k.

Quaternions are convenient to represent arbitrary rotations in the 3d space. They are more compact than matrices and are easier to normalize. This makes them suitable for simulation and control of mechanical systems and vehicles, such as flight simulators and robotics.

Functions below are specific to quaternions:

FunctionPurpose
isquaterniontest for quaternion type
q2matconversion to rotation matrix
q2rpyconversion to attitude angles
q2strconversion to string
qimagimaginary parts
qinvelement-wise inverse
qnormscalar norm
qslerpspherical linear interpolation
quaternionquaternion creation
rpy2qconversion from attitude angles

Operators below accept quaternions as arguments:

FunctionOperatorPurpose
ctranspose'conjugate transpose
eq==element-wise equality
horzcat[,]horizontal array concatenation
ldivide.\left division
ne~=element-wise inequality
minus-difference
mldivide\matrix left division
mrdivide/matrix right division
mtimes*matrix multiplication
rdivide./division
times.*multiplication
transpose.'transpose
uminus-unary minus
uplus+unary plus
vertcat[;]vertical array concatenation

Most of these operators work as expected, like with complex scalars and matrices. Multiplication and left/right division are not commutative. Matrix operations are not supported: operators *, /, \, and ^ are defined as a convenience (they are equivalent to .*, ./, .\, and .^ respectively) and work only element-wise with scalar arguments.

Mathematical functions below accept quaternions as arguments; with arrays of quaternions, they are applied to each element separately.

FunctionPurpose
absabsolute value
conjconjugate
coscosine
expexponential
lognatural logarithm
realreal part
signquaternion sign (normalization)
sinsine
sqrtsquare root

Functions below performs computations on arrays of quaternions.

FunctionPurpose
cumsumcumulative sum
diffdifferences
doubleconversion to array of double
meanarithmetic mean
sumsum

Functions below are related to array size.

FunctionPurpose
beginningfirst subscript
catarray concatenation
endlast subscript
flipdimflip array
fliplrflip left-right
flipudflip upside-down
ipermutedimension inverse permutation
isemptytest for empty array
lengthlength of vector
ndimsnumber of dimensions
numelnumber of elements
permutedimension permutation
repmatarray replication
reshapearray reshaping
rot90array rotation
sizearray size
squeezeremove singleton dimensions

Finally, functions below are related to output and assignment.

FunctionPurpose
dispdisplay
dumpvarconversion to string
subsasgnassignment to subarrays or to quaternion parts
subsrefreference to subarrays or to quaternion parts

Function imag is replaced with qimag which gives a quaternion with the real part set to zero, because there are three imaginary components instead of one with complex numbers.

Operators and functions which accept multiple arguments convert automatically double arrays to quaternions, ignoring the imaginary part of complex numbers.

Conversion to numeric arrays with double adds a dimension for the real part and the three imaginary parts. For example, converting a scalar quaternion gives a 4-by-1 double column vector and converting a 2-by-2 quaternion array gives a 2-by-2-by-4 double array. Real and imaginary components can be accessed with the field access notation: q.w is the real part of q, q.x, q.y, and q.z are its imaginary parts, and q.v is its imaginary parts as an array similar to the result of double but without the real part.

Compatibility note: native functions for quaternions replace library quaternion which defined quaternion scalars and matrices. It is much faster and supports arrays of more than two dimensions; on the other hand, matrix-oriented functions are not supported anymore, and the result of dumpvar is not directly compatible.

### isquaternion

Test for a quaternion.

#### Syntax

b = isquaternion(q)


#### Description

isquaternion(q) is true if the input argument is a quaternion and false otherwise.

#### Examples

isquaternion(2)
false
isquaternion(quaternion(2))
true


### q2mat

Conversion from quaternion to rotation matrix.

#### Syntax

R = q2mat(q)


#### Description

R=q2mat(q) gives the 3x3 orthogonal matrix R corresponding to the rotation given by scalar quaternion q. For a vector a=[x;y;z] and its representation as a pure quaternion aq=quaternion(x,y,z), the rotation can be performed with quaternion multiplication bq=q*aq/q or matrix multiplication b=R*a.

Input argument q does not have to be normalized; a quaternion corresponding to a given rotation is defined up to a multiplicative factor.

#### Example

q = rpy2q(0.1, 0.3, 0.2);
R = q2mat(q)
R =
0.9363 -0.1688  0.3080
0.1898  0.9810  0.0954
-0.2955  0.0954  0.9506
aq = quaternion(1, 2, 3);
q * aq / q
1.5228i+2.0336j+2.7469k
a = [1; 2; 3];
R * a
1.5228
2.4380
2.7469


### q2rpy

Conversion from quaternion to attitude angles.

#### Syntax

(pitch, roll, yaw) = q2rpy(q)


#### Description

q2rpy(q) gives the pitch, roll, and yaw angles corresponding to the rotation given by quaternion q. It is the inverse of rpy2q. All angles are given in radians.

If the input argument is a quaternion array, the results are arrays of the same size; conversion from quaternion to angles is performed independently on corresponding elements.

### q2str

Conversion from quaternion to string.

#### Syntax

str = q2str(q)


#### Description

q2str(q) converts quaternion q to its string representation, with the same format as disp.

### qimag

Quaternion imaginary parts.

#### Syntax

b = qimag(q)


#### Description

qimag(q) gives the imaginary parts of quaternion q as a quaternion, i.e. the same quaternion where the real part is set to zero. real(q) gives the real part of quaternion q as a double number.

#### Example

q = quaternion(1,2,3,4)
q =
1+2i+3j+4k
real(q)
1
qimag(q)
2i+3j+4k


quaternion

### qinv

Quaternion element-wise inverse.

#### Syntax

b = qinv(q)


#### Description

qinv(q) gives the inverse of quaternion q. If its input argument is a quaternion array, the result is an quaternion array of the same size whose elements are the inverse of the corresponding elements of the input.

The inverse of a normalized quaternion is its conjugate.

#### Example

q = quaternion(0.4,0.1,0.2,0.2)
q =
0.4+0.1i+0.2j+0.2k
p = qinv(q)
p =
1.6-0.4i-0.8j-0.8k
abs(q)
0.5
abs(p)
2


### qnorm

Quaternion scalar norm.

#### Syntax

n = qnorm(q)


#### Description

qnorm(q) gives the norm of quaternion q, i.e. the sum of squares of its components, or the square of its absolute value. If q is an array of quaternions, qnorm gives a double array of the same size where each element is the norm of the corresponding element of q.

### qslerp

Quaternion spherical linear interpolation.

#### Syntax

q = qslerp(q1, q2, t)


#### Description

qslerp(q1,q2,t) performs spherical linear interpolation between quaternions q1 and q2. The result is on the smallest great circle arc defined by normalized q1 and q2 for values of real number t between 0 and 1.

If q1 or q2 is 0, the result is NaN. If they are opposite, the great circle arc going through 1, or 1i, is picked.

If input arguments are arrays of compatible size (same size or scalar), the result is a quaternion array of the same size; conversion from angles to quaternion is performed independently on corresponding elements.

#### Example

q = qslerp(1, rpy2q(0, 1, -1.5), [0, 0.33, 0.66, 1]);
(roll, pitch, yaw) = q2rpy(q)
roll =
0.0000  0.1843  0.2272  0.0000
pitch =
0.0000  0.3081  0.6636  1.0000
yaw =
0.0000 -0.4261 -0.8605 -1.5000


### quaternion

Quaternion creation.

#### Syntax

q = quaternion
q = quaternion(w)
q = quaternion(c)
q = quaternion(x, y, z)
q = quaternion(w, x, y, z)
q = quaternion(w, v)


#### Description

With a real argument, quaternion(x) creates a quaternion object whose real part is w and imaginary parts are 0. With a complex argument, quaternion(c) creates the quaternion object real(c)+i*imag(c).

With four real arguments, quaternion(w,x,y,z) creates the quaternion object w+i*x+j*y+k*z.

With three real arguments, quaternion(x,y,z) creates the pure quaternion object i*x+j*y+k*z.

In all these cases, the arguments may be scalars or arrays of the same size.

With two arguments, quaternion(w,v) creates a quaternion object whose real part is w and imaginary parts is array v. v must have one more dimension than w for the three imaginary parts.

Without argument, quaternion returns the zero quaternion object.

The real or imaginary parts of a quaternion can be accessed with field access, such as q.w, q.x, q.y, q.z, and q.v.

#### Examples

q = quaternion(1, 2, 3, 4)
q =
1+2i+3j+4k
q + 5
6+2i+3j+4k
q * q
-28+4i+6j+8k
Q = [q, 2; 2*q, 5]
2x2 quaternion array
Q.y
3  0
6  0
q = quaternion(1, [5; 3; 7])
q =
1+5i+3j+7k
q.v
5
3
7


### rpy2q

Conversion from attitude angles to quaternion.

#### Syntax

q = rpy2q(pitch, roll, yaw)


#### Description

rpy2q(pitch,roll,yaw) gives the quaternion corresponding to a rotation of angle yaw around the z axis, followed by a rotation of angle pitch around the y axis, followed by a rotation of angle roll round the x axis. All angles are given in radians. The result is a normalized quaternion whose real part is cos(theta/2) and imaginary part sin(theta/2)*(vx*i+vy*j+vz*k), for a rotation of theta around unit vector [vx;vy;vz]. The rotation is applied to a point [x;y;z] given as a pure quaternion a=x*i+y*j+z*k, giving point b also as a pure quaternion; then b=q*a/q and a=q\b*q. The rotation can also be seen as changing coordinates from body to absolute, where the body's attitude is given by pitch, roll and yaw.

In order to have the usual meaning of pitch, roll and yaw, the x axis must be aligned with the direction of motion, the y axis with the lateral direction, and the z axis with the vertical direction, with the usual sign conventions for cross products. Two common choices are x pointing forward, y to the left, and z upward; or x forward, y to the right, and z downward.

If input arguments are arrays of compatible size (same size or scalar), the result is a quaternion array of the same size; conversion from angles to quaternion is performed independently on corresponding elements.

#### Example

Conversion of two vectors from aircraft coordinates (x axis forward, y axis to the left, z axis upward) to earth coordinates (x directed to the north, y to the west, z to the zenith). In aircraft coordinates, vectors are [2;0;0] (propeller position) and [0;5;0] (left wing tip). The aircraft attitude has a pitch of 10 degrees upward, i.e. -10 degrees with the choice of axis, and null roll and yaw.

q = rpy2q(0, -10*pi/180, 0)
q =
0.9962-0.0872j
q * quaternion(2, 0, 0) / q
1.9696i+0.3473k
q * quaternion(0, 5, 0) / q
5j