Main Content

dcm2angle

Create rotation angles from direction cosine matrix

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.

For more information on angle constraints, see Limitations.

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.

Introduced in R2006b