# quatrotate

Rotate vector by quaternion

## Syntax

``n = quatrotate(q,r)``

## Description

example

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

collapse all

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.0000 1.0000 1.0000 ```

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.0000 1.0000 1.0000 -4.0000 3.0000 2.0000 ```

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

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

collapse all

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`

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

collapse all

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

collapse all

### 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}\left(1-2{q}_{2}^{2}-2{q}_{3}^{2}\right)& 2\left({q}_{1}{q}_{2}+{q}_{0}{q}_{3}\right)& 2\left({q}_{1}{q}_{3}-{q}_{0}{q}_{2}\right)\\ 2\left({q}_{1}{q}_{2}-{q}_{0}{q}_{3}\right)& \left(1-2{q}_{1}^{2}-2{q}_{3}^{2}\right)& 2\left({q}_{2}{q}_{3}+{q}_{0}{q}_{1}\right)\\ 2\left({q}_{1}{q}_{3}+{q}_{0}{q}_{2}\right)& 2\left({q}_{2}{q}_{3}-{q}_{0}{q}_{1}\right)& \left(1-2{q}_{1}^{2}-2{q}_{2}^{2}\right)\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.

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

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