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

[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

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 =
         0
    0.3000

roll =
         0
    0.1000

yaw =
         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 z-axis rotation, rotationAng2 is the y-axis rotation, and rotationAng3 is the x-axis rotation.

Data Types: char | string

lim — Angle constraint

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

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.

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 rads.

rotationAng2 — Second rotation angles

m-by-1 array

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

rotationAng3 — Third rotation angles

m-by-1 array

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.