# rotmat

Convert quaternion to rotation matrix

## Syntax

``rotationMatrix = rotmat(quat,rotationType)``

## Description

example

````rotationMatrix = rotmat(quat,rotationType)` converts the quaternion, `quat`, to an equivalent rotation matrix representation.```

## Examples

collapse all

Define a quaternion for use in point rotation.

```theta = 45; gamma = 30; quat = quaternion([0,theta,gamma],'eulerd','ZYX','point')```
```quat = quaternion 0.8924 + 0.23912i + 0.36964j + 0.099046k ```

Convert the quaternion to a rotation matrix.

`rotationMatrix = rotmat(quat,'point')`
```rotationMatrix = 3×3 0.7071 -0.0000 0.7071 0.3536 0.8660 -0.3536 -0.6124 0.5000 0.6124 ```

To verify the rotation matrix, directly create two rotation matrices corresponding to the rotations about the y- and x-axes. Multiply the rotation matrices and compare to the output of `rotmat`.

```theta = 45; gamma = 30; ry = [cosd(theta) 0 sind(theta) ; ... 0 1 0 ; ... -sind(theta) 0 cosd(theta)]; rx = [1 0 0 ; ... 0 cosd(gamma) -sind(gamma) ; ... 0 sind(gamma) cosd(gamma)]; rotationMatrixVerification = rx*ry```
```rotationMatrixVerification = 3×3 0.7071 0 0.7071 0.3536 0.8660 -0.3536 -0.6124 0.5000 0.6124 ```

Define a quaternion for use in frame rotation.

```theta = 45; gamma = 30; quat = quaternion([0,theta,gamma],'eulerd','ZYX','frame')```
```quat = quaternion 0.8924 + 0.23912i + 0.36964j - 0.099046k ```

Convert the quaternion to a rotation matrix.

`rotationMatrix = rotmat(quat,'frame')`
```rotationMatrix = 3×3 0.7071 -0.0000 -0.7071 0.3536 0.8660 0.3536 0.6124 -0.5000 0.6124 ```

To verify the rotation matrix, directly create two rotation matrices corresponding to the rotations about the y- and x-axes. Multiply the rotation matrices and compare to the output of `rotmat`.

```theta = 45; gamma = 30; ry = [cosd(theta) 0 -sind(theta) ; ... 0 1 0 ; ... sind(theta) 0 cosd(theta)]; rx = [1 0 0 ; ... 0 cosd(gamma) sind(gamma) ; ... 0 -sind(gamma) cosd(gamma)]; rotationMatrixVerification = rx*ry```
```rotationMatrixVerification = 3×3 0.7071 0 -0.7071 0.3536 0.8660 0.3536 0.6124 -0.5000 0.6124 ```

Create a 3-by-1 normalized quaternion vector.

`qVec = normalize(quaternion(randn(3,4)));`

Convert the quaternion array to rotation matrices. The pages of `rotmatArray` correspond to the linear index of `qVec`.

`rotmatArray = rotmat(qVec,'frame');`

Assume `qVec` and `rotmatArray` correspond to a sequence of rotations. Combine the quaternion rotations into a single representation, then apply the quaternion rotation to arbitrarily initialized Cartesian points.

```loc = normalize(randn(1,3)); quat = prod(qVec); rotateframe(quat,loc)```
```ans = 1×3 0.9524 0.5297 0.9013 ```

Combine the rotation matrices into a single representation, then apply the rotation matrix to the same initial Cartesian points. Verify the quaternion rotation and rotation matrix result in the same orientation.

```totalRotMat = eye(3); for i = 1:size(rotmatArray,3) totalRotMat = rotmatArray(:,:,i)*totalRotMat; end totalRotMat*loc'```
```ans = 3×1 0.9524 0.5297 0.9013 ```

## Input Arguments

collapse all

Quaternion to convert, specified as a scalar, vector, matrix, or multidimensional array.

Data Types: `quaternion`

Type of rotation represented by the `rotationMatrix` output, specified as `'frame'` or `'point'`.

Data Types: `char` | `string`

## Output Arguments

collapse all

Rotation matrix representation, returned as a 3-by-3 matrix or 3-by-3-by-N multidimensional array.

• If `quat` is a scalar, `rotationMatrix` is returned as a 3-by-3 matrix.

• If `quat` is non-scalar, `rotationMatrix` is returned as a 3-by-3-by-N multidimensional array, where `rotationMatrix(:,:,i)` is the rotation matrix corresponding to `quat(i)`.

The data type of the rotation matrix is the same as the underlying data type of `quat`.

Data Types: `single` | `double`

## Algorithms

Given a quaternion of the form

`$q=a+bi+cj+dk\text{\hspace{0.17em}},$`

the equivalent rotation matrix for frame rotation is defined as

`$\left[\begin{array}{ccc}2{a}^{2}-1+2{b}^{2}& 2bc+2ad& 2bd-2ac\\ 2bc-2ad& 2{a}^{2}-1+2{c}^{2}& 2cd+2ab\\ 2bd+2ac& 2cd-2ab& 2{a}^{2}-1+2{d}^{2}\end{array}\right]\text{\hspace{0.17em}}.$`

The equivalent rotation matrix for point rotation is the transpose of the frame rotation matrix:

`$\left[\begin{array}{ccc}2{a}^{2}-1+2{b}^{2}& 2bc-2ad& 2bd+2ac\\ 2bc+2ad& 2{a}^{2}-1+2{c}^{2}& 2cd-2ab\\ 2bd-2ac& 2cd+2ab& 2{a}^{2}-1+2{d}^{2}\end{array}\right]\text{\hspace{0.17em}}.$`

## References

[1] Kuipers, Jack B. Quaternions and Rotation Sequences: A Primer with Applications to Orbits, Aerospace, and Virtual Reality. Princeton, NJ: Princeton University Press, 2007.

## Version History

Introduced in R2021a