quatrotate

Rotate vector by quaternion

Syntax

n = quatrotate(q,r)

Description

n = quatrotate(q,r) calculates the resulting vector following the passive rotation of initial vector r by quaternion q and returns a final vector n. If quaternions are not yet normalized, the function normalizes them.

Aerospace Toolbox uses quaternions that are defined using the scalar-first convention. This function normalizes all quaternion inputs.

Examples

Rotate a 1-by-3 Vector

This example shows how to rotate a 1-by-3 vector by a 1-by-4 quaternion.

q = [1 0 1 0];
r = [1 1 1];
n = quatrotate(q, r)

n = 1×3

    -1     1     1

Rotate Two 1-by-3 Vectors by a 1-by-4 Quaternion

This example shows how to rotate two 1-by-3 vectors by a 1-by-4 quaternion.

q = [1 0 1 0];
r = [1 1 1; 2 3 4];
n = quatrotate(q, r)

n = 2×3

    -1     1     1
    -4     3     2

Rotate a 1-by-3 Vector by Two 1-by-4 Quaternions

This example shows how to rotate a 1-by-3 vector by two 1-by-4 quaternions.

q = [1 0 1 0; 1 0.5 0.3 0.1];
r = [1 1 1];
n = quatrotate(q, r)

n = 2×3

   -1.0000    1.0000    1.0000
    0.8519    1.4741    0.3185

Rotate Multiple Vectors by Multiple Quaternions

This example shows how to rotate multiple vectors by multiple quaternions.

q = [1 0 1 0; 1 0.5 0.3 0.1];
r = [1 1 1; 2 3 4];
n = quatrotate(q, r)

n = 2×3

   -1.0000    1.0000    1.0000
    1.3333    5.1333    0.9333

Input Arguments

q — Quaternion

m-by-4 matrix | 1-by-4 array

Quaternion or set of quaternions, specified as an m-by-4 matrix containing m quaternions, or a single 1-by-4 quaternion. Each element must be real.

q must have its scalar number as the first column.

Data Types: double | single

r — Initial vector

m-by-3 matrix | 1-by-3 array

Initial vector or set of vectors to be rotated, specified as an m-by-3 matrix, containing m vectors, or a single 1-by-3 array. Each element must be real.

Data Types: double | single

Output Arguments

n — Final vector

m-by-3 matrix

Final vector, returned as an m-by-3 matrix.

More About

q

The normalized quaternion q has the form:

$$q=q_0+i{q}_1+j{q}_2+k{q}_3$$

r

Vector r has the form:

$$v=i{v}_1+j{v}_2+k{v}_3$$

The Aerospace Toolbox defines a passive quaternion rotation of the form:

$$v^{\prime }=q^{-1}\otimes \left[\frac{0}{v}\right]\otimes q\text{,}$$

where Ⓧ is the operator of a quaternion multiplication.

n

Rotated vector n has the form:

$$v^{\prime }=\left[\begin{array}{c}{v}_1{}^{\prime }\\ v_2{}^{\prime }\\ v_3{}^{\prime }\end{array}\right]=\left[\begin{array}{ccc}(1-2q_2^2-2q_3^2)& 2(q_1{q}_2+q_0{q}_3)& 2(q_1{q}_3-q_0{q}_2)\\ 2(q_1{q}_2-q_0{q}_3)& (1-2q_1^2-2q_3^2)& 2(q_2{q}_3+q_0{q}_1)\\ 2(q_1{q}_3+q_0{q}_2)& 2(q_2{q}_3-q_0{q}_1)& (1-2q_1^2-2q_2^2)\end{array}\right]\left[\begin{array}{c}{v}_1\\ v_2\\ v_3\end{array}\right]$$

The direction cosine matrix for this equation expects a normalized quaternion.

References

[1] Stevens, Brian L., Frank L. Lewis. Aircraft Control and Simulation, 2nd Edition. Hoboken, NJ: John Wiley & Sons, 2003.

[2] Diebel, James. "Representing Attitude: Euler Angles, Unit Quaternions, and Rotation Vectors." Stanford University, Stanford, California, 2006.

Version History

Introduced in R2006b