# dcm2angle

Create rotation angles from direction cosine matrix

## Syntax

``[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm)``
``[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm,rotationSequence)``
``[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm,rotationSequence,lim)``
``[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm,rotationSequence,lim,action)``
``[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm,rotationSequence,lim,action,tolerance)``

## Description

### Basic Syntax

example

````[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm)` calculates the rotation angles, `rotationAng1`, `rotationAng2`, `rotationAng3`, for a direction cosine matrix, `dcm`. The rotation used in this function is a passive transformation between two coordinate systems.`[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm,rotationSequence)` calculates the rotation angles for a specified rotation sequence, `rotationSequence`. ```

### Constraint, Action, and Tolerance Syntax

example

````[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm,rotationSequence,lim)` calculates the rotation angles for a specified angle constraint, `lim`. Specify `lim` after all other input arguments. `[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm,rotationSequence,lim,action)` calculates the rotation angles and performs an action if the direction cosine matrix is not orthogonal. Specify `action` after all other input arguments. `[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm,rotationSequence,lim,action,tolerance)` calculates the rotation angles and uses a `tolerance` level to evaluate if the direction cosine matrix is orthogonal. Specify `tolerance` after all other input arguments. ```

## Examples

collapse all

Determine the rotation angles from the 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','Default','None',0.1)```
```pitch = 0 0.3000 roll = 0 0.1000 yaw = 0 0.5000```

Calculate the rotation angles from direction cosine matrix and specify the rotation order and angle constraint.

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

Calculate the rotation angles from direction cosine matrix, specifying the rotation order, angle constraint, and action.

```dcm = [1 0 0; 0 1 0; 0 0 1]; [yaw, pitch, roll] = dcm2angle( dcm, 'zyx', 'robust', 'warning')```
```yaw = 0 pitch = 0 roll = 0```

Calculate the rotation angles from direction cosine matrix, specifying the rotation order, angle constraint, action, and tolerance.

```dcm = [1 0 0; 0 1 0; 0 0 1]; [yaw, pitch, roll] = dcm2angle( dcm, 'zyx', 'robust', 'warning', 0.01)```
```yaw = 0 pitch = 0 roll = 0```

## Input Arguments

collapse all

Direction cosine matrices, specified as a 3-by-3-by-m matrix, where `m` is the number of direction cosine matrices. The direction cosine matrices must be orthogonal with determinant +1.

Rotation sequence, specified as:

• `'ZYX'`

• `'ZYZ'`

• `'ZXY'`

• `'ZXZ'`

• `'YXZ'`

• `'YXY'`

• `'YZX'`

• `'YZY'`

• `'XYZ'`

• `'XZY'`

• `'XYX'`

• `'XZX'`

where `rotationAng1` is the `z`-axis rotation, `rotationAng2` is the `y`-axis rotation, and `rotationAng3` is the `x`-axis rotation.

Data Types: `char` | `string`

Angle constraint, specified as:

• `'Default'` — Returns the default case of R1, R2, and R3. In the event of a gimbal lock, use `'ZeroR3'` or `'Robust'`.

• `'ZeroR3'` — In the event of gimbal lock, sets R3 to `0` and solves for R1 and R2.

• `'Robust'` — Returns R1, R2, and R3 from either the `'Default'` or `'ZeroR3'` case that produces a rotation matrix that most closely matches the input matrix.

Action for invalid direction cosine matrix, specified as:

• `'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.

Valid direction cosine matrices are orthogonal and proper when:

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

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

Data Types: `char` | `string`

Relative tolerance level to evaluate if the direction cosine matrix, `dcm`, is orthogonal, specified as a scalar.

Data Types: `char` | `string`

## Output Arguments

collapse all

First rotation angles, returned as an m-by-1 array, in rads.

Second rotation angles, returned as an m-by-1 array, in rads.

Third rotation angles, returned as an m-by-1 array, in rads.

## Limitations

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

• The `'Default'` limitations for the `'ZYZ'`, `'ZXZ'`, `'YXY'`, `'YZY'`, `'XYX'`, and `'XZX'` implementations generate a `rotationAng2` angle that lies between 0–180 degrees, and `rotationAng1` and `rotationAng3` angles that lie between ±180 degrees.

• The `'ZeroR3'` limitations for the `'ZYX'`, `'ZXY'`, `'YXZ'`, `'YZX'`, `'XYZ'`, and `'XZY'` implementations generate a `rotationAng2` angle that lies between ±90 degrees, and `rotationAng1` and `rotationAng3` angles that lie between ±180 degrees. However, when `rotationAng2` is ±90 degrees, `rotationAng3` is set to 0 degrees.

• The `'ZeroR3'` limitations for the `'ZYZ'`, `'ZXZ'`, `'YXY'`, `'YZY'`, `'XYX'`, and `'XZX'` implementations generate a `rotationAng2` angle that lies between 0–180 degrees, and `rotationAng1` and `rotationAng3` angles that lie between ±180 degrees. However, when `rotationAng2` is 0 or ±180 degrees, `rotationAng3` is set to 0 degrees.

## Version History

Introduced in R2006b