Documentation

# dcm2angle

Create rotation angles from direction cosine matrix

## Syntax

```[r1 r2 r3] = dcm2angle(n) [r1 r2 r3] = dcm2angle(n,s) [r1 r2 r3] = dcm2angle(n,s,lim) [r1 r2 r3] = dcm2angle(n,s,lim,action) [r1 r2 r3] = dcm2angle(n,s,lim,action,tolerance) ```

## Description

`[r1 r2 r3] = dcm2angle(n)` calculates the set of rotation angles, `r1`, `r2`, `r3`, for a given direction cosine matrix, `n`. `n` is a 3-by-3-by-`m` matrix containing `m` direction cosine matrices. `r1` returns an `m` array of first rotation angles. `r2` returns an `m` array of second rotation angles. `r3` returns an `m` array of third rotation angles. Rotation angles are output in radians. This function applies only to direction cosine matrices that are orthogonal with determinant +1.

`[r1 r2 r3] = dcm2angle(n,s)` calculates the set of rotation angles, `r1`, `r2`, `r3`, for a given direction cosine matrix, `n`, and a specified rotation sequence, `s`.

The default rotation sequence is `'ZYX'`, where `r1` is `z`-axis rotation, `r2` is `y`-axis rotation, and `r3` is `x`-axis rotation.

Supported rotation sequences are `'ZYX'`, `'ZYZ'`, `'ZXY'`, `'ZXZ'`, `'YXZ'`, `'YXY'`, `'YZX'`, `'YZY'`, `'XYZ'`, `'XYX'`, `'XZY'`, and `'XZX'`.

`[r1 r2 r3] = dcm2angle(n,s,lim)` calculates the set of rotation angles, `r1`, `r2`, `r3`, for a given direction cosine matrix, `n`, a specified rotation sequence, `s`, and a specified angle constraint, `lim`. `lim` specifies either `'Default'` or `'ZeroR3'`. See Assumptions and Limitations for full definitions of angle constraints.

`[r1 r2 r3] = dcm2angle(n,s,lim,action)` performs `action` if the direction cosine matrix is invalid (not orthogonal).

• Warning — Displays warning and indicates that the direction cosine matrix is invalid.

• Error — Displays error and indicates that the direction cosine matrix is invalid.

• None — Does not display warning or error (default).

`[r1 r2 r3] = dcm2angle(n,s,lim,action,tolerance)` uses a `tolerance` level to evaluate if the direction cosine matrix, `n`, is valid (orthogonal). `tolerance` is a scalar whose default is `eps(2)` (`4.4409e-16`). The function considers the direction cosine matrix valid if these conditions are true:

• The transpose of the direction cosine matrix times itself equals `1` within the specified tolerance `tolerance` (```transpose(n)*n == 1±tolerance```)

• The determinant of the direction cosine matrix equals `1` within the specified tolerance (`det(n) == 1±tolerance`).

## Examples

Determine the rotation angles from direction cosine matrix:

```dcm = [1 0 0; 0 1 0; 0 0 1]; [yaw, pitch, roll] = dcm2angle(dcm) yaw = 0 pitch = 0 roll = 0```

Determine the rotation angles from multiple direction cosine matrices:

```dcm = [ 1 0 0; 0 1 0; 0 0 1]; dcm(:,:,2) = [ 0.85253103550038 0.47703040785184 -0.21361840626067; ... -0.43212157513194 0.87319830445628 0.22537893734811; ... 0.29404383655186 -0.09983341664683 0.95056378592206]; [pitch, roll, yaw] = dcm2angle(dcm,'YXZ') pitch = 0 0.3000 roll = 0 0.1000 yaw = 0 0.5000```

Determine the rotation angles from direction matrices validated within tolerance:

```dcm = [ 1 0 0; 0 1 0; 0 0 1]; dcm(:,:,2) = [ 0.85253103550038 0.47703040785184 -0.21361840626067; ... -0.43212157513194 0.87319830445628 0.22537893734811; ... 0.29404383655186 -0.09983341664683 0.95056378592206]; [pitch, roll, yaw] = dcm2angle(dcm,'YXZ','Default','None',0.1) pitch = 0 0.3000 roll = 0 0.1000 yaw = 0 0.5000```

## Assumptions and Limitations

The `'Default'` limitations for the `'ZYX'`, `'ZXY'`, `'YXZ'`, `'YZX'`, `'XYZ'`, and `'XZY'` implementations generate an `r2` angle that lies between ±90 degrees, and `r1` and `r3` angles that lie between ±180 degrees.

The `'Default'` limitations for the `'ZYZ'`, `'ZXZ'`, `'YXY'`, `'YZY'`, `'XYX'`, and `'XZX'` implementations generate an `r2` angle that lies 0–180 degrees, and `r1` and `r3` angles that lie between ±180 degrees.

The `'ZeroR3'` limitations for the `'ZYX'`, `'ZXY'`, `'YXZ'`, `'YZX'`, `'XYZ'`, and `'XZY'` implementations generate an `r2` angle that lies between ±90 degrees, and `r1` and `r3` angles that lie between ±180 degrees. However, when `r2` is ±90 degrees, `r3` is set to 0 degrees.

The `'ZeroR3'` limitations for the `'ZYZ'`, `'ZXZ'`, `'YXY'`, `'YZY'`, `'XYX'`, and `'XZX'` implementations generate an `r2` angle that lies 0–180 degrees, and `r1` and `r3` angles that lie between ±180 degrees. However, when `r2` is 0 or ±180 degrees, `r3` is set to 0 degrees. 