compassAngle

Navigational heading relative to north

Since R2023b

Syntax

C = compassAngle(orientations)

C = compassAngle(orientations,RF)

Description

C = compassAngle(orientations) returns the compass angles in the north-east-down (NED) reference frame based on the orientations. Compass angles are counter-clockwise angles from north of the reference frame to the x-directions of the frames defined by orientations. See Compass Angle for more details.

C = compassAngle(orientations,RF) specifies the reference frame as the "NED" (north-east-down) or "ENU" (east-north-up) reference frame.

Examples

Get Compass Angles from Orientations

Define four sets of Euler angles and obtain their corresponding quaternions.

angles = [0 0 0; 10 0 0; 190 0 0; -10 0 0];
quats = quaternion(angles,"eulerd","ZYX","frame");

Obtain the compass angles and convert their units to degrees.

C = rad2deg(compassAngle(quats))

C = 4×1

         0
   10.0000
  190.0000
  350.0000

Next, obtain the compass angles assuming the ENU reference frame.

CENU = rad2deg(compassAngle(quats,"ENU"))

CENU = 4×1

    90
    80
   260
   100

Input Arguments

orientations — Orientations

N-by-1 vector of quaternion objects | 3-by-3-by-N array of rotation matrices

Orientations, specified as an N-by-1 vector of quaternion objects or as a 3-by-3-by-N array of rotation matrices. N is the total number of orientations.

RF — Reference frame

"NED" | "ENU"

Reference frame, specified as "NED" for the north-east-down frame or "ENU" for the east-north-up frame.

Data Types: string | char

Output Arguments

C — Compass angles

N-by-3 matrix of scalars in range [0, 2*pi)

Compass angles, in radians, returned as an N-by-3 matrix of scalars in the range [0, 2*pi). N is the total number of orientations.

More About

Compass Angle

The compass angle is defined as the angle from the north to the x-direction of the body frame. In the NED reference frame, the compass angle is the counter-clockwise angle from the positive-x direction of the NED frame to the positive-x direction of the body frame. The orientations input defines the rotational coordinate transformation from the reference frame to the body frame. The compass angles of the north, east, south, and west directions are 0, π/2, π, and 3π/2, respectively.

References

[1] Gade, Kenneth. “The Seven Ways to Find Heading.” Journal of Navigation, vol. 69, no. 5, Sept. 2016, pp. 955–70.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2023b