# compassAngle

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

example

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

## Examples

collapse all

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

collapse all

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.

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

collapse all

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.

collapse all

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

## Version History

Introduced in R2023b