Sysquake Pro – Table of Contents

Sysquake for LaTeX – Table of Contents

# 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**k**w+ix+jy+kz*

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

It follows that the product of two quaternions is not commutative;
for instance, `ij=k``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:

Function | Purpose |
---|---|

isquaternion | test for quaternion type |

q2mat | conversion to rotation matrix |

q2rpy | conversion to attitude angles |

q2str | conversion to string |

qimag | imaginary parts |

qinv | element-wise inverse |

qnorm | scalar norm |

qslerp | spherical linear interpolation |

quaternion | quaternion creation |

rpy2q | conversion from attitude angles |

Operators below accept quaternions as arguments:

Function | Operator | Purpose |
---|---|---|

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 |

plus | + | addition |

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.

Function | Purpose |
---|---|

abs | absolute value |

conj | conjugate |

cos | cosine |

exp | exponential |

log | natural logarithm |

real | real part |

sign | quaternion sign (normalization) |

sin | sine |

sqrt | square root |

Functions below performs computations on arrays of quaternions.

Function | Purpose |
---|---|

cumsum | cumulative sum |

diff | differences |

double | conversion to array of double |

mean | arithmetic mean |

sum | sum |

Functions below are related to array size.

Function | Purpose |
---|---|

beginning | first subscript |

cat | array concatenation |

end | last subscript |

flipdim | flip array |

fliplr | flip left-right |

flipud | flip upside-down |

ipermute | dimension inverse permutation |

isempty | test for empty array |

length | length of vector |

ndims | number of dimensions |

numel | number of elements |

permute | dimension permutation |

repmat | array replication |

reshape | array reshaping |

rot90 | array rotation |

size | array size |

squeeze | remove singleton dimensions |

Finally, functions below are related to output and assignment.

Function | Purpose |
---|---|

disp | display |

dumpvar | conversion to string |

subsasgn | assignment to subarrays or to quaternion parts |

subsref | reference 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

#### See also

### 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

#### See also

### 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.

#### See also

### 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`.

#### See also

### 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

#### See also

### 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

#### See also

### 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`.

#### See also

### 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

#### See also

### 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

#### See also

### 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)``sin(theta/2)*(vx*i+vy*j+vz*k)``theta``[vx;vy;vz]``[x;y;z]``a=x*i+y*j+z*k``b``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