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

[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm) calculates the rotation angles, rotationAng1, rotationAng2, rotationAng3, for a direction cosine matrix, dcm, using the default rotation sequence of 'ZYX' (yaw, pitch, roll). The direction cosine matrix represents a passive transformation from frame A to frame B. The resulting rotation angles represent a series of right-hand intrinsic passive rotations from frame A to frame B.

[rotationAng1 rotationAng2 rotationAng3] = dcm2angle(dcm,rotationSequence) calculates the rotation angles for a specified rotation sequence, rotationSequence. The rotation sequence parameter also specifies the order of the three rotation angles. For example, if rotationSequence has a value of XYZ, the output rotation angles are in the order x-y-z (roll, pitch, yaw).

Constraint, Action, and Tolerance Syntax

[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

Determine Rotation Angles from Direction Cosine Matrix Using dcm2angle

These examples show how to use dcm2angle to determine rotation angles from the direction cosine matrix.

Determine Rotation Angles from Direction Cosine Matrix

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 Rotation Angles from Multiple Direction Cosine Matrices

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 = 2×1

         0
    0.3000

roll = 2×1

         0
    0.1000

yaw = 2×1

         0
    0.5000

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 = 2×1

         0
    0.3000

roll = 2×1

         0
    0.1000

yaw = 2×1

         0
    0.5000

Determine Rotation Angles from Multiple Direction Cosine Matrices and Angle Constraint

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

Determine Rotation Angles from Multiple Direction Cosine Matrices, Angle Constraint, and Action

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

Determine Rotation Angles from Multiple Direction Cosine Matrices, Angle Constraint, Action, and Tolerance

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

dcm — Direction cosine matrices

3-by-3-by-m matrix

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.

rotationSequence — Rotation sequence

'ZYX' (default) | 'ZYX' | 'ZYZ' | 'ZXY' | 'ZXZ' | 'YXZ' | 'YXY' | 'YZX' | 'YZY' | 'XYZ' | 'XZY' | 'XYX' | 'XZX'

Rotation sequence, specified as:

• 'ZYX'

• 'ZYZ'

• 'ZXY'

• 'ZXZ'

• 'YXZ'

• 'YXY'

• 'YZX'

• 'YZY'

• 'XYZ'

• 'XZY'

• 'XYX'

• 'XZX'

where rotationAng1 is the first angle in the sequence, rotationAng2 is the second angle in the sequence, and rotationAng3 is the third angle in the sequence.

Data Types: char | string

lim — Angle constraint

'Default' (default) | 'ZeroR3' | 'Robust'

Angle constraint, specified as:

• 'Default' — Calculates rotation angles for both nominal and gimbal-lock conditions. After calculating the rotation angles, the option converts both rotation angles back to DCM and outputs the rotation angle whose value is closest to the dcm value. This option returns the most accurate solution in all conditions. This behavior is the same as the 'Robust' behavior.

• 'ZeroR3' — In the event of gimbal lock, this option sets rotationAng3 to zero and solves for rotationAng1 and rotationAng2.

• 'Robust' — Calculates rotation angles for both nominal and gimbal-lock conditions. After calculating the rotation angles, the option converts both rotation angles back to DCM and outputs the rotation angle whose value is closest to the dcm value. This option returns the most accurate solution in all conditions. This behavior is the same as the 'Default' behavior.

For more information on angle constraints, see Limitations.

action — Action for invalid direction cosine matrix

'None' (default) | 'Error' | 'Warning'

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

tolerance — Relative tolerance

eps(2) (default) | scalar

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

Data Types: char | string

Output Arguments

rotationAng1 — First rotation angles

m-by-1 array

First rotation angles, returned as an m-by-1 array, in radians. The rotationAng1 argument represents the first rotation in rotationSequence.

rotationAng2 — Second rotation angles

m-by-1 array

Second rotation angles, returned as an m-by-1 array, in radians. The rotationAng2 argument represents the second rotation in rotationSequence.

rotationAng3 — Third rotation angles

m-by-1 array

Third rotation angles, returned as an m-by-1 array, in radians. The rotationAng3 argument represents the third rotation in rotationSequence.

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

R2025a: dcm2angle function calculates rotation angles for both nominal and gimbal-lock conditions

The dcm2angle function now calculates rotation angles for both nominal and gimbal-lock conditions when you set the lim argument to Default or Robust.After calculating the rotation angles, the option converts both rotation angles back to DCM and outputs the rotation angle whose value is closest to the dcm value.

When you run an application from a release prior to R2025a, the output now differs from the same application run in R2025a and after.