M-File Help: Quaternion

M-File Help: Quaternion | View code for Quaternion

# Quaternion

Quaternion class

A quaternion is a compact method of representing a 3D rotation that has computational advantages including speed and numerical robustness. A quaternion has 2 parts, a scalar s, and a vector v and is typically written: q = s &lt;vx, vy, vz&gt;.

A unit-quaternion is one for which sˆ2+vxˆ2+vyˆ2+vzˆ2 = 1. It can be considered as a rotation by an angle theta about a unit-vector V in space where

    q = cos (theta/2) < v sin(theta/2)>

q = quaternion(x) is a unit-quaternion equivalent to x which can be any of:

- orthonormal rotation matrix.
- homogeneous transformation matrix (rotation part only).
- rotation angle and vector

## Methods

inv | inverse of quaterion
norm | norm of quaternion
unit | unitized quaternion
plot | same options as trplot()
interp | interpolation (slerp) between q and q2, 0<=s<=1
scale | interpolation (slerp) between identity and q, 0<=s<=1
dot | derivative of quaternion with angular velocity w
R | equivalent 3x3 rotation matrix
T | equivalent 4x4 homogeneous transform matrix
double | quaternion elements as 4-vector
inner | inner product of two quaternions

## Overloaded operators

q1==q2 | test for quaternion equality
q1~=q2 | test for quaternion inequality
q+q2 | elementwise sum of quaternions
q-q2 | elementwise difference of quaternions
q*q2 | quaternion product
q*v | rotate vector by quaternion, v is 3x1
s*q | elementwise multiplication of quaternion by scalar
q/q2 | q*q2.inv
q^n | q to power n (integer only)

## Properties (read only)

s | real part
v | vector part

## Notes

- Quaternion objects can be used in vectors and arrays.

## References

- Animating rotation with quaternion curves, K. Shoemake, in Proceedings of ACM SIGGRAPH, (San Fran cisco), pp. 245-254, 1985.
- On homogeneous transforms, quaternions, and computational efficiency, J. Funda, R. Taylor, and R. Paul, IEEE Transactions on Robotics and Automation, vol. 6, pp. 382-388, June 1990.
- Robotics, Vision & Control, P. Corke, Springer 2011.

## See also

trinterp, trplot

# Quaternion.Quaternion

Constructor for quaternion objects

Construct a quaternion from various other orientation representations.

q = Quaternion() is the identitity unit-quaternion 1&lt;0,0,0&gt; representing a null rotation.

q = Quaternion(q1) is a copy of the quaternion q1

q = Quaternion([S V1 V2 V3]) is a quaternion formed by specifying directly its 4 elements

q = Quaternion(s) is a quaternion formed from the scalar s and zero vector part: s&lt;0,0,0&gt;

q = Quaternion(v) is a pure quaternion with the specified vector part: 0&lt;v&gt;

q = Quaternion(th, v) is a unit-quaternion corresponding to rotation of th about the vector v.

q = Quaternion(R) is a unit-quaternion corresponding to the SO(3) orthonormal rotation matrix R (3x3). If R (3x3xN) is a sequence then q (Nx1) is a vector of Quaternions corresponding to the elements of R.

q = Quaternion(T) is a unit-quaternion equivalent to the rotational part of the SE(3) homogeneous transform T (4x4). If T (4x4xN) is a sequence then q (Nx1) is a vector of Quaternions corresponding to the elements of T.

# Quaternion.char

Convert to string

s = Q.char() is a compact string representation of the quaternion's value as a 4-tuple. If Q is a vector then s has one line per element.

# Quaternion.display

Display quaternion

Q.display() displays a compact string representation of the quaternion's value as a 4-tuple. If Q is a vector then S has one line per element.

## Notes

- This method is invoked implicitly at the command line when the result of an expression is a Quaternion object and the command has no trailing semicolon.

## See also

Quaternion.char

# Quaternion.dot

Quaternion derivative

qd = Q.dot(omega) is the rate of change of a frame with attitude Q and angular velocity OMEGA (1x3) expressed as a quaternion.

# Quaternion.double

Convert a quaternion to a 4-element vector

v = Q.double() is a 4-vector comprising the quaternion elements [s vx vy vz].

# Quaternion.eq

Test quaternion equality

Q1==Q2 is true if the quaternions Q1 and Q2 are equal.

## Notes

- Overloaded operator '=='.
- Note that for unit Quaternions Q and -Q are the equivalent rotation, so non-equality does not mean rotations are not equivalent.
- If Q1 is a vector of quaternions, each element is compared to Q2 and the result is a logical array of the same length as Q1.
- If Q2 is a vector of quaternions, each element is compared to Q1 and the result is a logical array of the same length as Q2.
- If Q1 and Q2 are vectors of the same length, then the result is a logical array of the same length.

## See also

Quaternion.ne

# Quaternion.inner

Quaternion inner product

v = Q1.inner(q2) is the inner (dot) product of two vectors (1x4), comprising the elements of Q1 and q2 respectively.

## Notes

- Q1.inner(Q1) is the same as Q1.norm().

## See also

Quaternion.norm

# Quaternion.interp

Interpolate quaternions

qi = Q1.interp(q2, s) is a unit-quaternion that interpolates a rotation between Q1 for s=0 and q2 for s=1.

If s is a vector qi is a vector of quaternions, each element corresponding to sequential elements of s.

## Notes

- This is a spherical linear interpolation (slerp) that can be interpretted as interpolation along a great circle arc on a sphere.
- The value of S is clipped to the interval 0 to 1.

## References

- Animating rotation with quaternion curves, K. Shoemake, in Proceedings of ACM SIGGRAPH, (San Fran cisco), pp. 245-254, 1985.

## See also

Quaternion.scale, ctraj

# Quaternion.inv

Invert a unit-quaternion

qi = Q.inv() is a quaternion object representing the inverse of Q.

# Quaternion.minus

Subtract quaternions

Q1-Q2 is the element-wise difference of quaternion elements.

## Notes

- Overloaded operator '-'
- The result is not guaranteed to be a unit-quaternion.

## See also

Quaternion.plus, Quaternion.mtimes

# Quaternion.mpower

Raise quaternion to integer power

QˆN is the quaternion Q raised to the integer power N.

## Notes

- Overloaded operator '^'
- Computed by repeated multiplication.
- If the argument is a unit-quaternion, the result will be a unit quaternion.

## See also

Quaternion.mrdivide, Quaternion.mpower, Quaternion.plus, Quaternion.minus

# Quaternion.mrdivide

Quaternion quotient.

Q1/Q2 | is a quaternion formed by Hamilton product of Q1 and inv(Q2).
Q/S | is the element-wise division of quaternion elements by the scalar S.

## Notes

- Overloaded operator '/'
- If the dividend and divisor are unit-quaternions, the quotient will be a unit quaternion.

## See also

Quaternion.mtimes, Quaternion.mpower, Quaternion.plus, Quaternion.minus

# Quaternion.mtimes

Multiply a quaternion object

Q1*Q2 | is a quaternion formed by the Hamilton product of two quaternions.
Q*V | is a vector formed by rotating the vector V by the quaternion Q.
Q*S | is the element-wise multiplication of quaternion elements by the scalar S.

## Notes

- Overloaded operator '*'
- If the two multiplicands are unit-quaternions, the product will be a unit quaternion.

## See also

Quaternion.mrdivide, Quaternion.mpower, Quaternion.plus, Quaternion.minus

# Quaternion.ne

Test quaternion inequality

Q1~=Q2 is true if the quaternions Q1 and Q2 are not equal.

## Notes

- Overloaded operator '~='
- Note that for unit Quaternions Q and -Q are the equivalent rotation, so non-equality does not mean rotations are not equivalent.
- If Q1 is a vector of quaternions, each element is compared to Q2 and the result is a logical array of the same length as Q1.
- If Q2 is a vector of quaternions, each element is compared to Q1 and the result is a logical array of the same length as Q2.
- If Q1 and Q2 are vectors of the same length, then the result is a logical array of the same length.

## See also

Quaternion.eq

# Quaternion.norm

Quaternion magnitude

qn = q.norm(q) is the scalar norm or magnitude of the quaternion q.

## Notes

- This is the Euclidean norm of the quaternion written as a 4-vector.
- A unit-quaternion has a norm of one.

## See also

Quaternion.inner, Quaternion.unit

# Quaternion.plot

Plot a quaternion object

Q.plot(options) plots the quaternion as an oriented coordinate frame.

## Options

Options are passed to trplot and include:

'color', C | The color to draw the axes, MATLAB colorspec C
'frame', F | The frame is named {F} and the subscript on the axis labels is F.
'view', V | Set plot view parameters V=[az el] angles, or 'auto' for view toward origin of coordinate frame

## See also

trplot

# Quaternion.plus

Add quaternions

Q1+Q2 is the element-wise sum of quaternion elements.

## Notes

- Overloaded operator '+'
- The result is not guaranteed to be a unit-quaternion.

## See also

Quaternion.minus, Quaternion.mtimes

# Quaternion.R

Convert to orthonormal rotation matrix

R = Q.R() is the equivalent SO(3) orthonormal rotation matrix (3x3). If Q represents a sequence (Nx1) then R is 3x3xN.

# Quaternion.scale

Interpolate rotations expressed by quaternion objects

qi = Q.scale(s) is a unit-quaternion that interpolates between a null rotation (identity quaternion) for s=0 to Q for s=1. This is a spherical linear interpolation (slerp) that can be interpretted as interpolation along a great circle arc on a sphere.

If s is a vector qi is a vector of quaternions, each element corresponding to sequential elements of s.

## Notes

- This is a spherical linear interpolation (slerp) that can be interpretted as interpolation along a great circle arc on a sphere.

## See also

Quaternion.interp, ctraj

# Quaternion.T

Convert to homogeneous transformation matrix

T = Q.T() is the equivalent SE(3) homogeneous transformation matrix

(4x4). | If Q represents a sequence (Nx1) then T is 4x4xN.

Notes:

- Has a zero translational component.

# Quaternion.unit

Unitize a quaternion

qu = Q.unit() is a unit-quaternion representing the same orientation as Q.

## See also

Quaternion.norm

© 1990-2014 Peter Corke.